Menu

Semantics and status

This page is the compact contract for what is stable in Org2 today, what is implementation-defined, and what is roadmap.

Normative now

Stable implementation behavior (documented, but not yet fully spec-locked)

  • CLI workflows and flags in org2 --help families (agenda, roam, crypt, publish, etc.).

  • Agenda query semantics used by current CLI/editor integrations.

  • Backlinks presentation behavior in current VS Code extension.

These are intended to remain stable for users, but details can still change across alpha releases.

Implementation-defined today

  • Exact editor UX choices (panes, command names, prompt flows, keybinding defaults).

  • Some advanced agenda UX semantics in editor commands (quick actions and display ordering details).

  • Some formatting details that may evolve with parser/printer convergence.

Roadmap / not yet normative

  • Full semantic modules beyond parser scope (deeper planning semantics, richer automation contracts).

  • Broader editor parity beyond VS Code.

  • Stable plugin API surface.

Practical reading order

  1. Start with Language reference for syntax.

  2. Read Tooling reference for actual workflows.

  3. Use this page to understand stability expectations.

Identity, provenance, and graph operations

Org2 treats linked knowledge as compiler state rather than editor decoration. A note corpus should be able to answer three practical questions reliably:

  • What is this node's stable identity?

  • Where did this fact, link, or derived artifact come from?

  • What graph operations can tools safely build on?

Identity contract

  • ID properties are the primary stable identity for headings/nodes.

  • id: links should target those stable IDs rather than fragile heading text.

  • Wiki links and aliases are useful authoring conveniences, but tooling should resolve them into concrete represented nodes before making graph claims.

  • File links identify files or file-local targets; they should not be silently conflated with roam node identity.

Provenance contract

Generated views should preserve enough source context for users and tools to audit them. For compiler-style workflows, that means derived output should prefer citations that include at least:

  • source file path,

  • heading or node identity when available,

  • line/section context when available,

  • the command or workflow that produced the derived artifact.

This keeps search results, backlinks, exports, and future maintenance passes explainable instead of becoming anonymous generated text.

Graph operation contract

Graph-aware commands should separate three phases:

  1. parse source files into syntax and metadata,

  2. resolve identities, aliases, links, and backlinks into a graph model,

  3. emit derived operations such as link suggestions, reports, exports, or maintenance fixes.

That separation matters because users need dry-run reports and safe, reviewable edits. A linkify command, for example, can now distinguish exact title/alias replacements from represented-node suggestions, explain the evidence tokens and source range behind a semantic match, and keep review-only suggestions out of automatic writes. The AI-assisted suggestion command follows the same contract: compiler graph/linkify/entity candidates are passed to a deterministic mock adapter for ranking and explanation, and --apply can only write a report artifact, not canonical note edits.

Useful next steps

  • Make cited query/search output available as a stable CLI surface for knowledge-base workflows.

  • Add an acceptance workflow for individual AI-assisted link/entity suggestions while preserving explicit approval.

  • Document which generated artifacts are safe to commit and which are cache-like rebuild outputs.

  • Add maintenance commands that detect duplicate IDs, unresolved aliases, broken links, and stale derived graph artifacts.