@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.12

package/docs/obsidian.md

@@ -72,13 +72,18 @@ A focus keeps the full vault on disk and filters the native Graph view. The
 query is
 
 ```
-path:"<note path>" OR path:"<note path>" ...
+path:/^<note path>$/ OR path:/^<note path>$/ ...
 ```
 
-in the order of the selected set (canonical-id order). Inside the quoted term
-a backslash and a double quote are escaped with a backslash; nothing else is
-changed, so a path that itself contains search operators (`tag:`, `-`, `OR`,
-parentheses) stays text. Paths are NFC-normalized before they are quoted. A
+in the order of the selected set (canonical-id order). Each term is a regular
+expression anchored at both ends, so it matches exactly one note: a plain
+`path:` term matches any path that contains it, and with titles as names one
+note's path can lie inside another's. In the term every regular-expression
+character and the `/` delimiter is escaped with a backslash, and a space and
+a double quote are written as `\x20` and `\x22`, so a path that itself
+contains search operators (`tag:`, `-`, `OR`, parentheses) stays text. Paths
+are NFC-normalized first. A persisted focus of the earlier query version
+(`obsidian-graph-search-paths/v1`, quoted substring terms) is still read. A
 path that carries a control character, a C1 control, or the U+2028 or U+2029
 line separator cannot be a search term and refuses with
 `focus-path-unrepresentable`; so does an absolute path, a backslash path or a
@@ -256,7 +261,7 @@ nothing under `scripts/obsidian/` ships.
 | --- | --- |
 | `@mnstry/atelier/obsidian` | `src/runtime/obsidian/index.mjs`: enablement, machine settings, engine, service lifecycle, production seams, app qualification |
 | `@mnstry/atelier/obsidian/contracts` | `src/projection/obsidian/contracts.mjs`: contract validation, `selectScope`, note paths |
-| `@mnstry/atelier/obsidian/materialize` | `prepareView`, settings, path registry |
+| `@mnstry/atelier/obsidian/materialize` | `prepareView`, settings (including the plugin's files and entry), path registry |
 | `@mnstry/atelier/obsidian/publication` | `publishView`, editor adapters, the exchange |
 | `@mnstry/atelier/obsidian/recovery` | recovery store, journals, late-writer recheck |
 | `@mnstry/atelier/obsidian/edits` | edit observation, arbitration, apply policy, source apply |
@@ -272,9 +277,10 @@ What the tarball must and must not carry, and the package proof, are in
 
 ## First vault: what to expect
 
-This is the path an adopter walks on one machine, in the order the command
-requires it. Every operation and flag below is the shipped `atelier obsidian`
-usage text; `atelier obsidian --help` prints it.
+This is the path an adopter walks on one machine. Every operation and flag
+below is the shipped `atelier obsidian` usage text; `atelier obsidian --help`
+prints it. There are three steps, and none of them is done by hand in
+Obsidian.
 
 1. Enable the projection in the project configuration. The member
    `ext["mnstry.atelier.obsidian"]` is an `atelier-obsidian-ext-settings/v1`
@@ -295,19 +301,54 @@ usage text; `atelier obsidian --help` prints it.
      has to carry; `policy install FILE` installs it and leaves the mode
      unchanged; `policy revoke` returns the mode to `manual` and stops every
      later apply.
-3. Start the maintenance service:
-   `atelier obsidian service start --consent-actor ID --adapter=obsidian-cli`.
-   Reaching the installed app is never a default, so `--adapter=obsidian-cli`
-   is required, and the consent actor records who allowed the service to run.
-   `service status` and `service stop` manage it; `service unit --print
-   --adapter=obsidian-cli` prints a startup unit and installs nothing.
-4. Open a view: `atelier obsidian open --scope ID --adapter=obsidian-cli`.
-   The command starts or reconnects maintenance, verifies the vault by reading
-   it back, and asks the app (version 1.13.7 or later) to open it. Quit
-   Obsidian before a view's first publication (on Linux, also any app that
-   runs on a system Electron): while a process that may be Obsidian runs, the
-   first publication stops, and `open` and `status` say so; see
-   [First publication while Obsidian is running](#first-publication-while-obsidian-is-running).
+3. Open a view:
+   `atelier obsidian open --scope ID --consent-actor ID --adapter=obsidian-cli`.
+   That's it. Reaching the installed app is never a default, so
+   `--adapter=obsidian-cli` is required, and the first open of a workspace
+   records who allowed the maintenance service to run (`--consent-actor`;
+   later opens reconnect to it and need no consent). `open` starts or
+   reconnects maintenance and asks it for a tick, makes Obsidian (version
+   1.13.7 or later) know the view's vault as one of its vaults, opens it,
+   publishes the view, verifies the vault by reading it back, and waits until
+   the app answers for exactly that vault. It does this in whatever state
+   Obsidian is in; see
+   [What `open` does in each state of Obsidian](#what-open-does-in-each-state-of-obsidian).
+
+The maintenance service can also be managed on its own:
+`atelier obsidian service start --consent-actor ID --adapter=obsidian-cli`,
+`service status` and `service stop`; `service unit --print
+--adapter=obsidian-cli` prints a startup unit and installs nothing.
+
+After an upgrade of Atelier, a maintenance service started earlier still runs
+the earlier release. `open` replaces it: when the service of this workspace
+proves itself Atelier's own but runs an earlier release than the installed one
+(its record names the release it runs: the package version and a digest of
+its modules; an earlier version, the same version with other modules, or no
+release named), or refuses a tick that names a view as releases up to
+0.2.0-alpha.11 do,
+`open` stops it as `service stop` would and starts the installed release under
+the consent already recorded, and says `service: restarted (outdated)`. A
+service of a later release is never replaced by an earlier one, so two
+installations used on one workspace (a global and a project-local one, say)
+do not replace each other's service on every open: `open` answers
+`service-unavailable` / `service-other-release`; run `atelier obsidian service
+stop`, then open again, or open with the later release. A service in a long
+tick is not stopped (`open` answers `busy`), and a listener that does not
+prove itself this workspace's service is never touched.
+
+The first time Obsidian opens a view's vault it asks "Do you trust the author
+of this vault?", because every vault Atelier publishes carries Atelier's own
+plugin. "Trust author and enable plugins" turns it on: a status bar item then
+says whether the view is current, updating, held for an edit you made, stale,
+or whether the maintenance service does not answer, and "Atelier: show status"
+says why. "Browse vault in Restricted Mode" keeps every community plugin off
+in that vault, and nothing else changes: maintenance, `open` and `status` work
+without the plugin, as they always did. Obsidian keeps the answer per vault in
+its own storage and asks again the next time until the vault is trusted or
+restricted mode is switched on for good in its settings. Turning the plugin
+off in a vault, or uninstalling it there, is respected from then on;
+`atelier obsidian plugin on --scope ID` brings it back. What the plugin does
+and never does is in [obsidian-plugin.md](obsidian-plugin.md).
 
 `open` and `status` answer with a freshness state, not a promise. `current`
 means the vault is the present generation, verified by read-back, and the app
@@ -319,7 +360,9 @@ and the view is not republished over it. The remaining outcomes (`indexing`,
 `publisher-conflict`, `app-missing`, `app-version-unsupported`,
 `app-cli-unavailable`, `launch-failed`, `service-unavailable`, `busy`,
 `disabled`) each name what to do next, and exit code 3 says the answer is not
-success.
+success. Both also report Atelier's plugin for each view, under `plugin`:
+present while it holds the vault open in the app, with the app and plugin
+versions, or not present with the reason.
 
 Edits made in the vault are preserved before anything is republished. A body
 replacement is held as a pending edit; under manual mode it reaches its source
@@ -342,34 +385,120 @@ absolute directory. Private state inside an enrolled repository is refused.
 Publication is proven on macOS arm64 only and is refused on Windows; see
 [Known limits](#known-limits).
 
-### First publication while Obsidian is running
-
-The publisher writes into a vault only when it can coordinate with every
+### What `open` does in each state of Obsidian
+
+Obsidian opens a vault from a link only when the folder is in its own vault
+list, the `vaults` of `obsidian.json` in its user-data directory. `open` puts
+the view's vault there first, and never asks a person to open a folder by
+hand. It then names the vault by its id (`obsidian://open?vault=<id>`), never
+by path where the id reaches it first: a path is matched against the list by
+string prefix, so a link for a note under `/A/strategy-lab` can open the
+listed vault `/A/strategy`. When another vault's folder is named like the id,
+or the id is unusual, the vault's own path is used, which the app matches
+exactly because the folder is listed.
+
+- **Obsidian runs and answers its command line (any vault is open).** `open`
+  reads the app's vault list through its command line. A vault the app does
+  not list is added and opened in a new window through the app itself (it
+  writes its own settings), and read back from its list. `open`
+  then waits, bounded, until the app answers for exactly this vault, and asks
+  maintenance for the view again: the publication runs through the app, which
+  now holds the vault, with every editor check of the publication protocol.
+  Obsidian does not have to be quit.
+- **Obsidian is not running.** The view is published on the path with no app,
+  as before. `open` then adds the vault to the app's settings file (see
+  [Obsidian's vault list](obsidian-contract.md#obsidians-vault-list) for
+  exactly when and how that one file is written, marked to reopen) and starts
+  Obsidian plainly, with no link: an Obsidian started with a link opens only
+  that vault and drops the reopen flag of every other one, so your other
+  vaults would not come back the next time you start it. Started plainly, it
+  reopens every vault it had open, this one included, and once its command
+  line answers (the app itself, not the tool's "unable to find Obsidian")
+  `open` hands it the vault's link through that tool, never through the
+  operating system. On Linux a plain start is not
+  qualified yet, and Obsidian is started with the link (the other vaults'
+  reopen marks are lost there; a known limit).
+  An Obsidian that never ran on this account has no settings file yet, and
+  `open` does not create one: start Obsidian once, then open again.
+- **Obsidian runs with no vault open.** Its command line then answers every
+  command with "Vault not found.", so nothing can be asked of it, and its
+  settings file belongs to the running app, so it is only read. A vault the
+  app already lists is opened by path and published through the app as
+  above. A vault it does not list yet is answered as outcome
+  `app-version-unsupported` with reason `no-vault-open`: open any vault in
+  Obsidian, or quit it, and open again. This is the one state of a running
+  Obsidian that `open` cannot get through alone.
+- **Obsidian's command line is turned off** (the default of a new
+  installation). It then answers every command with "Command line interface
+  is not enabled", and only a link reaches it. With Obsidian running, `open`
+  adds and launches nothing. With Obsidian quit, `open` adds the vault to its
+  settings and starts it, and Obsidian opens the vault. Either way `open` then
+  answers `app-cli-unavailable` with reason `cli-turned-off` and says where to
+  turn it on: Settings > General > Advanced > Command line interface.
+  Publishing into a vault Obsidian holds needs it until Atelier's plugin takes
+  over that part.
+
+Only `open` adds a vault to Obsidian: the maintenance service never does, so
+it never opens a window nobody asked for. A declared view that was never
+opened is published while Obsidian is quit, and `open --scope ID` adds it.
+
+In no state does `open` add a view's vault inside a folder Obsidian already
+lists as a vault (your home folder, say): that vault would show the view's
+notes too, and a command-line call run in the view's folder would reach it.
+`open` answers `launch-failed` with reason `vault-inside-another-vault`:
+remove that vault from Obsidian's vault list, or keep Atelier's data root
+outside that folder. A view's vault that Obsidian lists already, below such a
+vault, is reached by its id instead (see "Which window answers" in
+[Known limits](#known-limits)).
+
+Obsidian can list one folder more than once, under another letter case or
+through a link, and then open it in one window per entry. Each of those
+windows holds the view's vault, and a publication coordinates with one window
+only, so none is made: the view reports `publisher-conflict` with reason
+`vault-open-in-several-windows`, and `open` answers the same, names the
+entries (`open in Obsidian as: …`; `duplicates` in JSON) and launches nothing.
+Remove the extra entries from Obsidian's vault list and open again. Closing
+the extra windows is not enough: Obsidian keeps the last window it closed
+marked open, so two entries can stay marked open with one window showing, and
+the view stays refused until the list names the folder once.
+While one entry of the folder has a window, `open` reaches only that one and
+never opens another entry of the same folder beside it.
+
+The publisher still writes into a vault only when it can coordinate with every
 Obsidian that may hold it, or when the process table shows, positively, that
 none runs. Otherwise it stops, and the view reports `publisher-conflict` with
 reason `editor-uncoordinated`. That reason has several causes, and the report
 does not say which: Obsidian runs without this vault open, or with it open but
 its command line did not answer; the process table could not be read, or on
 Linux shows an app that runs on a system Electron, which may be Obsidian; the
-app's version was not checked when the publication began (it started just
-then, or on macOS it is installed outside `/Applications`; see "Known
-limits"); or an app started while the view was being published with the app
-closed, which stops that publication partway. Before a first publication no
-app has the vault open, so only the first way on applies: quit Obsidian (on
-Linux, also any app that runs on a system Electron). The service then
-publishes the view directly, and
-`atelier obsidian open --scope ID --adapter=obsidian-cli` starts Obsidian on
-it. `status` and `open` give that as the next step. Once a view
-has been published, the last published vault stays in place and there is a
-second way on: open it in the running app as it is with
-`atelier obsidian open --allow-stale`, which waits, bounded, until the app
-answers for it. The publication is retried automatically either way.
-
-An Obsidian with no vault open at all answers its command line with "Vault not
-found." for every command, its version included. That is reported as outcome
-`app-version-unsupported` with reason `no-vault-open`, under `service.app` in
-`status` and by `open`. Opening any vault in Obsidian resolves it, because the
-version can then be read, and so does quitting Obsidian.
+app's version was not checked when the publication began; or an app started
+while the view was being published with the app closed. `status` gives
+`atelier obsidian open` as the next step (it adds the vault to Obsidian and
+publishes through it), or quitting Obsidian (on Linux, also any app that runs
+on a system Electron). When `open` itself already did that and the
+publication still stopped, it says to quit Obsidian and open again.
+
+The tick `open` asks for prepares and publishes its view once more, whatever
+state the view is in. A view whose last publication did not settle (refused,
+stale or still updating) is also tried again without waiting for a change: as
+soon as the app looks different (it quit or started, or opened or closed a
+vault in its list), and otherwise after a delay that starts at 30 seconds and
+doubles per attempt, up to the full reconciliation every five minutes. What
+the app looks like is read from the process table and the app's vault list
+alone: maintenance runs nothing in Obsidian to find out, and asks it for its
+version only when a view is about to be published, without blocking.
+
+While Atelier's plugin holds the view's vault open in the app and the command
+line gives no version (as it answers while a vault is still loading), the
+version the plugin reports stands in (reason `plugin-reported`); a version the
+command line gives always decides, and while the process table shows no app
+running, a plugin's report counts for nothing. `open` then asks the command
+line nothing: a vault the app's settings file lists is opened by path, and one
+it does not show is answered as `app-cli-unavailable` with reason
+`vault-open-cli-silent` (the app has the vault open; make sure its
+command-line interface is turned on). So is a listed vault the command line
+does not answer for once it is opened, while only the plugin reports the
+version: `open` says so at once instead of waiting for the app.
 
 ## Known limits
 
@@ -402,8 +531,10 @@ test reported as a pass.
   built on it does not coordinate with any app it then finds running, and
   asks it nothing. That publication stops as `publisher-conflict` with reason
   `editor-uncoordinated`, and the next publication asks again and reads the
-  version. A view that stopped is tried again on its next change, or at the
-  next full reconciliation, every five minutes.
+  version. A view that stopped is tried again on the next tick `open` asks
+  for, as soon as the app looks different, and otherwise after a delay that
+  starts at 30 seconds and doubles, up to the full reconciliation every five
+  minutes. A tick `open` asks for never reuses a remembered app answer.
 - Install location (macOS): the app is found only at
   `/Applications/Obsidian.app`, and its command-line tool only inside it. An
   Obsidian installed elsewhere, or a renamed bundle, is `app-missing`.
@@ -417,9 +548,46 @@ test reported as a pass.
   published through the app. `status` (under `service.app`) and `open` say what
   to do: open any vault in Obsidian, or quit Obsidian. With the app quit,
   maintenance publishes on its own path again; with a vault open, it reads
-  the version again on a later tick. `open` launches nothing while the app
-  runs with no vault open, and after its own launch it waits, bounded, while
-  the app is still opening the vault.
+  the version again on a later tick. While the app runs with no vault open,
+  `open` has it open a vault only when its list already knows that vault,
+  by path; one it does not know cannot be added then (see below). After its
+  own launch `open` waits, bounded, while the app is still opening the vault;
+  an app whose vault window is still loading answers a command with `Error:
+  Command "…" not found`, which is read as not up yet, never as a version.
+- Obsidian's settings file: `open` adds a view's vault to the app's own list,
+  `obsidian.json` in its user-data directory: `~/Library/Application
+  Support/obsidian` on macOS and `$XDG_CONFIG_HOME/obsidian` (else
+  `~/.config/obsidian`) on Linux. It is written only while the process table
+  shows, positively, that no Obsidian runs, only when Obsidian created it
+  before, and with a backup beside it; see
+  [Obsidian's vault list](obsidian-contract.md#obsidians-vault-list). A
+  Flatpak or snap build keeps its list inside its sandbox and never reads that
+  file. Which build is in use is read from which vault list was written last
+  (every build rewrites its own when a vault window opens or closes), and only
+  when no build wrote one from its installation; for a Flatpak or snap build
+  the file is then neither read nor written: `open` answers
+  `obsidian-sandboxed` and says to start Obsidian with any vault open, then
+  open again, and adds the vault through the app. On Windows no location is
+  known, and `open` adds the vault through the app in the same way.
+- Recent items: adding a vault through the running app is Obsidian's own
+  "open folder as vault", which also puts the vault's folder in the operating
+  system's recently used documents (Recent Items on macOS).
+- Which window answers: Obsidian answers a command-line call that names a
+  vault (`vault=<id>` first) in that vault's window; any other call in the
+  window of the first vault in its list whose folder is the tool's working
+  directory or contains it, and otherwise in the vault window that had focus
+  last. A vault that takes a call is opened when it is closed. Calls about a
+  vault therefore name its id; only when that id would name another vault
+  first (one whose folder has the id as its name) do they run inside its
+  folder instead, and not at all when a vault listed before it at a folder
+  above it (your home folder, say) would take them there. The vault root is
+  taken in the spelling the file system stores, so a data root given in
+  another letter case on macOS changes nothing. Publication calls do this
+  only while the app's list shows the view's vault open, and run in a
+  directory that is no vault otherwise. So maintenance never reopens a vault
+  window you closed while Obsidian keeps running, and never reaches another
+  vault: publication then stops as `publisher-conflict` until `atelier
+  obsidian open` opens the vault again or Obsidian quits.
 - Detecting the app: the process table is read with `ps -A -o comm=`
   (`pid=,comm=` on Linux), and the app is recognised by the executable a
   process runs, never by its arguments, so a path argument that contains an
@@ -469,6 +637,15 @@ test reported as a pass.
 - An edit the byte lens cannot turn into source bytes (a new or changed link
   to another note of the vault, an edited front matter) becomes a copy-only
   proposal. No operation applies one.
+- Atelier's plugin (phase 1) reports presence and status and decides
+  nothing: publication still coordinates with the app through its
+  command-line tool, which must be enabled, and the plugin only supplies the
+  app version where that tool gives none. A person who turns the plugin off
+  in a vault, or uninstalls it there, is followed: its entry is not added
+  back and a deleted folder is not made again until the person turns it on
+  in Obsidian's settings or runs
+  `atelier obsidian plugin on --scope ID`. Plugin files are never removed from
+  a vault. See [obsidian-plugin.md](obsidian-plugin.md).
 - Acceptance: a schema-valid receipt closes no gate, the package proof closes
   no gate, and no adopter acceptance is recorded in this repository.
 
@@ -482,3 +659,9 @@ The test suite proves each oracle can fail:
 - `createReceiptValidatorForOracleTests` accepts a rule table with one rule
   switched off; every negative case that depends on that rule then passes,
   and even that closes nothing.
+- `openScopeForOracleTests` with an `OPENING_PRIMITIVES.keptByApp` that
+  never holds: an open with Obsidian running without the vault reports the
+  publisher conflict it could have cleared, and the first-open oracle fails.
+- `createMaintenanceEngineForOracleTests` with an
+  `ENGINE_PRIMITIVES.isRetryDue` that never holds: a refused view waits for
+  the full reconciliation, and the retry oracle fails.

package/docs/release-engineering.md

@@ -63,7 +63,13 @@ Shipped, and required by the audit:
 - Every `contracts/atelier-obsidian-<name>.v<n>.schema.json` present in the
   source tree (lowercase name, versioned). Each must be packed and exported
   under its own path, and the audit fails if it finds none.
-- `docs/obsidian.md` and `docs/obsidian-contract.md`.
+- `docs/obsidian.md`, `docs/obsidian-contract.md` and `docs/obsidian-plugin.md`.
+- Atelier's own Obsidian plugin, which every managed vault receives:
+  `plugins/obsidian/manifest.json`, `main.js` and `styles.css`, the only files
+  admitted under `plugins/`, with its channel
+  (`src/projection/obsidian/plugin-bridge/index.mjs`) and the service's half
+  (`src/runtime/obsidian/plugin-channel.mjs`). `main.js` is scanned for egress
+  like every packed script.
 - `fixtures/obsidian/**`: small synthetic text only. Every packed fixture, in
   any subtree and spelling under `fixtures/`, is at most 262,144 bytes. The
   acceptance receipts under `fixtures/obsidian/acceptance/receipts/` are

package/docs/upgrade.md

@@ -9,6 +9,26 @@ workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.12
+
+This release makes the first open of an Obsidian view automatic and ships
+Atelier's own plugin. `open` adds the view's vault to Obsidian itself, whether
+Obsidian is running or not, and publishes without quitting it; a closed
+Obsidian is started so your other vaults reopen. Vaults are laid out
+readably: folders mirror your repository and file names are note titles,
+with identity kept in a properties block; a vault published by an earlier
+release is laid out again once, keeping held edits. Each managed vault gets
+the Atelier plugin (one trust prompt per vault) with a status bar. A
+maintenance service of an earlier release is replaced by `open` under the
+consent already recorded. No project or machine setting needs to change.
+Machine settings stay v1; generation manifests move to v2 (below).
+
+Node.js 24 (24.13.1 or later) is now supported alongside Node.js 22, and
+both write byte-identical graph files, so people on either can share a
+repository. `atelier dev` on a port that is already taken now says
+`port-in-use` and names `--port=<free port>`; before, it printed an internal
+error. A script that read that failure's exit code sees 2 instead of 1.
+
 ## Upgrading to 0.2.0-alpha.11
 
 This release tightens the Obsidian projection's app checks after independent
@@ -163,7 +183,7 @@ See `docs/contract-stability.md`.
 ## Before You Upgrade
 
 - Start from a clean Git status in the copied workspace.
-- Confirm Node.js matches the package range: `>=22.18.0 <23`.
+- Confirm Node.js matches the package range: `>=22.18.0 <23 || >=24.13.1 <25`.
 - Keep this package root and copied starter workspaces separate.
 - Keep upgrade diffs generic: placeholders only, no project-specific private
   material, transcripts, support bundles, local absolute paths, local agent
@@ -185,7 +205,7 @@ For registry installs, pin the exact version and record the resolved version
 in the lockfile:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.11
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.12
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -193,7 +213,7 @@ For Git installs, pin the release tag rather than a branch, so the lock file
 records exactly what was reviewed:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.11"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.12"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 

package/fixtures/obsidian/contracts/generation-manifest-v2/invalid/case-only-collision.v2.json

@@ -0,0 +1,160 @@
+{
+  "schema": "atelier-obsidian-generation-manifest/v2",
+  "layoutVersion": 2,
+  "generationId": "gen-0001",
+  "scopeId": "scope-topic",
+  "snapshotId": "snap-0001",
+  "notes": [
+    {
+      "repoId": "north",
+      "nodeId": "a",
+      "title": "Shared concept",
+      "path": "north/topics/Shared concept.md",
+      "noteDigest": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+      "regions": {
+        "frontmatter": {
+          "start": 0,
+          "end": 120
+        },
+        "identity": {
+          "start": 40,
+          "end": 116
+        },
+        "body": {
+          "start": 120,
+          "end": 280
+        },
+        "generated": [
+          {
+            "kind": "relations",
+            "range": {
+              "start": 280,
+              "end": 340
+            }
+          }
+        ]
+      }
+    },
+    {
+      "repoId": "north",
+      "nodeId": "d",
+      "title": "Shared concept",
+      "path": "north/topics/shared CONCEPT.md",
+      "noteDigest": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
+      "regions": {
+        "frontmatter": {
+          "start": 0,
+          "end": 40
+        },
+        "body": {
+          "start": 40,
+          "end": 200
+        },
+        "generated": [
+          {
+            "kind": "relations",
+            "range": {
+              "start": 200,
+              "end": 260
+            }
+          },
+          {
+            "kind": "identity",
+            "range": {
+              "start": 260,
+              "end": 340
+            }
+          }
+        ],
+        "identity": {
+          "start": 260,
+          "end": 340
+        }
+      }
+    },
+    {
+      "repoId": "north",
+      "nodeId": "e",
+      "title": "Diagram",
+      "path": "north/figures/diagram.svg.md",
+      "noteDigest": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
+      "regions": {
+        "frontmatter": {
+          "start": 0,
+          "end": 80
+        },
+        "identity": {
+          "start": 0,
+          "end": 80
+        },
+        "body": {
+          "start": 240,
+          "end": 240
+        },
+        "generated": [
+          {
+            "kind": "representation",
+            "range": {
+              "start": 80,
+              "end": 240
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "links": [
+    {
+      "edgeId": "e4",
+      "sourceNodeId": "d",
+      "targetNodeId": "a",
+      "type": "links_to",
+      "origin": "markdown",
+      "targetState": "in-scope",
+      "inversions": [
+        {
+          "source": {
+            "start": 12,
+            "end": 30
+          },
+          "note": {
+            "start": 52,
+            "end": 96
+          }
+        }
+      ]
+    },
+    {
+      "edgeId": "e5",
+      "sourceNodeId": "a",
+      "targetNodeId": "d",
+      "type": "supersedes",
+      "origin": "declared",
+      "targetState": "in-scope"
+    },
+    {
+      "edgeId": "e1",
+      "sourceNodeId": "a",
+      "targetNodeId": "b",
+      "type": "related",
+      "origin": "declared",
+      "targetState": "outside-selection"
+    }
+  ],
+  "attachments": [
+    {
+      "path": "north/figures/diagram.svg",
+      "digest": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
+      "byteLength": 900
+    }
+  ],
+  "completeness": {
+    "status": "complete",
+    "expectedNotes": 3,
+    "writtenNotes": 3
+  },
+  "freshness": {
+    "status": "current",
+    "checkedAt": "2026-01-05T10:00:05Z"
+  }
+}