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

package/docs/obsidian-contract.md

@@ -35,6 +35,11 @@ Portable shapes refuse absolute paths. `atelier-project-config.v1` is
 unchanged: extension settings are validated by their own schema, and an
 unknown extension key refuses in the adapter, not in the project validator.
 
+The `ext-settings` key `ext["mnstry.atelier.personal-workspace"]` is reserved.
+Only a personal-workspace binding sets it, in memory, to name its generation.
+A project whose settings declare it without a binding is refused at every
+build with `personal-binding-lost`.
+
 ## Selection
 
 `selectScope({ canonicalSnapshot, profile, selector, expansion })` is the only
@@ -47,6 +52,31 @@ proceeds in canonical-identity order and reports truncation. Relation types are
 `contradicts`, `belongs_to` and the derived `links_to`. Literal oracles and
 refusals live in `fixtures/obsidian/contracts/oracles/scope-cases.json`.
 
+### Which notes are eligible
+
+The eligibility a view is built with is decided by the machine settings of
+the workspace (`eligibilityFor` in `src/runtime/obsidian/pipeline.mjs`), and
+the engine, source apply, the proposal adapter and the selection operation
+all ask it, so they agree on what a view holds. By default
+(`DEFAULT_ELIGIBILITY`, revision
+`classified-documents/v2+assets-embedded-by-eligible-documents/v1`) a node is
+eligible only when the census classified it. When the audience decision is
+`only-you` with `unclassified: shown`, and only then, an unclassified note is
+eligible too, provided its bytes pass the byte lens the emitter reads notes
+with, and it has no front matter or front matter whose every top-level line
+starts at column 0 with a plain `key:` (an ASCII letter or `_`, then ASCII
+letters, digits, `_` and `-`), none of them `kg`, with indented lines only as
+the values of such keys, and in which the graph's own reading finds no `kg`
+key either. A quoted key, a flow or JSON mapping, a complex key, a top-level
+list, an indented root mapping or front matter the graph could not read keeps
+it withheld, since it may carry a `kg.audience` such as `sensitive`
+(`onlyYouEligibility`, revision
+`classified-documents/v2+unclassified-notes-read-as-notes-for-only-you/v4+assets-embedded-by-eligible-documents/v1`).
+An unclassified note carries the `private` audience, which "only you" admits.
+An admitted note is an ordinary member of the view for the redaction guard:
+its identity may appear in generated bytes of that view, and stays forbidden
+in every view it is not part of. Assets follow the documents that embed them.
+
 ### What redaction covers
 
 The guarantee: Atelier never generates a reference to a note outside the
@@ -635,6 +665,29 @@ again, so bytes that drift under an unchanged pinned digest are not seen by
 describes, and the next observation by digest sees the drift. A note whose pin
 changed is read and verified against the pin as always.
 
+The maintenance engine prepares a view cooperatively (the
+`prepareViewCooperatively` production seam): it waits between notes so that
+the service keeps answering. The bound above holds there too. After a
+cooperative preparation, and again while the publisher holds its locks,
+before the journal entry that says the publication settled and before the
+commit, the engine checks every selected source as observation does: a source
+that still has the stat hint it was indexed with is taken as unchanged and is
+not opened, and one whose hint moved is read and must still be the pinned
+bytes. A source that changed during the tick, or was removed, refuses the
+generation as `mixed-read`: its manifest is not committed, at that tick or by the restart
+recovery of a later one, and the next tick observes in full and prepares the
+view again. The same waits check that the configuration files, the machine
+settings and the eligibility revision are still the ones the tick read. A
+configuration file that cannot be read at such a check (no permission, an I/O
+error) refuses the view as `mixed-read` too, and the tick goes on to its
+other views.
+
+Called on its own, a cooperative preparation reads every selected source
+against its pin once more before it returns, a reused note's included, unless
+its caller says it checks them itself (`scheduling.recheckSources: false`, as
+the engine does). A preparation refused or cancelled on the way leaves the
+preparation cache as it was.
+
 The engine holds one graph file cache and one preparation cache per scope for
 its lifetime and hands them through the `createGraphCache` and
 `createPreparationCache` production seams; a test replaces either with
@@ -740,6 +793,77 @@ Before 0.2.0-alpha.10 no production reading was ever absent, because the probe
 found Atelier's own service; from that release this path, and this window, are
 live.
 
+### First publication into a vault no Obsidian lists
+
+A running or unknowable app that cannot be coordinated with still refuses the
+whole publication, with one exception, the `direct-unheld` path. It is chosen
+at path selection only when all of these hold:
+
+1. The view has no committed generation.
+2. Its vault is the folder allocated for it (`vaultOrigin: 'allocated'`), and
+   that folder's device and inode are the ones its record names.
+3. The app's own settings file (`obsidian.json`) was read, and none of its
+   entries is the vault folder, a folder above it or a folder inside it. Both
+   sides are compared as written and by their real paths, in any letter case.
+   A file that cannot be read is read again, up to three times 50 ms apart,
+   because the app rewrites it with a plain write. A missing or unreadable
+   file, an entry whose folder is not an absolute path, an entry with a `..`
+   segment (the folder it names through a link cannot be placed by its text),
+   or a Flatpak or snap build of the app anywhere on the account (its list is
+   elsewhere) gives no evidence.
+4. The platform is macOS or Linux.
+
+Any other case gives the refusal it gave before. The maintenance service reads
+the evidence from the file and never asks the app.
+
+On this path the publisher writes only creates: a file appears through the
+exclusive link where nothing is, or not at all. A unit that would replace or
+remove a file, or write a settings file over one that is there, refuses as
+`editor-uncoordinated` (blocking) and writes nothing. A settings file that
+already holds exactly what the policy asks is left as it is, which is what an
+interrupted run of this path leaves. A file already at a note path is kept as
+`create-conflict`. The evidence is read again immediately before the first
+unit and whenever two seconds have passed. Once a reading gives none, every
+remaining unit refuses, a kept one included, and nothing is committed. The
+view lock and the vault lock are taken as on every path, and the journal
+records `mode: 'direct-unheld'`. Restart recovery and the late-writer check
+treat it as a `direct` journal.
+
+Why this loses nothing a person wrote, whoever holds the vault: no editor can
+hold an unsaved buffer of a file that does not exist; the link either makes
+the whole file appear or fails because something is there, which is kept; and
+an editor that later saves over a created file wins, and is read as an edit.
+The list evidence is for the experience, and it holds only for a run that
+completes: that run is committed before `open` first tells the app about the
+vault. A run that stops partway commits nothing. That happens when the list
+names the folder meanwhile, a settings file with other bytes is already there,
+or an interrupted run left a replacement or a removal. The view then reports
+`editor-uncoordinated` and falls back to the coordinated path: `open` may add
+the vault to the app and open it before it is complete, and what is left,
+every replacement and removal included, is published through the app with its
+usual base and buffer checks. The person may see an incomplete vault then;
+nothing they write is at risk. Lists this account's app does not keep are
+covered by the argument above alone: another user-data folder, another
+machine through a synced folder.
+
+A maintenance service whose app does not qualify (its command line off, no
+vault open, a version below the floor) no longer keeps such a view from its
+first publication: the publisher is reached with an adapter that coordinates
+with nothing, and takes this path when every condition holds. When the path
+does not apply, or the run stops partway at a unit refused as
+`editor-uncoordinated`, the view reports the app's refusal, as before. `open`
+then answers that refusal without adding the vault to the app, unless the
+person asks it to restart Obsidian (`--restart-obsidian`): the vault is then
+added and opened, and may be incomplete until the app has published the rest.
+One case opens a vault without that flag: with the app running and no vault
+open, a vault the app already lists is opened by its path, as before this
+path existed, and may be incomplete. A run that stops only on a file in its
+way reports that (`create-conflict`). When it stops for more than one reason,
+one is reported: while the app does not qualify, the app's refusal wins over a
+file in the way, and while it qualifies, the first blocking unit's reason is
+reported. A reason not reported comes back at a later run, and nothing is
+written meanwhile.
+
 ### Proven boundary
 
 macOS (Darwin 25, arm64) with Obsidian 1.13.7 (installer 1.12.7), CLI enabled,
@@ -793,9 +917,13 @@ each open item is discharged with its own evidence.
 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.
+policy-owned `.obsidian/core-plugins.json`), the settings file that holds the
+list is the only file of another application that Atelier writes, and in it
+only two things: the view's vault entry and the command-line switch `cli`. To
+write it, Atelier writes nothing else outside the app's user-data directory,
+and no vault note. Every write is shown in `open`'s answer
+(`obsidianSettings`: the file, whether it was created, whether the vault was
+added, whether the switch was turned on, and the backup).
 
 **The file.** `obsidian.json` in the app's user-data directory:
 `$HOME/Library/Application Support/obsidian/` on macOS and
@@ -833,7 +961,14 @@ 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`.
+`no-vault-open`, unless the person asked for a restart (below).
+
+**While Obsidian runs with its command line off**, it answers every command
+but a link with "Command line interface is not enabled", read as
+`app-cli-unavailable` / `cli-turned-off`. The file is the running app's, which
+holds the switch in memory and writes it back with its list, so it is not
+written; the switch is turned on only while no Obsidian runs, or through the
+restart below.
 
 **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
@@ -879,19 +1014,21 @@ then:
    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
+   old list. A missing file means Obsidian never started on this account; it
+   is created as described under "Obsidian never started" below. 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`).
+3. A vault whose real path an entry already has is left as it is. When `cli`
+   is already `true` too, 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`).
+   ts: <now, ms>, open: true }`, unless the vault is listed already, and with
+   `cli` set to `true` when it is not (the command-line switch: in its place
+   when the file has the key, otherwise last, as the app adds it). 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.
@@ -912,6 +1049,91 @@ then:
 
 Every refusal writes nothing and leaves nothing behind: a temporary file or
 backup created on the way is removed again whichever later step fails.
+
+**Obsidian never started.** When the file does not exist and the process
+table says, positively, `absent` (read before, and again immediately before
+the file appears), the file is created, and only then:
+
+1. The user-data directory must be this user's own real directory. When it
+   does not exist, it is created with mode 0700, only inside an existing
+   parent directory that is this user's own and no link; a missing parent is
+   `obsidian-settings-missing`, and nothing is created above the directory.
+2. The content is exactly `{ "vaults": { "<16 hex>": { "path": <the vault
+   root's real path>, "ts": <now, ms>, "open": true } }, "cli": true }`, mode
+   0600. The app reads the file at start-up (a missing or unreadable one reads
+   as no settings) and opens every vault flagged open, so a plain start opens
+   this one, with its command line on.
+3. The bytes are written and fsynced to a temporary file in the directory,
+   which is then hard-linked to `obsidian.json` and removed: the file appears
+   complete or not at all, and the link fails on any file there, one the app
+   wrote meanwhile included, which is kept (`obsidian-settings-changed`). The
+   directory is fsynced. There is nothing to back up.
+4. An app that appears before the link refuses (`app-may-be-running`); one
+   that appears right after it leaves the addition unconfirmed, as in step 7
+   above. A refusal removes the temporary file and a directory created on the
+   way.
+
+`open` answers `registration.how: 'created-settings'` for it.
+
+**Restart, only when the person asks** (`open --restart-obsidian`; never
+implied, and refused by every other operation). Only in the two states above
+where the app runs and cannot be reached: its command line off, or no vault
+open and the view's vault not in its list. Module:
+`src/runtime/obsidian/app-restart.mjs`.
+
+0. Read-only, before anything is sent (`settingsWriteOutlook`): the view's
+   vault folder exists, the settings file reads as in step 2 above (no
+   Flatpak or snap build), has one name, would stay within 4 MiB with the
+   entry, and lists no vault at a folder above the vault's. A file that does
+   not exist (the app has shown only its starter window, which writes none)
+   is the create case, checked as "Obsidian never started" checks before it
+   writes (step 1 there); it is created after the quit. Otherwise `open`
+   answers that refusal and the app keeps running. Once the main process is
+   proven (step 2 below), right before the first signal, a copy of an existing
+   file is kept beside it under the backup name (`backupObsidianSettings`,
+   fsynced, the file's mode; `restart.settingsCopy`); a copy that cannot be
+   kept sends nothing. The write in the same run does not prune that copy
+   (`keepBackups`); a later write prunes it as step 7 says.
+1. The app's main process is proven from the process table
+   (`ps -ww -A -o pid=,ppid=,uid=,comm=`; a uid is signed, since macOS shows
+   `nobody` as -2): every Obsidian process (the names the process probe
+   counts) runs as this user, exactly one names the app bundle's main
+   executable by an absolute path (`…/Contents/MacOS/Obsidian`), and every
+   other one is its child. `comm` is the process's argv[0], not a verified
+   image: a process of the same user could take that name, which proves
+   nothing while the real app runs too (two main processes). Otherwise nothing
+   is sent (`app-main-process-unproven`, with `restart.detail`).
+2. That process is read again (`ps -o ppid=,uid=,lstart=,comm=`): it must be
+   this user's, under the parent the table showed, with the same name, and
+   read the same twice in a row; then it, and only it, gets SIGTERM, which
+   Electron handles as a quit. The app closes every window, keeping the
+   vaults that were open flagged open, and its helpers end (1.13.7, checked on
+   an isolated instance).
+3. The process probe must say `absent` within 30 seconds. On macOS the main
+   process can stay after the first SIGTERM, with no window (seen on
+   an isolated 1.13.7, with vaults open and with only the starter window).
+   Electron handles only the first SIGTERM as a quit; a second one ends the
+   process at once, without its quit handlers. It is sent once, only when the
+   table shows that same process alone (no helper) and it reads the same, at
+   two readings at least 5 seconds apart. There is never a third signal, and
+   never another kind; `restart.signals` counts the signals delivered.
+   Otherwise `open` answers `launch-failed` / `app-did-not-quit`, writes
+   nothing and starts nothing.
+4. The file is written as above, with the vault and the switch.
+5. The app is started plainly (`open -b md.obsidian`) by the launch steps
+   below, and reopens its vaults and this one. An answer given after the quit
+   and before the launch (the file could not take the vault, say) starts the
+   app plainly first, as it was; a start that fails is said, with the next
+   step to start it by hand.
+
+The answer carries `restart: { asked, state, quit, signalled, pid, signals,
+settingsCopy, startedAgain }`, and `reason` and `detail` when it did not quit.
+An `open` interrupted between the quit and the start leaves the app quit (a
+known limit). At a terminal the restart still needs the flag; the question the
+design asks in that state comes with the first-run command. Qualified on macOS only; elsewhere the answer is
+`restart-platform-unqualified`, since a quit app there is started with a
+link, which would drop the other vaults' reopen flags.
+
 `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
@@ -925,7 +1147,13 @@ plainly (`open -b md.obsidian`), which reopens every vault the list flags open
 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
+this launch started, since that would reach it while it starts. A link the
+started app did not take is left to it when the list flags the vault open,
+since the plain start reopens it; for a listed vault that is closed, which a
+plain start does not reopen, the link is handed once more, through the tool
+only (this launch started the app), one wait round later, before `open`
+answers `launch-failed` /
+`app-did-not-answer-for-this-vault`. 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
@@ -1095,6 +1323,7 @@ today) it refuses `exchange-unavailable`. Both write nothing.
 | `interrupted-before-exchange`, `apply-interrupted-needs-person` | what restart recovery decided for an interrupted apply |
 | `recovery-state-unreadable` | a candidate, backup or source path of an interrupted apply may not be looked at or read; nothing is settled from a read this process was denied, that record is reported with its intent still open, and every other one is still settled |
 | `apply-outcome-unknown` | the source was exchanged and the settlement from digests could not be carried out; the source may have been changed, the intent stays open and `apply recover` decides |
+| `personal-overlay-proposals-only` | the note is a private note of a personal workspace, whose file belongs to a module-owned generation; nothing is written there. The proposal adapter's observation answers the same edit with `personal-overlay-not-proposed`, and records nothing |
 
 A path that another program removes or replaces between two steps, before the
 intent is recorded, answers one of these refusals (`source-missing`,
@@ -1317,7 +1546,9 @@ line, 16 MiB, 10,000 events, and an unreadable line refuses every append.
 | `ledger-corrupt` | refused, for that repository only; other repositories progress in the same tick |
 | `store-unavailable` | the store cannot be read or is locked now; waits like a full one |
 
-A waiting operation is tried at most 8 times, 60 seconds after the first attempt
+For a personal workspace whose graph the engine has not confirmed yet, a due
+operation is left as it is (`personal-validation-pending`), and that tick is not
+counted as an attempt. A waiting operation is tried at most 8 times, 60 seconds after the first attempt
 and twice as long after each, up to an hour. At most 8 operations per repository
 and 64 unexamined edits are looked at per tick. A repository holds at most 4096
 operations, 256 of them open, 64 records of 16 KiB each; a full queue refuses