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

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
@@ -740,6 +770,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 +894,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 +938,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 +991,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 +1026,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 +1124,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 +1300,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 +1523,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

package/docs/obsidian-plugin.md

@@ -104,18 +104,48 @@ at the maintenance service's next tick, with nothing changed at the view's
 sources: the service compares the plugin files each committed generation pins
 with the disk, has a view whose files differ prepared again, and a generation
 that is already committed is published again, as it is, with its notes kept.
-A drift left for the person is asked about once, and again once it changes;
+A drift left for the person is asked about once, and again once it changes.
+What a publication could not change is not asked about again: a drift that
+publishing cannot repair (the data file of a vault root that is a link, say)
+is asked about at most once more after a publication that left it, which
+writes no vault file (the view is prepared again and takes the vault's lock,
+and for that tick shows as `stale`, then `updating`, before it is `current`
+again), and not again after that. A plugin file
+another writer removes or changes after the publication, even while the same
+tick goes on, unless it holds again what it held before the tick under the
+same pin and vault root, and a path
+the person repairs before the tick ends (the vault root made private,
+say), is asked about at the next look and written;
 where the plugin is turned off in the vault, a pinned file that is gone is no
 drift. Publishing a committed generation again needs the app when one runs;
 if that app does not qualify, nothing is written, the view stays `current`
 (a committed generation needs no app, so an app that cannot be qualified
 never makes a current view stale), and the file is written at a later
 attempt, on the retry schedule of an unsettled view, once the app
-qualifies. (The settings files are held to the same rule for a file nobody
+qualifies. A drift that publishing would only leave for the person again
+(the data file of a vault root that is a link or not private, a folder where
+a file goes) is no reason to publish again and needs no app: the path is
+left as it is, and the view keeps its plain reason. Nothing in `status` or
+`open` names such a path yet; without its data file the plugin cannot reach
+the service, so it shows as not present (`no-live-lease`). A few paths the
+publisher leaves for the person still count as a drift here, and wait for the
+app as one: a file nobody may read, a parent folder that cannot be looked
+into, and a vault root Atelier keeps whose mode cannot be changed. Until the app qualifies, a
+view waiting for it has the reason
+`verified-by-read-back-plugin-waits-for-app` rather than
+`verified-by-read-back`, and `status` and `open` add `plugin files wait for
+the app` to the plugin line (`files: "waits-for-app"` in `--json`), with a
+next step for the plugin. (The settings files are held to the same rule for a file nobody
 may read.) A plugin file that another program changes while a publication runs
 is a race and is handled like one on a note: that publication does not
 commit, the view is tried again, and the file is planned from the disk anew
 (`plugin-file-changed`); nothing reads a plugin file as an edit of a note.
+The view is then `publisher-conflict`, and its next step in `status` and
+`open` names that file as what stopped the publication (changed by another
+program or by the person; one change is enough), rather than asking the
+person to close another publisher; the same holds for a settings file
+(`settings-changed`). The reason is the first unit that stopped the
+publication, so other causes are not ruled out.
 Upgrades replace the plugin files the same way. The plugin's version in
 `manifest.json` changes whenever its code does, and the test suite holds the
 two together: the app keeps running the `main.js` it loaded until it reloads
@@ -423,10 +453,14 @@ answer decides wherever it gives one:
   and opens by path the vault the app lists. Where the settings file does
   not show it (a sandboxed build, say), or where it lists it and, once the
   vault is opened, the command line still does not answer for it while only
-  the plugin reports the version, `open` answers at once
+  the plugin reports the version, `open` answers
   `app-cli-unavailable` / `vault-open-cli-silent`: the plugin shows the vault
   open, so the command line is what did not answer, and waiting for the app
-  would change nothing.
+  would change nothing. After a launch that answer is given at the second
+  such round in a row, not the first: one tool call that timed out while the
+  app was busy opening its window looks the same once, and `open` then goes
+  on waiting for the vault. A wait that ends right after one such round gives
+  the same answer.
 - Whether an app runs is the process table's answer, which says no only when
   it finds no Obsidian process at all. A lease outlives its app by up to the
   lease time (six seconds after a crash), and any process that holds the