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

package/contracts/atelier-obsidian-generation-manifest.v2.schema.json

@@ -0,0 +1,372 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mnstry.ai/schemas/atelier/atelier-obsidian-generation-manifest.v2.schema.json",
+  "title": "Obsidian generation manifest",
+  "$comment": "contract revision 2.0.0; portable shape; vault layout 2: readable paths mirroring each repository, the identity of every note in a generated region of its own, authored and generated byte regions, link inversion map, attachment hashes, completeness and freshness. Withheld endpoints never appear.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "layoutVersion",
+    "generationId",
+    "scopeId",
+    "snapshotId",
+    "notes",
+    "links",
+    "attachments",
+    "completeness",
+    "freshness"
+  ],
+  "properties": {
+    "schema": {
+      "const": "atelier-obsidian-generation-manifest/v2"
+    },
+    "layoutVersion": {
+      "const": 2
+    },
+    "generationId": {
+      "$ref": "#/$defs/identifier"
+    },
+    "scopeId": {
+      "$ref": "#/$defs/identifier"
+    },
+    "snapshotId": {
+      "$ref": "#/$defs/identifier"
+    },
+    "notes": {
+      "type": "array",
+      "maxItems": 1000000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "repoId",
+          "nodeId",
+          "path",
+          "title",
+          "noteDigest",
+          "regions"
+        ],
+        "properties": {
+          "repoId": {
+            "$ref": "#/$defs/identifier"
+          },
+          "nodeId": {
+            "$ref": "#/$defs/identifier"
+          },
+          "path": {
+            "$ref": "#/$defs/notePath"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          },
+          "noteDigest": {
+            "$ref": "#/$defs/digest"
+          },
+          "regions": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "identity",
+              "body",
+              "generated"
+            ],
+            "properties": {
+              "frontmatter": {
+                "$ref": "#/$defs/byteRange"
+              },
+              "identity": {
+                "$ref": "#/$defs/byteRange"
+              },
+              "body": {
+                "$ref": "#/$defs/byteRange"
+              },
+              "generated": {
+                "type": "array",
+                "maxItems": 64,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "kind",
+                    "range"
+                  ],
+                  "properties": {
+                    "kind": {
+                      "enum": [
+                        "relations",
+                        "outside-selection",
+                        "representation",
+                        "identity"
+                      ]
+                    },
+                    "range": {
+                      "$ref": "#/$defs/byteRange"
+                    },
+                    "ext": {
+                      "type": "object"
+                    }
+                  }
+                }
+              },
+              "ext": {
+                "type": "object"
+              }
+            }
+          },
+          "ext": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "links": {
+      "type": "array",
+      "maxItems": 5000000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "edgeId",
+          "sourceNodeId",
+          "targetNodeId",
+          "type",
+          "origin",
+          "targetState"
+        ],
+        "properties": {
+          "edgeId": {
+            "$ref": "#/$defs/identifier"
+          },
+          "sourceNodeId": {
+            "$ref": "#/$defs/identifier"
+          },
+          "targetNodeId": {
+            "$ref": "#/$defs/identifier"
+          },
+          "type": {
+            "$ref": "#/$defs/relationType"
+          },
+          "origin": {
+            "enum": [
+              "declared",
+              "markdown"
+            ]
+          },
+          "targetState": {
+            "enum": [
+              "in-scope",
+              "outside-selection"
+            ]
+          },
+          "inversions": {
+            "type": "array",
+            "maxItems": 4096,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "source",
+                "note"
+              ],
+              "properties": {
+                "source": {
+                  "$ref": "#/$defs/byteRange"
+                },
+                "note": {
+                  "$ref": "#/$defs/byteRange"
+                },
+                "ext": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "ext": {
+            "type": "object"
+          }
+        },
+        "if": {
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "const": "links_to"
+            }
+          }
+        },
+        "then": {
+          "properties": {
+            "origin": {
+              "const": "markdown"
+            }
+          }
+        },
+        "else": {
+          "properties": {
+            "origin": {
+              "const": "declared"
+            }
+          }
+        }
+      }
+    },
+    "attachments": {
+      "type": "array",
+      "maxItems": 1000000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "digest",
+          "byteLength"
+        ],
+        "properties": {
+          "path": {
+            "$ref": "#/$defs/vaultPath"
+          },
+          "digest": {
+            "$ref": "#/$defs/digest"
+          },
+          "byteLength": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "ext": {
+            "type": "object"
+          }
+        }
+      }
+    },
+    "completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "expectedNotes",
+        "writtenNotes"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "complete",
+            "partial"
+          ]
+        },
+        "expectedNotes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "writtenNotes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "ext": {
+          "type": "object"
+        }
+      }
+    },
+    "freshness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "checkedAt"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "current",
+            "stale",
+            "unknown"
+          ]
+        },
+        "checkedAt": {
+          "$ref": "#/$defs/timestamp"
+        },
+        "ext": {
+          "type": "object"
+        }
+      }
+    },
+    "ext": {
+      "type": "object"
+    },
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^2\\.[0-9]+\\.[0-9]+$"
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^(?![/~])(?![A-Za-z]:)(?!.*(?:^|/)\\.\\.(?:/|$))[^\\\\\\u0000]+$"
+    },
+    "byteRange": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "start",
+        "end"
+      ],
+      "properties": {
+        "start": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "end": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "ext": {
+          "type": "object"
+        }
+      }
+    },
+    "relationType": {
+      "enum": [
+        "related",
+        "supports",
+        "supersedes",
+        "implements",
+        "depends_on",
+        "evidences",
+        "contradicts",
+        "belongs_to",
+        "links_to"
+      ]
+    },
+    "vaultPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^(?:(?![ .])[^/\\\\\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029:*?\"<>|#^\\[\\]]+(?<![ .])/)+(?![ .])[^/\\\\\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029:*?\"<>|#^\\[\\]]+(?<![ .])$"
+    },
+    "notePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^(?:(?![ .])[^/\\\\\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029:*?\"<>|#^\\[\\]]+(?<![ .])/)+(?![ .])[^/\\\\\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029:*?\"<>|#^\\[\\]]+(?<![ .])\\.md$"
+    }
+  }
+}

package/contracts/compat-baseline.json

@@ -1,6 +1,6 @@
 {
   "schema": "atelier-compat-baseline@v1",
-  "baselineTag": "v0.2.0-alpha.0",
+  "baselineTag": "v0.2.0-alpha.11",
   "preEpochTags": [
     "v0.1.0-alpha.0",
     "v0.1.0-alpha.1",

package/docs/assurance-controls.md

@@ -15,13 +15,14 @@ commit and packed-tarball digest.
 | Resident Sync state cannot escape or grow without bound | Contained private directories, no-follow/identity-checked leaves, a 4,096-entry observation ceiling, bounded state projection, nonce-bound locks with aged abandoned-claim recovery, lock-directory identity validation and an ambiguous live-PID maximum age, consumed plans under age/file/byte ceilings, and corruption-recovering hash-chained traces with per-event/resident ceilings | `sync:test` observation/state ceilings, redirected-state/lock, plan lifecycle, concurrent enrollment/recovery, corruption, and trace ceilings | Machine-local state is diagnostic convenience; Git and readable repository files remain authoritative |
 | Local review serves only generated publication output | Loopback-only bind, required `atelier.manifest.json`, realpath containment, enrolled safe types, POSIX no-follow plus cross-platform leaf type/identity validation for local state, and host/fetch-site/origin/method/nonce checks | `server:security:test`; sidecar case in `assurance:mutation-smoke` | The sidecar is a local review tool, not user authentication or runtime authorization |
 | Collaboration cannot become a hidden apply path | Proposal authority is capability-derived; records are typed; POSIX ledger and snapshot leaves are no-follow, while every platform rejects redirected leaves and validates opened file identity when available; ledger reads are bounded, one-pass for lists, and corrupt tails fail closed | `collaboration:test` and ledger ceiling/performance tests | Collaboration remains copy-only proposal metadata; snapshots are rebuildable projections and Git review owns source changes |
-| The Obsidian maintenance service is reachable from this machine only, and only by its owner | Bind and client are restricted to the literal `127.0.0.1` or `::1`; `Host` must be the exact bound authority; cross-site `Origin` and `Sec-Fetch-Site` are refused; four fixed operations with exact paths and methods; status, tick and stop need a per-runtime random bearer kept only in the mode-0600 record; payloads are bounded and name their runtime; health carries no path or title | `test/obsidian-maintenance.test.mjs` listener, disclosure and unauthorised-request cases, each with a deliberately broken listener that must fail | A local process running as the same user can read the record; the bearer is ownership proof between local processes, not user authentication |
+| The Obsidian maintenance service is reachable from this machine only, and only by its owner | Bind and client are restricted to the literal `127.0.0.1` or `::1`; `Host` must be the exact bound authority; cross-site `Origin` and `Sec-Fetch-Site` are refused; four fixed operations and five fixed plugin commands with exact paths and methods; status, tick and stop need a per-runtime random bearer kept only in the mode-0600 record; payloads are bounded and name their runtime; health carries no path or title | `test/obsidian-maintenance.test.mjs` listener, disclosure and unauthorised-request cases, each with a deliberately broken listener that must fail | A local process running as the same user can read the record; the bearer is ownership proof between local processes, not user authentication |
+| Atelier's Obsidian plugin reaches only its own vault's maintenance service, writes nothing and can only report | The plugin calls a literal loopback address through Node's `http` only. Its random per-vault key is kept owner-only in private state and in a mode-0600 data file inside a vault root that must be private (`0700`; Atelier's own vault roots are made so, a linked or any other root never receives the key) and never crosses the wire: the service proves it holds the key over its own exact address before the plugin sends anything that names the vault, the plugin proves the same key, and every later request and answer is sealed with a per-session key and a counter that only goes up; a challenge is answered once and only while fresh, handshakes are used once, lapse, and are bounded per view. A session grants presence and read-only status of that one view, never status, tick or stop of the service; payloads are 1 KiB JSON objects of exact fields; the plugin's files are Atelier-owned settings whose digests are pinned in the generation manifest, whose previous bytes are displaced to recovery when replaced, and which never hold a view back on a path a person has to repair | `test/obsidian-plugin.test.mjs`: the shipped plugin run in a stand-in app whose writes throw, with every request, its exact body and every required module recorded; parity of constants and of every proof and MAC with the channel contract; a program squatting the service's address that learns no key, view or path and, replaying all it received, opens no session and sets no version; a relayed answer that does not verify; the refusal table with deliberately broken channels that must fail; publication, privacy and recovery cases; an egress-scan variant that must fail | A process running as the same user, including another plugin in the same app, can read the data file, hold sessions for that view and claim an app version for it; a claimed version never bypasses the app's own answer for the vault or the in-app capability check. The plugin's app version stands in only where the command-line tool gives none and the process table does not show the app stopped; if the tool then still coordinates while a second app without the plugin holds the vault, that version may be the other app's. The plugin is optional: restricted mode leaves the command-line path unchanged |
 | A maintenance service is stopped or reported as running only when it is proven to be this workspace's own | Record and health must agree on service name, workspace, runtime identifier, PID, executable digest and loopback address; anything else on the port is `occupied`; a reused PID is never signalled; a malformed or foreign record refuses; `start` stops only the child it created, by handle | Unowned and silent listener, wrong-identity, PID-reuse, stale-record, malformed-record, idempotent and concurrent start, and launcher-survival cases, with mutation controls | Status probes have a deadline: a service busy in a long synchronous tick can be reported `occupied` until it answers |
 | Maintenance never sweeps recovery or staging, and one workspace has one ticking engine | The service deletes only its generated record; the engine and the publisher own every other write; a hard kill is settled by the publisher's journaled restart recovery; each tick holds a private per-workspace lock taken from a holder only with proof of abandonment | Directory-listing oracles across start, ticks, stop, hard kill and stale record; hard kill between exchange and manifest commit; lock exclusion and takeover cases; each with a mutation control | A live lock holder that recorded no health address needs a person; a tick that outlasts the shutdown grace period ends with the process and is settled on the next start |
 | Source application policy is re-read before every automatic apply | The engine authorizes from disk immediately before each dispatch; manual mode never reaches the apply operation; the service keeps this on every tick; the apply operation reads the installed policy again at its decision and immediately before the write, recomputes its digest and evaluates its selector over the current canonical graph; `policy install` verifies that digest and names the expected one; whether this machine may see the object is asked before anything else, so an absent and a withheld object get one answer | Revocation, manual-mode and apply-unavailable cases in `test/obsidian-maintenance.test.mjs`; policy, refusal-table and late-revocation cases in `test/obsidian-edits.test.mjs`, each with a deliberately broken rule that must fail | A policy is private configuration of one machine; whoever can write that private state can install one |
 | Applying an edit to a source file cannot lose another program's bytes | One operation for a person and for a policy: exact identity, path and digest checks at commit; the write is an atomic exchange, never a check followed by a rename; displaced bytes that are not the base are exchanged back and retained; the old source stays as a backup that is looked at again for late writers; write-ahead record and intent before the exchange; restart recovery decides from digests only, and so does an exchange that reports a failure; generated regions never reach a source: the tail is intact, or removed with the end of the authored text proven, and anything else refuses; every git directory is refused, nested, respelled or relocated; the hold on an edited note lifts only on a read of the note at that moment; no git command that writes | `test/obsidian-edits.test.mjs`: end to end through the real engine, a refusal table with a whole-project byte and `git status` oracle, a real second process writing in three styles and four timings with both outcomes asserted, a crash at every durable step, a disclosure walk, a generated tail cut at every byte offset from both sides and a fuzz over the whole note; every oracle has a mutation control | macOS arm64 on APFS only; refuses where no atomic exchange exists; the source becomes a new file (permission bits kept, hard links refused); a late writer's bytes are retained and surfaced, never merged; a hard link made after the path check is not detected; a fragment of generated text shorter than eight bytes left inside an edited body cannot be told from typing |
 | A structural edit made in a vault becomes one copy-only proposal and never a source change | The proposal adapter routes by whole identity to the existing store of the enrolled repository or refuses typed and writes nothing; it records the operation in private immutable state first, looks in the persisted store for its operation identity before creating, under a private per-repository lock taken over only with proof; it preflights the ledger limits, defers `ledger-full`, refuses `proposal-too-large` and `ledger-corrupt`, bounds batches and retries, and never compacts; a proposal holds codes, offsets and digests and no note text; acceptance is shown and never acted on | `test/obsidian-proposals.test.mjs`: routing table with a whole-project byte and `git status` oracle, identity survival against the real store, a crash at every step, two real processes, generated ledgers at 256 KiB, 16 MiB and 10,000 events and an invalid line, a no-busy-loop count of store reads, a disclosure walk; engine cases in `test/obsidian-maintenance.test.mjs`; every oracle has a mutation control | In manual mode an operation exists only after apply has looked at the edit; a refused or exhausted operation waits for a person; the store directory lives in the repository and must be git-ignored; two workspaces that enrol one repository create one proposal each |
-| Opening a view reports `current` only for the exact, verified, present generation and a qualified app | `open` needs a tick of the proven service after the request, a persisted `current`, an independent read-back of the trusted pointer and every note, and an app at or above the minimum version that answers for that vault; every other outcome is typed, distinct and exits non-zero; the app and the operating system are reached only through injected seams, and the production ones only behind `--adapter=obsidian-cli` | `test/obsidian-open.test.mjs`: outcome table, read-back, app-floor, busy and read-only cases, each with a deliberately broken rule that must fail; a spawn guard and a production-seam import check | The production probe and launcher are not exercised against a real app here; `indexing` relies on an undocumented readiness field until acceptance qualifies it |
+| Opening a view reports `current` only for the exact, verified, present generation and a qualified app | `open` needs a tick of the proven service after the request, a persisted `current`, an independent read-back of the trusted pointer and every note, and an app at or above the minimum version that lists the vault and answers for it; the vault is added to the app's list through the app while it runs, and in its settings file only while the process table shows no Obsidian, atomically, with a backup, keeping every other key, and leaving nothing behind when a step fails; never inside a folder the app lists as a vault; a call about the vault is routed, from the app's list, to that vault only (its folder or its id) or not made; every other outcome is typed, distinct and exits non-zero; the app and the operating system are reached only through injected seams, and the production ones only behind `--adapter=obsidian-cli` | `test/obsidian-open.test.mjs`: outcome table, read-back, app-floor, busy, read-only, every app state, settings-file refusal and retry cases, each with a deliberately broken rule that must fail; a failure injected at every file-system call of the settings write; call routing against a model of the app's own routing; a spawn guard (a private HOME, on Linux a private XDG_RUNTIME_DIR, and no such child on Windows) and a production-seam import check; the opt-in `test/obsidian-first-open-real-app.test.mjs` against an isolated app | The operating system's URL opener is not exercised by any test (the real-app suite hands URLs to its isolated app directly); `indexing` relies on an undocumented readiness field; the real-app suite has run on macOS only |
 | Operating-system startup is never installed implicitly | `buildStartupAdapter` is pure text generation; Windows refuses typed; the service refuses `--startup` without a consent that covers startup | Builder purity oracle (no filesystem, process or home-directory access; no machine path beyond its inputs) and startup-consent refusal | Generated units have not been qualified against real launchd or systemd hosts |
 | Expected operator failures are actionable without leaking internals | Typed project/JSON diagnostics and the CLI execution wrapper | `test/cli-brand.test.mjs` | Unexpected stacks require the operator to opt in with `ATELIER_DEBUG=1` |
 | Published APIs do not disappear silently | Tag-derived subpath and named-export baseline plus version/tag identity refusal | `public-api:compat`; `test/public-api-compat.test.mjs` | Additive API checks do not decide whether a new version number is appropriate |

package/docs/install.md

@@ -34,19 +34,19 @@ The registry is the distribution channel of record, as `docs/continuity.md`
 commits:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.10
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.12
 ```
 
 Installing from the matching Git tag resolves to the same reviewed commit:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.10"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.12"
 ```
 
 Or over SSH:
 
 ```bash
-npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.10"
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.12"
 ```
 
 Keep the `@mnstry/` scope — see the command-form note above for why the

package/docs/local-services.md

@@ -145,8 +145,9 @@ explicit consent that names its actor.
 | --- | --- | --- | --- |
 | Health | `GET /health` | none | service name, workspace identity, runtime identifier, PID, loopback host and port, executable digest, start time, status |
 | Status | `GET /status` | bearer | the health fields, loop state, last tick, last error code, and per-view freshness with held notes counted, not named |
-| Tick now | `POST /tick` | bearer | the state of the tick that ran |
+| Tick now | `POST /tick` | bearer | the state of the tick that ran. The body may also name one view (`scopeId`, a contract identifier), which that tick prepares and publishes once more, asking the app again |
 | Stop | `POST /stop` | bearer | an acknowledgement naming the runtime and PID, then the service ends |
+| Plugin challenge, hello, lease, release, status | `POST /plugin/challenge`, `/plugin/hello`, `/plugin/lease`, `/plugin/release`, `/plugin/status` | a handshake over one vault's key, which never crosses the wire | Atelier's Obsidian plugin inside that vault: presence and read-only status of that one view ([obsidian-plugin.md](obsidian-plugin.md)) |
 
 Health carries no path, no note title, no source name and no withheld
 identity. There is no other operation: no file serving, no command, no
@@ -159,13 +160,29 @@ The listener refuses a request before looking its operation up when:
   also refuses a name that resolves to loopback;
 - `Sec-Fetch-Site` is present and is neither `none` nor `same-origin`, or
   `Origin` is present and is not the listener itself;
-- the path is not one of the four, exactly and without a query, or the method
+- the path is not one of the nine, exactly and without a query, or the method
   is not that path's method.
 
 Status, tick and stop additionally refuse without the bearer of the running
 runtime. A `POST` payload is a JSON object of at most 1 KiB that names the
 runtime identifier it is meant for, so a request aimed at an earlier runtime on
-the same port does nothing.
+the same port does nothing (409, `request-names-another-runtime`). A tick may
+also name one view by its `scopeId`, which must be a contract identifier as
+the scope contract defines it (400, `request-invalid`); any other member, and a
+`scopeId` on a stop, is refused (400, `request-member-unknown`). A refused
+request runs nothing.
+
+The plugin commands carry no credential in a header, and refuse one. The key
+of a vault the workspace maintains is random per view and kept owner-only in
+private state and in that vault's plugin data file; it never crosses the
+wire. The service answers a challenge only for a key it holds, with a proof
+over its own exact address, before the plugin sends anything that names the
+vault; the plugin then proves the same key, and every later command and answer
+is sealed with a key for that session, with a counter that only goes up. What
+a session grants is the plugin commands for that one view and nothing else:
+the runtime bearer is not accepted there, and a vault's key is not accepted by
+status, tick or stop. A plugin payload is a JSON object of at most 1 KiB with
+exactly the fields of its command.
 
 ### Status values and refusal cases
 
@@ -178,8 +195,9 @@ the same port does nothing.
 | `stale-record` | the recorded address is closed and the recorded PID is gone | starts; the new service replaces the record once it listens | refuses; nothing is proven to stop |
 | `pid-not-ours` | the recorded address is closed and a process has the recorded PID (the number was reused, or a process outlived its listener) | starts; that PID is never signalled | refuses; that PID is never signalled |
 
-`start` is serialized per workspace, spawns the service without a shell, and
-detaches it only when asked for a service that survives the launching command.
+`start` is serialized per workspace, spawns the service without a shell, in
+the root directory rather than the one the command runs in, and detaches it
+only when asked for a service that survives the launching command.
 It waits for health to echo the runtime identifier it generated and the PID of
 the child it created. If that proof never arrives it stops only that child, by
 its process handle, and reports the private operational log,
@@ -198,6 +216,39 @@ to end and removes only the generated record. It never looks a process up by
 port, name or pattern. Ending a proven runtime that ignores the request is
 opt-in and is proven again immediately before the signal.
 
+A runtime of an earlier release is replaced by a command that asks for a tick
+with the start options of the installed entry (`requestServiceTick({ service
+})`; `open` does). Every runtime records at its start the release it runs
+(`executable.ext.release` in its record): the package version and a digest of
+every runtime module it ships (`src/` and `contracts/`, by path and content),
+and of the plugin it publishes into every vault (`plugins/`; none where a
+package has no such folder).
+A runtime of an earlier release proves itself `healthy` but records an earlier
+version than this package's, this version with an entry module or modules of
+other content, or no release at all (releases up to the one that began
+recording it); or it refuses a tick that names a view, as releases up to
+0.2.0-alpha.11 do (their `POST` payload has exactly one member). Versions are
+ordered as semantic versions, a prerelease below its release
+(`0.2.0-alpha.11` < `0.2.0-alpha.12` < `0.2.0`; `releaseStanding` in
+`lifecycle.mjs`). It is stopped as `stop` stops it and the installed entry is
+started, detached, under the consent already recorded; the answer carries
+`restarted: "outdated"`, and `open` shows `service: restarted (outdated)`. A
+runtime that records a later version, or another version that cannot be
+ordered against the installed one, is never
+replaced by this release, nor asked for the tick: the answer is
+`service-other-release` (`open`: `service-unavailable`, with the next step
+`atelier obsidian service stop`, then open again). So two installations used
+on one workspace, a global and a project-local one for example, do not replace
+each other's runtime on every open; within one version, other content is
+replaced. The same version string is compared by content even when it cannot
+be ordered (a fork's `dev`, say), so the runtime `open` just started is always
+this release and "service stop, then open" cannot loop. A listener of now refuses a tick only when it names another runtime,
+which happens when a concurrent command replaced the runtime between the check
+and the request: the record is read again, the runtime that took its place is
+asked, and nothing is restarted. A `busy` runtime is not stopped, and anything
+that is not a proven runtime of this workspace is never stopped. Without the
+start options the runtime is only reported (`service-outdated`).
+
 The service itself refuses to start beside a runtime of the same workspace
 that proves itself, and ends cleanly when its record no longer names it. Two
 engines can never tick one workspace together: each tick holds a private
@@ -254,14 +305,14 @@ error, 3 the operation ran and its answer is not success.
 
 | Operation | What it does | Writes |
 | --- | --- | --- |
-| `status` | enablement, machine settings, proven service state, per-view freshness, whether an apply operation exists | nothing |
+| `status` | enablement, machine settings, proven service state, per-view freshness with its diagnostics (a code, the rule and the in-view note concerned, never a value; see [the Obsidian contract](obsidian-contract.md#notes-that-were-laid-out-anyway)), whether an apply operation exists | nothing |
 | `scope list`, `scope show ID` | the declared views | nothing |
 | `audience show`, `audience set A,B`, `audience clear` | the audiences this machine lets into a view; none by default, which publishes an empty view. A change invalidates every view at the next tick | private machine settings |
 | `mode show`, `mode set manual\|automatic` | `automatic` refuses without an installed, matching, active automatic policy | private machine settings |
 | `policy show`, `policy install FILE`, `policy revoke` | `install` validates against the apply-policy contract and stores the policy owner-only beside the machine settings, never in a project, a repository or a note. `revoke` marks the stored policy revoked, which the engine reads before its very next dispatch, and returns the mode to manual | private machine settings |
 | `service start`, `service status`, `service stop` | `startService`, `serviceStatus`, `stopService`. The first start needs `--consent-actor ID` | what the lifecycle writes |
 | `service unit --print` | the text `buildStartupAdapter` returns. Installing a unit is not offered | nothing |
-| `open [--scope ID]` | starts or reconnects the owned service, asks it for a tick, reads the view back, qualifies the installed app, has the vault opened | what the service writes |
+| `open [--scope ID]` | starts or reconnects the owned service, asks it for a tick, reads the view back, qualifies the installed app, makes the app know the vault (through the app while it runs; in its settings while none runs), has the vault opened, and asks again for a view the app kept from publication | what the service writes; the app's vault list (see [Obsidian's vault list](obsidian-contract.md#obsidians-vault-list)) |
 
 Reaching the installed app or the operating system is never a default.
 `open`, `service start` and `service unit` refuse with
@@ -276,16 +327,16 @@ step. Only `current` is success:
 
 | Outcome | Meaning |
 | --- | --- |
-| `current` | the proven service ticked after the request; the view's persisted freshness is `current`; read back independently, the trusted generation is the prepared one and every note has the bytes it was published with; the app meets the minimum version, was asked to open this vault, answers for exactly this vault and has finished reading it |
+| `current` | the proven service ticked after the request; the view's persisted freshness is `current`; read back independently, the trusted generation is the prepared one and every note has the bytes it was published with; the app meets the minimum version, knows this vault as one of its vaults, was asked to open it, answers for exactly this vault and has finished reading it |
 | `updating` | a publication is under way, a tick outlasted the wait, or a note differs from the trusted generation and has not been looked at yet |
 | `held-for-your-edit` | an edited note is preserved and held |
 | `stale-readable` | a last good vault exists and reads back, but is not proven to be the present generation |
 | `not-prepared` | no generation of this view has been published |
 | `publisher-conflict` | another publisher or an uncoordinated editor holds the vault |
-| `app-missing`, `app-cli-unavailable`, `app-version-unsupported` | no installation; no command-line capability; below the minimum version, or a version that cannot be read (reason `no-vault-open` when the app runs with no vault open and its command line answers nothing else) |
-| `launch-failed` | the operating system refused, or the app never answered for this vault |
+| `app-missing`, `app-cli-unavailable`, `app-version-unsupported` | no installation; no command-line capability, or the command line turned off in Obsidian (`cli-turned-off`); below the minimum version, or a version that cannot be read (reason `no-vault-open` when the app runs with no vault open and its command line answers nothing else) |
+| `launch-failed` | the vault could not be added to the app's list (a typed reason names why), the operating system refused, or the app never answered for this vault |
 | `indexing` | the app answers for this vault and has not finished reading it |
-| `service-unavailable` | the service could not be started or is not provably ours (`occupied`, no consent yet, a start that never proved ownership) |
+| `service-unavailable` | the service could not be started or is not provably ours (`occupied`, no consent yet, a start that never proved ownership), or it runs a later release than this command (`service-other-release`) |
 | `busy` | the service is ours and in a long tick |
 | `disabled` | the integration is off or not declared |