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

package/docs/obsidian-contract.md

@@ -10,16 +10,19 @@ here enables a feature. The publisher under
 ## Registered shapes
 
 Eleven closed v1 schemas, `contracts/atelier-obsidian-<shape>.v1.schema.json`,
+and one v2 schema, `contracts/atelier-obsidian-generation-manifest.v2.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.
+under `fixtures/obsidian/contracts/<shape>/` (the v2 manifest under
+`generation-manifest-v2/`). `src/projection/obsidian/contracts.mjs` validates
+them and adds the refusals a schema cannot express; a generation manifest is
+validated against the version its `schema` names.
 
 | 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 |
+| `generation-manifest` | yes | Path map, byte regions, link inversion map, completeness. v1 is vault layout 1; v2 is layout 2 (see "Vault layout") |
 | `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 |
@@ -46,15 +49,38 @@ 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.
+The guarantee: Atelier never generates a reference to a note outside the
+view. No link, embed or relation row the emitter writes targets one, no
+identity block names one, and no folder name or collision qualifier is
+derived from one; manifest entries and link inversions carry nothing about
+one either.
+
+Text that comes from an author is carried as authored. Emission is
+byte-faithful: a visible author's bytes are emitted unchanged, so a visible
+author's own references to withheld or out-of-selection documents (canonical
+identities in front matter, repository-relative paths, link text) appear in
+the vault exactly as written. Generated regions repeat author text as well:
+the titles of in-view notes in relation rows, and a wrapped file's title,
+summary and tags in its note. That text is carried as its authors wrote it
+too, escaped for Markdown or, in file names and link aliases, with the
+characters those cannot hold turned into spaces. A scoped vault is not a
+confidentiality boundary against what visible authors wrote (owner decision,
+2026-09-22). A redaction boundary over authored bytes cannot coexist with
+byte-faithful emission; it would be a separate mode with its own evidence.
+The deny-list below is defence in depth over the author text that generated
+regions repeat, not the guarantee, and it follows the audience: a note outside
+the selection that the view's audience may see is not withheld from the
+vault's readers, so text naming it is reported, not refused (see "The
+redaction guard").
+
+A layout 2 vault shows, in its folder names, the repository identity and the
+source directory chain of the notes in the view, and every note names its
+repository and source path in its `atelier-repo` and `atelier-source`
+properties; layout 1 showed neither. A folder exists only because a note of
+the view, a file the view copies for an embed, or a file held for an open edit
+is in it, though it may hold only some of that source directory's files. This
+surface is acceptable for every vault, scoped ones included (owner decision,
+2026-09-24).
 
 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
@@ -62,15 +88,416 @@ 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.
+A collision qualifier is the qualified note's own source file stem, or a
+short id of its own identity (see "Collisions"); a qualified folder carries a
+short id of its own source folder or repository. A qualifier appears only
+because something this vault shows took the name first: another note of the
+view, an asset the view copies, or a file held for an open edit, which stays
+in the vault while its edit is open, also after its note has left the view.
+The one exception is fixed and names no note: a repository whose folder would
+be `notes` or `attachments` spelled another way (see "Folders"). It stays while the
+qualified note is in the view, also after the other has left, because a path
+never moves while its note is in the view. A note of another view, a withheld
+note, or one that was never in this view never causes a qualifier by itself:
+each view allocates among its own notes and the files its vault holds.
+
+### The redaction guard
+
+Before anything is returned, `prepareView` checks the whole result, every
+note included, whether it was emitted on this call or reused from the
+preparation cache. Any failure refuses the view with `redaction-failure`,
+whose detail names the rule (`allow-list`, `identity-block` or `deny-list`)
+and, where there is one, the note or file of this view it concerns: a path
+allocated to this view (`notePath` or `filePath`), never the value that was
+found and never a path in question. A deny-list refusal names the note whose
+generated region holds the text, which for an incoming relation row is the
+note the row is in, not the note whose title it repeats. An allow-list
+refusal names the note by its allocated path, or the rule alone when the path
+in question is the only one at hand (an attachment that is not the view's, a
+manifest entry of no note of the view). The engine records the same in the
+view's freshness entry, and `atelier obsidian status` shows it. Three rules,
+in the vault layout the view is prepared in:
+
+1. Allow-list. Every path the emitter wrote must be a path allocated to this
+   view: every note and attachment path of the manifest, every rewritten link
+   or embed target (the bytes an inversion emitted must be such a path, as it
+   is or percent-encoded the way the emitter encodes it; the words an
+   author's wikilink keeps after `|` are the author's), every attachment an
+   embed names, and every `[[…]]` or `![[…]]` target in a generated region,
+   without its `#` fragment or `|` alias (relation rows, a wrapper's link and
+   embed of its file). The identity block of each note must name exactly that
+   note's own repository, identity and source path, and nothing else may
+   appear in it.
+2. Deny-list, defence in depth, following the audience. The free text of the
+   generated regions (the titles in relation rows, a wrapper's title, summary
+   and tags), the link targets excluded, is read as a reader sees it, with the
+   backslashes the emitter adds to escape Markdown removed, and compared in
+   NFC, against the identifiers of every census node and embedded asset
+   outside this view:
+   - Of a node or asset the view's audience may not see (withheld), an
+     unambiguous identifier refuses the view: an identity qualified by any
+     repository of the census (`<repository>:…`, whichever repository holds
+     the note), a repository-qualified source path (`<repository>/<path>`), a
+     repository-relative path that holds a folder (a `/`), or a vault path
+     recorded for it (see below). An identity that is a bare
+     word, and a file name at a repository's root (`README.md`, `index.md`),
+     are ambiguous and only reported: in-view text names such words and files
+     all the time.
+   - Of a node or asset the audience may see but this view does not hold (not
+     selected, or an asset the view does not copy), every identifier, a vault
+     path of it in another view included, is only reported: every view of a
+     workspace has one audience today, so such a note is not withheld from
+     anyone who reads this vault (decided 2026-09-24 under the owner decision
+     of 2026-09-22). So is a vault path of a note no longer in the census.
+     The rule follows the audience: a view with an audience of its own would
+     refuse for whatever that audience may not see, with no change to this
+     rule.
+   - A value that also identifies a note of this view names nothing outside it
+     and is neither.
+
+   What is reported is recorded as a diagnostic (see "Notes that were laid out
+   anyway"). A match is a whole token when no letter or digit is beside it,
+   and no one of `. _ : / -` joined to a letter or digit (a full stop that
+   ends a sentence is beside a whole token; `x.north-desk:a` is one longer
+   token); it is compared exactly, case included. The identity block, the one
+   place a note names its own repository-relative path, is held to rule 1.
+3. Coverage. Rules 1 and 2 run over every note of the view on every
+   preparation; a reused note is judged exactly as an emitted one.
+
+What an author wrote inside the authored body or front matter of an in-view
+note (a withheld node's canonical identity in a relation list, a link to its
+path) is authored bytes: it is emitted as written and never triggers the
+guard. When the same words reach generated prose unchanged, as an incoming
+relation row repeats an in-view title or a wrapper repeats its summary, rule 2
+refuses the view. Where they reach generated text only in a form made safe for
+a name, the outgoing relation row's alias and every file name, `:` and `/`
+have become spaces and runs of whitespace one space; that form is the
+author's text carried as authored, and rule 2 does not match it: there is no
+fuzzy matching (the residual of the 2026-09-22 decision above).
+
+A refusing deny-list is itself a signal. Someone who can edit the text of an
+in-view note and watch the view go stale learns that the words they wrote name
+something the audience may not see; the refusal never says which note or
+value. That existence oracle is open only to a person who can already edit
+in-view text, and is accepted with the rule.
+
+The vault paths the deny-list knows come from two places only: the sections of
+the persistent registry, which hold each view's last allocation, this view's
+included, and this view's prior generation. So after the registry is lost, a
+vault path another view holds is not denied until that view is prepared again
+and writes its section; within one tick, what a view denies of another view
+depends on the order the views are prepared in; and a view still held in
+layout 1 records its layout 2 allocation in its section, not the layout 1
+paths its vault holds, which other views therefore do not deny. The
+identities and source paths of the same notes are always denied.
+
+Identities are what the graph records. A sidecar's identity is checked for its
+form, but a Markdown note's `kg.id` may be any non-empty string, a bare word
+included; Atelier's own documents use repository-qualified identities
+(`<repository>:<name>`). An identity qualified by any repository of the census
+is unambiguous, whichever repository holds its note. A bare word could be any
+word of a title, and a root file name such as `README.md` any repository's, so
+both are reported, never refused. The matcher is one Aho–Corasick automaton
+over every value, with the token boundary tested at each hit: building it
+takes time and memory linear in the total length of the values, on every
+preparation (some tenths of a second and about 100 MB at 120,000 values), and
+it then reads a text once, however many values there are.
+
+In layout 1 the guard additionally refuses any `--<hex>` identity suffix of a
+census identity outside the view, anywhere in generated text or emitted paths,
+as the earlier release did. `test/obsidian-materialization.test.mjs` carries a
+mutation control per rule: with that rule removed, a view that breaks it is
+accepted.
+
+## Vault layout
+
+A prepared view lays its files out in layout 2: the file name is the title a
+person reads, the folders are the repository's own folders, and the identity a
+machine needs is written into the note, not into its name. Obsidian shows a
+file name as the note's title in the file explorer, tabs, the graph, search and
+link completion, so the file name is the human title. The generation manifest
+records the layout (`layoutVersion: 2`, in
+`atelier-obsidian-generation-manifest/v2`) and keeps the path of every note and
+attachment beside its identity, as before. Layout 1
+(`notes/<readable title>--<identity suffix>.md`, flat, with attachments under
+`attachments/`) is what releases up to 0.2.0-alpha.11 wrote; see "Upgrade from
+layout 1".
+
+### Folders
+
+A note lives at `<repository folder>/<source directory>/<file name>`.
+`<source directory>` is the directory of its source relative to its repository
+root, segment by segment, and `<repository folder>` is the repository's
+identity (`repoId`); each segment is made safe as a name (below). Nothing is
+stripped or shared across repositories: a vault of several repositories has
+one top-level folder per repository. No part of a path depends on a property
+of the whole census, such as a prefix every path shares, so adding or removing
+a file never moves another.
+
+Two folders whose names differ only in case or Unicode normalization are one
+folder on a case-insensitive file system (APFS, NTFS), with one spelling. The
+first allocation of a folder in a view fixes its spelling, and a later note
+whose folder differs from it only that way takes the existing spelling: every
+path of a vault spells each folder one way, so the app reports each note under
+exactly the path the manifest records, which is how the publisher finds the
+note's open editors. Two repositories of a view whose folder names would
+collide that way are told apart: the one allocated later gets ` (<id>)`, the
+first 6 hexadecimal characters of the SHA-256 of its identity. A source folder
+whose mirrored folder would take the name of a file already allocated (a
+source directory `docs/Guide.md/` after a note `docs/Guide.md`, or `a/Data/`
+after a wrapped file `a/data`) is qualified the same way, with the id of the
+source folder: `docs/Guide.md (1a2b3c)/`. So is a repository folder whose name
+a file held for an edit already spells another way in its folder (a layout 1
+file under `notes/` and a repository named `Notes`).
+
+The folders `notes` and `attachments`, where layout 1 kept every note and file,
+count as taken in every vault: an upgrade retires their files but leaves the
+folders, and on a case-insensitive file system a repository folder named
+`Notes` would otherwise be merged into `notes`, spelled as the disk has it and
+not as the manifest does. A repository whose folder differs from either only
+in case or normalization gets ` (<id>)`; a repository named exactly `notes` or
+`attachments` uses the folder as it is.
+
+### File names
+
+The name of a note is:
+
+- for a Markdown source, its canonical title, the one the graph read: the
+  front-matter `title`, else the first H1, with the author's casing and
+  spacing. A title that ends in the source's own extension
+  (`07-tide-survey-brief.md`) loses that extension. When the graph's title
+  is exactly the title-cased file name, the graph's fallback, the title came
+  from the file name or equals it, and the file stem is used as written
+  (`getting-started`, not `Getting Started`). The rule reads the node record
+  only, so every allocation, and a selection resolved without the sources,
+  gives the same name. The record does not say where its title came from, so
+  an author heading that is exactly the title-cased file name (`# Getting
+  Started` in `getting-started.md`) names the note by its stem as well.
+- for any other source, a wrapped file, the file name itself: the note is
+  `<file name>.md` (`depth-chart.pdf.md`) and the file keeps its own name
+  (`depth-chart.pdf`) in the same folder. The pairing is visible, a search
+  for the file finds both, and the file's own title (from its sidecar or
+  `<title>`) is the first heading of the note.
+
+Every name and folder segment is made safe for macOS, Linux, Windows and
+Obsidian links:
+
+1. It is NFC-normalized.
+2. Control characters (C0, C1, U+2028 and U+2029) and
+   `/ \ : * ? " < > | # ^ [ ]` become a space; bidirectional embedding,
+   override and isolate controls and U+FEFF are removed.
+3. Runs of spaces become one space, and leading and trailing spaces and dots
+   are removed: a leading dot hides a file from the app, and Windows allows no
+   trailing dot or space.
+4. It is cut to 150 bytes of UTF-8 (a folder segment to 120, a wrapped file's
+   stem so that its extension still fits), on a character boundary; a
+   combining character, zero-width joiner or variation selector left at the end by
+   the cut is removed.
+5. A Windows device name (`CON`, `PRN`, `AUX`, `NUL`, `COM0` to `COM9`,
+   `LPT0` to `LPT9`, `COM¹` to `COM³`, `LPT¹` to `LPT³`, `CONIN$`, `CONOUT$`),
+   compared case-insensitively on the part before the first dot, gets a `_`
+   in front.
+6. A name left empty is the file stem, made safe the same way, else
+   `Untitled`; a folder segment left empty is `_`.
+
+A path longer than the file system allows (255 bytes a name, and
+`maxFullPathBytes`, 1024 by default, with the view's own vault root) is
+shortened by cutting the title part further, never below 16 bytes. A folder is
+kept only where a name of 16 bytes and its extensions still fits in it,
+whatever the title of the note at hand, so a folder's spelling depends on its
+source directory alone. A folder chain that leaves less room than that keeps
+as many leading folders as fit, and the last folder kept, cut, carries
+` (<id>)`, the first 6 hexadecimal characters of the SHA-256 of the
+repository and the whole source directory: two deep directories under one
+readable prefix stay two folders. When not even `<repository folder>/(<id>)`
+leaves that room, the note sits directly in its repository's folder. Only a
+note whose name does not fit even there, qualified if it collides, refuses
+the view, with `path-too-long`: its repository's folder under the view's vault
+root leaves no room for it.
+
+### Collisions
+
+Names are compared the way a case-insensitive, normalization-insensitive file
+system compares them (`collisionKey`: NFKC, case-folded), across every file of
+the vault: notes, wrapped files and embedded assets. When two would share a
+name in one folder, the one allocated later is qualified:
+
+1. `<name> (<source file stem>).md`, the stem made safe and cut to 60 bytes;
+2. when that is taken too, `<name> (<stem>) (<id>).md`, where `<id>` is the
+   first 6 hexadecimal characters of the SHA-256 of the repository identity
+   and the node identity, lengthened two at a time, up to 16, until it is
+   free.
+
+A wrapped file's name is already its file name, so it is qualified by the
+identity alone, before its extension: `depth-chart (1a2b3c).pdf` and
+`depth-chart (1a2b3c).pdf.md`. An embedded asset is qualified the same way.
+A name that collides with nothing carries no qualifier and no hash.
+
+Each view allocates among its own notes only, in canonical identity order
+(repository, then node), then its embedded assets, and an allocation that its
+prior generation published is never changed while the note is in the view: a
+newcomer that collides takes the qualifier. The same notes and prior
+generation give the same paths in whatever order the census lists them.
+
+### Stability
+
+A view's paths are seeded from what its prior generation published: a path,
+once published, stays while its note is in the view. A retitled source keeps
+its path: the note shows the new title in its heading and every relation row
+that names it shows it too. Renaming on retitle arrives with the in-vault
+plugin, which can use Obsidian's own rename so that the app's bookmarks, open
+tabs, graph layout and links follow; a rename made by a program outside the
+app would break all of them.
+
+A note that leaves the view (deleted, withheld, no longer selected, or renamed
+into a new identity, since a source without an identity of its own is
+identified by its path) releases its path there, unless its file is held for
+an edit: then the file stays in the vault and its name stays taken. A renamed
+source therefore takes its name back instead of keeping a qualifier its old
+name forced. A note that comes back is allocated again like a newcomer: it
+gets its earlier path only when its title is unchanged and the names around it
+are as they were, nothing having taken its name meanwhile and no note it
+collided with having left. A published path that no longer fits the view's
+vault root (a root that grew) is allocated again as well. One identity may
+have different paths in different views: each view allocates among its own
+notes, with its own vault root.
+
+The persistent path registry keeps each view's last allocation in a section of
+its own (`views.<scopeId>`); a selection resolved without the view's
+generation reads it. The engine passes the views it maintains
+(`viewScopeIds`), and the registry drops the section of any other view.
+Preparation seeds from the prior generation itself, so a lost registry costs
+no view its paths and is written again on the next preparation.
+
+### Notes that were laid out anyway
+
+What is worth a person's look, but no reason to refuse a view, is recorded as a
+diagnostic that names the note and never a value: in the generation manifest
+(`ext["mnstry.atelier.obsidian"].diagnostics`, layout 2), in the view's
+freshness entry (the first 100), and in `atelier obsidian status`. The manifest
+holds those of the preparation that first committed its generation: a
+preparation that yields the same generation (the same files) does not commit
+it again. The freshness entry, and so `status`, holds those of the latest
+preparation. Each is
+`{ code, rule?, repoId, nodeId, notePath }` (an embedded asset has `assetPath`
+and `filePath` instead of `nodeId` and `notePath`):
+
+- `folder-shortened`: the folder chain was cut to fit (see "File names");
+- `folder-qualified`: a folder met a file of the same name (see "Folders");
+- `author-identity-properties`: the author's own front matter holds one of the
+  identity keys, which Properties shows instead of the generated block (see
+  "Identity in the note");
+- `bare-identity-in-generated-text` (rule `deny-list`): generated text of the
+  note holds, as a whole token, the bare-word identity or the root file name
+  (`README.md`) of a note the audience may not see (see "The redaction
+  guard");
+- `unselected-identity-in-generated-text` (rule `deny-list`): generated text of
+  the note holds an identifier of a note or asset the audience may see but the
+  view does not hold.
+
+A view refused by the redaction guard records `{ code: "redaction-failure",
+rule, notePath | filePath }` in its freshness entry the same way.
+
+### Identity in the note
+
+Every note names its identity in three generated properties that Obsidian
+shows (Properties, Bases, search) and any YAML reader or agent can read
+without the manifest:
+
+```yaml
+atelier-id: "north-desk:harbor-plan"
+atelier-repo: "north-desk"
+atelier-source: "plans/harbor-plan.md"
+```
+
+`atelier-id` is the canonical node identity, `atelier-repo` the repository
+identity and `atelier-source` the repository-relative source path, each a
+JSON string. They are the last lines of the note's front matter, directly
+before its closing delimiter, when the source's front matter is a plain block
+mapping at column 0 that does not already use one of the three keys. A source
+without front matter gets a generated front matter holding only them (after a
+byte order prefix, which the app does not read). Any other front matter (a flow
+mapping, an indented or sequence root, a document marker, a line that is not a
+key) could change meaning with a line added, and one that already uses one of
+the three keys would hold it twice, so for those sources the lines go into a
+generated `%%` comment block at the very end of the note instead, the last
+generated region. Keys are not otherwise compared: a front matter that repeats
+a key of its own still takes the lines. The line ending is the source's. When
+the author's own front matter holds one of the three keys, it is what
+Properties shows, not the generated block; the note is reported as
+`author-identity-properties` (see "Notes that were laid out anyway").
+
+The source digest is not written into the note. Once a person's edit is
+applied, the source has a new digest, and the hold on the edited note lifts
+only when the note prepared from the new source is byte for byte the note the
+person edited; a digest in the note would keep it held forever. The digest of
+every generation is in the manifest
+(`notes[].ext["mnstry.atelier.obsidian"].source.rawDigest`).
+
+The block is generated. The manifest records its bytes as `regions.identity`,
+inverting a note removes them, and the edit lens never attributes them to the
+author. An edit to them is a front-matter edit, which is never applied to a
+source: it becomes a semantic proposal (see "Proposal adapter for structural
+edits"). In the end-of-note placement it is a generated-region edit and
+refuses.
+
+### Links
+
+A rewritten link or embed, a relation row and a wrapper's link to its file
+name the target by its full vault path:
+`[[north-desk/plans/Harbor plan.md|the plan]]`,
+`[tide table](south-desk/tables/Tide%20table.md#spring)`,
+`![[east-desk/pages/img/gauge.png|200]]`. A wikilink carries `.md`, so a note
+named after a file never resolves to the file. Obsidian's resolver
+(`MetadataCache.getLinkpathDest`, read in the 1.13.7 application bundle) looks
+a path that contains a folder up as an exact vault path before it tries any
+suffix or file-name match, so the target is exactly the allocated file,
+whatever folder the linking note is in. A wikilink rewrite keeps the words the
+author chose by appending `|<what the author wrote>`, as before.
+
+### Upgrade from layout 1
+
+A view whose prior generation is in layout 1 is laid out again once, in one
+generation:
+
+1. `prepareView` allocates layout 2 paths for every note and asset. The
+   layout 1 entries of the persistent registry are dropped, and the registry
+   records `layout: 2`. The generation is an
+   `atelier-obsidian-generation-manifest/v2`, and `changes.removed` names
+   every layout 1 path.
+2. The publisher retires each layout 1 path with its ordinary remove unit. A
+   note or file that still holds its published bytes is moved to the recovery
+   area with a receipt; a note somebody edited is never removed: it stays
+   where it is and is surfaced as a retained edit. Nothing is deleted.
+3. While a note of the view has an open edit, the view is not laid out again.
+   The engine passes as `heldNotePaths` the files of open edits, which stay in
+   the vault and keep their names taken in layout 2, and as
+   `layoutHeldNotePaths` those and the files whose edit closed on this tick.
+   `prepareView` prepares a view whose prior generation is in layout 1 and
+   holds one of the latter in layout 1, exactly as the earlier release did,
+   a new note included
+   (`notes/<title>--<suffix>.md`). A held note therefore stays under its
+   layout 1 path and is held, applied and withdrawn by the rules it was held
+   under. The engine lays a settled layout 1 view out again at the first tick
+   where no note holds it.
+4. An edit made on a layout 1 note can be applied after the upgrade: apply
+   and the proposal adapter prepare the generation the edit was made on in
+   that generation's own layout (`layout`) to recover the note as it was
+   published.
+
+The folders `notes/` and `attachments/` are left behind empty: the publisher
+moves files, never folders, and a person may delete them. While a view waits
+for a held note, a selection resolved from the registry names layout 2 paths
+that the vault does not hold yet.
+
+An edit that closes on a tick still holds the layout on that tick. In
+automatic mode a policy applies an edit on the very tick the edit is observed:
+the view is prepared in layout 1 once more, from the new source, so the note
+the person edited becomes the published note, and the next tick lays the view
+out again and retires that file to recovery like any other. It is never left
+in the vault unobserved. In manual mode the hold lifts when the observed note
+equals the published one, one tick in layout 1 follows the same way, and the
+view is then laid out again.
 
 ## Graph behaviour changes since the shared link resolver
 
@@ -124,9 +551,11 @@ 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
+its own. It is copied once, byte for byte, to its own path mirrored in the
+vault (`<repository folder>/<source directory>/<file name>`, allocated like a
+note; see "Vault layout"; in layout 1,
+`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
@@ -185,13 +614,18 @@ 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
+Each note's bytes and manifest entry are a function of the vault layout and
+emitter version, its pinned source digest, node record (repository, identity
+and source path, which also make its identity block), allocated path (which
+also names a wrapped file), generated rows (which carry the paths and titles
+of their targets), 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. Where the identity block goes and with which line
+ending is decided from the source bytes, which the pinned digest covers.
+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.
 
@@ -243,7 +677,7 @@ This is a layout inside the private store; the protocol is unchanged.
 | --- | --- |
 | 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` |
+| Candidate of a file that is replaced (note, attachment, policy settings, Atelier's plugin files) | 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
@@ -264,8 +698,10 @@ 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.
+publisher writes in a vault besides notes, attachments, the two policy
+settings files (`core-plugins.json`, `community-plugins.json`) and Atelier's
+own plugin files under `.obsidian/plugins/atelier-projection/` (see
+[obsidian-plugin.md](obsidian-plugin.md)).
 
 Release and recovery follow the view lock exactly. A finished publication
 writes a release marker. A publisher that dies leaves a ticket naming its
@@ -322,6 +758,13 @@ 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.
 
+Every vault Atelier publishes now carries Atelier's own plugin
+([obsidian-plugin.md](obsidian-plugin.md)), so a trusted vault runs one
+community plugin. In phase 1 it registers no editor extension, no vault event
+handler and nothing that writes; it only talks to the maintenance service over
+loopback. The protocol cases above have not been re-run with it loaded; that
+run is gate G20, before the plugin carries any part of publication.
+
 ### Receiving obligations for the production publisher
 
 The publisher may not claim the protocol outside the proven boundary until
@@ -345,6 +788,193 @@ each open item is discharged with its own evidence.
 | 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. |
 
+## Obsidian's vault list
+
+Obsidian opens a vault from a link only when the folder is in its own vault
+list. `atelier obsidian open` puts the view's vault there.
+Outside its own storage (the data root, which holds the vaults and their
+policy-owned `.obsidian/core-plugins.json`), the list is the only file of
+another application that Atelier writes; to write it, Atelier writes nothing
+else outside the app's user-data directory, and no vault note.
+
+**The file.** `obsidian.json` in the app's user-data directory:
+`$HOME/Library/Application Support/obsidian/` on macOS and
+`$XDG_CONFIG_HOME/obsidian/` (else `$HOME/.config/obsidian/`) on Linux; no
+location is known on other platforms. Its shape is
+`{ "vaults": { "<16 hex>": { "path", "ts", "open"? } }, …other settings }`.
+The app reads it when it starts and rewrites all of it, with
+`JSON.stringify`, whenever its list changes; `open` is true while a window of
+that vault is open and stays true for the vaults open when the app quit.
+Modules: `src/projection/obsidian/publication/vault-list.mjs` (read only) and
+`src/runtime/obsidian/app-registration.mjs` (the write).
+
+**While Obsidian runs and answers its command line**, the file is the running
+app's and is only read. `open` asks the app instead, through `obsidian-cli
+eval` with constant scripts: `vault-list` (the app's own map) and `vault-open`
+with the folder and `false`, which adds an existing folder to the list (the app
+writes its own file) and opens it in a window; `true`, which would create a
+folder, is never sent. The folder travels as a base64-encoded JSON payload, as
+in the publication bridge, so a path never becomes code. The addition is
+verified by reading the app's list again and finding the vault root's entry
+(asked again, a bounded number of times, while the window the app just opened
+is still loading and answers that a command does not exist yet); an addition
+the app did not answer (a call that timed out) is looked up the same way, and
+is `addition-not-answered` when the list does not show it. `open` then waits,
+bounded, until the app answers for exactly that vault. Like Obsidian's own
+"open folder as vault", `vault-open` also adds the folder to the operating
+system's recently used documents (Recent Items on macOS).
+
+An entry is the vault root's when its folder, as written, is the root as
+given or its real path; a listed folder's own real path is read only when its
+last component is the root's (the root reached through a linked parent), so
+a vault on a mount that does not answer is never waited on, and a link to the
+root under another name is not recognised.
+
+**While Obsidian runs with no vault open**, its command line answers nothing
+and the file is still the running app's: it is read, never written. A vault
+it already lists is opened by path; one it does not is refused as
+`no-vault-open`.
+
+**Never inside another vault.** In every state, a vault inside a folder the
+list has as a vault already (compared as written, against the vault root and
+its real path) is not added, through the
+app or in the file: that vault would show its notes too, and a call run in
+its folder would reach that vault. `open` answers `launch-failed` with reason
+`vault-inside-another-vault`.
+
+**One folder open in several windows.** The list can name one folder more
+than once (under another letter case, or through a link), and the app opens
+one window per entry. When more than one of the entries that name the view's
+folder is open, each window holds the vault and a call reaches one of them
+only (`vaultRoute` answers `duplicated`): no publication call is made (the
+publisher refuses `vault-open-in-several-windows`, a `publisher-conflict`),
+and `open` answers `publisher-conflict` with that reason, names the entries
+(`duplicates`) and launches nothing. The entries are read from the list's
+`open` marks, and the app keeps the last window it closed marked open, so this
+can hold with a single window showing; the next step is to remove the extra
+entries from the list. While one entry has a window, a call
+reaches only that entry, and `open` finds and launches it, so a closed entry of
+the same folder is never opened beside it.
+
+**A Flatpak or snap build** keeps its list inside its sandbox
+(`~/.var/app/md.obsidian.Obsidian/config/obsidian/`,
+`~/snap/obsidian/current/.config/obsidian/`) and never reads the file above.
+On Linux the build in use is the one whose `obsidian.json` (native, Flatpak or
+snap) was written last, since every build rewrites its own when a vault window
+opens or closes; only when none was ever written, a Flatpak or snap
+installation or leftover decides (`~/.var/app/md.obsidian.Obsidian`,
+`~/.local/share/flatpak/app/md.obsidian.Obsidian`,
+`/var/lib/flatpak/app/md.obsidian.Obsidian`, `~/snap/obsidian`,
+`/snap/obsidian`, `/var/lib/snapd/snap/obsidian`). For a Flatpak or snap
+build the file is neither read nor written, `open` answers
+`obsidian-sandboxed`, and the vault is added through the running app only.
+
+**While no Obsidian runs**, the vault is added to the file itself, and only
+then:
+
+1. The process table is read and must say, positively, `absent`. `running` or
+   `unknown` refuses (`app-may-be-running`).
+2. The user-data directory and the file must exist, be this user's own, and be
+   a real directory and a regular file (neither a link), and the file must be
+   a JSON object whose `vaults`, when present, is an object, of at most 4 MiB.
+   A file with a second name (a hard link) is refused as
+   `obsidian-settings-unsafe`: the replacement would leave that name with the
+   old list. A missing
+   directory or file means Obsidian has not run on this account and is
+   refused (`obsidian-settings-missing`): the file is never created. The other
+   refusals are `obsidian-settings-unsafe`, `obsidian-settings-not-owned`,
+   `obsidian-settings-unreadable` and `obsidian-settings-not-object`.
+3. A vault whose real path an entry already has is left as it is; nothing is
+   written. A vault inside a folder an entry has is refused
+   (`vault-inside-another-vault`).
+4. The new document is the file's object with one entry added under a fresh
+   random 16-hex id that no entry has: `{ path: <the vault root's real path>,
+   ts: <now, ms>, open: true }`. Every other key and every other entry is kept
+   in its place, as values. A document that would be larger than 4 MiB is
+   refused (`obsidian-settings-too-large`).
+5. A temporary file in the same directory is written with the file's mode and
+   fsynced; the bytes as they were are written, fsynced, to
+   `obsidian.json.atelier-backup-<UTC time>` beside it.
+6. Immediately before the rename, the process table must still say `absent`
+   and the file must still hold the bytes that were read; otherwise both new
+   files are removed and the write is refused (`app-may-be-running`,
+   `obsidian-settings-changed`).
+7. The temporary file is renamed over `obsidian.json` and the directory is
+   fsynced. Of the backups beside it, the first (the list as it was before
+   Atelier wrote it) and this one are kept, and any between them removed. The
+   process table is read once more: an app that appeared just then may have
+   read the list before the rename, so the addition is reported unconfirmed
+   and `open` answers `launch-failed` with reason
+   `app-started-during-registration` instead of launching; the next `open`
+   adds the vault through the app if it missed it. A file that cannot be read
+   back to find the new entry is reported unconfirmed as well, with reason
+   `registration-not-read-back`.
+
+Every refusal writes nothing and leaves nothing behind: a temporary file or
+backup created on the way is removed again whichever later step fails.
+`open` then shows the vault by the steps of `launchPlan`
+(`src/runtime/obsidian/launch-plan.mjs`, carried out by `runLaunchPlan`),
+naming it `obsidian://open?vault=<id>` when the id reaches it first (a path is
+matched against the list by string prefix, with no separator check), and by
+its own listed path otherwise (another vault's folder named like the id, an
+unusual id): a running app is handed the link through its command-line tool,
+which takes a link even with its command line turned off, or through the
+operating system when the tool did not take it; on macOS a quit app is started
+plainly (`open -b md.obsidian`), which reopens every vault the list flags open
+(the entry written above is flagged open), and handed the link through its
+tool once the app itself answers the tool (`appAnswered`: a version or one of
+the app's own lines; the tool's "unable to find Obsidian" while the app starts
+does not count). A link is never handed to the operating system for an app
+this launch started, since that would reach it while it starts. An app started with a link would delete the
+reopen flag of every other vault without a window (1.13.7, checked on an
+isolated instance). On Linux a quit app is started with the link, a known
+limit. With its command line turned off the app answers every other command
+with "Command line interface is not enabled"; that is read as
+`app-cli-unavailable` / `cli-turned-off`, never as a version.
+
+**Which window answers.** The command line (1.13.7) answers a call whose first
+argument is `vault=<value>` in the window of the first listed vault whose id is
+the value, or whose folder's name is the value in any letter case; any other
+call in the window of the first listed vault whose folder is the tool's working
+directory or contains it, the folders compared as written; and otherwise in the
+vault window that had focus last. It opens a vault that takes a call when it is
+closed. The first match in list order wins, not the deepest folder, so a vault
+listed before the view's vault at a folder above it would take every call run
+in the view's folder. Calls about no vault (the version, the vault list, the
+addition) run in a directory that is no vault and name none. A call about the
+view's vault goes where the list says only that vault takes it
+(`vaultRoute` in `vault-list.mjs`): from a directory that is no vault with
+`vault=<id>` first when that id names this vault first, which does not depend
+on how a working directory is spelled; otherwise in its folder when the first
+listed vault that is or contains that folder is this vault; when neither
+holds, no call is made. The vault root is taken in the spelling the file
+system stores (`realpathSync.native` on macOS and Linux), which is how the
+operating system reports the tool's working directory: on a volume that folds
+letter case, a data root given in another case neither hides a vault listed
+above it nor routes a call there. `open`'s check
+that the app answers for the vault is routed from the list it verified the
+vault in. Publication calls are routed from the file, and only while it lists
+the vault open; otherwise they run in a directory that is no vault and name
+none, so maintenance never reopens a vault window that was closed and never
+reaches another vault. The bridge still checks that the app answered for
+exactly this vault, and `open` that the app answers for it, both folders taken
+as the file system stores them: an app that holds the vault under another
+letter case or through a link holds this vault, and a store written under
+another spelling keeps its vault.
+
+**Retries.** The maintenance service is told what the app looks like from
+the process table and the file alone (whether an Obsidian process runs, and
+which vaults the file shows open; the file is read, never written, by the
+service): nothing runs in the app to find out. The app is asked for its
+version only when a view is about to be published, and without blocking the
+service. A tick requested over the service's listener for one view (`open`
+names its own) prepares and publishes that view once more, with the app's
+qualification asked again; the engine takes such requests only for views the
+project declared at its last tick, and at most 64 before its first. A view
+whose last publication did not settle is also tried again as soon as that
+picture changes, and otherwise after a delay that starts at 30 seconds and
+doubles per attempt, up to the full reconciliation interval.
+
 Source application back into canonical files carries the same conditional-write
 obligation against other source writers; its protocol follows.
 
@@ -556,7 +1186,11 @@ list`, `show`, `run` and `recover` answer such a record as a typed refusal.
   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.
+  is never accepted in exchange. The identity block in the front matter is
+  generated as well: it is removed before the source bytes are made, and a
+  note whose front matter changed, the identity lines included, is a
+  front-matter edit that becomes a proposal. A byte order prefix the editor
+  dropped is taken from the source, as before.
 - 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