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

package/docs/obsidian-contract.md

@@ -0,0 +1,698 @@
+# Obsidian projection contract
+
+This document freezes what later work receives from the contract and
+feasibility track. It states what is proven, on what, and what is not. Nothing
+here enables a feature. The publisher under
+`src/projection/obsidian/publication/` is called by the maintenance service
+(`atelier obsidian service start`) and so by `atelier obsidian open`; see
+[obsidian.md](obsidian.md).
+
+## Registered shapes
+
+Eleven closed v1 schemas, `contracts/atelier-obsidian-<shape>.v1.schema.json`,
+are registered in `src/contracts/corpus.mjs` with valid and invalid fixtures
+under `fixtures/obsidian/contracts/<shape>/`. `src/projection/obsidian/contracts.mjs`
+validates them and adds the refusals a schema cannot express.
+
+| Shape | Portable | Purpose |
+| --- | --- | --- |
+| `corpus-profile` | yes | Workspace and repository identities, enrollment, audience |
+| `scope` | yes | Mode and selector set-AST; an empty selection is valid and empty |
+| `source-snapshot` | yes | Raw byte digests, graph pin, dirty state, single consistent read |
+| `generation-manifest` | yes | Path map, byte regions, link inversion map, completeness |
+| `publication-journal` | no | Conditional operations, partial transition, restart; protocol ID required |
+| `service-state` | no | Literal loopback, port, runtime ID, PID, executable, consent |
+| `edit-operation` | yes | Object identity, origin generation, base digest, idempotency key |
+| `apply-policy` | no | `manual` or `automatic`; only `body-replacement` is an accepted edit class |
+| `proposal-receipt` | yes | Repository-scoped store, adapter operation identity, dedupe outcome |
+| `acceptance-receipt` | yes | Candidate identity, environment versions, evidence hashes, outcome |
+| `ext-settings` | yes | The object under `ext["mnstry.atelier.obsidian"]` |
+
+Portable shapes refuse absolute paths. `atelier-project-config.v1` is
+unchanged: extension settings are validated by their own schema, and an
+unknown extension key refuses in the adapter, not in the project validator.
+
+## Selection
+
+`selectScope({ canonicalSnapshot, profile, selector, expansion })` is the only
+runtime entry point. Visibility fails closed: a node is selectable only when it
+is explicitly eligible, its repository is enrolled and its audience is allowed.
+Edges to a withheld endpoint are dropped. Absent and withheld identities are
+reported together. Expansion requires an explicit depth and node budget,
+proceeds in canonical-identity order and reports truncation. Relation types are
+`related`, `supports`, `supersedes`, `implements`, `depends_on`, `evidences`,
+`contradicts`, `belongs_to` and the derived `links_to`. Literal oracles and
+refusals live in `fixtures/obsidian/contracts/oracles/scope-cases.json`.
+
+### What redaction covers
+
+Emission is byte-faithful: a visible author's bytes are emitted unchanged. A
+visible author's own references to withheld or out-of-selection documents
+(canonical identities in front matter, repository-relative paths, link text)
+therefore appear in the vault exactly as written. Only generated bytes are
+redacted: generated regions, note paths, manifest entries and link inversions
+never carry a withheld node's identity, title, summary, tags or path. A scoped
+vault is not a confidentiality boundary against what visible authors wrote. A
+redaction boundary over authored bytes cannot coexist with byte-faithful
+emission; it would be a separate mode with its own evidence.
+
+Each note may carry the generated line `Relationships leading outside this
+view: N`. N counts that note's relationships to notes that are visible but not
+selected, so it reveals that count, and two views of one workspace can be
+compared. It never counts a withheld node: edges to a withheld endpoint are
+dropped before the count is taken.
+
+## Note paths
+
+`notes/<readable title>--<identity suffix>.md`. The suffix derives from the
+stable repository identity plus node identity, starts at 12 hexadecimal
+characters and lengthens on collision. Titles are Unicode-normalized, platform
+reserved names are avoided, and case-folding collisions are detected. Duplicate
+titles are allowed; duplicate canonical identities refuse; a title-only link
+that matches more than one visible note refuses. Paths are allocated once per
+workspace and reused by every view.
+
+## Graph behaviour changes since the shared link resolver
+
+The resolver that produces `links_to` edges changed in these ways, each pinned by a
+test in `test/graph-knowledge-graph.test.mjs`. Repository artifacts committed by a
+consumer may differ after upgrading in exactly these classes and no others:
+
+1. Links inside fenced code (backtick or tilde, any info string, up to three
+   spaces of indent, CRLF, CommonMark fence-length rules), inside inline code
+   (including two stray backticks that happen to pair across a link) and inside
+   front matter no longer produce edges. Links after an unbalanced fence that
+   runs to the end of the file are inside code.
+2. A link to a directory resolves to that directory's `README.md`, then
+   `index.md`, testing eligibility per candidate; a link to a parent directory
+   now resolves where the earlier reader missed it.
+3. A link that climbs above its own repository root and re-enters through the
+   checkout's directory name is reported as leaving the enrolled roots, as it
+   always was; it is never turned into a repository-local edge.
+4. Malformed percent-encoding in a link is a `link-href-malformed` finding;
+   it no longer throws out of the graph build.
+5. The workspace graph (not repository artifacts) additionally carries
+   wikilink edges and cross-repository Markdown-link edges, de-duplicated.
+
+## Embedded assets
+
+An embed (`![](file)` or `![[file]]`) whose target is not a document of the
+census resolves in the canonical graph, never in the emitter. The resolver
+reports `embeds` beside `links`: one `embeds_asset` record per occurrence, with
+the same UTF-16 and byte offsets, naming an asset
+`{ id, repo, path, extension }` whose id is `<repository>:asset:<path>`.
+`buildCanonicalGraph` returns `embeds` and the de-duplicated `assets`. Neither
+is a node or an edge: committed graph artifacts and `markdownLinkEdges` are
+byte-identical with and without assets.
+
+An asset is a regular file inside an enrolled repository root. A link on disk,
+a file reached through one, a git-ignored path, anything inside `.git`, a
+Markdown file and a census node are never assets. Markdown embeds resolve by
+relative path like links. A wikilink embed whose target contains `/` resolves
+by repository-relative path, in the source's repository first and then as
+`<repository>/<path>`; a bare file name resolves by basename across enrolled
+repositories and refuses as `link-target-ambiguous` when more than one file
+matches. `isAssetEligible({ repo, path })` fails closed and is asked per
+candidate before choosing: a refused asset is reported exactly as an absent
+one (`link-target-unresolved`), so a finding never confirms that a withheld
+file exists.
+
+Behaviour change: an embed that resolves to an asset no longer produces a
+`link-target-unresolved` finding. No other finding changes.
+
+In a view, an asset is copied only when the embedding note is in the vault
+set, the asset record carries `eligible: true` (`withEligibility` takes a
+second predicate; without it every asset is withheld) and the profile enrols
+its repository under the same audience rule as a node without an audience of
+its own. It is copied once, byte for byte, to
+`attachments/<readable stem>--<identity suffix>.<ext>`, read through the pinned
+snapshot (`source-not-in-snapshot`, `mixed-read`). The embed target is
+rewritten through the link inversion machinery: a Markdown embed to the
+percent-encoded vault-root path, a wikilink embed to the plain path with its
+size or fragment left as authored and no alias added. The manifest lists the
+copy in `attachments[]` with
+`ext["mnstry.atelier.obsidian"] = { kind: "embedded-asset", repoId, assetPath }`
+and records the inversions on the embedding note at
+`notes[].ext["mnstry.atelier.obsidian"].assetEmbeds = [{ attachment, inversions }]`,
+in the shape of link inversions. A withheld or out-of-selection asset leaves
+the authored embed untouched and appears in no output, manifest entry or
+diagnostic.
+
+## Unclosed code fence at the end of a source
+
+An authored Markdown body that ends inside a fenced code block would turn any
+generated section after it into code. When, and only when, a generated section
+follows such a body, the emitter writes a closing fence as the first bytes of
+the first generated region. The fence is generated, not authored: it lies
+inside that region's range, so authored ranges and inversion stay exact. It
+repeats the opener's indentation (0 to 3 spaces), character and length, starts
+on its own line (a line break is added first when the body has none) and uses
+the source's line ending, CRLF or LF. The region records it as
+`ext["mnstry.atelier.obsidian"].fenceClosure = { fence, byteLength }`, where
+`fence` is the emitted fence line without its line ending and `byteLength`
+counts every closure byte, line breaks included. The view is not refused; its
+diagnostics carry `unclosed-code-fence-closed-in-generated-region`. With no
+generated section, nothing is emitted and nothing is reported.
+
+Fence detection is the canonical graph scanner's: `unclosedFenceAtEnd` in
+`src/graph/knowledge-graph.mjs` shares the rules that decide which text is
+scanned for links. Front matter is never read for fences.
+
+## Incremental preparation
+
+A maintenance tick rebuilds the canonical graph and prepares the whole view.
+Both stages accept a cache that makes repeated runs proportional to what
+changed, without changing a single emitted byte. Each cache is derived,
+in-memory, droppable state: it is never written anywhere, a dropped cache
+costs a full build or preparation, and the result is by construction the one
+a run with no cache produces. `test/obsidian-incremental.test.mjs` proves the
+equality over the materialization fixture under both scopes and over random
+change sequences (edits, retitles, relations, links, added and removed notes,
+eligibility and scope changes), and shows with mutation controls that the
+oracle sees a wrong cached byte, entry, inversion, node or scan.
+
+Graph stage: `buildKnowledgeGraph` / `buildCanonicalGraph` take `fileCache`
+(`createGraphFileCache`) and, optionally, `observedDigest`. A census node and
+link scan are reused only under an equal sha256 of the bytes and equal
+per-file inputs outside the bytes (coverage and the repository's read
+boundary), and the cache is rebuilt to hold exactly the current census.
+Without `observedDigest` every Markdown source is read and hashed on every
+build. The maintenance engine passes `observedDigest` from its observation
+index, and a source whose observed digest equals the cached one is then not
+opened: the bound is observation's own, a stat hint between full
+reconciliations, so bytes that change under an unchanged stat hint are not
+seen by the graph, the snapshot or the view until observation hashes the file
+again. The result reports `fileCensus: { reused, derived, read }`.
+
+Preparation stage: `prepareView` takes `cache` (`createPreparationCache`).
+Each note's bytes and manifest entry are a function of its pinned source
+digest, node record, allocated path, generated rows, outside-selection count
+and rewritten occurrences with their emitted targets; those inputs form a
+dependency key, and a note whose key equals the cached one reuses the cached
+bytes, manifest entry, attachment record and inversions. Everything else
+(asset copies, links, settings, collision checks, the manifest and the
+redaction guard over the whole result) runs as before. The result reports
+`preparation: { emitted, reused }`, and a preparation that emits exactly the
+notes whose output changed is what the tests pin.
+
+One bound is stated rather than hidden: a reused note's source is not read
+again, so bytes that drift under an unchanged pinned digest are not seen by
+`mixed-read` on that call. The emitted note is exactly the one the pin
+describes, and the next observation by digest sees the drift. A note whose pin
+changed is read and verified against the pin as always.
+
+The engine holds one graph file cache and one preparation cache per scope for
+its lifetime and hands them through the `createGraphCache` and
+`createPreparationCache` production seams; a test replaces either with
+`() => null` to build or prepare in full.
+
+## Publication protocol `obsidian-cli-critical-section/v1`
+
+The journal's `protocolId` names this protocol. A publisher may use it only
+within the proven boundary below.
+
+1. Stage the candidate on the vault's volume and bind it by SHA-256. A
+   candidate that replaces an existing file is staged in that file's unit
+   recovery directory (see "Where candidates are staged").
+2. Inside the app, in one synchronous step: refuse if any editor of the note in
+   any window is unsaved or differs from the expected base; refuse if the bytes
+   on disk differ from the expected base; refuse a staged file whose digest
+   differs; atomically exchange the staged candidate with the note, so
+   whatever occupied the path becomes the recovery file; update every open
+   editor in one transaction and record the view as saved with that content.
+   The app must not write the note as a result of publication.
+3. Reply immediately. Record the outcome in the app. A caller whose reply is
+   lost re-reads the outcome and never resends.
+4. Re-check the recovery file after a quiet period: a program that held the
+   note open before the exchange writes into it.
+5. Commit the trusted manifest last. Until then the transition is reported as
+   updating. A view converges to one verified generation; atomic visibility
+   across notes is not claimed.
+
+A refusal is always an acceptable outcome. A note being edited stays one
+generation behind until its editor is clean.
+
+### Where candidates are staged
+
+The exchange in step 2 leaves the displaced bytes at the candidate's path until
+they are moved to their recovery name. Those bytes may be a person's only copy,
+and `staging/` is classed discardable, so that path is never in `staging/`.
+This is a layout inside the private store; the protocol is unchanged.
+
+| Bytes | Path |
+| --- | --- |
+| Any candidate while it is written and fsynced (generated bytes only) | `staging/<journalId>/NNNNNN.candidate`, or `NNNNNN.late.candidate` for one that could not be known when the run began |
+| Candidate of a file that is created (exclusive link, no exchange) | stays at that staging path until it is linked |
+| Candidate of a file that is replaced (note, attachment, policy settings) | moved, complete, to `recovery/<journalId>/<unit>/exchange.candidate`, or `exchange.late.candidate` |
+| Displaced bytes | the vault path, then that same candidate path, then `recovery/<journalId>/<unit>/displaced.bin` |
+
+The journal names every exchange candidate, by path and SHA-256, before the
+file is at that path: in the header for candidates known when the run began, in
+a write-ahead entry for a late one. A file at a candidate path whose digest is
+the recorded one is a generated candidate and may be deleted; any other file
+there is displaced bytes and is moved to its recovery name with a receipt,
+never deleted. Restart recovery decides only this way. The candidate names end
+in `.candidate`; every other name in a unit directory ends in `.bin` or
+`.json`. The same-volume check covers staging and recovery, and the exchange
+self-test runs inside the recovery area, in `recovery/.exchange-probe/`.
+
+### One publisher per vault
+
+A publication holds two locks: the view's, in its private state, and the
+vault's. Two views, or two sets of workspace state, that point at one vault
+share nothing but the vault, so the vault lock lives under the vault's real
+path in `.atelier-publication/`, a dot-directory that no note path can name
+and that the app does not show. The second publisher refuses with
+`publication-in-progress` and writes nothing. It is the only thing the
+publisher writes in a vault besides notes, attachments and the policy
+settings file.
+
+Release and recovery follow the view lock exactly. A finished publication
+writes a release marker. A publisher that dies leaves a ticket naming its
+process; the next publisher on the same host sees that the process is gone and
+takes the lock over, so a crash does not wedge the vault. Superseded tickets
+are removed while the lock is held. Two cases refuse until a person acts: a
+ticket written on another host (a vault reached through a shared or
+synchronized folder), and an unrelated live process that reuses the dead
+publisher's process ID, which clears when that process exits. When no
+publisher is running anywhere, deleting `.atelier-publication/` is safe.
+
+### The path with no app
+
+When the process table shows, positively, that no Obsidian runs, the same
+critical section runs in the publisher's own process with no editor to
+coordinate with. The table is read at path selection, again immediately before
+the first note whatever time has passed, and again whenever two seconds have
+passed since the last reading. Once a reading is anything other than absent,
+every remaining note that would be written refuses.
+
+Residual window, stated plainly: an app that starts after a reading and before
+the next is not seen, for at most two seconds plus one note's publication. In
+that window a note is exchanged with no editor check. Bytes saved to disk are
+still protected by the on-disk comparison and the exchange. An unsaved buffer
+in the newly started app is not: the app then takes its own
+external-modification merge, which can drop overlapping edits. The probe also
+cannot see an app on another machine that reaches the vault through a shared
+or synchronized folder, or an app packaged under another executable name. It
+recognises the app by the executable a process runs (`ps -A -o comm=`, or
+`pid=,comm=` on Linux), never
+by its arguments; on Linux a system Electron process, which does not say which
+app it hosts, makes the reading unknown rather than absent, and a process whose
+name is not recognised is identified by the executable `/proc/<pid>/exe`
+resolves to. A `ps` that does not answer within five seconds is unknown.
+Before 0.2.0-alpha.10 no production reading was ever absent, because the probe
+found Atelier's own service; from that release this path, and this window, are
+live.
+
+### Proven boundary
+
+macOS (Darwin 25, arm64) with Obsidian 1.13.7 (installer 1.12.7), CLI enabled,
+no community plugin. Sixteen interleavings, 25 rounds for each racing case, in
+four complete clean runs of the prototype in `experiments/obsidian-publication/`
+at commits `34f5fab` and `c5142e7`. The receipts record those same trees under their
+pre-sign-off identities `5930f85` and `93303ff`; the branch was rewritten only to add
+sign-off trailers, with identical content. Receipt SHA-256 digests:
+
+- `379992a6cc0e6c95581459412e8cab68d9b260a631fa891089613f120b40a67a`
+- `63a5b69b203125b6099f2398d1ebddd0e4f3265a0401becbddff5e6d72fee16e`
+- `95995051859e02042d648d1a0b513d86fa9f1d72d82359030e21858cdba5d959`
+- `0984c35087ff91c0cc0d0f37f533eea1fc6c6380705491362eec98368f64fe01`
+
+A fifth run aborted because the harness could not open a note after the
+second-window case; no bytes were involved. The receipts are maintainer-held
+and are not part of this repository.
+
+### Receiving obligations for the production publisher
+
+The publisher may not claim the protocol outside the proven boundary until
+each open item is discharged with its own evidence.
+
+| Obligation | State |
+| --- | --- |
+| Atomic exchange without the system Python | Done. The system Python is gone. The exchange is a raw syscall (`renameatx_np` with `RENAME_SWAP` on macOS, `renameat2` with `RENAME_EXCHANGE` on Linux) reached through the system perl, with no perl module, compiler or package dependency. |
+| Interpreter trust | Done. The perl binary is used only when uid 0 owns it and neither group nor others can write it, in the publisher and in the script the app runs; otherwise `exchange-interpreter-untrusted`. An interpreter is still a dependency, and the exchange still costs a process start inside the critical section. |
+| Exit status of the exchange helper | Done. The critical section reads the staged path after the call and decides from the bytes whether the exchange took place; a helper killed after the call returned no longer reads as a failure. |
+| Linux | Partly open. The exchange primitive is proven in a container on aarch64. The app suite (the interleavings above) has not been run on Linux. |
+| x86_64 | Open. Never run, on macOS or Linux; the syscall numbers are present and untested. |
+| Windows | Refuses. No direct equivalent is known; the publisher refuses with `exchange-unsupported-platform` and publishes nothing. |
+| App capability floor | Partly open. The step that prevents an app write sets the view's undocumented `lastSavedData`; open notes refuse when it is absent. The floor is pinned: `MINIMUM_APP_VERSION` in `src/runtime/obsidian/app-capability.mjs` is 1.13.7, the only version the protocol was proven on, and an older, unreadable or unknown version is refused as `app-version-unsupported`. There is no ceiling: a newer app is admitted, and the cases must be re-run on each app release. |
+| Late-writer re-check | Partly open. The publisher re-checks displaced files twice per publication (on the blocking path, and after the quiet period). A holder can write later still, so the check must be repeated by the future maintenance service; carried to the maintenance track. |
+| Displaced bytes between exchange and recovery move | Done, by the maintenance track's staging layout change. The exchange still leaves the displaced bytes at the candidate's path until the next step moves them to their recovery name, and that path is now in the unit recovery directory: candidates for replaced files are staged there, and staging holds only generated bytes. A crash in between is settled by restart recovery from the journal, which names that path and the candidate's digest. A staging sweeper is still not provided; any future one may discard `staging/` only and must never touch `recovery/`. |
+| Transport | CLI replies are occasionally lost while the app stays responsive. Calls are serialized; every call is idempotent or outcome-recorded, and a publish is never resent. |
+| Timer throttling | A hidden app window delays the app's own autosave. Do not read that as a fault. |
+| Unreproduced anomaly | One early run ended with typed text on disk but absent from the editor buffer. It did not recur in any later run. Keep the typing-race case in every qualification run and treat a recurrence as a failed gate. |
+| Link scanner cost | Open, carried. The Markdown link scanner is roughly quadratic in skipped regions times link occurrences on pathological inputs; fine for ordinary documents, minutes for several megabytes of adversarial Markdown. |
+| Link-then-rename | Rejected. It leaves a window in which a concurrent replacement is destroyed. |
+| App-driven save after replacement | Rejected. Observed losing an outside writer's bytes; kept as a negative control. |
+
+Source application back into canonical files carries the same conditional-write
+obligation against other source writers; its protocol follows.
+
+## Source apply protocol `source-apply-exchange/v1`
+
+Source apply writes one edit made in a vault back to the one source file the
+note was generated from. It is the only operation of this integration that
+writes a source file. A person's explicit Apply (`atelier obsidian apply run
+EDIT [--actor ID]`, or the same call through the API by an agent acting for them)
+and an automatic policy reach the same function; they differ only in who
+authorises. It never stages, commits or otherwise asks git to change anything:
+its two git calls ask whether the path is ignored and where the git directory
+is.
+
+### Who authorises
+
+| Mode | Authority | Actor recorded |
+| --- | --- | --- |
+| `manual` | an explicit request that names the edit; the integration must be enabled | the request's actor, else `manual-request` |
+| `automatic` | the installed policy, read from private state at the decision and again immediately before the write: machine mode `automatic`, status `active`, the policy's recomputed digest equal to the digest it carries, the object inside the policy's `selector`, `body-replacement` in `allowedEditClasses`, retry budget not spent | the policy's actor, with the policy identifier and digest |
+
+In both modes the object must be visible in the canonical graph as it is now
+(eligible, enrolled, audience allowed). An absent object and a withheld one get
+the same answer, `object-not-visible`, and they get it first: before the
+manifest, the record of the object or the source path is looked at, with
+nothing recorded, so a moved or deleted source, an earlier apply or a missing
+manifest never tells the two apart. A source deleted from the corpus is
+therefore answered `object-not-visible` as well. There is no ambient agent mode: an automatic request with no
+matching active policy is refused.
+
+The digest of a policy is `sha256:` and the hex SHA-256 of its canonical form:
+the policy document without its `digest` member, keys sorted at every depth,
+two-space indentation, one final newline, UTF-8. `atelier obsidian policy
+digest FILE` prints it and writes nothing; `policy install FILE` recomputes it
+and refuses `policy-digest-mismatch`, naming the digest the file has to carry.
+The file is never rewritten for the person. `maxBatchSize` bounds an
+automatic dispatch (the engine's, and `applyBatch` in automatic mode); a batch
+a person names through `applyBatch` is bounded too, by 1000, the largest bound
+a policy can carry, and the rest of either batch refuses `batch-bound-reached`. `retryBudget` allows one attempt and
+that many retries per operation under one revision of the policy; it is counted
+over the refusals recorded in the events of the object, so a restart does not
+refill it, and a spent budget refuses before anything is recorded.
+`conflictDisposition` is `hold`: a conflict stays queued with its bytes, and
+nothing a policy says overrides a stale source.
+
+### Order of one apply
+
+1. Resolve the workspace and the pending edit. Build the canonical graph now
+   and ask whether this machine may see the object. Then resolve the view and
+   the immutable manifest of the generation the edit was observed under.
+2. The identity must still name the path the
+   manifest recorded, in an enrolled repository. That path must be a regular
+   file with one name, reached through no symbolic link, inside the repository,
+   outside every managed root and every git directory, and not git-ignored.
+   A git directory is any path with a segment spelled `.git` in any case (a
+   nested repository, a submodule), anything under `<root>/.git`, and anything
+   under the directory git itself names for the repository, which a `gitdir:`
+   file can place elsewhere; a git that cannot name it refuses
+   `source-ignore-state-unknown`. The only git calls ask whether the path is
+   ignored and where the git directory is.
+3. Read the source. Run the lens from the preserved edit bytes, never from the
+   note as it is now. Record the observation of this edit and of every other
+   open edit of the same object, so a divergent edit in another view makes the
+   object conflicted before anything is written.
+4. Take the object lease. An earlier apply whose outcome is unknown is settled
+   first, from digests on disk.
+5. Refuse, writing nothing: a repeated request (answered from the record), a
+   stale source, a conflicted object, a lens refusal, a change outside the
+   authored body, a result equal to the source, the policy, a volume that is
+   not the source's, a missing exchange.
+6. Write the apply record, then the candidate (the new source bytes, with the
+   source's mode, fsynced) in `recovery/<applyId>/000000/` of the private
+   workspace state.
+7. Record `apply-intent` in the object store.
+8. Read the policy again. Exchange the candidate with the source atomically.
+9. Read what the exchange displaced. Equal to the base: it stays as the
+   retained backup under its recovery name, with a receipt binding its digest;
+   the source is verified; `applied` is recorded with old and new digests, the
+   actor and the policy. Not equal: another program saved the source between
+   the read and the exchange. Its bytes are retained as an immutable object and
+   the files are exchanged back, so its bytes return to the source path; what
+   that displaces must be the candidate, and anything else is kept with a
+   receipt. `apply-refused`, `concurrent-source-writer`, with every reference.
+   Nothing is retried inside one call. An exchange that reports a failure is
+   not believed either way: only the candidate still at its path beside the
+   source as it was read means that nothing was exchanged
+   (`exchange-unavailable`); anything else is decided as restart recovery
+   decides it, so an exchange that did take place is recorded as applied
+   (`applied-after-restart`) with its backup.
+10. After a quiet period the backup is read again. A program that opened the
+    source before the exchange still holds the old file and can write into it
+    at any later time: `source-changed-after-apply`, both byte sets retained.
+    An applied source leaves a closed journal of this protocol beside the
+    publication journals of the view, so the maintenance engine's late-writer
+    re-check covers the backup on the tick of the apply and on later ticks,
+    for as long as it covers a publication.
+
+The candidate is never written inside a repository working tree, where a stray
+file could be committed by somebody. An exchange cannot cross a volume, so the
+private workspace state and the source must share one; otherwise the apply
+refuses `apply-volume-mismatch`. Where no atomic exchange exists (Windows
+today) it refuses `exchange-unavailable`. Both write nothing.
+
+### Refusals
+
+| Code | When |
+| --- | --- |
+| `integration-disabled`, `workspace-not-prepared`, `unknown-edit`, `foreign-workspace`, `unknown-scope`, `edit-not-open` | the request cannot be resolved |
+| `corpus-unreadable` | the canonical graph cannot be built on this machine: an enrolled file may not be read; no file is named |
+| `manifest-unavailable`, `published-note-unavailable` | the generation's manifest, or the note as it was published, cannot be established |
+| `repository-not-enrolled`, `source-not-in-graph`, `source-moved` | the identity of a visible object no longer names that path: a renamed or moved source (a deleted one is `object-not-visible`) |
+| `source-missing`, `source-symlink`, `source-not-regular-file`, `source-unreadable`, `source-hard-linked`, `source-outside-repository`, `source-inside-managed-root`, `source-inside-git-directory`, `source-git-ignored`, `source-ignore-state-unknown` | the path is not one this operation writes |
+| `invalid-apply-request`, `object-not-visible`, `edit-class-not-allowed`, `conflict-disposition-unsupported`, `maintenance-mode-manual`, `no-apply-policy-installed`, `apply-policy-revoked`, `apply-policy-paused`, `apply-policy-invalid`, `apply-policy-reference-mismatch`, `policy-digest-mismatch`, `policy-changed-since-dispatch`, `policy-selector-invalid`, `outside-policy-selection`, `retry-budget-exhausted`, `batch-bound-reached` | the decision |
+| `stale-source`, `object-conflicted`, `sibling-edit-unobservable`, `lease-held` | arbitration; the operation stays conflicted or pending with its bytes |
+| `edit-not-applicable`, `change-outside-authored-body`, `no-source-change` | the lens result is not an applicable body replacement |
+| `exchange-unavailable`, `apply-volume-mismatch` | this machine cannot write conditionally here |
+| `concurrent-source-writer`, `source-changed-during-apply` | another program wrote the source during the apply; every byte is retained |
+| `interrupted-before-exchange`, `apply-interrupted-needs-person` | what restart recovery decided for an interrupted apply |
+| `recovery-state-unreadable` | a candidate, backup or source path of an interrupted apply may not be looked at or read; nothing is settled from a read this process was denied, that record is reported with its intent still open, and every other one is still settled |
+| `apply-outcome-unknown` | the source was exchanged and the settlement from digests could not be carried out; the source may have been changed, the intent stays open and `apply recover` decides |
+
+A path that another program removes or replaces between two steps, before the
+intent is recorded, answers one of these refusals (`source-missing`,
+`source-not-regular-file`, `workspace-not-prepared`), never an exception; one
+that this process may not look at or read answers `corpus-unreadable` while the
+graph is built and `source-unreadable` from then on. The
+mode of the source is read from the descriptor its bytes were read from.
+
+### Restart recovery
+
+An `apply-intent` with no outcome is never guessed. `atelier obsidian apply
+recover`, and the next apply of the same object, decide from digests on disk.
+Only bytes with the recorded candidate digest are ours to delete. Every
+interrupted apply is settled on its own: an object whose record cannot be read
+is reported with its code, left exactly as it is, and delays no other. `apply
+list`, `show`, `run` and `recover` answer such a record as a typed refusal.
+
+| At the candidate path | Source | Decision |
+| --- | --- | --- |
+| the candidate | anything | nothing was exchanged, or it was exchanged back: the candidate is retired, `interrupted-before-exchange` |
+| the base | the candidate | applied: the base becomes the backup, `applied` is recorded |
+| anything else | anything | everything is kept with receipts, `apply-interrupted-needs-person` |
+| nothing, backup recorded as the base | the candidate | applied |
+| nothing, no backup | the base | `interrupted-before-exchange` |
+
+### Limits
+
+- The applied source is a new file: a hard link is refused up front, extended
+  attributes and ownership are those of the candidate, and only the permission
+  bits are carried over.
+- A hard link is refused when the path is checked. One that another program
+  creates on the source after that check and before the exchange keeps the old
+  bytes under its other name; the source path itself ends as the applied file,
+  and nothing detects the second name.
+- Every component of the source path is checked for a symbolic link, and the
+  file itself is opened without following one. A directory component that
+  another program replaces with a symbolic link after that check and before the
+  exchange is not detected; what contains it is the commit rule: unless the
+  file the exchange displaced holds exactly the bytes that were read, the files
+  are exchanged back and everything is retained.
+- When the exchange back reports a failure, or the displaced file cannot be
+  retained first, nothing is guessed and the report is not believed either way:
+  the apply is settled from the digests on disk by the restart table above.
+  If the exchange back did not take place, the source path keeps the candidate,
+  whole, the other program's bytes stay where recovery references name them,
+  and the answer is `apply-interrupted-needs-person`. If it did take place
+  before it reported the failure, the source path holds the other program's
+  bytes, the candidate is retired, and the answer is
+  `interrupted-before-exchange`. If the digests show that the first exchange
+  displaced the base after all, the apply happened and is answered as applied.
+- A refusal says that nothing was written. From the moment the first exchange
+  may have taken place (a clean exchange, or one that reported a failure while
+  the digests no longer show the untouched state), a failure is therefore never
+  returned as a plain refusal with the intent open: it is settled from the
+  digests on disk, and only when that settlement itself cannot be carried out
+  is the answer `apply-outcome-unknown`, which says that the source may have
+  been changed and that `apply recover` decides. Once the outcome is durable
+  that answer is no longer given.
+- A read that this process is denied (a permission or I/O error) proves
+  nothing about a file, unlike a path that is no longer a regular file. It is
+  never taken as evidence that the source changed or that another program
+  wrote: the apply is settled again from digests when the path can be read.
+  A typed failure of the late-writer check after a durable apply leaves the
+  answer applied; the engine repeats that check.
+- An enrolled file this process may not read while the canonical graph is built
+  refuses `corpus-unreadable`, naming no file. A source that cannot be read at
+  the moment of the apply refuses `source-unreadable`. Both carry the system's
+  error code as the cause. Only bytes with the recorded candidate digest are
+  ours to delete, so a file that cannot be read is never retired as a generated
+  candidate.
+- Where no atomic exchange exists the whole apply half of the test suite is
+  skipped: on such a platform the only executed evidence is that apply refuses
+  `exchange-unavailable` and writes nothing.
+- Lifting the hold after an apply relies on the publisher: it reads the note
+  again under its own lock and settles it as already current only while the
+  note still holds the prepared bytes. The engine's own read of the held note
+  narrows the window; the publisher's expected-bytes check closes it.
+- Between the exchange and the exchange back, readers of the source path see
+  the candidate for a moment. A third write in that moment is kept: the source
+  ends as one whole version and the other is in recovery with a receipt.
+- A program that holds the old file open and writes later has its bytes
+  retained and surfaced, not merged: deciding what the source should be is a
+  person's work.
+- Generated regions are never applied. The edited note must still end with the
+  exact generated bytes, or have lost them whole while the end of its authored
+  text is provably the published end: the last authored line and its line
+  endings byte for byte, followed by nothing but what is left of the separator
+  or fence closure. A region cut in the middle of a line from either side, a
+  fragment of one left in the body, and text typed at the very end of the body
+  together with a removed region all refuse `generated-region-edited`. Some of
+  those refusals a person could have been spared; a generated byte in a source
+  is never accepted in exchange.
+- After an apply the next tick prepares the view again. When the prepared note
+  is byte for byte the note the person edited (read from the vault at the
+  moment of that decision, never taken from the engine's observation index; a
+  note that cannot be read stays held), it is published over nothing,
+  the hold lifts and the pending record closes as `withdrawn`; the `applied`
+  record of the object store is the authority. When it is not (the person
+  removed a generated region, for example) the view stays held.
+- `--actor` is an option of `apply run`. The command has one option table for
+  every operation; every other operation, of `apply` or not, refuses it as a
+  usage error and does nothing.
+- Proven on macOS arm64 on APFS with a real second process. Linux, x86_64 and
+  other filesystems carry the open obligations of the exchange listed above.
+
+## Proposal adapter for structural edits
+
+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) is recorded as an edit
+operation of kind `semantic-proposal`, state `proposed`. It is never applied.
+The proposal adapter (`src/projection/obsidian/proposals/`) turns each such
+operation into exactly one copy-only proposal in the existing proposal store of
+the repository that owns the source, so that a reviewer of that repository sees
+one durable request. It writes no source file and no vault, it never accepts or
+applies a proposal, and no status of a proposal is an instruction to it.
+
+The adapter is a contribution (`src/runtime/obsidian/contributions/`). On a
+tick the engine first lets it observe the open pending edits (below), then,
+after the automatic dispatch, hands it a copy of the pending edits once.
+
+### Observation on a tick
+
+An operation exists once the edit has been observed: the source is read now,
+the lens runs over the PRESERVED edit bytes (never the live note) against it,
+and the resulting edit operation is recorded in the object store. Source apply
+does this before it takes its lease. The adapter does the same on every tick
+(`src/projection/obsidian/proposals/observation.mjs`), through the same
+observer and the same store, for every open pending edit the object store does
+not know yet, in manual and in automatic mode alike, so that a structural edit
+becomes `proposed`, and is routed in the same tick, without anybody running
+`atelier obsidian apply run EDIT`. What it records is what an apply would have
+recorded: a body replacement `pending`, which stays queued and is written only
+by apply; a structural edit `proposed`; a lens refusal `refused`; a base source
+that moved on `conflicted`. It writes no source file and no vault, and takes no
+lease.
+
+Ticks stay quiet. The object store answers the same for an origin it already
+holds and appends nothing, and an edit whose operation is recorded is not
+offered again: the record of the object is the authority, and an adapter that
+has just started finds it there. A refusal that comes before anything can be
+recorded (`object-not-visible`, `source-not-in-graph`, `source-moved`, the
+`source-*` codes of locating the file, `manifest-unavailable`,
+`published-note-unavailable`, `stale-source`) is remembered in memory with its
+code and offered again only at the full reconciliation cadence of the engine,
+never on every tick. At most 16 edits are observed per tick, in the order they
+were observed, starting where the last tick stopped. The tick reports
+`observed`: for each edit looked at, its identifiers, `observed` or `refused`,
+a code, and for a recorded one the kind and state of the operation.
+
+### Routing
+
+The routing key is the whole identity `(workspaceId, repoId, nodeId)`. The store
+is the one every other writer of proposals uses for a root:
+`<repository root>/.atelier-proposals`. Two repositories that hold the same
+relative path and the same local node id have different stores and different
+operation identities. A route that cannot be resolved refuses, writes nothing,
+and leaves the preserved bytes and the record of the object as they were:
+
+| Code | Meaning |
+| --- | --- |
+| `invalid-operation`, `foreign-workspace` | the identity is malformed or belongs to another workspace |
+| `repository-not-enrolled`, `repository-external`, `repository-root-unreadable` | the project does not enrol the repository on this machine |
+| `route-withheld` | this machine may not see the object now (the rule source apply asks); `route-visibility-unknown` waits instead |
+| `source-path-invalid`, `source-path-not-preservable` | the repository-relative path is unusable, or the store would trim or cut it (500 characters) |
+| `proposal-store-unsafe`, `proposal-store-inside-managed-root` | the store directory is a link or a file, or overlaps private state or a vault |
+| `proposal-store-not-ignored`, `proposal-store-ignore-unknown` | the store does not exist yet and git would report it; nothing is created that changes `git status` |
+
+### Operation identity and deduplication
+
+The adapter operation identity is `pa-` and the SHA-256 of the identity and the
+idempotency key of the edit operation, joined by a character no identifier can
+hold: 67 lower-case characters. It is carried in `payload.adapter.operationId`
+of the proposal, a member the store persists as JSON without normalising it.
+The identifier the store gives a proposal is seeded with the time and decides
+nothing here.
+
+Per operation, under a private lock per repository (the generation lock of the
+maintenance engine; taken over only with proof that its holder is gone, never
+because time passed):
+
+1. the operation is recorded in the adapter queue,
+   `<state>/state/proposals/<repo>/operations/<operation>--NNNNNN.json`:
+   immutable, owner-only, canonical files, each naming the digest of the one
+   before it;
+2. the ledger of the store is read and its room judged;
+3. the persisted store is searched for a proposal that carries the operation
+   identity, and one is created only when there is none;
+4. `submitted` is recorded, the proposal is read back, and `acknowledged` is
+   recorded with an `atelier-obsidian-proposal-receipt/v1` that binds the edit
+   to the proposal (`dedupe`: `new`, `recovered` after a lost acknowledgement,
+   `duplicate` when an acknowledged operation is offered again).
+
+A crash before the append leaves a queued record and no proposal; after it, a
+proposal that step 3 finds. An unchanged tick reads the queue and nothing else:
+no store is opened and nothing is written. An operation whose edit was withdrawn
+or superseded while it waited is refused `edit-withdrawn` or `edit-superseded`.
+
+### What a proposal holds
+
+Identifiers, the repository-relative source path, the lens code and reason,
+byte offsets into the edited note, digests and recovery references of the
+preserved bytes, and sentences made from those codes. It holds no text of any
+note: what a person typed can carry the title of another document, and a
+reviewer of one repository must not learn a title of another repository, or of
+a withheld document, from a proposal. The preserved bytes stay in private state.
+
+### Ledger limits and backpressure
+
+The limits are those of the existing ledger and are not widened: 256 KiB a
+line, 16 MiB, 10,000 events, and an unreadable line refuses every append.
+
+| Code | Outcome |
+| --- | --- |
+| `proposal-too-large` | refused before anything is appended; nothing is cut to fit |
+| `ledger-full` | fewer than 1 + 32 events or less than the line + 512 KiB of room (the reserve is the reviewers'); the operation waits as `backpressure` with its edit retained |
+| `ledger-corrupt` | refused, for that repository only; other repositories progress in the same tick |
+| `store-unavailable` | the store cannot be read or is locked now; waits like a full one |
+
+A waiting operation is tried at most 8 times, 60 seconds after the first attempt
+and twice as long after each, up to an hour. At most 8 operations per repository
+and 64 unexamined edits are looked at per tick. A repository holds at most 4096
+operations, 256 of them open, 64 records of 16 KiB each; a full queue refuses
+`queue-full` and records nothing. Nothing is compacted, rotated or deleted, in
+the ledger or in the queue. A refused or exhausted operation is final until the
+adapter's `requeue` is called for it, which is a person's decision after making
+room or fixing the route; it is an exported function, and no command binds it
+yet.
+
+`atelier obsidian proposals list` and `show OPERATION` are read-only: per
+repository the counts by state, the codes of the waiting and the refused, and
+the events and bytes the ledger has left; never note or source text.