@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

package/docs/{knowledge-workspace.md → guides/knowledge-workspace.md}

@@ -30,7 +30,7 @@ sources, concepts, relations, and questions before operational use.
 
 An existing enrolled project needs a valid `knowledge-plan.json` beside its
 project configuration. Use the schema and guide in
-[knowledge setup](knowledge-setup.md). Rebuild the projection when its source
+[knowledge setup](../start/knowledge-setup.md). Rebuild the projection when its source
 changes. The knowledge panels read the current enrolled graph on request; the
 ordinary projection remains the last explicitly built projection.
 
@@ -216,7 +216,7 @@ Start takes `requestId` (a fresh UUID, retained for exact retry), `flow`
 and `author`. Read/recover take only `sessionId`. Event takes `sessionId` and
 an `event` with a unique `id`, current `expectedRevision`, and reducer `type`.
 An `answer` or `propose` also carries `text`. All other event behavior follows
-[coauthor sessions](coauthor-session.md). Clients cannot submit receipts or
+[coauthor sessions](../reference/coauthor-session.md). Clients cannot submit receipts or
 failure events. Stale versions never silently overwrite an intervening answer.
 
 Ask one useful question at a time. Record the person's exact answer. For

package/docs/{learning-harnesses.md → guides/learning-harnesses.md}

@@ -1,8 +1,7 @@
 # Knowledge development and the learning cycle
 
-Status: implemented locally for the next release. Published alpha.7 does not
-contain these commands. Use `node bin/atelier.mjs harness help` in this source
-checkout, or `atelier harness help` from a package built from this candidate.
+Status: shipped since 0.2.0-alpha.13. Run `atelier harness help` for the
+commands.
 
 Knowledge Harness helps people establish, develop, use and revise what they know.
 Ingestion is one capability within that larger purpose. Sources can also originate

package/docs/{learning.md → guides/learning.md}

@@ -5,6 +5,11 @@ decisions, and supplies explicitly activated lessons to a named harness. It is
 an experimental local source capability. It requires consumer integration and
 does not establish availability in a published package or installed desktop.
 
+Here, `capture` means recording the observation explicitly supplied by a caller
+or on stdin. It does not monitor an editor, microphone, conversation or desktop.
+The [independent local start](../start/independent-start.md) needs no desktop or MNSTRY
+account; integrated capture is a separate host capability.
+
 A person defines the task and scope, an agent can propose a lesson, and the
 person reviews its wording and consequences. Evidence can be represented before
 acceptance. Only accepted, activated content is eligible for task context.
@@ -202,11 +207,13 @@ Campaigns may stay in their own workspaces; selected references do not change
 their writer ownership. Private evidence projections stay outside committed
 canonical graphs unless an owner explicitly authors an appropriate source.
 
-A desktop or other host owns integrated capture, authenticating its caller,
-background jobs, provider access, budgets, review controls and actual harness
-integration. Private feedback, preferences, methods and authored skills remain
-in their owning workspace. A commercial host should consume these contracts
-without making basic local learning or export depend on an account.
+A consuming host owns integrated capture, authenticating its caller, background
+jobs, provider access, budgets, review controls and actual harness integration.
+MNSTRY's desktop utility is a separate proprietary consumer of this public
+foundation. Other hosts can use the same portable APIs and optional public
+startup, editor and native-presentation bindings. Private feedback, preferences,
+methods and authored skills remain in their owning workspace. Basic local
+learning and export require no MNSTRY account or service.
 
 Run `node --test test/learning-*.test.mjs` on the supported Node version for
 the local acceptance cases. They cover terminal capture through withdrawal

package/docs/{obsidian.md → guides/obsidian.md}

@@ -4,7 +4,7 @@ This document describes the selection binding, the apply policy setup, the
 conflict-state view and the acceptance receipt validator under
 `src/projection/obsidian/selection-ui/`. It states what each one does on this
 machine and what it does not. The contract itself is in
-[obsidian-contract.md](obsidian-contract.md).
+[obsidian-contract.md](../reference/obsidian-contract.md).
 
 Nothing in this module starts the app, runs `obsidian-cli`, publishes a vault
 or writes a source file. The test suite installs a spawn guard that throws if
@@ -273,7 +273,7 @@ path. The package root (`@mnstry/atelier`) exports nothing of the projection.
 Names ending `ForOracleTests` are mutation controls for the test suite, not a
 supported API. The whole surface is alpha and may change between prereleases.
 What the tarball must and must not carry, and the package proof, are in
-[release-engineering.md](release-engineering.md#obsidian-package-contents).
+[release-engineering.md](../maintainers/release-engineering.md#obsidian-package-contents).
 
 ## First vault: what to expect
 
@@ -538,9 +538,19 @@ earlier one, so two installations used on one workspace (a global and a
 project-local one, say) do not replace each other's service on every open:
 `open` answers `service-unavailable` / `service-other-release`, and `service
 start` answers that it runs, with `release: later`; run `atelier obsidian
-service stop`, then open again, or open with the later release. A service in a
-long tick is not stopped (`open` answers `busy`), and a listener that does not
-prove itself this workspace's service is never touched.
+service stop`, then open again, or open with the later release. A service that
+does not answer health in time, in a stretch of a tick that does not yield, is
+not stopped (`open` answers `busy`), and a listener that does not prove itself
+this workspace's service is never touched. While a view is being prepared and
+published the service does answer: `open` asks it for a tick that starts after
+the one in flight and waits for that tick, two minutes at most unless
+`atelier obsidian open --wait-ms MS` sets another bound, before it reports the
+view as it is (one that read `current` is reported `updating`, with the reason
+`tick-still-running`, while that tick has not ended); and `service stop` is
+accepted and ends the
+service after the tick in flight or after its shutdown grace, whichever comes
+first. A publication cut short that way is settled by the publisher's restart
+recovery at the next one.
 
 The first time Obsidian opens a view's vault it asks "Do you trust the author
 of this vault?", because every vault Atelier publishes carries Atelier's own
@@ -554,7 +564,7 @@ its own storage and asks again the next time until the vault is trusted or
 restricted mode is switched on for good in its settings. Turning the plugin
 off in a vault, or uninstalling it there, is respected from then on;
 `atelier obsidian plugin on --scope ID` brings it back. What the plugin does
-and never does is in [obsidian-plugin.md](obsidian-plugin.md).
+and never does is in [obsidian-plugin.md](../reference/obsidian-plugin.md).
 
 `open` and `status` answer with a freshness state, not a promise. `current`
 means the vault is the present generation, verified by read-back, and the app
@@ -679,7 +689,7 @@ exactly because the folder is listed.
   Obsidian does not have to be quit.
 - **Obsidian is not running.** The view is published on the path with no app,
   as before. `open` then adds the vault to the app's settings file (see
-  [Obsidian's vault list](obsidian-contract.md#obsidians-vault-list) for
+  [Obsidian's vault list](../reference/obsidian-contract.md#obsidians-vault-list) for
   exactly when and how that one file is written, marked to reopen) and starts
   Obsidian plainly, with no link: an Obsidian started with a link opens only
   that vault and drops the reopen flag of every other one, so your other
@@ -815,7 +825,7 @@ names the folder meanwhile, a settings file with other bytes is already
 there, or an interrupted run left a replacement or a removal. `open` may then
 add and open the vault before it is complete, and the app publishes the rest.
 Anything that would replace or remove a file waits for the app. See "First publication into a vault no Obsidian lists" in
-[obsidian-contract.md](obsidian-contract.md). The plugin's entry written this
+[obsidian-contract.md](../reference/obsidian-contract.md). The plugin's entry written this
 way counts as offered until the plugin says hello from the vault.
 
 The publisher still writes into a vault only when it can coordinate with every
@@ -862,8 +872,9 @@ generationId })` in `src/projection/obsidian/personal-workspace.mjs`. Both
 arguments are explicit; neither is discovered from the environment or the
 working directory. A loader uses `loadBoundProject` with the same arguments,
 or `loadBoundProjectOffThread`, which composes in a worker thread; the engine
-awaits its loader. No command or service binds one yet: that waits for the selection seam that
-keeps one projection configuration per person.
+awaits its loader. The command, the service and the login item bind a personal
+home through `--personal-home`, which follows the generation the person
+confirmed there (see "A confirmed selection", below).
 
 - **One graph.** The binding is attached to the generation's resolved
   `atelier.project.json` under one symbol key. When a project carries it, the
@@ -960,9 +971,12 @@ keeps one projection configuration per person.
   (`personal-views-exceed-settings-limit`), within the Obsidian settings
   contract. The preferred view, when it names a saved one, is the default. No
   generation file is written. `view add` refuses `views-from-personal-overlay`;
-  `audience set`, `audience clear` and `location set` refuse
-  `personal-binding-decision-unavailable`. Each refuses before anything is
-  resolved or written.
+  `audience set me` records owner-only visibility in the machine settings, and
+  `audience clear` withholds every audience. Custom audience lists refuse
+  `personal-binding-owner-only`; `location set` still refuses
+  `personal-binding-decision-unavailable`. Refused operations do not change
+  audience, view or location settings. Following a selection may still keep
+  machine-private continuity evidence before the setting operation refuses.
 - **Preferences and coverage.** `preferences` are returned read only. A theme
   is reported and never written: `appearance.json` stays the person's.
   `coverage` is passed through untouched. No Obsidian code reads it: it states
@@ -984,6 +998,173 @@ keeps one projection configuration per person.
   in memory. A project configuration that declares it itself is refused at
   every build (`personal-binding-lost`, naming the key).
 
+### A confirmed selection
+
+`--personal-home DIR`, given instead of `--project` to `atelier obsidian`, to
+the service entry and in a login item's unit, binds the personal home DIR
+(`src/runtime/obsidian/personal-selection.mjs`). Without it, every argument,
+unit and loader is what it was.
+
+- **What is loaded.** The generation the person last confirmed with
+  `selectPersonalGeneration` (see [personal-workspace.md](personal-workspace.md)),
+  and nothing else. The loader reads the head of the selection history from
+  the history alone (`readPersonalSelectionHead`), loads the generation it
+  names through the route above (in a worker for the service, in the
+  command's thread for a command), then reads the head again. A head that
+  moved meanwhile refuses `personal-selection-changed`. Nothing here confirms
+  a selection or chooses one for the person.
+- **Nothing confirmed publishes nothing.** No record refuses
+  `nothing-selected`; a confirmed generation whose inputs were edited and not
+  confirmed again refuses `stale-generation`; a history whose hash chain does
+  not hold refuses `selection-history-corrupt`; a history that ends at an
+  earlier record than the running service has read refuses
+  `selection-history-shortened`; a home whose history cannot be read refuses
+  `personal-home-unavailable`, and a home that is gone or not
+  private refuses with the module's own code (`root-missing`,
+  `not-private-location`, `root-symlinked`). Every other refusal of the
+  composition keeps its code. Nothing falls back to another generation or to
+  the project without a binding. The vault keeps what it last published from
+  a confirmed generation. `status`, `open` and `service start` load the
+  selection and refuse with its code; the service's freshness shows every view
+  `stale` with it, and its status document has it as the last tick's reason.
+  The command and service read the same machine-private continuity state, so a
+  restart or a separate command does not accept a shortened history. An invalid
+  checkpoint refuses `invalid-selection-continuity`; a checkpoint that cannot be
+  kept refuses `selection-continuity-unavailable`. No project is returned in either case.
+  A confirmed selection is reported by `status` (`selection`: the generation
+  and the number of its record).
+- **The service starts from an initialized home whatever the selection.** A bound
+  project's folder is its private home. The home must contain its caller-authored
+  `atelier.personal.json`, even when its enrollment is explicitly empty and no
+  generation is confirmed. A bare directory or a missing/unreadable manifest
+  refuses before startup; the locator cannot infer that no repositories were
+  enrolled from missing evidence. This tightens the former lower-level API
+  behavior that could start from a bare home. The locator reads the home and the
+  current manifest's repository roots for exclusion, without composing or
+  selecting a generation. A data root
+  inside a declared repository is refused before private state is created or a
+  login item is removed for a restart, including when nothing is confirmed.
+  The service resolves its workspace from that at once and starts, and its
+  engine awaits the loader at each tick. `atelier obsidian --personal-home`
+  does this for a bound home. A
+  program that runs the service itself (`runMaintenanceService` from
+  `@mnstry/atelier/obsidian`) gives it the same through `locateProject`, a
+  synchronous function that answers, without loading anything, a project whose
+  `configDir` is the folder the workspace is resolved from. The workspace is
+  then resolved from that answer alone: a data root named only in the loaded
+  project's local overlay, and not in the answer, is not seen, so the service's
+  state can lie under another data root than the loaded project's. Name the data
+  root through the `dataRoot` option or the workspace pointer instead, which
+  both see. Started by a login item, the service asks the home, not the loader,
+  for its workspace and log. `service status` and `stop`, the ticks `open` asks
+  for, `service unit --remove` and `uninstall` locate the service the same way.
+  When no project loaded (a restart while nothing is confirmed), the engine
+  locates the workspace too, so each view published before says why nothing is
+  published now instead of keeping the previous run's `current`. A service given
+  a loader that answers a promise and no locator is still refused at start with
+  `service-loader-not-synchronous`, and so is one whose locator answers a
+  promise; a located value that names no folder refuses
+  `service-locator-invalid`. The workspace pointer is under the home, so a home
+  that is gone when the service starts leaves it no workspace to find
+  (`service-workspace-not-prepared`).
+- **Cleanup with nothing confirmed.** `service unit --remove` and `uninstall`
+  locate the existing protected workspace without a generation, and remember
+  the machine's login-item decision as `off` there. They do not change the
+  audience or confirm anything. Uninstall reports the actual kept workspace
+  pointer under the personal home, and leaves its bytes, private state,
+  generations and selection history in place.
+- **Following the history.** A loaded project is pinned to the record it was
+  loaded under, and the engine observes that record and the place of the next
+  one as configuration. A confirmation is therefore loaded at the next tick. A
+  history cut short is seen at the next tick too, and a running service does
+  not follow it back. Selections are only ever appended, so a history that
+  ends at an earlier record than the service has read it ending at was cut by
+  something other than a confirmation, and following it back could publish
+  what nobody confirmed after the records removed: cut after a restore nobody
+  confirmed, it would publish that restore. The service notes the highest
+  record number at every read of the history's end (a load's first read, its
+  read once the generation is loaded, the recheck at a full reconciliation,
+  and a read made when a tick stops a view as `mixed-read` because the tick's
+  settings changed or could not be read, once for views stopped one after
+  another), whether or not the
+  record's generation could be used, and whichever part of the service read
+  it. A history that ends earlier refuses `selection-history-shortened` at a
+  load and at a recheck until a fresh confirmation accepts it; at
+  the read made when a tick stops a view, the view says `mixed-read` at that
+  tick and the code at the next. A project already loaded is loaded again at
+  the next tick once any part of the service has read the history ending at a
+  later record than the one the project was loaded under, so a confirmation
+  read elsewhere in the service and removed before the engine looked refuses at
+  that tick; otherwise a project already loaded is held to this at its next
+  recheck, at the latest the next full reconciliation, and until then it
+  publishes nothing new under another record, and a change at its sources
+  brings the recheck forward. A record added and removed between two of those
+  reads was never read, and does not count: while a load of its own is under
+  way, the plugin's status read compares the files that decide its views and
+  reads no history, so a record it sees then only as a changed file is not
+  noted. The views say why (`open` and
+  `status --json` name the ways out), and the vault keeps what it last
+  published.
+- **What ends that refusal.** Put the removed records back, or explicitly confirm
+  the currently eligible generation through `selectPersonalGeneration` again.
+  That existing confirmation operation is the accepting act; no new command is
+  needed. One fresh confirmation accepts a shorter history even when its record
+  number remains below the highest ever observed. Its unique confirmation
+  identity distinguishes it from a previously observed record restored to the
+  same position. Replaying a previously observed prefix refuses, including after
+  a shorter history was accepted. Composition still decides whether the chosen
+  generation is eligible.
+- **Continuity across starts.** The highest observed number, accepted head and
+  previously observed record digests live in
+  `state/maintenance/selection-continuity.json` under the existing private
+  workspace. Reads validate its closed schema, workspace and personal-home
+  identities; changed writes are serialized through the existing private-state
+  lock, owner-only and atomic. State is bounded at 1 MiB and 8,192 observed record
+  identities; exhausting the identity budget refuses `selection-continuity-capacity`.
+  First use initializes from the current valid history, including historical v1
+  records without a confirmation identity. Retain this private state: deleting
+  all of it removes the evidence that distinguishes prior observation from a first
+  installation. Damaged existing state is never treated as a new installation.
+- **What the history is checked for besides.** At every full reconciliation the
+  history is read again, so a record before the last that no longer links, or
+  a confirmation that landed before the engine first looked at the record,
+  refuses with its code within the reconciliation interval. A confirmation
+  during a tick changes an observed file: the view being prepared or published
+  refuses `mixed-read` at its next wait, before its generation commits (one
+  already committed stays), so do the views after it, and the next tick
+  publishes under the new record. While the last load was refused, every tick
+  loads again: with nothing confirmed the manifest, history and private continuity
+  state are read without composition, and with a
+  confirmed generation that no longer holds, one composition runs in a worker
+  per tick.
+- **A narrowing.** When the newly confirmed generation drops a source (a
+  repository withdrawn, a view narrowed), each view follows the publisher's
+  rule for notes that leave a view; this binding adds no rule. At the view's
+  next publication a generated note of the dropped source leaves the vault and
+  its bytes are moved to private recovery. A note the person edited, once the
+  engine has queued the edit, holds the whole view at the generation it last
+  published (`held-for-your-edit`, `publication-withheld-for-your-edit`): the
+  note is neither removed nor overwritten. A note edited during the
+  publication itself stays in the vault (`retained-edit`).
+- **Who may see.** The existing machine audience setting owns this decision.
+  For a personal binding, an undecided empty audience initializes to `only-you`
+  with notes without a classification shown, recorded with `defaults` provenance.
+  Existing explicit `only-you` lists and unclassified choices retain their exact
+  meaning. An explicit `audience clear` stays empty across ticks and restarts.
+  A nonempty custom setting refuses `personal-binding-owner-only` until
+  `audience set me` or `audience clear` is recorded. Nothing is written into a
+  generation or the personal overlay.
+- **Reading the history on the service's event loop.** The head is one
+  directory listing and one bounded read per record. A record that is not a
+  regular file (a FIFO, a device) refuses `selection-history-corrupt` without
+  being waited on. A home that becomes unreadable while the engine holds a
+  project (its permissions changed, not removed) fails the tick when the
+  engine observes its files, as an unreadable configuration file does: nothing
+  is published, and the service reports the failed tick.
+  After a worker composes a generation, the caller still reads generation
+  files, resolves the generation's project configuration and assembles the
+  bound project on its own thread. Composition itself remains in the worker.
+
 Measured once on 2,156 notes in three repositories, with 50 annotations and five
 saved views (six views in all). The production contributions were loaded, as
 the service loads them, so the proposal adapter was registered. The host's load
@@ -1011,16 +1192,133 @@ again. While an edit stays open and shared sources are quiet, the adapter
 builds nothing more; under continuous change it builds once per tick until a
 quiet tick.
 
-**What remains before a service or `open` binds a personal workspace of this
-size.** The first publication blocks the event loop far longer than the
-service's five-second health probe: about ten minutes here. That is the
+**What a service binding needed.** The first publication blocked the event
+loop far longer than the service's five-second health probe: about ten minutes
+here. That is the
 publication path every project takes, not this route: an ordinary project of
 450 notes, measured the same way, blocked as long as a bound one. Preparing six
 views again blocked 4.5 s, under the probe. The proposal adapter's build of a
 newly observed edit, without the engine's file cache, blocked 2.0 s, at a
-two-second target, as for an ordinary project. A service binding needs the
-first publication to yield to the event loop (or run off it), or a corpus small
-enough to stay within the probe.
+two-second target, as for an ordinary project. A service binding needed the
+first publication to yield to the event loop, which it now does (see "Since
+that measurement"), and a start that does not wait for its loader. The service
+resolves its workspace from the project its loader answers when it starts, and refuses a loader that answers a promise or any
+other thenable, such as `loadBoundProjectOffThread`, with
+`service-loader-not-synchronous`, before it reads anything from it, listens or
+records anything; a promise it was handed is let go, and its refusal, if it
+is refused, does not go unhandled. Started by a login item (`--startup`), the
+service asks its loader (or, under `--personal-home`, its locator) once for both
+the lookup of its workspace and its own start. One that answers a promise there
+is never handed to the workspace resolution: a promise whose `constructor`
+reads as this realm's `Promise` is let go without calling a `then` of its
+own, any other thenable (as a rule another realm's promise or a subclass's)
+is adopted once (its `then` is called once in all), the refusal is recorded
+in the workspace the unit names, when that exists, and the process ends with
+0, so the service manager does not start it again at once. One that throws
+there, whatever it throws (`undefined` too, a value with no prototype, or one
+whose `code` cannot be read), or answers a project whose `then` cannot be
+read, ends the start as a failure of the loader does anywhere else: it is
+logged, and what carries no code is a crash.
+A service bound through `--personal-home` is given a locator as well, and starts
+from it (see "A confirmed selection"). The plugin's status read allows for such
+a loader without waiting for it (see "The channel" in
+[obsidian-plugin.md](../reference/obsidian-plugin.md)).
+
+**Since that measurement.** The engine prepares each view cooperatively and
+the publisher yields between complete units, so the service answers health and
+status while notes are emitted, staged and published. The first-tick figures
+in the table are from before that change and have not been taken again on that
+corpus. Building the canonical graph gives the event loop a turn between the
+Markdown sources it reads, hashes and parses (the census): a first tick reads
+every source, and on a heavily loaded host the build of one view of 10,000
+invented notes held the listener for 8 s in one stretch. The other sources
+(HTML files and the sidecars of PDF and Word documents) are read without a turn
+between them, and a project bound to a personal workspace is built by its own
+route in one stretch. Walking the directories, resolving the links and
+assembling the graph still run through.
+So do capturing the source snapshot, the publisher's restart recovery,
+validating a prepared view and planning its units, the exchange probe, writing
+and syncing the journal before the candidates move, and the look again at
+displaced files after the units (`recheckDisplacedFiles`).
+The read-back after a commit waits between
+notes: on a loaded host it took 16.8 s for one view of 10,000 invented notes
+and held the listener for all of it, and now a request is answered between two
+notes. Nothing is checked at those waits, since the generation is committed. A
+note edited in the vault while the read-back is under way is read as edited
+when the walk has not reached it, and is seen by the next tick when it has, as
+an edit made just after a read-back is. A stop whose grace runs out while a
+read-back waits ends the process after the commit and before the view is
+recorded as current, as a crash there does: the next start's first tick reads
+the committed generation back. Before a view is prepared, a tick looks at
+every view's notes and then at the sources, and both walks wait between files.
+They matter after a publication, when the watcher has named the notes it
+wrote, and at every full reconciliation, when every note and every source is
+hashed: on one view of 10,000 invented notes on a loaded host such a tick held
+the listener for 5.5 s when the walks ran through. Nothing is checked at their
+waits and nothing is written. Within Atelier only the engine commits a
+manifest or writes the pending edits, under the lock the tick holds, so the
+pending edits are read, compared and written in one stretch after the walk
+over the vault, and the bytes an edit keeps are read there. A file changed
+after its turn in a walk is seen by the next tick, by its stat hint or the
+watcher (one that keeps its size and times and draws no event, at the latest
+by the next full reconciliation), as one changed just after a walk that ran
+through is; when the tick builds the graph, the look again at the sources
+after the build refuses such a change as `mixed-read`. A source this tick
+observed, removed before the build read it (or its folder), is refused the
+same way. So is a selected source removed before a view's preparation, or the
+look again before its commit, read it: that view is refused, and the tick goes
+on to its other views. Either way the next tick reads everything again; a path
+that can never be read still fails the tick. A note gone from a
+vault, a source that changed, or a configuration file that changed is a change
+once: a tick that sees it and then fails without a typed reason (a file it
+cannot read, a disk that is full, a project loader that fails) has recorded it
+without acting on it. The next tick therefore starts as the first tick of a
+process does: it loads the project again and looks at every view, so a view
+whose note is missing reads `vault-note-missing` instead of staying `current`,
+and a changed source or view is published.
+The comparison of kept notes with their candidates reads asynchronously,
+sixteen at a time, and does not hold the listener. Observing pending edits
+and routing proposals wait between two edits and between two operations, so
+a burst of edits does not hold the listener for its whole length. One edit,
+or one operation, is still one stretch. The first edit an observation looks
+at that the object store does not hold yet builds the canonical graph in its
+stretch, and the first operation routed builds it again while the lock of
+its repository is held. An edit whose published note
+is not retained has its whole view prepared again in its stretch: once for a
+view and generation in an observation when the preparation succeeds, and for
+every such edit when it fails. A stop whose grace runs out while proposals
+are routed can end the process between two operations of a repository with
+that repository's proposal lock still held, as a crash can. A service in one
+of those stretches does not answer until it ends, and is `busy` if that
+outlasts the probe. A request can
+hold the listener too: the plugin's status read loads the project on the event
+loop at its first requests after the service starts (until two loads agree),
+when a configuration file changed, every two and a half minutes, again two to
+thirty seconds after a load that failed, and at every request while one of
+those files vouches for nothing or while its loads never agree. For a project
+named by `--project` none of those loads is taken off the loop. For a bound
+personal home they compose in a worker, as the engine's loads do, and the read
+starts each one on the loop by reading the selection history. A load that holds the loop
+for a second or more is logged (`status-project-loaded`), and so is a load at
+every request that names the files it started over (see "What the service
+shows of these loads" in [obsidian-plugin.md](../reference/obsidian-plugin.md)).
+
+What the waits cost. The waits of observation and routing are taken at
+every boundary between two edits or two operations and before each
+repository, whatever time was spent; while routing describes its operations
+a wait comes after about 8 ms of work or 32 units. Nothing is checked around
+any of them. In preparation and publication a wait
+comes after about 8 ms of work or 32 units,
+whichever is first, and around each one the engine checks that the tick's
+settings still hold: it reads and hashes every configuration file it observes
+(the project configuration, the repository access file, local overlays and,
+for a bound personal workspace, its inputs), reads and validates the machine
+settings, and asks the eligibility revision. Measured on six configuration
+files, that check took about 0.2 ms, twice per wait; a first publication of
+200 invented notes waited 463 times, so roughly 0.2 s of a 64 s tick, on a
+host with a load average above 200 (indicative only). The selected sources
+cost one stat call each after the preparation and one before the commit; a
+note reused from the preparation cache is still not read.
 
 ## Known limits
 
@@ -1047,7 +1345,7 @@ test reported as a pass.
   is admitted although the protocol depends on the view's undocumented
   `lastSavedData` field, and the protocol cases have not been re-run on any
   later release. See the "App capability floor" row of
-  [obsidian-contract.md](obsidian-contract.md). An app that was not running
+  [obsidian-contract.md](../reference/obsidian-contract.md). An app that was not running
   when an adapter was qualified had no version to check, and neither had an
   app that was not found. Such an answer is never reused, and the adapter
   built on it does not coordinate with any app it then finds running, and
@@ -1087,6 +1385,50 @@ test reported as a pass.
   first allocation or when a vault is made again. Every other check runs
   again at both, and a vault made again, or published into, through a link on
   the way is refused (`vault-allocation-moved`).
+- Private state after a wait: that the private state is outside every
+  repository the workspace declares now is proven when a project loads, around
+  each engine phase, inside the engine and selection locks, and after each wait
+  the publisher makes for the app, its list of vaults, its comparison of kept
+  notes or its quiet period. "Declares now" differs by binding. For a project
+  bound to a personal home, each proof reads the home's manifest again, so a
+  repository enrolled while a tick waits is seen at the next proof. For an
+  ordinary project, each proof uses the repositories of the project as it was
+  last loaded. A change to its configuration or overlay that declares a
+  repository enclosing the data root is not seen until the project is loaded
+  again, and the writes of the tick in flight (preserved edits, pending edits
+  and freshness, say) can land under it meanwhile. The proof is not made again
+  at every write, and it is not made at all for writes made outside the
+  engine's phases and the publisher. Those are:
+  - the built-in proposal store's writes for pending edits to shared notes
+    (kept bytes, arbitration records and its queue) while it works through
+    several of them;
+  - everything the service process itself keeps: its log, service settings,
+    runtime record (with its bearer), service-start lock, startup record,
+    error record and login-item record, including those written after it waits
+    for a free port, for its server to listen or for the service manager, and
+    those a login item's start writes in the workspace the unit names when the
+    project's loader fails;
+  - the plugin channel's bearer and the plugin choices it records, including a
+    first-use bearer minted while a view is prepared and the confirmation
+    written when a plugin session opens;
+  - lock cleanup when a proof fails: any private lock that is held, or whose
+    ticket was just published, when its proof refuses is still released or
+    withdrawn, so that ownership is never left behind. This covers the engine
+    lock (a release record, or the withdrawal of a ticket published before
+    the last check of its acquisition), the selection continuity lock and the
+    publication locks, including a release retried at the next acquisition.
+    Lock cleanup and removing staged candidates are the only changes the
+    engine and the publisher make after one of their proofs refuses.
+
+  Each of these writers keeps its file inside the workspace's private state,
+  but none checks the roots declared now. A manifest that comes to enclose the
+  data root, or that cannot be read, while the service runs can therefore
+  receive these writes. A refusal of the private state's own location
+  (`managed-root-unproven`) stops the whole tick, whichever view it is found
+  in: no later view is prepared, given a store or published, and no view is
+  reported current after it. A view whose own vault is in a bad place is still
+  refused alone. A single check of the declared
+  roots at every private-state write is planned as a separate change.
 - Replacing a vault during a publication: the allocated folder is checked
   before the vault lock is taken and again once its folder is made, after the
   app is asked about the vault, before each note and before the generation is
@@ -1111,7 +1453,7 @@ test reported as a pass.
   `~/.config/obsidian`) on Linux. It is written only while the process table
   shows, positively, that no Obsidian runs, only when Obsidian created it
   before, and with a backup beside it; see
-  [Obsidian's vault list](obsidian-contract.md#obsidians-vault-list). A
+  [Obsidian's vault list](../reference/obsidian-contract.md#obsidians-vault-list). A
   Flatpak or snap build keeps its list inside its sandbox and never reads that
   file. Which build is in use is read from which vault list was written last
   (every build rewrites its own when a vault window opens or closes), and only
@@ -1166,7 +1508,7 @@ test reported as a pass.
   - The command-line tool (`obsidian-cli`) is a client of the app and is not
     counted. An app packaged under another executable name, an app on
     another machine and an app that starts after a reading are not seen; see
-    "The path with no app" in [obsidian-contract.md](obsidian-contract.md).
+    "The path with no app" in [obsidian-contract.md](../reference/obsidian-contract.md).
 - The app-free path is live: before 0.2.0-alpha.10 the probe always found
   Atelier's own service, so publication never took the path with no app.
   From 0.2.0-alpha.10 it does, whenever the process table shows, positively,
@@ -1196,7 +1538,7 @@ test reported as a pass.
   back and a deleted folder is not made again until the person turns it on
   in Obsidian's settings or runs
   `atelier obsidian plugin on --scope ID`. Plugin files are never removed from
-  a vault. See [obsidian-plugin.md](obsidian-plugin.md).
+  a vault. See [obsidian-plugin.md](../reference/obsidian-plugin.md).
 - Login items: the tests run the launchd and systemd managers' own code
   against stand-ins that answer as launchctl and systemctl do, and never
   against a real session. What `launchctl print-disabled` says for an item
@@ -1227,3 +1569,8 @@ The test suite proves each oracle can fail:
 - `createMaintenanceEngineForOracleTests` with an
   `ENGINE_PRIMITIVES.isRetryDue` that never holds: a refused view waits for
   the full reconciliation, and the retry oracle fails.
+- `createMaintenanceEngineForOracleTests` with
+  `ENGINE_PRIMITIVES.rechecksEveryViewAfterFailure` false: a note removed, a
+  source changed or a view added in a tick that then fails without a typed
+  reason is lost, the view stays `current` with the note gone or the old
+  content, the new view is never published, and the oracle fails.