@awebai/oats 0.25.8 → 0.26.0

package/docs/design/package-runtime-api.md

@@ -1,588 +0,0 @@
-# Package-runtime API contract (addendum to the package-engine contract)
-
-Status: **SUPERSEDED** with its parent (workspace model v2 — see [2026-09-23-workspace-module-contracts.md](2026-09-23-workspace-module-contracts.md)); kept as history. Original status: **FROZEN** for the capability-materialization delivery, as an addendum to
-[`package-engine-contract.md`](./package-engine-contract.md). It answers the
-maintainer's four clarifications on the M1 freeze (maintainer review of
-1db919b): the public package-runtime boundary, the npm runtime closure,
-incremental transaction semantics, and runtime-validated schema invariants.
-Changes go through the coordinator to the maintainer.
-
-**What capability materialization changed here.** §1 (the public CLI boundary) is
-unchanged. §2 keeps every npm rule and moves the materialization root from the
-package root to each declared *capability* root, because the closure now lives
-inside the materialized artifact. §3 becomes incremental with respect to the
-*capability store*. §4 states the current lock invariants and the prototype-safety
-requirement. §5 records that a `"."` capability root is read compatibility only,
-discriminated by `configTemplates` rather than `configs`. §6 records that v1 is
-the only legacy format supported, and that the earlier transitional package-root
-`lockfileVersion: 2` is unsupported input rather than something to migrate.
-
-## 1. Public package-runtime boundary (structured CLI API)
-
-**Transport choice: the structured CLI API.** Rationale (tradeoff surfaced to
-the coordinator/maintainer before freezing, mail 09447984): a process contract
-is a true version boundary — it survives kernel-internal refactors and node/ESM
-changes, nothing private is importable by construction, and it extends the
-already-proven Desktop CLI API v1 envelope discipline instead of creating a
-second public JS surface that must be kept in semver lockstep with the CLI
-forever. The rejected alternative (a blessed `lib/runtime.mjs` import resolved
-via `oats root`) preserves exactly the dynamic-import coupling the maintainer
-ruled out.
-
-**Rule: independently released packages MUST NOT import kernel-private
-`lib/core.mjs` (including via `oats root` + dynamic import).** Package
-commands/hooks execute the CLI at the exact absolute path the dispatcher
-provides in `OATS_CLI_BIN` (§1 item 4) — never by resolving `oats` from PATH,
-which is untrusted inside worktrees.
-
-### Envelope and versioning
-
-Every boundary command supports `--json` with the Desktop CLI API v1 envelope:
-exactly one JSON object on stdout — `{ schemaVersion: 1, ok: true, result }`
-or `{ schemaVersion: 1, ok: false, error: { code, message } }` — nonzero exit
-on failure; progress prose only on stderr.
-
-- **Versioning** (maintainer ruling): the boundary is versioned by the
-  **compatibility floor plus a pinned consumer fixture** — the boundary shipped
-  in kernel **0.19.0** and is unchanged by capability materialization; the
-  materialized store and the capability-materialization lock (which REPLACES the
-  earlier package-root spelling in place and remains `lockfileVersion: 2`) raise
-  the floor for packages that rely on the new manifest surface
-  (`configTemplates`, dedicated capability roots), which
-  declare the materialization release's floor instead. Official packages declare
-  their floor as `compatibility.oats: ">=<floor>"` in `oats-package.json` (and
-  capability `compatibility.oats` likewise), and each consumer repo pins the kernel
-  consumer-fixture version its CI probes against. The exact Desktop
-  `oats version --json` probe payload is NOT extended (no `packageRuntimeApi`
-  field) — Desktop API compatibility is a separate contract.
-- Kernels below the floor are rejected by the consumer's normal
-  compatibility check (`incompatible-oats` at acquire; the consumer fixture
-  asserts the rejection).
-
-### Commands (exact surface, boundary v1 — maintainer-ruled minimal)
-
-The public boundary is HIGHER-LEVEL than the private core calls it replaces:
-private `findAgent`/`upsertLocalAgent`/`spawnInstance`/`resolveOatsConfig`
-usage maps onto capability-defined agents, `oats spawn`, and dispatch-provided
-settings — not onto one-for-one public equivalents. File-of-record for the
-consumer inventory: `packaging/oats-okf/KERNEL-API-NEEDS.md` on kernel branch
-`integrations-expert/official-packages-staging` @ `60d5eb6` (design input;
-this contract remains authoritative).
-
-1. **Capability-defined agents own lookup/registration/ephemerality.** A
-   package capability declares its service agents in its manifest `agents:`
-   (package-relative soul dirs, e.g. oats.okf ships
-   `agents/memory-harvest/{soul.yaml,AGENTS.md}`). `oats spawn <agent>`
-   resolves capability-defined agents for the active context, scaffolds a
-   fresh soul homed locally, and applies ephemeral (`kind: "capability"`)
-   semantics automatically. There is NO public `oats agent show`,
-   `oats agent upsert`, or generic `--ephemeral` flag — add such a surface
-   only when a reusable use case proves it.
-2. **Spawn** — `oats spawn <agent> ... --json` with the EXISTING flags:
-   `--purpose <slug>` (deterministic derived naming
-   `<agent>-<purpose>`; no raw instance-name authority), `--parent`,
-   `--repo`, `--work attached|worktree|checkout|workspace|directory`, `--work-dir`,
-   `--branch`, `--model`, `--task`/`--task-file` (owner-only tempfiles:
-   mode 0600, removed on every outcome). Existing validation and error codes
-   (`E_BAD_ARGS`, `E_PARENT_NOT_FOUND`, `E_SPAWN_FAILED`, ...) are part of
-   the contract; result is the fixed Desktop CLI API v1 spawn shape
-   (`{ instance, agent, home, work, tmux, ... }`). If an accepted consumer
-   mode cannot be expressed by an existing flag, ONE narrow flag is added
-   with JSON tests — never a general override.
-3. **Settings via dispatch** — `oats <namespace> <command>` passes the active
-   capability's EFFECTIVE settings to the dispatched process as
-   `OATS_SETTINGS` (JSON; from the instance metadata snapshot or the resolved
-   context), the same contract lifecycle hooks already have. Capabilities
-   read their settings (e.g. oats.okf's `harvest-model`) from `OATS_SETTINGS`;
-   there is NO public resolved-config read command.
-4. **Consumer rules**: a package command executes the CLI at the exact
-   absolute path the dispatcher or lifecycle runner provides in the
-   **`OATS_CLI_BIN`** environment variable (beside `OATS_SETTINGS`), via
-   `execFile` on that path — **never** by resolving `oats` from `PATH` and
-   never through a shell: PATH is not a trusted runtime boundary, and package
-   commands run in worktrees where it can be shadowed. The consumer parses
-   the one schema-v1 envelope, emits its own envelope, and never imports
-   `lib/core.mjs` or calls `oats root` for kernel-file resolution.
-
-Error codes are part of the contract: `E_USAGE`, `E_BAD_ARGS`,
-`E_UNKNOWN_COMMAND`, `E_SPAWN_FAILED`, `E_PARENT_NOT_FOUND`,
-`E_RELATIVE_NOT_FOUND`, `E_RELATIVE_AMBIGUOUS`, `E_CAPABILITY_BLOCKED`,
-`E_CAPABILITY_INACTIVE`.
-
-### Directory execution for capability workers
-
-A worker may explicitly select `work: directory` in its packaged `soul.yaml`,
-pass `--work directory` to spawn, or use `spawnInstance(..., {work: "directory"})`.
-This is a generic execution mode, independent of any knowledge provider.
-Consumers using it must declare the directory-mode release as their
-`compatibility.oats` floor, not the older boundary-v1 floor alone.
-
-- `repo` / `--repo` is an **existing config context directory** in this mode,
-  not a Git requirement or an edit target. Relative paths resolve from the
-  agents root's parent; absent a selector it defaults to that deployment scope.
-  The CLI does not substitute its ambient Git checkout. A configured workspace
-  can discover and spawn declared package agents before it has an `agents/` or
-  `local-agents/` directory. Laptop config alone does not declare a deployment.
-- `<home>/work` is a new, owned directory, not a symlink and not a fake Git
-  repository. The kernel creates no branch, copies no source tree, and does not
-  require Git in a non-Git deployment. Git-owned deployment placement still
-  requires readable Git metadata to establish the canonical home location.
-- `--work-dir` / `workDir` and `--branch` / `branch` are contradictory and
-  rejected with `E_BAD_ARGS`, even if empty or inherited from a caller bug.
-  Directory execution never takes ownership of a caller-selected filesystem
-  path. Existing modes retain their Git/context requirements and semantics;
-  failed Git operations never implicitly fall back to directory execution.
-- Canonical `AGENTS.md` / `CLAUDE.md`, skill composition, provider trust,
-  lifecycle hooks, frozen launch recipes, runtime preflight and no-launch
-  metadata are unchanged. Hooks receive `OATS_WORK=directory`, an empty
-  `OATS_BRANCH`, and the context in `OATS_REPO` / `OATS_CONTEXT` at spawn.
-  Worktree-only setup scripts are not run in this mode.
-- Retirement authenticates directory ownership against the independent spawn
-  baseline. Nonempty execution work is preserved in verified recovery custody
-  (`workRecovery.path/work`, with home bytes under `home/`) before removal;
-  post-hook changes produce another verified snapshot. No work is designated
-  disposable in this initial mode, including hook-created work. Symlinks inside
-  work are copied as links, never followed; an exchanged work-root symlink,
-  unsupported filesystem entry, or unverifiable copy fails closed. Recovery is
-  not provider delivery or publication, and retains the existing single-host,
-  quiesced-runtime safety model rather than a hostile-filesystem atomicity claim.
-
-### Lifecycle and scheduled-command context
-
-Lifecycle hooks receive `OATS_CLI_BIN` as the real, absolute `bin/oats.mjs`
-path belonging to the **running kernel**. This is authored by
-`runLifecycleHooks` itself, including direct core callers; neither ambient
-`OATS_CLI_BIN` nor a caller's `extraEnv.OATS_CLI_BIN` can override it. Spawn
-hooks also receive the known agents root as `OATS_ROOT`, rather than an empty
-value or the ambient caller's root.
-
-Scheduled command execution starts without the invoking instance's identity:
-`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, legacy `OATS_HOME`, the `PI_AGENT_*`
-aliases and `PI_AGENTS_ROOT`, plus kernel-authored soul, root, context, work,
-team, capability, operation, settings and lifecycle metadata are removed.
-The command's explicit cwd and selectors (for example `--soul`) determine
-its dispatch; a scheduler invoked from another home must not select that
-home's frozen capabilities/settings. Host configuration (`HOME`,
-`OATS_HOME_DIR`, package catalog configuration) and ordinary credentials are
-preserved. No job schema or knowledge-provider policy is implied by this
-isolation.
-
-### Native record capture result
-
-`oats capture --home <dir>` (also `turn-record capture --home <dir>` and the
-standalone `capture.mjs`) answers **native JSON**, not a Desktop schema-v1
-`{ok,result}` envelope. Do not add `--json`: `--home` already selects JSON.
-Diagnostics go to stderr, including lock contention without `--quiet`.
-Existing home/owner/appended/session boundary fields remain; the outcome adds:
-
-- `status`: `complete`, `skipped`, `held`, `incomplete`, or `failed` (failure
-  takes priority, then skip/held/incomplete).
-- `complete`: true only for a performed pass with no holds, incomplete source
-  records, unattributed candidates or reported errors.
-  An unchanged performed pass may be complete with `appended: 0`.
-- `skipped`: true when another pass owns the capture lock. `lock` then carries
-  holder/liveness/recovery details; no capture or indexing was performed.
-- `held`: count of sessions the underlying pass held pending a timestamp.
-- `incomplete`: count of source files with pending torn, oversized, invalid
-  UTF-8 or otherwise incomplete records; later complete input can recover.
-- `issues`: optional metadata-only diagnostics identifying source paths and
-  reasons; no record bodies are embedded. `unattributed` candidates also make
-  the pass incomplete rather than silently certifying missing source evidence.
-- `failed`: zero on success, nonzero for a capture/read/index/lock-release
-  failure; `error` describes the failure. `appended: null` on a thrown failure
-  means the number appended before the failure is unknown, not zero.
-- `ignored`: count excluded by configured privacy rules, distinct from a
-  whole-pass skip. Home capture pins exactly attributed source files; sharing
-  a Codex day directory does not authorize capturing unrelated records.
-
-Lock skips, held sessions and incomplete input retain exit status 0 (background reconciliation
-must stay nonfatal on contention); errors and failed lock release exit 1.
-Previously captured visible boundaries may still be returned on a skipped or
-held pass. They are **not** evidence that final capture ran. Consumers requiring
-a final pass must check `complete === true`, not exit status or the presence of
-boundaries alone; older results lacking that field cannot certify a pass.
-
-**Snapshot boundary:** completion describes a performed pass over the exact
-attributed source files, not a promise about future appends. Discovery carries
-an open-descriptor-derived identity and content witness through capture-lock
-acquisition. Capture stages bytes from one descriptor and validates that witness
-and source stability **before appending**: replacement, truncation and prefix
-rewrites fail without appending the replacement's bytes. Same-inode append
-growth is allowed only when the witnessed prefix is unchanged. Discovery/read
-failures and files disappearing during the pass fail closed; pending trailing
-records and unattributed candidates cannot certify completion. A retirement
-consumer must first quiesce its writers and then preserve the captured evidence
-under its own durable-input protocol. `complete:true` alone does not mean a
-harvest was delivered or that a consumer stored those inputs. Configured privacy
-exclusions remain exclusions, not an invitation to copy excluded source bytes.
-
-**Native roots:** managed `--home` capture uses independent execution history,
-not the observer's environment or the latest relaunch recipe. New scaffolds
-initialize `<instances>/.oats-native-record/<sha256(canonical-home)>/history.json`.
-Each managed spawn/start/restart writes a separate pending receipt before
-backend dispatch. Inside the backend shell, under the exact environment prefix
-and cwd that will exec the harness, the native recorder atomically replaces
-that receipt with the effective absolute **record locations** and runtime. Only
-these allowlisted locations, home, start id/time and custody state are saved;
-no environment map, credential reference value, task or argv is persisted.
-The saved `instance.json` command/recipe remains a relaunch **template**, not
-execution evidence: use `oats session start`, not a manual shell replay of it.
-
-Location rules at execution are `CLAUDE_CONFIG_DIR/projects` (default exactly
-`$HOME/.claude/projects`), `PI_CODING_AGENT_DIR/sessions` (default
-`$HOME/.pi/agent/sessions`), and `CODEX_HOME/sessions` (default
-`$HOME/.codex/sessions`). Pi's `--session-dir` wins over
-`PI_CODING_AGENT_SESSION_DIR`, which wins over its agent-dir location; Pi tilde
-paths expand against the effective HOME. Relative paths resolve from the source
-home. Existing symlinks resolve at recording time, including existing ancestors
-of not-yet-created roots. Inherited overrides and resolved `fromEnv` location
-inputs are thereby retained **after backend shell startup**, independently of
-later observer/config/reference changes. The recorder runs before the native
-exec; unsupported explicit Pi `--session` or a receipt write failure refuses
-that exec and leaves pending custody, rather than claiming a default root.
-Wrappers must preserve this native storage contract: arbitrary scripts which
-change storage internally cannot be inferred from their executable name.
-
-History is never replaced by a newer runtime selection, truncated with the
-bounded restart log, or deleted with the source home. Capture unions all
-historically recorded locations for each runtime and still attributes every
-file by its own cwd. Missing/unreadable historical roots, unreadable/invalid
-receipts, and pending/unfinished launches fail closed. A newly scaffolded home
-with no managed launches has an authoritative empty managed-launch inventory.
-A legacy home without that scaffold authority cannot acquire proof of its
-**earlier** roots merely by restarting: later starts retain new locations but
-its history remains incomplete. Do not remove pending/history receipts just
-to get a green capture; recovery requires establishing the source inventory.
-
-Standalone fixtures and explicit legacy inventories can opt into
-`capture --home <dir> --current-roots` (`sourceRoots: "current-env"` in JSON),
-or use `sessionsForHome(home, {roots: {cc: [...], pi: [...], codex: [...]}})`.
-Explicit API roots exclude unspecified formats, and every supplied root must
-exist. The CLI fallback uses current environment plus recorded hook/config
-location overrides; `fromEnv` resolves from that **current** base environment.
-Its `complete:true` certifies only that chosen observer-time inventory, **not**
-all historical roots; do not enable it implicitly for final-capture consumers.
-Normal managed reports say `sourceRoots: "launch-history"`. Background capture
-without `--home` retains observer-time discovery (including `.claude*` profiles)
-and optional absent native defaults. Neither fallback introduces knowledge
-policy into the kernel.
-
-**Claude children:** discovery also enumerates the native
-`<project>/<sessionId>/subagents/*.jsonl` layout, including children whose parent
-transcript is absent. Each child requires its own cwd attribution; neither its
-parent's cwd nor its directory supplies missing attribution. Child streams use
-`cc.<sessionId>.<child-file-stem>` (threads
-`cc:session:<sessionId>.<child-file-stem>`) so identical child filenames under
-different sessions cannot collide. Complete native lines are preserved verbatim;
-torn, unstamped or unattributed child evidence blocks certification, and child
-read/discovery failures fail the pass. Ignore rules run before child opens and
-can match its path, filename, qualified id, native child id or parent session id.
-
-**Piped recall:** native `oats recall` JSON responses drain stdout before process
-termination, including large thread windows and individual `--show` records.
-Consumers must still bound their own reads/buffers (use `--ids-only` for sizing);
-a successful producer does not imply an unbounded consumer buffer.
-
-### Consumer fixture
-
-The engine ships a consumer fixture driving the full oats.okf pattern
-exclusively through this surface: a capability-defined `memory-harvest`
-agent resolved and spawned via `oats spawn --json` in all three source modes
-(local-soul / workspace-mode / repo-resident), parent relation,
-purpose-derived naming + debounce, model via `OATS_SETTINGS` dispatch,
-task-file privacy/cleanup, clean JSON success/failure, no private
-import/`oats root` lookup, Pi + Claude scaffold parity, and sub-floor kernel
-rejection. WS3 reuses the fixture shape as each official repo's per-repo CI
-probe, combined with the acquire → lock → trust → activate → spawn probe
-from `test/packages.test.mjs`. (The oats.okf tree changes themselves —
-`agents/memory-harvest`, dropping the core import — are WS3 deliverables.)
-
-## 2. Capability-local npm runtime closure
-
-- **Detection and placement**: materialization roots are the manifest-declared
-  CAPABILITY roots — each one carrying BOTH `package.json` AND
-  `package-lock.json` is materialized independently, and the resulting
-  `node_modules` becomes part of that capability's materialized artifact. This
-  is what lets an inner `oats.json` resolve resources via `node_modules/...`
-  relative to its own manifest (e.g. oats-aweb's
-  `node_modules/@awebai/pi/skills/...`) inside a self-contained artifact.
-  A **package-root-only** closure has no durable home and is NOT
-  materialized: it is package tooling. If a capability actually depends on it,
-  self-containment fails and the package is rejected
-  (`capability-not-self-contained`) rather than silently installing a broken
-  artifact. For a legacy `"."` capability root the capability root *is* the
-  package root, so that package-root lock is the capability's own closure (it is
-  detected once, not twice). Directories not enumerated by the manifest are
-  never scanned.
-- **When and how**: materialization runs IN STAGING during acquire, update and
-  restore, after payload integrity verification and BEFORE the capability
-  artifact's integrity is computed or swapped in. The command is exactly
-  `npm ci --omit=dev --omit=peer --ignore-scripts` (plus `--no-audit
-  --no-fund` noise suppression) per materialization root — **dev AND host
-  peer dependencies are omitted**; **no npm lifecycle scripts ever run**, at
-  any phase. A package may consume host-provided peer APIs only through an
-  explicit supported host boundary (§1) — never by auto-materializing an
-  unrelated harness peer into its closure.
-- **Closure/integrity/audit scope**: the runtime-closure contract covers the
-  ACTUALLY MATERIALIZED production dependency tree, not the full lock
-  metadata (a lockfile may describe dev/peer subtrees that are never
-  materialized and are out of contract). Vulnerability audit uses the
-  identical scope: `npm audit --omit=dev --omit=peer --ignore-scripts`.
-  Consumer/package CI must include a fixture asserting omitted peer
-  dependencies are ABSENT from the materialized tree.
-- **Integrity coverage**: the lock has TWO digests at two levels, and the
-  closure sits inside one of them.
-  - The package row's `integrity` covers the staged package PAYLOAD only —
-    every `node_modules` (at any depth) and a root `oats-lock.json` are excluded,
-    so it is stable whether or not materialization has run. Root source-control
-    metadata (`.git`) is stripped before staging; if it later appears in a
-    managed artifact it is ordinary drift, not an integrity exclusion.
-  - The capability row's `integrity` covers the MATERIALIZED ARTIFACT with **no
-    exclusions at all**: capability source bytes, the materialized
-    `node_modules`, and the generated `.oats-installation.json` provenance file.
-  - There is consequently NO separate dependency digest anywhere in the model —
-    tampering with a materialized dependency changes the capability artifact
-    integrity directly, which invalidates `trusted` exactly like source drift and
-    makes bare restore reproject. A lock row carrying `depsIntegrity` is
-    evidence of the unsupported transitional shape (contract §4.1), not a field
-    to honour.
-  - `npm ci` fails closed on any lockfile mismatch. Doctor reports the package
-    payload integrity and each capability artifact's integrity/trust state.
-- **Reproducibility (v1 MUST: platform-invariant closures)**: `node_modules`
-  is a derived artifact — never part of the package payload hash, never
-  committed, always reproduced from the locked `package-lock.json` and verified
-  through the capability artifact integrity that contains it. Because that
-  single artifact digest lives in a shared lock, **v1 packages MUST have
-  platform-invariant materialized closures**: no native builds, no
-  platform-specific optional dependencies, no install-time variance of any kind.
-  A closure that cannot materialize byte-identically across supported platforms
-  is UNSUPPORTED in v1 — the package must vendor a pure-JS closure or drop the
-  dependency; official dependency-bearing packages gate this across their
-  published platforms in CI. The engine ENFORCES this at materialization as a
-  transaction-wide preflight PLUS a post-materialization scan: every
-  materialization root's lockfile (every declared capability root, kept and
-  fresh) is scanned BEFORE any `npm ci` — only entries in the materialized
-  non-dev/non-peer closure are evaluated (omitted metadata cannot fail an
-  otherwise valid closure); an INCLUDED entry with os/cpu/libc constraints,
-  optional-dependency variance, or an install script is rejected (an included
-  install script is disallowed even though `--ignore-scripts` inerts it — the
-  runtime almost certainly expects the artifacts it would have built). After
-  `npm ci`, before digest/swap, the materialized tree is scanned for `.node`
-  native binaries alongside symlink containment. npm lockfileVersion 1 (no
-  `packages` map) fails closed — regenerate with modern npm. (A future keyed
-  per-platform closure map may relax this.)
-- **Containment**: capability code/hook/skill/agent paths must resolve inside
-  the CAPABILITY root after symlink resolution — that is what makes the
-  materialized artifact self-contained and independently hashable. Materialized
-  `node_modules` trees under that root are inside the boundary by construction —
-  and ENFORCED: after `npm ci`, before any digest or swap, every symlink under
-  every materialized `node_modules` is realpath-checked to resolve inside the
-  capability root; a broken or escaping link fails the transaction
-  (`path-escape`) with full rollback. Node import resolution follows symlinks,
-  so this check is global, not best-effort.
-- **Rollback**: materialization happens IN STAGING before any destination
-  mutation; a materialization failure fails the whole acquire/update
-  transaction with the capability store and lock unchanged, and a restore whose
-  reprojected artifact does not reproduce the locked capability `integrity`
-  fails as `integrity-drift` with the prior artifact left in place. Staging
-  directories are removed wholesale on any failure.
-
-## 3. Incremental transaction semantics
-
-Acquire/update of one package closure is **incremental with respect to the
-scope's capability store**, never a wholesale store replacement:
-
-- Capability artifacts, package rows and capability rows belonging to packages
-  NOT in the resolved closure are untouched — bytes on disk and lock JSON both.
-- Within the closure, a capability whose newly projected artifact integrity
-  EQUALS its currently locked integrity is kept in place ("kept" in reports) and
-  its `trusted` flag is preserved verbatim.
-- Only capabilities whose artifact integrity CHANGES have their artifact
-  replaced and their `trusted` reset to `false`. Trust is per capability, so an
-  unchanged capability inside a changed package keeps its approval.
-- All validation (manifests, self-containment, cycles, identity and
-  capability-ID collisions, compatibility, platform invariance) completes against
-  a staging area BEFORE any destination mutation; the artifact swaps and the lock
-  write happen only after full-closure validation. On any failure before that
-  point the staging area is removed and the destination store + lock are
-  byte-identical to the pre-operation state.
-- An update replaces ALL of one package's exports together or none of them; a
-  removed export is retired only when no config references it (otherwise
-  `remove-blocked`, with nothing changed).
-- Restore is per-capability transactional: a failure (`integrity-drift`,
-  `capability-list-mismatch`) leaves that capability absent or untouched — never
-  partially installed — and does not affect other capabilities' restores.
-
-## 4. Runtime-validated schema invariants
-
-JSON Schema cannot express these in the current shapes, so they are normative
-SEMANTIC validation rules with tests; validators of the schemas alone are not
-complete:
-
-- `oats-package.json`:
-  - `capabilities` is REQUIRED and non-empty — config-only and empty packages
-    are `invalid-package-manifest`;
-  - `configTemplates` is OPTIONAL and is the canonical spelling; `configs` is a
-    deprecated read-only alias; both spellings normalize to one descriptor shape
-    carrying a diagnostic `legacySpelling`, and carrying BOTH is
-    `invalid-package-manifest`;
-  - a `"."` capability root is accepted only when the manifest does NOT carry
-    `configTemplates` (§5), and remains exclusive with any other capability path;
-    authoring never emits it;
-  - at most one `configTemplates.*.default === true` (equivalently
-    `configs.*.default`) per manifest → `invalid-package-manifest`;
-  - `compatibility.oats` is REQUIRED with exactly the grammar `>=x.y.z`,
-    `^x.y.z`, or `x.y.z` — schema and runtime agree; malformed/missing →
-    `invalid-package-manifest`, valid-but-unsatisfied → `incompatible-oats`;
-  - every declared capability must be projectable self-contained — each declared
-    resource exists and realpath-resolves inside its own capability root →
-    `capability-not-self-contained` / `path-escape`. JSON Schema cannot see this
-    at all: it is a filesystem property of the staged payload.
-- `oats-lock.json`, validated BEFORE restore, trust/approval, update/remove
-  planning, migration planning, the locked-template reader, and doctor/list
-  consumption → `invalid-lock` (fail closed before executable approval or
-  artifact replacement; no normalization, no auto-repair, NO side effects;
-  message/provenance carry lock file, package or capability identity, and the
-  violated field/edge):
-  - both top-level `packages` and `capabilities` maps are required;
-  - `dependencies` is required on every package row (empty array when none), so
-    a reader never distinguishes absent from empty;
-  - normalized source prefix (`git:`/`path:`/`catalog:`) and source/commit
-    pairing: `path:` requires `commit: "local"` AND `path: "."`; `git:`/`catalog:`
-    require an exact 40-hex `commit`;
-  - canonical `path` spelling on both row kinds — a non-canonical spelling is
-    invalid, never repaired;
-  - every `capabilities.*.package` is a key of the same lock's `packages` map
-    (the provider back-reference is the single truth for which capabilities a
-    package supplies — package rows never list them);
-  - every `packages.*.dependencies[]` id is a key of the same lock's `packages`
-    map; no self-dependency and no cycle in the locked dependency graph;
-  - `trusted` is a boolean, and it is the ONLY trust field: there is no
-    package-level approval anywhere in the model;
-  - `integrity` digests are well-formed sha256 on both row kinds;
-  - arrays retain schema uniqueness (no duplicates);
-  - `.oats-installation.json` inside a materialized artifact must AGREE with the
-    capability and package rows it was projected from (§3.1 of the contract);
-    disagreement is `invalid-lock`, modification is `integrity-drift`;
-  - the unsupported transitional v2 shape is rejected centrally by the exact
-    predicate of contract §4.1, using direct raw lock-scope reads rather than
-    `configChain` so lock-only scopes are visible, with own-property presence —
-    never truthiness or array length — as the row test;
-  - v1 documents are validated against their own historical shape when read, so
-    migration planning and doctor operate on verified data.
-
-**Prototype safety is required at EVERY lookup or membership check keyed by a
-package or capability ID** — central read, dependency graph, provider
-resolution, trust, approval, update and remove alike, not merely at the
-transitional tell fields. Raw parsed JSON objects return inherited
-`constructor`, `toString` or `valueOf` for `map[id]` even when no own entry
-exists, so identity keys are charset-validated and every map is null-prototype
-or accessed through `Object.hasOwn`. A prototype-named or hostile raw-JSON ID
-must never impersonate a provider, a dependency or a trust entry, nor bypass a
-membership check. Fixtures cover empty transitional arrays and falsey values
-plus prototype-named package AND capability IDs across central read, graph,
-provider and trust lookups.
-
-Fail-closed enforcement points: `parseLockFileStrict`, `readPackageLocks` and
-`listInstalledPackages` RAISE `invalid-lock` — consumers never see invalid
-locks as absent or usable data; `writePackageLock` and
-`writeCapabilityLockEntry` validate the complete prospective document (both
-maps, together) before writing; restore, trust queries, approval, update/remove
-planning, migration planning and the locked-template reader validate before
-acting. Doctor (human and `--json`) catches the typed error and renders the
-actionable diagnosis — it is the only consumer that continues past an invalid
-lock, and it never uses the invalid data.
-
-`invalid-lock` joins the error taxonomy of the main contract (§8).
-
-## 5. Flat single-capability packages (`capabilities: ["."]`)
-
-**Read compatibility only.** A capability directory may BE the package root —
-`oats-package.json` and `oats.json` side by side with `capabilities: ["."]` — in
-an already-published manifest. The discriminator is `configTemplates`, NOT
-`configs`: `oats.authoring@1.0.0` is `capabilities: ["."]` and ships no template
-map at all, so keying acceptance on the deprecated spelling would strand a
-package the kernel is required to keep reading. A manifest carrying
-`configTemplates` is unambiguously new and its `"."` is
-`invalid-package-manifest`; authoring tooling never emits `"."` either way.
-Semantics for the layouts that still exist:
-
-- **The projection is still a capability artifact.** The capability root equals
-  the package root, so the materialized artifact under
-  `.agents/capabilities/installed/<id>/` contains the whole package root
-  including `oats-package.json` and any config templates. That is a superset, not
-  a leak: everything in it is validated payload from one exact locked source,
-  and the artifact remains self-contained, independently hashable and
-  independently trustable. Its `integrity` is the artifact hash like any other.
-- **Two digests, no double counting.** The package row's payload `integrity` and
-  the capability row's artifact `integrity` cover overlapping bytes on purpose:
-  one proves the distribution, the other proves the installation. Trust binds to
-  the capability digest only.
-- **Resource indexing**: only the manifest-declared `.` is indexed; `oats.json`
-  loads from the root with normal capability validation. `oats-package.json`
-  living inside the capability's file set is harmless — each file has exactly
-  one loader (`oats-package.json` → package manifest, `oats.json` → capability
-  manifest), so no manifest-kind ambiguity can arise.
-- **Constraint**: `.` implies a SINGLE-capability package. Listing `.` together
-  with any other capability path would nest one capability inside another and is
-  rejected as `invalid-package-manifest`.
-- Per-capability npm closures (§2) degenerate to the package root: a root
-  `package.json` + `package-lock.json` pair is the capability's closure (it is
-  detected once, not twice).
-- **Fail rather than degrade**: if such a package's capability cannot be
-  projected self-contained, acquisition and migration fail
-  (`capability-not-self-contained`) instead of silently retaining package-only
-  paths.
-
-## 6. Legacy locks: v1 compatibility, and no transitional-v2 compatibility
-
-There is exactly one legacy format to support, and it is v1.
-
-1. The kernel **writes only** the capability-materialization lock.
-   `writePackageLock` and `writeCapabilityLockEntry` refuse an existing v1
-   file — **including an empty one** — with `legacy-lock`. Only an ABSENT lock
-   is a fresh document; an empty v1 file still carries a format decision the
-   user has not made, and converting it implicitly would contradict explicit
-   migration.
-2. **v1 stays usable.** Runtime discovery, exact restore, trust checks,
-   approval updates and doctor/list diagnosis keep working against v1 locks and
-   the existing v1 artifacts in `.agents/capabilities/installed/`. Ordinary use
-   of an unconverted deployment never requires migration; only lifecycle
-   mutation through the package surface does. `readPackageLocks` surfaces v1
-   files in `legacy` and in `migration` (with kind `v1` or `v1-empty`), and
-   nothing is normalized, repaired or rewritten on read.
-3. **Conversion is explicit, transactional and all-or-nothing per scope.** The
-   lock has no residue container, so a v1 scope with even one unmappable entry
-   stays v1 in full — reported as `hold`/`manual` — and keeps working.
-   Re-running `oats migrate` retries it once the catalog can map it. Guided
-   official migration converts directly into flat capability materialization.
-4. **Trust is never carried over from v1.** A v1 capability artifact and a
-   materialized artifact are different bytes, so every executable surface is
-   re-earned and listed in the returned `trust[]`.
-5. **Rollback is byte-exact.** Any conversion failure restores the original v1
-   lock byte-identically, removes every artifact the conversion created, leaves
-   superseded v1 artifacts in place, and rolls back the ignore bytes. Owned/path
-   capabilities are never touched.
-6. **The earlier transitional package-root v2 is not supported at all.** It is
-   detected centrally by contract §4.1 and rejected as `invalid-lock` with an
-   actionable message naming the unsupported shape and scope recreation. It is
-   never converted, never partially interpreted, and there is no
-   `.agents/packages/installed/` handling, offline projection, or trust
-   carry-over anywhere in the engine. Existing local pre-adoption state is
-   recreated by reinstalling. The one exception is the state-free empty
-   document `{ "lockfileVersion": 2, "packages": {} }`, which carries no state
-   and normalizes to the empty current lock.
-7. **Cutover gate**: zero lockfileVersion 1 files (including empty
-   `{capabilities:{}}` ones) and zero `.agents/packages/` directories across
-   every reconciled scope. Doctor reports each remaining one with its exact
-   command.
-
-Required engine tests (`test/package-engine.test.mjs`): v1 empty file stays
-pending (never implicitly converted), v1 partial-mappability hold with the scope
-untouched, v1 full conversion with trust not carried, byte-exact rollback on
-failure, unsupported transitional v2 rejected with no side effects (both
-predicate arms, including empty transitional arrays and a dependency-free old
-row), state-free empty transitional v2 normalization, prototype-named package
-and capability IDs across central read / graph / provider / trust lookups, and
-`.oats-installation.json` determinism, field agreement, tamper failure and
-future-kernel restore.

package/docs/desktop-succession.md

@@ -1,57 +0,0 @@
-# BREAKING: desktop succession — `oats.web`, `oats pane`, and the control-pane library are retired
-
-**The next release of `@awebai/oats` containing this change is a
-BREAKING release.** Three previously shipped surfaces were removed in favor of
-the OATS Desktop app (`packages/desktop/` in the framework repo):
-
-| Removed surface | Replacement |
-|---|---|
-| `oats.web` marketplace capability (`oats web start`, browser panel) | OATS Desktop app — the same zero-dependency loopback server is bundled at `packages/desktop/server/` and spawned by the app |
-| `oats pane` CLI command and the Control Pane TUI | OATS Desktop app (Active overview / instance roster) |
-| `@awebai/oats/control-pane` package export (`lib/control-pane/model.mjs`) | The roster model moved into the Desktop app; under workspace model v2 the app reads the kernel's `oats status --json` instead ([deployment model](../packages/desktop/docs/desktop-deployment-model.md)). It is not a public kernel export |
-
-## Migrating a deployment that used `oats.web`
-
-Under the **0.25 workspace model** there is nothing to uninstall: remove
-`oats.web` from `oats-workspace.yaml` `packages:` / `defaults.capabilities`
-and from any `soul.yaml` `capabilities:`, run `oats sync` (the lock v3 entry
-disappears with the declaration), and use the Desktop app (step 3 below).
-
-For a **0.24 classic** deployment:
-
-1. Remove the `oats.web` entry from `capabilities.additive` in every
-   `oats-config.yaml` in your config chain.
-2. Remove the `oats.web` entry from `oats-lock.json` (v2) at the same scope(s),
-   and delete any stale installed copy under `.agents/capabilities/installed/`.
-3. Use the OATS Desktop app instead: `cd packages/desktop && npm install &&
-   npm run rebuild && npm start` (see `packages/desktop/README.md`).
-
-The CLI diagnoses stale references instead of failing opaquely:
-
-- `oats doctor` warns when an `oats-lock.json` still pins `oats.web`, with the
-  fix spelled out.
-- A soul or workspace default naming `oats.web` fails at resolution with a
-  message naming the successor and the exact cleanup steps (remove it from
-  `packages:` / the soul's `capabilities:`).
-
-## Migrating `oats pane` usage
-
-`oats pane` now exits with a pointer to the desktop app. Scripts or docs
-invoking it should launch OATS Desktop instead. The `--theme` themes (dark,
-solarized) exist in the app's theme system.
-
-## Consumers of the `./control-pane` export
-
-`import ... from "@awebai/oats/control-pane"` no longer resolves. The
-model's pure helpers (`readMarkdownSection`, `parseTmuxWindows`,
-`parseGitStatus`, `parseGitDiffStat`, `buildConstellation`, `relativeAge`)
-moved into the private Desktop app and were retired with its workspace-model v2
-rebuild. If you depended on this export, vendor the helpers from a released tag
-or open an issue — no known external consumer existed at removal time.
-
-## Release gating (maintainers)
-
-Downstream installers/packaging for the desktop app must exist **before** the
-next release ships; this migration note travels with the release notes and
-the release must be flagged **BREAKING** (major or clearly-marked minor per
-the project's pre-1.0 conventions).