Skip to content

Declare source-of-truth and derivation intent for spaces and their representations #146

Open

Description

@mindsocket

Summary

There is no way to say which representation of some structured content is canonical, and which ones are derived from it. Config registers each space independently, and render/sync commands are run ad hoc.

Example

A Wardley map could exist as:

  • a directory of markdown files, one per component, with frontmatter for evolution, visibility and needs links;
  • an OnlineWardleyMaps (OWM) text file;
  • a visual canvas or board in a tool like Obsidian Canvas or Miro.

If the markdown directory is the source of truth, the OWM file and the canvas should be generated from it and treated as read-only, or at least checked for drift. There may also be several maps over one body of content. Nothing in config or the CLI records that intent today.

Questions

  • How to express it: a space-level setting (for example derivedFrom / renders with target formats and paths), a relationship between spaces, or a separate project-level "pipeline" concept?
  • What tooling follows from it:
    • a sctx render/sync that regenerates all derived outputs;
    • drift detection when a derived file is edited by hand;
    • hooks that warn on edits to derived files.
  • How one space maps to several derived artefacts (many maps or views over one space), and several spaces feed one artefact.
  • How this relates to bidirectional sync with external systems of record, where the canonical side may differ per field.

Related: #6 (systems of work), #8 (cross-space references), #88 (frameworks as plugins), #138 (serialisable graph)

Activity

  1. mindsocket commented on Oct 7, 2026

    @mindsocket
    OwnerAuthor

    Note: one schema, several representations already works

    A plugin can parse a non-markdown representation against the same schema the markdown reader uses. The Wardley mapping plugin (in an extensions repo) is an example:

    • Its parser handles a .owm file path.
    • For a directory path it returns null, so the markdown reader takes over with the same schema.

    Round-trip check with a sample map: .owm space → sctx render … markdown.directory → markdown space → sctx render … owm.

    • Both spaces validate with the same 15 nodes and 0 errors.
    • The regenerated OWM is semantically equivalent. The differences are formatting, explicit pipeline bounds and normalised element syntax, plus one dropped comment line.

    What's missing is the link between the two: today they are two unrelated spaces, and the render step is a manual command.

    Possible direction: render targets in space config

    A space keeps its path (what is parsed and validated) and gains render targets, so source-of-truth intent sits where the space is defined. For example:

    {
      name: "market-map",
      path: "maps/market",            // canonical: markdown directory
      schema: "…/wardley_map.json",
      render: [
        { format: "wardley-mapping.owm", out: "exports/market.owm" },
      ],
    }

    That gives:

    • a single sctx render <space> (or sync) that regenerates every declared target;
    • drift detection by re-parsing a target and comparing graphs, where the target has a parser;
    • a hook that warns when a declared target is edited directly.

    Two-way sync, where either side can be edited, would build on this rather than replace it.

  2. mindsocket commented on Oct 29, 2026

    @mindsocket
    OwnerAuthor

    Context note (2026-10-29). Separate from what this issue asks.

    The working assumption for core, the Obsidian plugin and map views is that each space has one canonical source, and that today the source is the space's markdown. An editing surface (a map view, an editor) writes back to the markdown, and anything else is derived from it. That is a scoping assumption for those three, not an answer to this issue.

    This issue stays open for the wider question: declaring which representation is canonical and which are derived (OWM text, canvases, boards), and what happens when a non-markdown source arrives. Candidate mechanisms, none chosen:

    • everything goes via markdown, with two-way sync for other representations;
    • the source system parses straight into nodes, with no markdown;
    • updates go to the source system and are re-parsed.

    Decide when the first non-markdown source arrives.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions