@awebai/oats 0.25.8 → 0.26.0

package/docs/workspaces.md

@@ -8,7 +8,6 @@ contracts the kernel is built against are in
 [design/2026-09-23-workspace-module-contracts.md](design/2026-09-23-workspace-module-contracts.md);
 a full worked example (an imaginary company with three teams) is in
 [design/2026-09-23-simplified-workspace-model.md](design/2026-09-23-simplified-workspace-model.md).
-Moving an existing 0.24.x deployment: [rebuild-to-v2.md](rebuild-to-v2.md).
 
 ## The rule
 
@@ -19,7 +18,7 @@ versioned.**
 | Source kind | `from:` | Versioned | Trust |
 |---|---|---|---|
 | Member repo | `<repo key>` or `here` | no — always the member's **latest** default-branch state | membership (the reciprocal handshake) |
-| Package | `package` | yes — the version pinned in the workspace's `packages:`; `oats-lock.json` records the exact commit + integrity | executables approved **once per version**, recorded in the lock |
+| Package | `package` | yes — the version pinned in the workspace's `packages:`; `oats-lock.json` records the exact commit + integrity | the declaration in `packages:` (no separate approval) |
 
 A soul names each capability **with where it comes from — a location, never a
 version**. The workspace's `packages:` says which version; materialization
@@ -39,8 +38,8 @@ machine (`oats-local.yaml`); the lock (`oats-lock.json`) sits beside
 `oats-local.yaml` and is identical on every machine that synced the same
 workspace commit. Schemas: [`oats-workspace.schema.json`](oats-workspace.schema.json),
 [`oats-membership.schema.json`](oats-membership.schema.json),
-[`soul.schema.json`](soul.schema.json), [`oats-local.schema.json`](oats-local.schema.json),
-[`oats-lock-v3.schema.json`](oats-lock-v3.schema.json). The JSON schemas encode
+[`soul.schema.json`](soul.schema.json), [`oats-local.schema.json`](oats-local.schema.json);
+the lock's format is in [packages](packages.md#lock-v3). The JSON schemas encode
 shapes; domain rules (declared teams, duplicate members, canonical `from:` keys,
 the two `packages:` value forms) live in the kernel's `validateWorkspace` /
 `validateSoul`, which are the authority.
@@ -61,7 +60,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
 
 packages:                                  # the ONLY versioned things
   oats.framework: v1.1.3                   # bare version → resolves through the official catalog
-  oats.okf: v2.1.4
+  oats.okf: v2.1.5
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # labels, declared once so they cannot drift
@@ -141,8 +140,9 @@ declaration; it travels with the soul into the per-commit soul cache. The
 carry only the binding's settings keys (`bindings-file`, `state-dir`,
 `harvest-runtime`, `harvest-model`); `owns`/`reads`/`root` there are refused by
 the provider, not read (a soul payload grammar is an OKF follow-up). Every
-`souls/*/soul.yaml` in a member is discoverable; one that wants to stay
-internal says `private: true` (spawnable only from its own repo). A soul's
+`souls/*/soul.yaml` in a member is listed and spawnable — souls have no
+private mode (`private:` in a soul.yaml is ignored since 0.26.0, with a
+`soul-private-ignored` warning). A soul's
 `name` must equal its directory name; the first of two souls declaring one
 name (by path) is listed, the second is a problem.
 
@@ -151,7 +151,8 @@ name (by path) is listed, the second is a problem.
 The capability manifest is the one file that did not change (see
 [capabilities.md](capabilities.md)). Discovery relies on `capability` (the same
 `^[a-z0-9][a-z0-9._-]*$` grammar every `capabilities:` key uses), `version`,
-`layer`, and may read `private: true` and `team: <label>`. `version` is
+`layer`, and may read `private: true` (a **repo-owned** capability) and
+`team: <label>`. `version` is
 informational for member capabilities — a materialized copy is identified by
 its content digest.
 
@@ -188,7 +189,14 @@ with the right name, is not admission.
 model as a repo's committed `.agents/skills/`: whoever can push to the repo
 decides what runs, and the branch's latest state is what runs. No per-operator
 trust lists, no per-capability approval for members. Packages come from
-*outside* that boundary and keep a one-time executable approval per version.
+*outside* that boundary, and **declaring one in the workspace's `packages:` is
+the trust decision** (human decision, 2026-09-24): people install a package only
+when they trust it, so there is no second, per-version approval step. The lock
+is reproducibility, not approval — it pins the exact commit and content
+integrity, and `oats sync` refuses drift (a moved tag, changed content, an
+edited capability list). A spawn admits only a locked package the workspace
+**still declares**: one removed from `packages:` but left in a stale lock is
+`E_PACKAGE_MISSING { reason: "undeclared" }` until `oats sync` drops it.
 
 **The handshake is observed with the operator's own Git read access, in one
 access context.** The kernel reads both halves over the remotes
@@ -210,10 +218,11 @@ its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).
 Reading the workspace repo *is* being in the workspace — a workspace's access
 control is Git's.
 
-**Private items.** `private: true` on a soul or a capability keeps it out of the
-workspace listing; a private capability is usable only by souls of the same
-repo (`E_CAPABILITY_PRIVATE` otherwise). Owners still see their own private
-items.
+**Repo-owned capabilities.** `private: true` in a capability's `oats.json`
+makes it **repo-owned**: it is listed like any other capability (with
+`private: true`; the human table marks it "(repo-owned)"), and it is usable
+only by souls of the same repo (`E_CAPABILITY_PRIVATE` otherwise). Souls have
+no private mode: every soul of a confirmed member is listed and spawnable.
 
 **External souls.** `external:` adopts a soul by reference from a repo that is
 **not** a member, pinned to a full commit. No handshake is asked for and none is
@@ -226,7 +235,7 @@ its slots. An `external[].team` overrides the soul's own `team`.
 A repository may be a **member** (it completed the handshake; its `souls/*` and
 `capabilities/*` are member-tier: latest state, trusted by membership) **and** a
 **package publisher** (its `oats-package/` is consumed only through
-`packages:`: versioned, locked, approved). The two never collapse:
+`packages:`: versioned and locked). The two never collapse:
 
 - `from: <repo key>` looks **only** under `<repo>/capabilities/<name>/oats.json`
   at the member's latest state. It never looks inside `oats-package/`. A name
@@ -244,31 +253,32 @@ So the framework's own souls say `oats.okf: { from: package }` even though
 member soul that is the expert in that capability (`okf-expert`, `aweb-expert`,
 …), discoverable at latest state like any member soul.
 
-## Packages, lock, approval, catalog
+## Packages, lock, catalog
 
 `packages:` values have exactly two forms:
 
 - a **bare version** (`v2.1.3`, `2.1.3`, `v1.0.0-rc.1`) — resolved through the
   official catalog (`package-catalog.json` in the `oats` repo; the reviewed
-  marketplace, see [official-marketplace.md](official-marketplace.md)). This is
+  list, see [official-catalog.md](official-catalog.md)). This is
   the only way a package becomes *pinnable by id*.
 - **`git:<repo>@<ref>`** — a direct package ref: `<repo>` is any ref the kernel
   understands (`github.com/org/repo`, `https://…`, `git@host:…`, `/abs/bare.git`,
   `file:///…`), `<ref>` a tag name or a full commit OID. The package is read at
   `oats-package/` inside that repo.
 
-Both are packages: versioned, locked, approved. A ref that resolves to a
-**branch** is refused (`E_PACKAGE_INTEGRITY { why: "branch" }`) — versions are
-immutable. A tag that moved (same version string, different commit) fails
-integrity on the next `oats sync` and asks again.
-
-`oats sync` confirms membership, resolves every `packages:` entry to a commit +
-content digest, asks (on a terminal) for any missing per-version executable
-approval — or takes it from repeatable `--approve <id>@<version>` flags for
-unattended runs (each approves exactly the entry the resolution contains; the
-digest is always computed, never typed; Ctrl+D at the prompt is a decline,
-exit `2`) — writes `oats-lock.json` (lockfileVersion 3), creates `agents/` if
-absent and reports what changed. `oats package add <id> <version|git:…@…>` / `oats package remove <id>` edit
+Both are packages: versioned and locked. A ref that resolves to a **branch** is
+refused (`E_PACKAGE_INTEGRITY { why: "branch" }`) — versions are immutable. A
+tag that moved (same version string, different commit), or content that no
+longer matches the locked integrity, fails with `E_PACKAGE_INTEGRITY` on the
+next `oats sync`.
+
+**There is no package approval** (human decision, 2026-09-24). Declaring a
+package in `packages:` is the trust decision; `oats sync` asks nothing and
+`--approve` is `E_BAD_ARGS`. `oats sync` confirms membership, resolves every
+`packages:` entry to a commit + content digest, writes `oats-lock.json`
+(lockfileVersion 3), creates `agents/` if absent, reports what changed and
+exits `0`. A lock written by an earlier kernel may still carry an `approved`
+record per entry: it is ignored, and the next write drops it. `oats package add <id> <version|git:…@…>` / `oats package remove <id>` edit
 `packages:` in the workspace file when it is tracked by the current checkout,
 else print the line to add — the workspace file is shared through Git. Details:
 [packages.md](packages.md).
@@ -282,8 +292,8 @@ the workspace's slot default):
 
 ```
 from: package → some locked package provides `name`            else E_PACKAGE_MISSING (run `oats sync`)
-              → that package version is approved                 else E_PACKAGE_UNAPPROVED
-              → read its capability manifest at the locked commit; copy; record package/version/commit/digest
+              → read its manifests at the locked commit; the lock's capability list must match   else E_PACKAGE_INTEGRITY
+              → copy; record package/version/commit/digest
 from: <repo>  → <repo> is a CONFIRMED member                     else E_NOT_A_MEMBER / E_MEMBERSHIP_UNCONFIRMED
  (or `here`)  → it has capabilities/<name>/oats.json             else E_CAPABILITY_MISSING
               → not private, unless <repo> is the soul's own    else E_CAPABILITY_PRIVATE
@@ -308,13 +318,12 @@ Nothing is symlinked, nothing is shared between instances.
 ```
 <agents-root>/<soul>/instances/<instance>/
 ├── AGENTS.md                          # composed: soul AGENTS.md + kernel/work-mode blocks + each module's inject
-│                                      #   (with oats.core resolved, the module's "You run on OATS" block is the only one — the kernel's legacy copy is suppressed)
+│                                      #   (the "You run on OATS" block is oats.core's inject; the kernel ships no copy)
 ├── CLAUDE.md → AGENTS.md
 ├── .agents/skills/<capability>/<skill>/SKILL.md    # full copies; where pi/codex look
 ├── .claude/skills → ../.agents/skills
 ├── .oats/modules/<capability>/        # the full capability copy: oats.json, bin/, injects/, skills/
 ├── instance.json                      # modules{}, providers{}, workspace{} recorded here
-├── soul → <agents-root>/<soul>/soul   # read-only reference
 ├── TASK.md
 └── work/
 ```
@@ -347,10 +356,16 @@ not exclude anything.
 ## Teams
 
 `teams:` declares labels once (`global`, `engineering`, …) so they cannot drift
-into typos. A soul or capability carries `team:`, else its repo's default from
-`oats-membership.yaml`, else `unassigned`. A label not declared in `teams:` is
-`E_TEAM_UNKNOWN` (the item is still listed). `defaults.byTeam.<team>.capabilities`
-adds capabilities additively for souls with that label (`off` removes). **A
+into typos. A soul carries `team:` — one label or a list (`team: [engineering,
+reviewers]`, the first the primary) — else its repo's default from
+`oats-membership.yaml` (same shape), else `unassigned`; a capability carries one
+label. A label not declared in `teams:` is `E_TEAM_UNKNOWN` (the item is still
+listed); a declared label without a `messaging.byTeam` entry is the
+`unmapped-team-label` warning. `defaults.byTeam.<team>.capabilities` adds
+capabilities additively for souls with that label, for each label in order
+(`off` removes; two labels that disagree are `E_TEAM_CONFLICT`). Each label is
+an *eligible* messaging team the provider may join on request — see
+[capabilities.md](capabilities.md#several-team-labels). **A
 label never gates, restricts, changes trust or partitions the knowledge
 store** — it organises and can supply defaults. The messaging provider's payload
 (private teams, channels) lives under `messaging:`, so "team" means one thing.
@@ -364,9 +379,13 @@ store** — it organises and can supply defaults. The messaging provider's paylo
 | A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
 
 The merged payload is `workspace.messaging` (messaging slot only; its base
-keys ⊕ `byTeam[<soul's team>]`, with `byTeam` itself stripped) ⊕ soul slot
-payload ⊕ `local.settings[cap]` ⊕ `spawn.providers[cap]` — objects deep-merge,
-later wins on scalars and arrays. The provider's own `binding` contract
+keys, with `byTeam` stripped) ⊕ soul slot payload ⊕ `local.settings[cap]` ⊕
+`spawn.providers[cap]` — objects deep-merge, later wins on scalars and arrays.
+**No `byTeam[<label>]` is merged into it, the primary's included** (teams
+amendment K): each label's `base ⊕ byTeam[label]` reaches the provider only as
+that label's entry in `OATS_TEAMS` (the preview's `teams`). So `settings.team`
+(and `OATS_TEAM_ID`) is the personal team if the host, the soul or the spawn
+set one; empty means the provider's own default. The provider's own `binding` contract
 (`normalize → bind → check`) runs over the merged payload exactly as before.
 Two teams, two messaging identities, one workspace:
 
@@ -378,18 +397,21 @@ messaging:
     cloud: { team: aweb:example.cloud }
 ```
 
-A soul with `team: cloud` hands its messaging provider `{ team: aweb:example.cloud, … }`;
-a label under `byTeam` that is not declared in `teams:` is `E_WORKSPACE_SCHEMA`.
-**`byTeam` is kernel-merged; whether a provider honours what arrives is the
-provider's.** `spawn --preview` shows the merged `settings.<cap>` so the
-delivery is verifiable, and `instance.json.providers.<cap>` records it — but
-**oats.aweb 1.12.0 reads `team` from its payload** and mints into exactly that
-team (`--team-id`), warning when the payload disagrees with an `OATS_TEAM_*`
-value — so `byTeam.<label>.team` IS the per-label identity. What the payload
-does not change is **where the `.aw` root is found**: the hook still searches
-the bounded candidates in
-[rebuild-to-v2.md §8b](rebuild-to-v2.md#8b-where-the-team-aw-lives-now-and-what-byteam-does-today)
-and that root must hold a membership of the named team (the deployment's `.aw`
+A soul with `team: cloud` hands its messaging provider the eligible team
+`{ label: cloud, team: aweb:example.cloud, mapped: true, payload: { team: aweb:example.cloud, … } }`
+in `OATS_TEAMS`; its settings carry no `team` unless the host, soul or spawn set
+one. A label under `byTeam` that is not declared in `teams:` is
+`E_WORKSPACE_SCHEMA`. **Joining an eligible team is the provider's explicit
+act.** `spawn --preview` shows the merged `settings.<cap>` and the `teams`, so
+the delivery is verifiable, and `instance.json` records both. With oats.aweb
+1.13.1 (which reads `team` from its settings and ignores `OATS_TEAMS`) the
+primary identity therefore mints into the personal team: the `.aw` root's
+active team, or the one the host set. What the payload does not change is
+**where the `.aw` root is found**: the hook still searches
+bounded candidates, first hit wins — the instance home, the Git repository
+containing it, the soul's work repository and the Git repository containing
+it, then the deployment directory (`OATS_WORKSPACE`); never the user home or
+above the deployment — and that root must hold a membership of the named team (the deployment's `.aw`
 joined to every team its labels name is the simple layout). On oats.aweb
 1.11.2 `team` was ignored (the root's active team won), so `byTeam` there is
 a recorded intent only.
@@ -428,7 +450,7 @@ The deployment directory is **yours to choose** (decision 9) — an existing fol
 ```
 ~/acme/                           ← the directory you chose
 ├── oats-local.yaml               ← which workspace this machine realizes + host paths + disabled souls
-├── oats-lock.json                ← exact commit + integrity + per-version approval per package
+├── oats-lock.json                ← exact commit + integrity per package
 ├── agents/                       ← instance homes (each self-contained) + fetched soul sources
 ├── platform/                     ← clone of github.com/acme/platform (only if someone works IN it; may live elsewhere — see clones:)
 └── tools/
@@ -454,8 +476,8 @@ the host repo readable (it holds declarations, no secrets) or grant access.
 
 Two things keep the standalone spawn useful rather than hollow: `oats.core`
 (the framework's own operational package) is the kernel's default here as
-well, resolved from the official catalog through the operator's own lock and
-approved like any package (a soul may say `oats.core: off`); and the
+well, resolved from the official catalog through the operator's own lock like any
+package (a soul may say `oats.core: off`); and the
 operator's `oats-local.yaml` may name the repo directly (`workspace: <member
 ref>` — the kernel notices it is a member whose workspace it cannot read and
 falls back to the standalone view — or `standalone: <repo ref>` to ask for
@@ -467,8 +489,8 @@ an explicit `standalone:` header its next steps say so and name that one repo.
 member capability's hooks and command scripts run on every operator's machine at
 spawn, gated by nothing but the handshake. In a mixed public/private
 organisation keep **souls only** in public members and let executable
-capabilities come from packages (approved per version in the lock) or from
-private members.
+capabilities come from packages (declared in `packages:`, pinned by the lock)
+or from private members.
 
 **Hosting the workspace file when some members are private.** Everyone who
 can read the workspace file sees the member list. So: a public member never
@@ -502,12 +524,12 @@ installed-capability tier (`.agents/capabilities/installed/`) and
 `E_UNKNOWN_COMMAND` naming its replacement); per-soul `stores.<x>.inherit`;
 ambient-skill exclusion at launch. Lock v1/v2 files are `E_LOCK_SCHEMA`.
 There is no converter and no dual-schema reader: a 0.24.x kernel keeps
-spawning 0.24.x deployments; see [rebuild-to-v2.md](rebuild-to-v2.md).
+spawning 0.24.x deployments.
 
 ## Related
 
 - [Souls and instances](souls-and-instances.md) · [Packages](packages.md) ·
-  [Configuration (`oats-local.yaml`)](configuration.md) · [Rebuild guide](rebuild-to-v2.md)
+  [Configuration (`oats-local.yaml`)](configuration.md)
 - [Capability manifests](capabilities.md) · [Contracts](layers.md) ·
   [Desktop CLI API — workspace model](desktop-cli-api.md#workspace-model-workspaceapi-2)
 - [Design navigation](design/README.md)

package/injects/instance-boundary.md

@@ -20,7 +20,7 @@ root, and not the work tree. Anything that says "your home" means this directory
 - **Soul work is repository work.** If your TASK is to change soul content that
   lives in this repository, that is ordinary code work — do it on tracked paths
   under `work/`, reviewed like the rest. How your own learnings reach your soul
-  is your knowledge layer's business, and its instructions below say so if you
+  is your knowledge capability's business, and its instructions below say so if you
   have one.
 
 **`<instance-home>/work` is your repository or workspace view** — whatever your

package/injects/work-attached.md

@@ -8,7 +8,7 @@ their branch and their uncommitted state. You are a guest in their workspace.
 - Keep your changes and commits **small and clearly attributable** (your
   instance name in commit messages where ambiguity is possible).
 - Do not touch files the owner is mid-editing unless your task says so; when
-  in doubt, coordinate through your messaging layer or your spawner.
+  in doubt, coordinate through your messaging capability or your spawner.
 - Retiring you never removes the shared tree — cleanup of the tree is the
   owner's concern, not yours.
 

package/injects/work-workspace.md

@@ -6,8 +6,8 @@ cross-repo coordinator: your product is routing, analysis, and coordination —
 not code changes.
 
 - **Read freely across all member repos; never edit or commit inside them.**
-  Repo changes are routed to that repo's own agents (see `oats status --team`,
-  your task layer, or messaging) or to the human.
+  Repo changes are routed to that repo's own agents (see `oats status` in the
+  deployment, your tasks capability, or messaging) or to the human.
 - No git state operations in any member repo: no branch switching, no
   commits, no worktrees, no resets.
 - Your own working state lives in your instance home, not in any member repo,

package/lib/{portable-files.mjs → bounded-read.mjs}

@@ -1,4 +1,4 @@
-/** Bounded descriptor-backed reads shared by private portable metadata stores. */
+/** Bounded descriptor-backed reads of kernel-owned files (manifests, instance records). */
 import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
 import { oatsError } from "./errors.mjs";
 
@@ -8,19 +8,19 @@ export function readPortableBytes(path, { missingCode = "resource-not-found", in
   catch (error) {
     if (error.code !== "ENOENT") throw error;
     if (allowMissing) return null;
-    throw oatsError(missingCode, "portable metadata is absent");
+    throw oatsError(missingCode, "metadata file is absent");
   }
-  if (!stat.isFile()) throw oatsError(invalidCode, "portable metadata must be a regular file");
-  if (stat.size > 8 * 1024 * 1024) throw oatsError("resource-limit", "portable metadata byte limit exceeded");
+  if (!stat.isFile()) throw oatsError(invalidCode, "metadata file must be a regular file");
+  if (stat.size > 8 * 1024 * 1024) throw oatsError("resource-limit", "metadata file byte limit exceeded");
   const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
   try {
     const before = fstatSync(fd);
-    if (!before.isFile() || before.dev !== stat.dev || before.ino !== stat.ino || before.size !== stat.size) throw oatsError("integrity-drift", "portable metadata changed during opening");
+    if (!before.isFile() || before.dev !== stat.dev || before.ino !== stat.ino || before.size !== stat.size) throw oatsError("integrity-drift", "metadata file changed during opening");
     const buffer = Buffer.alloc(stat.size + 1);
     let count = 0, size;
     while (count < buffer.length && (size = readSync(fd, buffer, count, buffer.length - count, null)) > 0) count += size;
     const after = fstatSync(fd);
-    if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) throw oatsError("integrity-drift", "portable metadata changed during reading");
+    if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) throw oatsError("integrity-drift", "metadata file changed during reading");
     return buffer.subarray(0, count);
   } finally { closeSync(fd); }
 }

package/lib/{portable-values.mjs → canonical-json.mjs}

@@ -1,5 +1,6 @@
-/** Bounded data codecs shared by portable declarations and retained records.
- * No source resolution, filesystem access, getters, or caller serialization hooks. */
+/** Bounded data codecs: strict JSON decoding and canonical JSON (config documents,
+ * instance records, provider answers). No source resolution, filesystem access,
+ * getters, or caller serialization hooks. */
 import { oatsError } from "./errors.mjs";
 
 const DEFAULTS = Object.freeze({ maxBytes: 8 * 1024 * 1024, maxDepth: 64, maxEntries: 100_000 });
@@ -39,16 +40,6 @@ export function decodeUtf8(input, where = "input") {
 }
 export const compareUtf8 = (a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
 
-/** Freeze a bounded JSON observation, never caller accessors or cyclic objects. */
-export function freezeJson(value) {
-  canonicalJson(value);
-  const seen = new WeakSet();
-  const freeze = (item) => {
-    if (!item || typeof item !== "object" || seen.has(item)) return;
-    seen.add(item); for (const child of Object.values(item)) freeze(child); Object.freeze(item);
-  };
-  freeze(value); return value;
-}
 
 /** Canonical JSON includes exactly one final LF. Emit sorted keys directly:
  * JSON.stringify on a rebuilt object would reorder integer-looking keys. */

package/lib/capability-contract.mjs

@@ -0,0 +1,110 @@
+/** The capability manifest's kernel contract, shared by every reader: workspace
+ *  discovery (member capabilities, E_WORKSPACE_SCHEMA), package manifests
+ *  (E_PACKAGE_MANIFEST), the resolver (payload values) and the kernel's own
+ *  manifest loader. One rule set, so a manifest a workspace accepts is one the
+ *  kernel can run.
+ *
+ *  Covers what the kernel enforces when it RUNS a capability, checked where the
+ *  manifest is READ instead: the launch environment a capability may declare
+ *  (names, namespaces), its hooks (approved events, declaration shape, `required`
+ *  only on spawn, the script inside the capability), and a provider payload's
+ *  value against the manifest's `settings.<key>.values`. Dependency-free. */
+
+export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch"]);
+export const PORTABLE_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+export const CAPABILITY_ENV_ID_RE = /^[a-z][a-z0-9]*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+export const CORE_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]);
+export const PROCESS_BOOTSTRAP_ENV = new Set([
+  "PATH", "HOME", "SHELL", "TMPDIR", "TMP", "TEMP", "PWD", "OLDPWD", "SHLVL", "_",
+  "ENV", "BASH_ENV", "BASHOPTS", "SHELLOPTS", "CDPATH", "IFS", "PROMPT_COMMAND", "PS4", "ZDOTDIR",
+  "NODE_OPTIONS", "NODE_PATH", "_JAVA_OPTIONS", "GCONV_PATH", "GLIBC_TUNABLES", "ELECTRON_RUN_AS_NODE",
+]);
+export const PROCESS_BOOTSTRAP_PREFIXES = [
+  "NODE_", "LD_", "DYLD_", "PYTHON", "PERL", "RUBY", "JAVA_", "JDK_JAVA_",
+  "DOTNET_", "COMPlus_", "COREHOST_", "LUA_", "PHP_", "ELECTRON_", "GLIBC_",
+];
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const pointerKey = (k) => String(k).replace(/~/g, "~0").replace(/\//g, "~1");
+
+/** A hook's script, the first word of its command: relative to the capability root and inside it. */
+export function hookScriptEscapes(command) {
+  const script = String(command).trim().split(/\s+/)[0] || "";
+  return script.startsWith("/") || script.startsWith("~") || /^[A-Za-z]:[\\/]/.test(script) || script.split(/[\\/]/).includes("..");
+}
+
+/** Every contract problem of one manifest → [{ pointer, message }] (empty when it is sound).
+ *  Messages name the capability; `pointer` is the JSON pointer inside oats.json. */
+export function manifestContractProblems(m) {
+  const problems = [];
+  const id = m?.capability;
+  const bad = (pointer, message) => problems.push({ pointer, message: `capability ${id} ${message}` });
+
+  if (m.environmentNamespaces !== undefined && (!Array.isArray(m.environmentNamespaces) || m.environmentNamespaces.some((ns) => typeof ns !== "string"))) {
+    bad("/environmentNamespaces", "manifest environmentNamespaces must be an array of prefixes");
+  }
+  if (m.environment !== undefined) {
+    if (!Array.isArray(m.environment) || m.environment.some((name) => typeof name !== "string")) {
+      bad("/environment", "manifest environment must be an array of exact variable names");
+    } else if (new Set(m.environment).size !== m.environment.length) {
+      bad("/environment", "manifest environment contains duplicate names");
+    } else if (m.environment.length) {
+      const vendor = CAPABILITY_ENV_ID_RE.test(id) ? id.match(/^([a-z][a-z0-9]*)\./)?.[1] : undefined;
+      if (!vendor) bad("/capability", "must use a lowercase dotted ID (vendor.name) without package or path syntax to declare launch environment");
+      else {
+        const extra = Array.isArray(m.environmentNamespaces) ? m.environmentNamespaces.filter((ns) => typeof ns === "string") : [];
+        extra.forEach((ns, i) => {
+          if (!/^[A-Z][A-Z0-9]*_$/.test(ns)) bad(`/environmentNamespaces/${i}`, `manifest environmentNamespaces entry ${JSON.stringify(ns)} must be an uppercase prefix ending in an underscore`);
+          else if (ns === "OATS_" || ns === "PI_AGENT_" || PROCESS_BOOTSTRAP_PREFIXES.some((reserved) => ns.startsWith(reserved) || reserved.startsWith(ns))) bad(`/environmentNamespaces/${i}`, `manifest environmentNamespaces entry ${ns} is a reserved namespace`);
+        });
+        const allowed = [`${vendor.toUpperCase()}_`, ...extra];
+        m.environment.forEach((name, i) => {
+          const at = `/environment/${i}`;
+          if (!PORTABLE_ENV_NAME_RE.test(name)) bad(at, `manifest environment name ${JSON.stringify(name)} is invalid`);
+          else if (CORE_LAUNCH_ENV.has(name) || name.startsWith("OATS_") || name.startsWith("PI_AGENT_")) bad(at, `manifest environment name ${name} collides with a reserved core variable`);
+          else if (PROCESS_BOOTSTRAP_ENV.has(name) || PROCESS_BOOTSTRAP_PREFIXES.some((reserved) => name.startsWith(reserved))) bad(at, `manifest environment name ${name} collides with a reserved process bootstrap variable`);
+          else if (!allowed.some((ns) => name.startsWith(ns))) bad(at, `manifest environment name ${name} is outside its ${allowed.join(", ")} namespace${allowed.length > 1 ? "s" : ""} (declare another in environmentNamespaces)`);
+        });
+      }
+    }
+  }
+
+  if (m.hooks !== undefined && !isObject(m.hooks)) bad("/hooks", "manifest hooks must be an object of event → command");
+  const hooks = isObject(m.hooks) ? Object.entries(m.hooks) : [];
+  // A hook's launch environment is claimed under the capability's dotted vendor
+  // component; an undotted id has none, so its hooks cannot run.
+  if (hooks.length && !/^[a-z][a-z0-9]*\./.test(String(id))) bad("/hooks", "declares hooks but its id has no dotted lowercase vendor component (e.g. acme.tool); only a dotted id can carry hooks");
+  for (const [event, value] of hooks) {
+    const at = `/hooks/${pointerKey(event)}`;
+    if (!APPROVED_HOOKS.has(event)) { bad(at, `declares unsupported hook "${event}" (${[...APPROVED_HOOKS].join(", ")})`); continue; }
+    const extraKeys = isObject(value) ? Object.keys(value).filter((k) => !["command", "required", "inputs"].includes(k)) : [];
+    const command = typeof value === "string" ? value : isObject(value) && typeof value.command === "string" ? value.command : undefined;
+    if (command === undefined || !command.trim() || extraKeys.length) { bad(at, `hook "${event}" must be a command string or { command, required, inputs }${extraKeys.length ? ` (unknown: ${extraKeys.join(", ")})` : ""}`); continue; }
+    if (isObject(value) && value.required !== undefined && typeof value.required !== "boolean") bad(`${at}/required`, `hook "${event}": "required" must be a boolean`);
+    // Only a spawn hook can fail a spawn; marking others required would promise
+    // an enforcement that has no defined moment to act.
+    else if (isObject(value) && value.required === true && event !== "spawn") bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn hook is enforced (retire, launch and soul-scaffold run outside a spawn transaction)`);
+    if (hookScriptEscapes(command)) bad(isObject(value) ? `${at}/command` : at, `hook "${event}" script ${JSON.stringify(command.trim().split(/\s+/)[0])} escapes the capability directory; a hook script is a path inside it`);
+  }
+  return problems;
+}
+
+/** The setting keys a manifest declares (`settings.<key>`), sorted: names only, never their
+ *  descriptions or defaults. The spawn preview and inspect expose them so a client can gate
+ *  a choice on a declared key (e.g. a messaging provider's `join`). */
+export function declaredSettings(manifest) {
+  return isObject(manifest?.settings) ? Object.keys(manifest.settings).sort() : [];
+}
+
+/** Top-level payload keys whose value is outside the manifest's `settings.<key>.values`
+ *  → [{ key, value, values }]. A conditional `requires` row reads these values, so a
+ *  misspelled one would silently skip every row instead of failing. */
+export function settingValueProblems(manifest, payload) {
+  const out = [];
+  if (!isObject(manifest?.settings) || !isObject(payload)) return out;
+  for (const [key, decl] of Object.entries(manifest.settings)) {
+    if (!isObject(decl) || !Array.isArray(decl.values) || !Object.hasOwn(payload, key) || payload[key] === undefined) continue;
+    if (!decl.values.some((v) => String(v) === String(payload[key]))) out.push({ key, value: payload[key], values: decl.values });
+  }
+  return out;
+}

package/lib/config-data.mjs

@@ -2,8 +2,8 @@
  * object-construction language: no tags, anchors, aliases, merges or coercive keys.
  * Legacy core readers are unchanged until the explicit consumer migration. */
 import { Composer, CST, Lexer, Parser, isAlias, isMap, isScalar, isSeq } from "yaml";
-import { bytesIntegrity } from "./portable-digest.mjs";
-import { byteView, canonicalJson, dataLimits, decodeUtf8, parseStrictJson } from "./portable-values.mjs";
+import { bytesIntegrity } from "./digest.mjs";
+import { byteView, canonicalJson, dataLimits, decodeUtf8, parseStrictJson } from "./canonical-json.mjs";
 import { oatsError } from "./errors.mjs";
 
 const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");