@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/docs/local-review.md

@@ -0,0 +1,84 @@
+# Local source review
+
+The optional review workspace helps a reader inspect claims, ask a question or
+propose a correction, and retain that contribution. It records **locally asserted
+identity**. A typed name is not an authenticated approver. Acceptance does not
+edit source, publish content, grant access or admit a runtime.
+
+Start with `atelier init --template external-project --target NEW_DIRECTORY`.
+Use a destination whose ancestors are real directories, not symlinks. The
+starter refuses existing destinations and does not initialize Git or install
+hooks. Initialize its adapter and synthetic source as separate repositories when
+ready. An established repository can replace the synthetic source through
+`--repo-path source=PATH`; this changes location, never read authority.
+
+From the adapter, run `atelier graph`, then `atelier project`, followed by:
+
+```sh
+atelier review packs
+atelier review run sample.readiness:contract-gate --answers answers.example.json
+atelier dev --review
+```
+
+Open `/review` on the loopback address printed by the foreground sidecar. Enter
+repository `source` and path `README.md`, copy an exact passage, type a question
+or correction, and choose **Save response**. Save is confirmed only after the
+ledger acknowledges the write. On contention, stale content or service failure,
+the wording remains in the form and the page does not claim success. Retry an
+unchanged contribution after restoring service. A changed draft is a new request.
+Unsaved browser drafts are not durable across tab closure.
+
+To resume, save a reading position using the exact passage. Close the page,
+reopen it, enter the same asserted name and choose the recorded **Resume** button.
+The response history remains visible. A position is restored only against the
+same document digest. After a source edit, earlier responses retain their exact
+wording, anchor and original digest; explicitly select a passage in the new
+revision and contribute a new response. Reading and scrolling never imply agreement.
+
+Enter the returned run ID to review individual subject/predicate/object claims.
+Each shows its ID, mapped answer fields, source-reference resolution, source
+identity and a bounded excerpt. References in this first cut resolve exact graph
+node IDs. Free text, URLs and other reference schemes remain unresolved; they
+are never silently treated as source evidence. A linked source establishes
+which bytes were read, not whether they logically support the proposed claim.
+Read the document and record your judgment. Missing mapped sources or required
+answers prevent acceptance. Rejection and revision remain available against
+current evidence, so missing evidence can be discussed honestly.
+
+Accept/reject/revise requires a reason, request ID and expected version. Every
+contribution is immutable. Subsequent versions link through the same claim/run
+identity and target version; proposed successor wording is retained without
+rewriting the original claim. A later rejection supersedes an earlier acceptance
+for current handoff. An identical retry returns the prior record. Another
+reader's intervening contribution refuses a stale version; reopen the run before
+making a new decision. Previous history remains visible rather than being
+collapsed into a single latest-state approval.
+
+**Inspect owner handoff**, or `atelier review handoff REQUEST_ID`, displays the
+proposed relationship, rationale, affected IDs and required evidence digest.
+The source owner decides the concrete edit in its own workflow. Source changes
+remain unapplied and promotion remains unestablished. No owner-application receipt
+or publication authorization is fabricated. Changed source/configuration,
+policy, pack or evaluator inputs make current handoff ineligible.
+
+The legacy readiness score and `ready`-shaped packet fields retain their existing
+contract meanings: input completion and draft preparation. They are not evidence
+confidence, independent rule execution, human acceptance or runtime readiness.
+New claims omit the former arbitrary numeric confidence. Bound snapshots store
+protocol content, normalized answers, pack identity, declared source byte digests,
+policy identity, and the shipped source/schema evaluator inventory. Dependency
+bytes and upstream publisher authentication need separate installation proof.
+Historic v1 runs without snapshots remain available through the existing readiness
+commands, but cannot be accepted as current evidence through this review surface.
+
+The existing sidecar supplies loopback host/origin checks, session nonce checks
+and private-file protection. `--review` is opt-in. The new ledgers live separately
+from legacy proposals under `.atelier-local/review/`. Each record occupies its own
+immutable event aggregate, so existing compaction retains the complete audit
+history. Per-target versions are checked while holding the ledger write lock.
+Local files and locally asserted identities are not protection from an operator
+who controls that same account and its filesystem.
+
+Synthetic installed and browser checks establish software behavior. An unfamiliar
+reader's useful question or correction, assistance required, and actual adopter
+acceptance still need a human observation; automated tests cannot supply it.

package/docs/local-services.md

@@ -99,3 +99,230 @@ A consumer implementation is not complete until tests prove:
 
 Use synthetic fixtures for public Atelier tests. Tenant-specific proof remains
 in the tenant repository.
+
+## The Obsidian maintenance service
+
+The continuous maintenance of Obsidian views (`src/runtime/obsidian/`) is a
+consumer of this contract that ships with Atelier. It keeps one service per
+enabled workspace: a process that ticks the maintenance engine on an interval
+and answers on one loopback port. Its lifecycle is `startService`,
+`serviceStatus` and `stopService` in `src/runtime/obsidian/lifecycle.mjs`.
+
+### Identity record
+
+Each workspace has one record, `state/service/runtime.json`, under the
+workspace's private state root in the machine-private data directory. It is
+never inside a repository or a vault, its directory is owner-only, the file is
+mode 0600, and it is replaced atomically. It satisfies
+`contracts/atelier-obsidian-service-state.v1.schema.json`:
+
+- the service name, derived from the workspace identity;
+- the literal loopback host, `127.0.0.1` or `::1`, never a hostname and never
+  a wildcard address, and the selected port;
+- the executable identity: the path of the service entry module and the
+  SHA-256 digest of its bytes;
+- a random runtime identifier and the PID;
+- the state location, a health description, and the startup consent (who
+  granted it, when, and whether it covers the service only or the service and
+  operating-system startup);
+- in its private part, the random bearer of that one runtime. The bearer exists
+  nowhere else, and nothing that `start`, `status` or `stop` returns carries it.
+
+The record is validated on every read. A record that does not validate, or
+that names another workspace, service or state location, makes `start`,
+`status` and `stop` refuse with `invalid-service-record`. It is never repaired,
+adopted or removed automatically; a person inspects it and removes it.
+
+The port is a machine-specific value. `start` takes an explicit port, or
+selects a free loopback port once and records it beside the consent in
+`state/service/settings.json`, so later starts, `status` and any installed
+unit name the same one. The first start of a workspace refuses without an
+explicit consent that names its actor.
+
+### Health fields and fixed operations
+
+| Operation | Method and path | Credential | Answer |
+| --- | --- | --- | --- |
+| Health | `GET /health` | none | service name, workspace identity, runtime identifier, PID, loopback host and port, executable digest, start time, status |
+| Status | `GET /status` | bearer | the health fields, loop state, last tick, last error code, and per-view freshness with held notes counted, not named |
+| Tick now | `POST /tick` | bearer | the state of the tick that ran |
+| Stop | `POST /stop` | bearer | an acknowledgement naming the runtime and PID, then the service ends |
+
+Health carries no path, no note title, no source name and no withheld
+identity. There is no other operation: no file serving, no command, no
+evaluation, and no route that takes a path or code from a request. The service
+opens no outbound connection, has no telemetry and depends on nothing remote.
+
+The listener refuses a request before looking its operation up when:
+
+- `Host` is not exactly the literal loopback authority it is bound to, which
+  also refuses a name that resolves to loopback;
+- `Sec-Fetch-Site` is present and is neither `none` nor `same-origin`, or
+  `Origin` is present and is not the listener itself;
+- the path is not one of the four, exactly and without a query, or the method
+  is not that path's method.
+
+Status, tick and stop additionally refuse without the bearer of the running
+runtime. A `POST` payload is a JSON object of at most 1 KiB that names the
+runtime identifier it is meant for, so a request aimed at an earlier runtime on
+the same port does nothing.
+
+### Status values and refusal cases
+
+| Status | Meaning | `start` | `stop` |
+| --- | --- | --- | --- |
+| `healthy` | record and health agree on service name, workspace, runtime identifier, PID, executable digest and loopback address, and the PID is alive | reports already running | asks that runtime to stop |
+| `busy` | the recorded port accepts a connection and does not answer health in time, the recorded PID is alive, the recorded entry module still has the recorded digest, and that PID's command line names that entry module (and the recorded runtime identifier when it names one) | reports it as running and busy; starts nothing | refuses with a retry hint; nothing is signalled |
+| `stopped` | no record and nothing listens | starts | nothing to do |
+| `occupied` | something answers on the port without that proof: another program, a silent listener that is not provably ours, or a health answer with any field different | refuses; never takes over | refuses |
+| `stale-record` | the recorded address is closed and the recorded PID is gone | starts; the new service replaces the record once it listens | refuses; nothing is proven to stop |
+| `pid-not-ours` | the recorded address is closed and a process has the recorded PID (the number was reused, or a process outlived its listener) | starts; that PID is never signalled | refuses; that PID is never signalled |
+
+`start` is serialized per workspace, spawns the service without a shell, and
+detaches it only when asked for a service that survives the launching command.
+It waits for health to echo the runtime identifier it generated and the PID of
+the child it created. If that proof never arrives it stops only that child, by
+its process handle, and reports the private operational log,
+`state/service/service.log`.
+
+A tick is largely synchronous, so a healthy service in a long tick may not
+answer health within the deadline. That is `busy`, not `occupied`: it is
+never adopted, never stopped and never started over, and a `start` whose own
+child went straight into a long first tick reports it as started and busy
+instead of ending it. The command line of another process is read from
+`/proc/<pid>/cmdline` on Linux and from `/bin/ps` on macOS. It is not
+established on Windows, where a silent service still reads as `occupied`.
+
+`stop` sends the stop operation to the proven runtime only, waits for that PID
+to end and removes only the generated record. It never looks a process up by
+port, name or pattern. Ending a proven runtime that ignores the request is
+opt-in and is proven again immediately before the signal.
+
+The service itself refuses to start beside a runtime of the same workspace
+that proves itself, and ends cleanly when its record no longer names it. Two
+engines can never tick one workspace together: each tick holds a private
+per-workspace lock, and an engine that finds it held writes nothing and
+reports busy.
+
+### What stop and a hard end leave intact
+
+On `stop` the tick in flight finishes, within a grace period. Drafts in a
+vault, pending edits, recovery copies, staging and the last good view are left
+exactly as they are. The service never sweeps or deletes anything under
+`staging/` or `recovery/`: not at start, on a tick, at shutdown, after a hard
+kill or when it finds a stale record. A publication cut short by a hard kill
+is settled by the publisher's own journaled restart recovery on a later tick.
+
+A tick that fails for a reason nobody typed (a full disk, a crash inside a
+step) does not end the service. Its error code is kept in
+`state/service/last-error.json`, its message only in the private log; the
+delay before the next attempt doubles up to a ceiling, and the next tick
+proceeds.
+
+### Cases that need a person
+
+- a record that does not validate, or that belongs to another workspace;
+- an `occupied` port: decide what owns it, or select another port;
+- an engine lock whose holder is a live process that recorded no health
+  address, a lock written on another machine, an unreadable ticket, or an
+  unknown file in the lock directory. A lock is taken from a holder only with
+  proof that its process is gone, or that it was a service whose recorded
+  address is closed or answers as another runtime or PID. An address that
+  accepts a connection and does not answer in time proves nothing.
+  `inspectPrivateGenerationLock` reports the holder without changing anything.
+
+### Operating-system startup
+
+`buildStartupAdapter` returns the text of a launchd user agent (macOS) or a
+systemd user unit (Linux) from the values it is given. It writes no file,
+installs nothing, runs no service manager and looks nothing up on the machine.
+Windows startup has not been qualified and refuses with
+`startup-platform-unqualified`. Installing a unit is a separate system change
+that needs explicit user authorization; the service refuses to run with
+`--startup` unless the recorded consent covers startup.
+
+The service entry refuses to run without an explicitly selected editor
+adapter. Public Atelier tests start only a test entry whose adapter reports
+that no app runs, in temporary directories, on ephemeral loopback ports.
+
+### The `obsidian` command
+
+`atelier obsidian <operation>` is the noninteractive surface over all of the
+above. With `--json` it prints exactly one JSON document, for a refusal too.
+Exit codes: 0 done, 1 an error nobody typed, 2 a typed refusal or a usage
+error, 3 the operation ran and its answer is not success.
+
+| Operation | What it does | Writes |
+| --- | --- | --- |
+| `status` | enablement, machine settings, proven service state, per-view freshness, whether an apply operation exists | nothing |
+| `scope list`, `scope show ID` | the declared views | nothing |
+| `audience show`, `audience set A,B`, `audience clear` | the audiences this machine lets into a view; none by default, which publishes an empty view. A change invalidates every view at the next tick | private machine settings |
+| `mode show`, `mode set manual\|automatic` | `automatic` refuses without an installed, matching, active automatic policy | private machine settings |
+| `policy show`, `policy install FILE`, `policy revoke` | `install` validates against the apply-policy contract and stores the policy owner-only beside the machine settings, never in a project, a repository or a note. `revoke` marks the stored policy revoked, which the engine reads before its very next dispatch, and returns the mode to manual | private machine settings |
+| `service start`, `service status`, `service stop` | `startService`, `serviceStatus`, `stopService`. The first start needs `--consent-actor ID` | what the lifecycle writes |
+| `service unit --print` | the text `buildStartupAdapter` returns. Installing a unit is not offered | nothing |
+| `open [--scope ID]` | starts or reconnects the owned service, asks it for a tick, reads the view back, qualifies the installed app, has the vault opened | what the service writes |
+
+Reaching the installed app or the operating system is never a default.
+`open`, `service start` and `service unit` refuse with
+`app-adapter-not-selected` unless `--adapter=obsidian-cli` is given, the same
+explicit rule the service entry has, and the modules that talk to an app are
+loaded only after that check. Tests pass their own seams and a guard in the
+test file throws if anything tries to start the app, its command-line tool, an
+operating-system opener or a service manager.
+
+`open` answers one typed outcome, each with a one-line explanation and a next
+step. Only `current` is success:
+
+| Outcome | Meaning |
+| --- | --- |
+| `current` | the proven service ticked after the request; the view's persisted freshness is `current`; read back independently, the trusted generation is the prepared one and every note has the bytes it was published with; the app meets the minimum version, was asked to open this vault, answers for exactly this vault and has finished reading it |
+| `updating` | a publication is under way, a tick outlasted the wait, or a note differs from the trusted generation and has not been looked at yet |
+| `held-for-your-edit` | an edited note is preserved and held |
+| `stale-readable` | a last good vault exists and reads back, but is not proven to be the present generation |
+| `not-prepared` | no generation of this view has been published |
+| `publisher-conflict` | another publisher or an uncoordinated editor holds the vault |
+| `app-missing`, `app-cli-unavailable`, `app-version-unsupported` | no installation; no command-line capability; below the minimum version, or a version that cannot be read |
+| `launch-failed` | the operating system refused, or the app never answered for this vault |
+| `indexing` | the app answers for this vault and has not finished reading it |
+| `service-unavailable` | the service could not be started or is not provably ours (`occupied`, no consent yet, a start that never proved ownership) |
+| `busy` | the service is ours and in a long tick |
+| `disabled` | the integration is off or not declared |
+
+`apply-unavailable` is not an opening outcome. It is reported beside pending
+edits, by `status`, `open`, `mode` and the placeholder `apply` operation, for
+as long as no apply operation is registered. `status` does not repeat a
+persisted `current` while no healthy service proves it: opening a vault
+directly bypasses this command, so an old check is reported as
+`stale-readable` with the reason.
+
+The minimum app version is `MINIMUM_APP_VERSION` in
+`src/runtime/obsidian/app-capability.mjs`: 1.13.7, the only version the
+publication protocol was proven on. A prerelease ranks below its release and a
+version that cannot be parsed never passes. The service entry constructs the
+CLI editor adapter only through `createQualifiedAdapterFactory`: for a running
+app below the floor, an unreadable version or a missing command-line
+capability the factory refuses, the engine records that code as the view's
+freshness reason and nothing is published. An app that is positively not
+running needs no version, because nothing is published through it.
+
+The production probe and launcher (`app-production-seams.mjs`) are written
+against the documented command-line interface and have not been exercised
+against a running app in this repository's tests, by design. They are to be
+qualified on an isolated host before they are relied on.
+
+`atelier sync` does not maintain a vault and does not try. When the enrolled
+project enables the integration, `sync status` gains one member,
+`obsidianMaintenance`, that repeats what maintenance last persisted and points
+at `atelier obsidian status`; it starts no service, ticks no engine and writes
+nothing. With the settings absent or switched off its output is unchanged.
+
+### Registering later work
+
+An apply operation, a proposal adapter and further `obsidian` sub-operations
+are contributions: a module in `src/runtime/obsidian/contributions/` whose
+default export is `{ id, register({ extensions, operations }) }`. The command
+and the service entry both load that directory, so an apply operation
+registered there is the one the service dispatches to and the one `status`
+reports. No dispatch file is edited. A built-in operation name cannot be
+taken, except the placeholder `apply`.

package/docs/local-state.md

@@ -0,0 +1,107 @@
+# Durable local state
+
+`@mnstry/atelier/local-state` provides filesystem mechanisms for local adapters.
+The adapter owns paths, schema, content, transport, authentication, state limits,
+and user-facing recovery. These helpers do not create a service or publish data.
+
+- `publishPrivateFile(path, bytes)` stages and syncs bytes, publishes with an
+  atomic non-overwriting hard link, syncs the directory, and verifies readback.
+  An identical existing file is an idempotent success. A differing file refuses.
+- `acquirePrivateLock(path)` returns an idempotent release function. Callers must
+  release in `finally`, after all asynchronous work has finished.
+- `withPrivateLock(path, operation)` is for **synchronous** operations only.
+- `createVerifiedFileSequence({directory, initial, apply})` reads immutable
+  records in filename order. `initial()` creates reducer state and
+  `apply(text, previous, oneBasedIndex, filename)` validates each record and
+  returns the next state. The adapter validates names, chain, schema and limits.
+  Unchanged prefixes reuse their validated result; file identity and timestamps
+  are checked on each call. Startup verifies the complete history.
+- `isPendingPrivateWrite(name)` recognizes incomplete staging names. They are
+  never committed records. Preserve them for diagnosis after interruption.
+- `syncPrivateDirectory(path)` flushes a directory where supported. Windows
+  directory durability requires target-filesystem qualification; synced file
+  contents alone do not prove survival of power loss.
+
+Use an ignored private directory whose ancestors have already been validated.
+Leaves refuse symlinks. These are local integrity mechanisms, not a sandbox
+against an actor able to rewrite the same user's files or filesystem metadata.
+Do not run old and new writer implementations concurrently against one store.
+
+## Recovery and compatibility
+
+Locks use atomic numbered ownership tickets. A definitely absent local process
+can be succeeded without deleting its ticket. Contending recoverers compete for
+the same next number. Live, reused, foreign-host and unverifiable process IDs
+block. No elapsed timeout grants ownership. The nonce binds release to the
+exact ticket. Legacy PID-only lock records can be bypassed only when the PID is
+definitely absent; unidentified legacy locks require operator diagnosis.
+
+Process interruptions can leave staging files or dead-owner tickets. Retain
+these as evidence. Never clear an entire private-state directory to recover a
+single interrupted operation. A corrupted committed record is still an error;
+the reader does not silently skip or truncate it.
+
+The collaboration ledger retains its existing bounded NDJSON format but writes
+each complete validated successor atomically. Coauthor and intake reuse the
+same ownership protocol. Immutable intake blobs and coauthor values use atomic
+publication. Existing history is not rewritten by these changes.
+
+Adapters should bind retries to the same operation identity and exact input,
+retain newer edits while an earlier save is pending, measure limits in UTF-8
+bytes, and verify runtime build identity before declaring an existing service
+current. Opening a previously verified artifact must not require optional graph
+or projection generation to succeed.
+
+## Evidence boundaries
+
+Local tests inject interruption before publication, verify the previous ledger
+remains readable, restart after an owner exits without releasing, refuse live
+and unknown owners, verify binary readback, and exercise cache invalidation.
+These are process-interruption tests, not physical power-loss qualification.
+No cache promises constant memory or constant metadata work for unbounded
+history. A different checkpoint format needs its own migration and replay proof.
+
+## Ownership diagnostics and offline recovery
+
+`inspectPrivateLock(path)` is read-only and reports availability, reason, newest
+filename and generation. It does not authorize overriding an unresolved owner.
+Only the newest ticket is checked for process liveness. Its predecessor was
+adjudicated when the successor was published. Release now retains the ticket and
+publishes a matching `.released` file; without that marker, removing a successor
+would expose an obsolete PID again. A matching release proves operation completion
+even if a later host name or PID changes. An unresolved newest ticket on another
+host, a reused PID, or an empty legacy lock still blocks with a specific diagnostic.
+A successful successor binds the old legacy lock's exact bytes and supersedes that
+liveness decision. A newly created or changed legacy lock must be adjudicated again.
+
+If the newest owner cannot be established, stop all writers and verify that no
+other machine or process can write this store. Preserve a complete private backup,
+including records and both the legacy lock and ownership directory. With exclusive
+offline custody, move the lock file and its whole `.owners` directory together to
+a uniquely named recovery directory outside the live store. Do not edit individual
+tickets, forge release markers, remove event records or bypass a live owner. Run
+the adapter's history verification before reopening. If exclusive custody cannot
+be established, remain blocked. Do not mix this protocol with an older writer.
+
+Ownership tickets and releases accumulate; adapters must monitor their size and
+perform any retirement under the same offline recovery procedure. Automatic
+age-based cleanup cannot establish whether a writer or operation is finished.
+
+## Filesystem and adapter contract
+
+Publication requires same-directory hard links and atomic non-overwrite creation.
+Unsupported filesystems must fail; there is no copy/overwrite fallback. Qualify the
+actual target filesystem with a disposable write, exact readback and reopening
+before moving a store there. This does not prove physical power-loss durability.
+Incomplete `.atelier-write-<uuid>.tmp` residue is uncommitted. Preserve it until
+writers are stopped and diagnosis is complete; never reap it by age during writes.
+
+`createVerifiedFileSequence` accepts an optional `ignoreFiles` array of exact
+adapter-owned metadata filenames. Those entries must still be regular files.
+All other names reach the adapter validator; unknown or corrupt records must not
+be hidden by a suffix wildcard. Staging names, ownership tickets/release markers
+and synchronous `withPrivateLock` semantics are compatibility obligations of this
+export. Consumers should use the exported helpers rather than infer these formats.
+Locking is non-reentrant. Async callers must acquire/release explicitly in `finally`.
+A release error after a committed operation still reports uncertainty; reconcile
+an operation ID before writing again rather than treating it as evidence of no save.