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

package/docs/obsidian-plugin.md

@@ -32,7 +32,24 @@ is `src/projection/obsidian/plugin-bridge/channel.mjs`; the service's half is
   a window with the view, its state and the reason in words, the committed and
   the prepared generation, when freshness was last checked, the held, retained
   and pending edits, the service address and state, and the plugin and app
-  versions.
+  versions. While the service is unreachable, current generations, check time
+  and edit counts are unknown. After a connection refusal or timeout on the
+  same channel, the window also shows the last authenticated state, reason,
+  generation and check under "Last observed" labels. Those rows are historical
+  and never establish current freshness, service health or permission.
+  History stays only in memory. It is cleared on a channel change, missing or
+  unsupported setup, authentication refusal, an untrusted answer, a missing or
+  malformed view, a report for another scope, a disabled view or unload.
+  A connection reset or any other failure outside connection refusal and
+  timeout also clears it. Without a prior usable report, "Last observed
+  status" says "not available". After startup admits the channel, a republish
+  that names a different channel (host, port, scope or key) resets the display
+  to `connecting` before its next answer; this reset does not repeat an
+  unchanged notice or lose the transition back to current. A republish of the
+  same channel keeps the display and history, and unusable data shows
+  `not set up`.
+  Republish keeps an unsupported-app or unavailable-Node setup label and its
+  channel closed. Plugin 1.1.2 adds this status continuity.
 - A notice appears when the view moves into a state that needs a person (held,
   stale, service unreachable, app too old) and when it is current again.
   `updating` is not announced: it is what every change looks like.
@@ -336,6 +353,124 @@ the vault's key without sending it, and the service proves it first
 | `POST /plugin/release` | `sessionId`, `counter`, `mac` | sealed: whether the session was released |
 | `POST /plugin/status` | `sessionId`, `counter`, `mac` | sealed: the view's state, reason, verification, committed and prepared generation, held notes (counted, not named), retained edits, open pending edits, and the service's own state |
 
+A status answer carries the view and its pending edits only while the project
+allows that view at the moment of the request, not as of the last tick
+(`src/runtime/obsidian/view-permission.mjs`): its Obsidian settings are
+enabled and declare the view, and its workspace pointer still names the
+workspace this service runs for, with its private state where the service
+keeps it. Otherwise the answer is still sealed and still carries the service's
+own state, but `view` and `pendingEdits` are `null`, which the plugin already
+reads as nothing known about the view. That covers a view turned off or taken
+out of the settings before the next tick, and the freshness a later tick
+writes for it, which keeps its generations and counts. It also covers anything
+that cannot be established: settings that refuse, a project that does not
+load, a pointer that cannot be read. The plugin then shows `Atelier: stale`
+with the reason "no freshness recorded", keeps its session and asks again at
+its next round; it is not told why, and it remembers nothing of the view to
+show later.
+
+Loading the project runs Git in child processes, which would otherwise happen
+every two seconds for every open vault, so the project is kept:
+
+- **What decides it.** The files the engine observes as configuration,
+  compared at every request by a digest of what they hold, never by their
+  times. Each file holds where it really is and the bytes there: its path
+  resolved as the system resolves it when the loader opens it (`realpath(3)`,
+  through a link anywhere on the way, a `..` after a link included), so a
+  configuration kept in a dotfiles repository and linked into the project is
+  kept like any other, and a link pointed elsewhere, the file's own or one to
+  a folder above it, is a change even where every byte is the same. A folder
+  in a file's place, a link that leads nowhere or to a folder, and a file
+  that cannot be read vouch for nothing: then nothing is kept, and the
+  project is loaded at every request. Where the system resolves no path for a
+  regular file that is there and is not a link (some volumes on Windows
+  answer `EISDIR`; a C library that needs `/proc` and has none), the file is
+  compared by its own path as given and its bytes, so the project is still
+  kept; a link above such a file, pointed elsewhere, is not seen there. A
+  link the system does not resolve vouches for nothing. The pointer and the
+  place of the private state are read at every request.
+- **When it is kept.** Two loads in a row, each started after those files
+  were read and found to hold the same, must return the same project as far
+  as the decision reads one: the views it enables, where its pointer is, the
+  data root its local overlay prefers and the roots it protects. A field that
+  differs from load to load, such as a time or a personal-workspace binding
+  kept under a symbol key, does not keep a project from being kept. One
+  load is not enough: a file changed and changed back while it ran leaves the
+  same bytes around a project read from other ones. So three loads keep the
+  project when the service has just started, and two after a change.
+- **For how long.** A kept project is loaded again once it is two and a half
+  minutes old, and is never used once it is five, the interval of the
+  engine's full reconciliation. Whatever no file here names (an overlay named
+  by `MNSTRY_ATELIER_LOCAL_CONFIG` that did not exist at the last load, for
+  instance) is seen by then.
+- **A loader that answers a promise** is never waited for, because the plugin
+  gives a request a second and a half. Its view is told nothing until two of
+  its loads have agreed; one load runs at a time, and a kept project goes on
+  deciding, within its time, while it is loaded again. A load that has not
+  answered within two and a half minutes is given up and its later answer
+  ignored, whether a request or that answer is the first to come after the
+  deadline. A service bound to a personal home (`--personal-home`) has such a
+  loader: it starts from the home alone, and its plugins are told about a view
+  once two of the loads that compose the confirmed generation have agreed. A
+  service given only a loader that answers a promise still refuses to start
+  (see "Personal workspaces" in [obsidian.md](obsidian.md)).
+- **A load that fails** (it throws, it is refused, it is given up, or a file
+  vouches for nothing under a loader that answers a promise) ends whatever
+  was kept, and is asked for again after two seconds, then four, up to
+  thirty, while the files hold the same. A change to them is tried at once,
+  with two exceptions. Until a load has answered and named the files, a
+  corrected configuration waits for the next try. And while one of the files
+  vouches for nothing there is no digest to change, so after a load that
+  failed then (one that answers a promise, or one that answers at once and
+  threw) a change to another file waits for the next try as well.
+- **What the service shows of these loads.** Its status document counts
+  them (`statusLoads`: `answered`, `failed`, `givenUp`, `slow`, `notKept` and
+  `longestMs`). Its log gets a `status-project-loaded` line, with the
+  milliseconds, the outcome, flags and counts and never a path, only for a
+  load somebody has to see, each kind on its own row, written when the row is
+  1, 2, 4, 8 and so on long (from 2 for loads after which nothing is kept):
+  - a load that failed or was given up;
+  - a load that answered at once and took a second or more (`slow`). A second
+    is most of the second and a half the plugin gives a request, spent on the
+    listener's own event loop; a load that answers a promise holds nothing;
+  - a load after which nothing is kept although it named the files it
+    started over (`notKept`, from the second in a row, with `vouched` false
+    while a file vouches for nothing): a load at every request. A load that
+    named other files than it started over (the first, which started over
+    none, or the one after a change that names other files, such as a new
+    confirmed selection) neither counts nor ends that row, so loads that
+    each name other files than the one before are never counted. A start and
+    a change each have one load that names the files it started over and has
+    nothing to agree with yet, so neither writes such a line; each is
+    counted, so a healthy service shows one `notKept` at its start and one
+    after each change. A change that lands while a load reads the files,
+    names the same files, and changes the views or what the workspace is
+    resolved from, makes that load keep nothing as well, and so writes one
+    line and counts two. Any other change that lands then counts one, as a
+    change does, and writes nothing.
+
+  A row of failures goes on through loads that answer between them, and ends
+  at the first load that answers a minute or more after its last failure; a
+  line is written then (`afterFailures`). That line comes with the first load
+  after the minute, which under a kept project is the next reload, two and a
+  half minutes after the load that kept it, and none comes if no load
+  follows. A row of slow
+  loads ends the same way, at a load that answers in time a minute or more
+  after the last slow one. So, while loads come less than a minute apart (a
+  load at every request, or the retries after a failure), a loader that
+  fails, or is slow, every other load or every third keeps one row, written
+  less and less often, instead of a line per load. While a project is kept it
+  is loaded again every two and a half minutes, so there a row of failures
+  ends at the next reload that answers: a loader that answers at least one
+  reload between two failures writes each failure and the load that ends its
+  row, as before, and one that fails at every reload and answers only at its
+  retry keeps one row. Each slow load is written there, as before. A row
+  of loads after which nothing is kept ends at the next load that keeps the
+  project and named the files it started over. A healthy service writes none
+  of these lines. The log is cut over only when it is opened, so a line per
+  load, every two seconds while a file vouches for nothing, would have grown
+  it without bound.
+
 Refusals, before anything else is looked at: `Host` other than the listener's
 literal loopback authority, a cross-site `Origin` or `Sec-Fetch-Site`, a path
 other than one of the nine exactly (a query included), or another method (the
@@ -414,7 +549,11 @@ is authenticated, so they only ever decide what is shown.
   directory changed) and one HMAC per vault; at most four handshakes wait per
   view, and recorded challenges can keep them filled for at most about
   thirty seconds after a restart, since a challenge is answered only within
-  thirty seconds of the time it names.
+  thirty seconds of the time it names. A status request of a session costs a
+  read of the project's configuration files and of its workspace pointer; the
+  project itself is loaded again when one of those files changed, every two
+  and a half minutes, or at every request while one of them vouches for
+  nothing (see "The channel").
 - Egress. `plugins/` is in the egress scan, which fails a request whose target
   is not a literal loopback address, and the release audit requires the three
   plugin files in the package and scans them in the tarball.
@@ -488,6 +627,72 @@ note open in the editor.
 
 ## Evidence
 
+- `test/obsidian-plugin-status-continuity.test.mjs` exercises transient history
+  and the shipped request flow through a finite, socket-free `http.request`
+  stand-in. Canonical channel computations seal the invented replies. It
+  checks refused and timed-out lease/status requests, rejected leases followed
+  by interrupted handshakes, listener proof and answer authentication,
+  republished data, notice deduplication and recovery, and late answers after
+  a channel change or unload. It opens no service or app and writes no plugin
+  data. These tests complement the real-listener and real-app checks below.
+- `test/obsidian-view-permission.test.mjs` asks whether the project allows a
+  view the way the service asks before a status answer, over real project
+  files, the real loader and the real workspace resolution, with no listener,
+  with time a number the test moves: every way a view or its
+  workspace is withdrawn and given back; the workspace's identity compared as
+  well as its place; two loads per change however often a view is asked
+  about; a change that keeps a file's size and modification time; a change
+  that lands during a load; a file the project comes to name; a configuration
+  file that is a link, retargeted, or a link to a link; a folder, a link that
+  leads nowhere and a link to a folder in a file's place; a kept project's
+  time; a loader that fails, with its backoff; and a loader that answers a
+  promise: one load at a time, a change undone and done again while it runs,
+  through a link, a load that never answers, one whose answer comes after its
+  deadline before any request, and one refused again and again; a link whose
+  target has a `..` after a link, and a link to a folder above a file pointed
+  at a byte-for-byte copy; two loads that differ in a time and a symbol-keyed
+  binding, or in a protected root; how long each load took and how it ended;
+  and the service refusing to start on a loader that answers a promise, a
+  refused promise or a thenable. Mutations of the module (a link that vouches
+  for nothing, a project kept from one load whose files are read again when
+  it answers, no deadline, no backoff, no identity check, the files not taken
+  from the load, no time limit, a late answer taken, JavaScript's realpath, no
+  real path for a regular file, the whole project compared, no protected
+  roots compared) and a service that does not refuse each fail at least one
+  of them. It also covers: a late refusal after the deadline; which loads the
+  log report writes (a row of failures or of slow loads kept through loads in
+  time between them until a minute without one, so a loader that fails every
+  other or every third load writes one row; loads after which nothing is
+  kept, from the second in a row, and loads that named other files, which
+  neither count nor end that row) and that a line holds no path; a load at
+  every request written while a file vouches for nothing and while loads
+  never agree, and none at a change that names other files; each input of the
+  workspace resolution (pointer folder, data-root preference, protected
+  repositories) keeping two loads apart; a system that resolves no path, for
+  a regular file and for a link; and, through the test service entry in a
+  child process, a start under `--startup` on a promise, a refused promise,
+  a thenable (its `then` called once) and a refused promise with a `then` of
+  its own that throws (never called), which asks the loader once, records the
+  refusal and ends with 0; and one on a loader that throws `undefined`, a
+  value with no prototype or one whose `code` cannot be read, or answers a
+  project whose `then` cannot be read, which logs `untyped-error` with the
+  text of what was thrown (its message, or the value itself, `undefined` for
+  `undefined`, and `unprintable` when it cannot be made text) and ends
+  with 1. `test/obsidian-personal-selection.test.mjs` covers a locator that
+  answers a thenable (its `then` called once) or throws `undefined`. Ten more
+  mutations (the loader asked twice at such a start, its
+  promise not let go, every load or every failure written, no fallback for a
+  regular file or one for a link too, a late refusal not given up, and each
+  of the three inputs dropped) each fail at least one case, and so do a row
+  of failures or of slow loads ended at any load in time, a load after which
+  nothing is kept written from the first in a row, the first load counted
+  among those, a kept project that does not end that row, a load that named
+  other files counted or ending it, and the files taken as vouching when they
+  did not.
+  `test/obsidian-personal-workspace.test.mjs` keeps a bound personal
+  workspace from the loader that composes in a worker: its views once two
+  compositions agree, nothing while its generation is refused, and the next
+  generation's views once that is bound.
 - `test/obsidian-plugin.test.mjs` runs the shipped `main.js` in a stand-in app
   against a real listener on an ephemeral loopback port: parity of the
   plugin's constants and of every proof and MAC with the channel contract (a
@@ -517,7 +722,13 @@ note open in the editor.
   drift left for the person asked about once),
   and an upgrade; the service publishing the plugin and the plugin it
   published holding the view; qualification from a plugin report, with one
-  launch or two; and `status` and `open` reporting it. A spawn guard refuses
+  launch or two; `status` and `open` reporting it; a view the project turns
+  off or no longer declares, told nothing of what the service stored about
+  it, before the next tick and after it, and told as before once it is
+  allowed again; a project whose pointer is pointed at another workspace,
+  told nothing until it names this one again; and a loader that answers a
+  promise, never waited for, with the plugin keeping its session meanwhile.
+  A spawn guard refuses
   any child of the suite that could reach an Obsidian with the developer's
   own `HOME`.
 - The same file has three real-app tests, skipped unless

package/docs/obsidian.md

@@ -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
@@ -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
@@ -984,6 +995,133 @@ 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.
+  `selection-history-shortened` comes only from a process that read the
+  history longer, which is the running service: a command of the command line
+  reads the history in a process of its own, as it then stands, so `status`
+  reports the selection a cut history ends with while the service refuses it.
+  A confirmed selection is reported by `status` (`selection`: the generation
+  and the number of its record).
+- **The service starts whatever the selection.** A bound project's folder is
+  its private home, so the home alone locates the workspace
+  (`locatePersonalHome`): the service resolves its workspace from that at once
+  and starts, and its engine awaits the loader at each tick. 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`).
+- **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, and nothing is loaded from it while it is shorter; 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.** The removed records put back; a history as long
+  again, since a record in a place already read, with other content, is read
+  as a confirmation (after a cut of one record the person's next confirmation
+  is followed; after a cut of several, one confirmation is not enough); or a
+  start of the service. The number is kept in the process only, so a service
+  started after the cut cannot tell a cut history from one never longer: it
+  reads the history as it then stands and follows what it ends with,
+  publishing it if its generation still holds. Every start counts, the
+  person's own and one at login, after an upgrade or after a failure. Stopping
+  and starting the service is therefore how a person accepts a shorter
+  history, and a start nobody chose accepts it too. Nothing here keeps the
+  number across a start.
+- **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 only the history is read, 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 binding never decides it. It stays this machine's
+  audience setting, none by default, and `audience set` still refuses for a
+  bound project: until an audience is allowed some other way, a bound vault
+  shows no note. Deciding who may see a bound vault is not built.
+- **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.
+
 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 +1149,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](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](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
 
@@ -1227,3 +1482,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.

package/docs/personal-workspace.md

@@ -29,7 +29,7 @@ stable local enrollment keys; matching a recorded remote is an offline change
 check, not proof of upstream membership or provider identity.
 
 The module entrypoint is `src/personal-workspace/index.mjs`; its public package
-subpath is `@mnstry/atelier/personal-workspace`. The API consists of fifteen exports:
+subpath is `@mnstry/atelier/personal-workspace`. The API consists of sixteen exports:
 
 - `MANIFEST_SCHEMA` and `OVERLAY_SCHEMA`.
 - `PersonalWorkspaceRefusal`.
@@ -37,8 +37,8 @@ subpath is `@mnstry/atelier/personal-workspace`. The API consists of fifteen exp
 - `resolvePersonalWorkspace`.
 - `planPersonalGeneration`, `materializePersonalGeneration`, and
   `composePersonalWorkspace`.
-- `selectPersonalGeneration`, `selectionConfirmDigest`, and
-  `readPersonalSelection`.
+- `selectPersonalGeneration`, `selectionConfirmDigest`,
+  `readPersonalSelection`, and `readPersonalSelectionHead`.
 - `inventoryPersonalHome`.
 - `planPersonalRestore` and `restorePersonalInputs`.
 
@@ -127,7 +127,16 @@ remove only their own temporary files. Every failure is a
   reordering refuses `selection-history-corrupt`. Truncating, or consistently
   rewriting, any trailing run of records (up to the whole history) yields another
   valid chain; it changes the returned `head`, so a host that needs to detect it
-  keeps the head it last observed and compares it.
+  keeps the head it last observed and compares it. The Obsidian maintenance
+  service keeps the highest record number it has read a history ending at, for
+  as long as it runs and no longer, and refuses a history that ends earlier
+  (see [obsidian.md](obsidian.md)).
+- `readPersonalSelectionHead({ personalHome })` returns `{ selected, sequence,
+  head }` from the history alone, with `sequence` 0 while nothing is selected.
+  It composes nothing, so it does not say whether the selection is still
+  eligible; the chain is checked as above. It is for a host that composes
+  elsewhere, and that reads the head again to compare it with the one it acted
+  on.
 - `inventoryPersonalHome({ personalHome })` lists what these operations write, for
   review before any deletion the person chooses: the authored files, each
   generation with its eligibility, interrupted staging directories, every

package/docs/release-engineering.md

@@ -257,7 +257,8 @@ offline-only hosts keep the behaviour above:
    online install.
 
 Failures print as `[code] message` with a `Next:` step. The pure classifiers
-are in `scripts/consumer-closure-diagnostics.mjs`:
+are in `src/upgrade/closure-diagnostics.mjs`, and
+`scripts/consumer-closure-diagnostics.mjs` re-exports them for this script:
 
 - `consumer-closure-incomplete`: an offline install or reinstall hit
   `ENOTCACHED`, or the captured lockfile has a registry entry missing