@awebai/oats 0.23.2 → 0.24.0

package/lib/artifact-tree.mjs

@@ -0,0 +1,141 @@
+/** Tree mechanics only. No acquisition, selection, trust, lock or lifecycle
+ * policy. Callers supply the verifier used during publication. */
+import {
+  chmodSync, copyFileSync, lstatSync, mkdirSync, mkdtempSync, readFileSync,
+  readdirSync, readlinkSync, renameSync, rmdirSync, rmSync, symlinkSync,
+} from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { createHash } from "node:crypto";
+import { oatsError } from "./errors.mjs";
+
+/** Recursively copy a tree the way `cpSync(..., { recursive: true })` would —
+ * except catchably.
+ *
+ * Node 22's recursive `cpSync` performs its recursion in native code, and on
+ * macOS an unreadable directory inside the tree surfaces as an uncaught libc++
+ * `filesystem_error` that TERMINATES THE PROCESS. No JS `catch` or `finally`
+ * runs, so a transaction using it can never clean up staging or roll back the
+ * store, the lock and the ignore file. Every package-, capability- and
+ * user-shaped tree in the engine therefore goes through this hand-walk instead,
+ * where an EACCES is an ordinary throwable error.
+ *
+ * Semantics chosen to be safe rather than maximally faithful:
+ * - deterministic traversal (sorted entries), so two copies of one tree hash
+ *   identically;
+ * - symlinks are recreated VERBATIM — never followed, never rewritten — because
+ *   the bytes about to be hashed must be the bytes the author wrote;
+ * - FIFOs, sockets and device nodes are rejected fail-closed: they are not
+ *   distributable content, and copying them has no defined meaning here;
+ * - directory modes are applied AFTER their children, so a read-only source
+ *   directory cannot block writing its own contents. */
+export function copyTreeSafe(src, dest) {
+  const st = lstatSync(src);
+  if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src), dest); return; }
+  if (st.isFile()) { copyFileSync(src, dest); chmodSync(dest, st.mode & 0o7777); return; }
+  if (!st.isDirectory()) {
+    throw oatsError("invalid-source", `${src} is not a regular file, directory or symlink (${st.isFIFO() ? "FIFO" : st.isSocket() ? "socket" : st.isBlockDevice() || st.isCharacterDevice() ? "device node" : "unsupported file type"}) — package and capability trees carry distributable content only`);
+  }
+  mkdirSync(dest, { recursive: true });
+  for (const e of readdirSync(src, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    copyTreeSafe(join(src, e.name), join(dest, e.name));
+  }
+  chmodSync(dest, st.mode & 0o7777);
+}
+
+/** Stable integrity of a MATERIALIZED capability artifact: every byte under
+ * `.agents/capabilities/installed/<id>/`, with NO exclusions — capability source,
+ * the materialized runtime closure (node_modules), and the generated
+ * `.oats-installation.json` provenance file all count. This is the only digest
+ * executable trust binds to, which is why a separate dependency digest does not
+ * exist at capability level: the closure is inside the artifact, so tampering
+ * with a dependency is ordinary artifact drift. */
+export function capabilityArtifactIntegrity(dir) {
+  const hash = createHash("sha256");
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile()) { hash.update(relative(dir, p)); hash.update("\0file\0"); hash.update(readFileSync(p)); hash.update("\0"); }
+      else if (e.isSymbolicLink()) { hash.update(relative(dir, p)); hash.update("\0symlink\0"); hash.update(readlinkSync(p)); hash.update("\0"); }
+    }
+  };
+  walk(dir);
+  return `sha256-${hash.digest("hex")}`;
+}
+
+// ONLY for this preparer's unpublished staging, never source/destination trees.
+// copyTreeSafe preserves read-only directories after copying their children; rm's
+// force option does not make those directories removable. Restore owner access
+// top-down, using lstat at every entry so even directory symlinks stay untouched.
+// Files need no chmod to unlink them. Successful publication transfers the whole
+// staging root to the destination; the caller must not clean that root afterwards.
+export function removeOwnedStaging(staging) {
+  const makeRemovable = (path) => {
+    let st;
+    try { st = lstatSync(path); }
+    catch (error) { if (error.code === "ENOENT") return; throw error; }
+    if (!st.isDirectory()) return;
+    if ((st.mode & 0o700) !== 0o700) chmodSync(path, (st.mode & 0o7777) | 0o700);
+    for (const name of readdirSync(path)) makeRemovable(join(path, name));
+  };
+  makeRemovable(staging);
+  rmSync(staging, { recursive: true, force: true });
+}
+
+/** Copy into same-parent staging, verify, then publish by rename.
+ * The staged root is a sibling of the destination: Darwin can refuse moving a
+ * read-only directory between parents even when both parents are writable. A
+ * sibling rename preserves the copied root's mode without rewriting its `..`.
+ * The caller preflights the source/destination and owns existing-entry policy.
+ * `verify` is synchronous and must throw on invalid copied or competing bytes;
+ * this mechanical helper knows nothing about the kind of artifact or its lock.
+ * A competing nonempty tree is reused only after verification. Rename is NOT a
+ * general no-replace primitive: an empty destination appearing after caller
+ * preflight can be replaced. Normal errors remove owned staging; cleanup failure
+ * throws with its stagingPath, preserving the primary code/provenance and cause
+ * in an AggregateError when both fail. No success receipt hides failed cleanup.
+ * Hostile concurrent mutation, crash recovery and power-loss durability are not
+ * promised. */
+export function publishArtifactTree(sourceDir, dir, verify) {
+  const staging = mkdtempSync(join(dirname(dir), ".staging-"));
+  const tree = staging;
+  let failed = false, published = false, primary;
+  try {
+    // Preserve mechanical copy semantics for file/link roots too; retention's
+    // verifier owns the directory/containment policy. Only remove our empty slot.
+    if (!lstatSync(sourceDir).isDirectory()) rmdirSync(tree);
+    copyTreeSafe(sourceDir, tree);
+    verify(tree); // source may have changed during copy
+    try { renameSync(tree, dir); }
+    catch (e) {
+      // Darwin may report EACCES rather than ENOTEMPTY for a read-only winner.
+      // Permission denial alone proves nothing: require an observed destination,
+      // then let the caller verify its exact bytes, shape and provenance. If it
+      // is absent, preserve the original denial; damage is never repaired.
+      if (e.code === "EACCES") {
+        try { lstatSync(dir); }
+        catch (lookup) { if (lookup.code === "ENOENT") throw e; throw lookup; }
+      } else if (e.code !== "EEXIST" && e.code !== "ENOTEMPTY") throw e;
+      verify(dir);
+      return "kept";
+    }
+    published = true;
+    return "retained";
+  } catch (error) {
+    failed = true;
+    primary = error;
+    throw error;
+  } finally {
+    try { if (!published) removeOwnedStaging(staging); }
+    catch (cleanup) {
+      const diagnostic = `artifact staging cleanup failed at ${staging}: ${cleanup?.message ?? cleanup}`;
+      const error = failed
+        ? new AggregateError([primary, cleanup], `${primary?.message ?? primary}; ${diagnostic}`, { cause: primary })
+        : new Error(diagnostic, { cause: cleanup });
+      error.code = failed ? primary?.code : cleanup?.code;
+      if (failed && primary?.provenance !== undefined) error.provenance = primary.provenance;
+      error.stagingPath = staging;
+      throw error;
+    }
+  }
+}

package/lib/capability-artifacts.mjs

@@ -0,0 +1,179 @@
+/** Immutable retention of already materialized capabilities. Acquisition,
+ * selection, approval and instance dispatch remain the caller's responsibility.
+ * See docs/design/2026-09-14-artifact-retention-contract.md. */
+import {
+  linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync,
+  readlinkSync, realpathSync, rmSync, writeFileSync,
+} from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { capabilityArtifactIntegrity, publishArtifactTree } from "./artifact-tree.mjs";
+import { oatsError } from "./errors.mjs";
+import {
+  CAPABILITIES_DIRNAME, isMaterializedCapabilityId, validateCapabilityLockEntry,
+  validateLockEntry, verifyCapabilityInstallation,
+} from "./capability-provenance.mjs";
+
+const INTEGRITY = /^sha256-[0-9a-f]{64}$/;
+const STORE_PARTS = [...CAPABILITIES_DIRNAME.split(sep), "artifacts"];
+const exists = (path) => {
+  try { return lstatSync(path); }
+  catch (e) { if (e.code === "ENOENT") return null; throw e; }
+};
+const outside = (root, path) => {
+  const rel = relative(root, path);
+  return rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+};
+
+/** The complete digest, not a short display prefix, identifies a revision. */
+export function retainedCapabilityDir(scope, capability, integrity) {
+  if (!isMaterializedCapabilityId(capability) || typeof integrity !== "string" || !INTEGRITY.test(integrity)) {
+    throw oatsError("invalid-artifact-reference", "retained capability requires a valid capability ID and full sha256 integrity");
+  }
+  return join(resolve(scope), CAPABILITIES_DIRNAME, "artifacts", capability, integrity);
+}
+
+function lockRows(capability, lock) {
+  if (!lock?.capabilities || !Object.hasOwn(lock.capabilities, capability) || !lock.packages) {
+    throw oatsError("invalid-lock", `no captured capability/package lock for ${capability}`);
+  }
+  for (const [id, row] of Object.entries(lock.packages)) validateLockEntry(id, row, lock.packages);
+  const row = lock.capabilities[capability];
+  validateCapabilityLockEntry(capability, row, lock.packages);
+  return { row, pkg: lock.packages[row.package] };
+}
+
+// A retained tree must remain usable after its source disappears. In particular,
+// an absolute symlink pointing back into today's source is not a portable link.
+export function assertRetainableTree(root) {
+  const st = exists(root);
+  if (!st) throw oatsError("artifact-not-found", `artifact tree is absent: ${root}`);
+  if (!st.isDirectory()) throw oatsError("invalid-artifact", `artifact root must be a directory: ${root}`);
+  const boundary = realpathSync(root);
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, e.name);
+      if (e.isDirectory()) walk(path);
+      else if (e.isSymbolicLink()) {
+        let target;
+        try { target = realpathSync(path); }
+        catch { throw oatsError("artifact-not-contained", `broken artifact symlink: ${path}`); }
+        if (isAbsolute(readlinkSync(path)) || outside(boundary, target)) {
+          throw oatsError("artifact-not-contained", `artifact symlink must stay relative and inside its retained tree: ${path}`);
+        }
+      } else if (!e.isFile()) {
+        throw oatsError("invalid-artifact", `artifact contains an unsupported file type: ${path}`);
+      }
+    }
+  };
+  walk(root);
+}
+
+function verifyTree(dir, capability, row, pkg) {
+  assertRetainableTree(dir);
+  const actual = capabilityArtifactIntegrity(dir);
+  if (actual !== row.integrity) {
+    throw oatsError("integrity-drift", `retained capability ${capability}: expected ${row.integrity}, got ${actual} at ${dir}`);
+  }
+  verifyCapabilityInstallation(dir, capability, row, pkg);
+}
+
+export function ensureStoreIgnore(dir) {
+  const ignore = join(dir, ".gitignore");
+  const verify = () => {
+    if (!exists(ignore)?.isFile() || readFileSync(ignore, "utf8") !== "*\n") {
+      throw oatsError("invalid-artifact-store", `managed artifact ignore file must contain exactly '*': ${ignore}`);
+    }
+  };
+  if (exists(ignore)) { verify(); return; }
+
+  // Exclusive creation at the public name exposes an empty/partial file. Write
+  // and close in an owned, same-filesystem directory, then link atomically with
+  // no replacement. EEXIST is evidence to verify, never permission to repair.
+  // No retries, hostile-host isolation or power-loss durability are promised;
+  // a crash can leave dot-prefixed metadata staging for explicit cleanup.
+  const staging = mkdtempSync(join(dir, ".gitignore-"));
+  let failed = false, primary;
+  try {
+    const temp = join(staging, ".gitignore");
+    writeFileSync(temp, "*\n", { flag: "wx" });
+    try { linkSync(temp, ignore); }
+    catch (e) { if (e.code !== "EEXIST") throw e; }
+    verify();
+  } catch (error) {
+    failed = true;
+    primary = error;
+    throw error;
+  } finally {
+    // Only our metadata staging. Never unlink the public name (even on error),
+    // traverse another producer's staging, or change source/published modes.
+    try { rmSync(staging, { recursive: true, force: true }); }
+    catch (cleanup) {
+      const diagnostic = `artifact ignore staging cleanup failed at ${staging}: ${cleanup?.message ?? cleanup}`;
+      const error = failed
+        ? new AggregateError([primary, cleanup], `${primary?.message ?? primary}; ${diagnostic}`, { cause: primary })
+        : new Error(diagnostic, { cause: cleanup });
+      error.code = failed ? primary?.code : cleanup?.code;
+      if (failed && primary?.provenance !== undefined) error.provenance = primary.provenance;
+      error.stagingPath = staging;
+      throw error;
+    }
+  }
+}
+
+// The scope itself may be a user's symlink. Managed descendants must be real
+// directories, so a stale/broken store link cannot redirect publication.
+function storePath(scope, capability, create) {
+  let dir;
+  try { dir = realpathSync(scope); }
+  catch (e) {
+    if (e.code === "ENOENT") throw oatsError("artifact-not-found", `artifact scope is absent: ${scope}`);
+    throw e;
+  }
+  for (const [index, part] of [...STORE_PARTS, capability].entries()) {
+    dir = join(dir, part);
+    if (create) {
+      try { mkdirSync(dir); }
+      catch (e) { if (e.code !== "EEXIST") throw e; }
+    }
+    const st = exists(dir);
+    if (!st && !create) throw oatsError("artifact-not-found", `artifact store path is absent: ${dir}`);
+    if (!st || !st.isDirectory()) throw oatsError("invalid-artifact-store", `artifact store component must be a directory: ${dir}`);
+    if (index === STORE_PARTS.length - 1 && create) {
+      // Owned store metadata, outside every hashed artifact. Write before any
+      // staging payload; no Git command or change to authored directories.
+      ensureStoreIgnore(dir);
+    }
+  }
+  return dir;
+}
+
+/** Verify an exact retained revision using captured provenance. No current lock,
+ * source repository, trust approval or network lookup participates. */
+export function verifyRetainedCapability(scope, capability, lock) {
+  const { row, pkg } = lockRows(capability, lock);
+  retainedCapabilityDir(scope, capability, row.integrity); // validate before path use
+  const dir = join(storePath(scope, capability, false), row.integrity);
+  verifyTree(dir, capability, row, pkg);
+  return { capability, integrity: row.integrity, dir };
+}
+
+/** Publish once by same-filesystem rename. Never repairs or replaces a retained
+ * revision; a damaged existing entry requires explicit operator intervention.
+ * `lock` carries validated package/capability provenance from one resolution.
+ * Its trust flags are not grants from this API, and are never written here. */
+export function retainCapabilityArtifact(scope, sourceDir, capability, lock) {
+  const { row, pkg } = lockRows(capability, lock);
+  retainedCapabilityDir(scope, capability, row.integrity);
+  verifyTree(sourceDir, capability, row, pkg);
+  const root = storePath(scope, capability, true);
+  const dir = join(root, row.integrity);
+  const receipt = { capability, integrity: row.integrity, dir };
+  if (exists(dir)) {
+    verifyTree(dir, capability, row, pkg);
+    return { ...receipt, status: "kept" };
+  }
+  // Refuse recursive copies if a caller supplied an ancestor of the store.
+  if (!outside(realpathSync(sourceDir), root)) throw oatsError("invalid-artifact", "artifact source contains its destination store");
+  const status = publishArtifactTree(sourceDir, dir, (tree) => verifyTree(tree, capability, row, pkg));
+  return { ...receipt, status };
+}

package/lib/capability-execution.mjs

@@ -0,0 +1,15 @@
+/** The single existing executable-surface definition, shared with captured
+ * approval diagnostics. This projection does not validate/compile a manifest
+ * or permit execution; the action adapter must validate the full contract. */
+export function executableSurfaceOf(manifest) {
+  return {
+    commands: Object.keys(manifest?.commands || {}),
+    hooks: Object.keys(manifest?.hooks || {}),
+    environment: [...(manifest?.environment || [])],
+    ...(manifest?.environmentNamespaces?.length ? { environmentNamespaces: [...manifest.environmentNamespaces] } : {}),
+  };
+}
+export function hasExecutableSurface(manifest) {
+  const s = executableSurfaceOf(manifest);
+  return s.commands.length > 0 || s.hooks.length > 0 || s.environment.length > 0;
+}

package/lib/capability-inputs.mjs

@@ -0,0 +1,39 @@
+/** Capability-owned helper instruction policy and selected supplemental inputs.
+ * Shape only: no source lookup, binding, readiness, side effects or fallback. */
+import { canonicalJson } from './portable-values.mjs';
+import { objectAt, invalidShape } from './portable-shape.mjs';
+import { portablePath } from './source-spec.mjs';
+
+export function validateHelperInjection(value) {
+  canonicalJson(value);
+  const file = value?.mode === 'file';
+  objectAt(value, file ? ['version', 'mode', 'path'] : ['version', 'mode'], file ? ['version', 'mode', 'path'] : ['version', 'mode']);
+  if (value.version !== 1 || !['inherit', 'omit', 'file'].includes(value.mode)) invalidShape('/helperInjection', 'unsupported helper instruction policy');
+  if (file) portablePath(value.path);
+  return value;
+}
+
+export function validateHookInputs(value) {
+  canonicalJson(value);
+  objectAt(value, ['sourceReceipt'], [], '/inputs');
+  if (Object.hasOwn(value, 'sourceReceipt')) {
+    objectAt(value.sourceReceipt, ['version'], ['version'], '/inputs/sourceReceipt');
+    if (value.sourceReceipt.version !== 1) invalidShape('/inputs/sourceReceipt/version', 'unsupported source receipt input version');
+  }
+  return value;
+}
+
+/** Presence is explicit. In particular, absent/empty inputs are NOT consent;
+ * this validator does not infer whether a provider depends on that input. */
+export function validateCapabilityInputDeclarations(manifest) {
+  canonicalJson(manifest);
+  objectAt(manifest, null, []);
+  if (Object.hasOwn(manifest, 'helperInjection')) validateHelperInjection(manifest.helperInjection);
+  if (Object.hasOwn(manifest, 'hooks')) {
+    objectAt(manifest.hooks, null, [], '/hooks');
+    for (const hook of Object.values(manifest.hooks)) {
+      if (hook !== null && typeof hook === 'object' && Object.hasOwn(hook, 'inputs')) validateHookInputs(hook.inputs);
+    }
+  }
+  return manifest;
+}

package/lib/capability-provenance.mjs

@@ -0,0 +1,231 @@
+/** Existing materialized-capability data contract: layout/identity, lock-row
+ * validation and installation provenance. No scope discovery, lock writes,
+ * acquisition, approval, resolver or lifecycle dispatch. */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { oatsError } from "./errors.mjs";
+
+/** Scope-relative capability store subtrees. */
+export const CAPABILITIES_DIRNAME = join(".agents", "capabilities");
+export const INSTALLED_SUBDIR = "installed";
+
+/** THE identity grammar for a MATERIALIZED (revised-v2) capability.
+ *
+ * A materialized capability id is not merely a label: it becomes a DIRECTORY
+ * NAME directly under `installed/`, so anything that can steer a filesystem
+ * join must be impossible before the join happens. The grammar is deliberately
+ * the package-id grammar — namespaced dots are fine, and `/`, `\`, `..`,
+ * absolute forms, `@`, and percent-encoded spellings are all outside it.
+ *
+ * The LEGACY v1 / owned / `from: path:` grammar (loadManifestAt) stays looser
+ * on purpose: those artifacts are named by `basename()` of their source, never
+ * by the declared id, so the id never reaches a path there. Tightening it would
+ * strand already-published standalone capabilities. */
+export const CAPABILITY_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
+export const isMaterializedCapabilityId = (id) => typeof id === "string" && CAPABILITY_ID_RE.test(id);
+/** Why a capability id was refused, in one sentence, for every caller's own
+ * typed error (the lock parser raises invalid-lock, manifest validation raises
+ * invalid-package-manifest — the code each consumer already branches on). */
+export const capabilityIdViolation = (id) =>
+  `${JSON.stringify(id)} is not a valid capability identity — expected ${CAPABILITY_ID_RE.source} (a namespaced id such as "oats.okf"; path separators, "..", absolute paths, "@" and encoded forms are refused because the id names a directory under ${INSTALLED_SUBDIR}/)`;
+
+/** Generated provenance file inside every materialized artifact. It is INSIDE
+ * the hashed tree, so tampering with it is integrity drift; the lock stays
+ * authoritative. */
+export const CAPABILITY_INSTALLATION_FILE = ".oats-installation.json";
+
+export const PACKAGE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
+/** Own-property PRESENCE of any of these on a package row is forbidden
+ * transitional evidence (contract §4.1) — never truthiness and never array
+ * length, so an empty `capabilities: []` or a dependency-free old row still
+ * classifies. Package-row `path`/`dependencies` are NEVER tells: the current
+ * shape retains both. */
+export const TRANSITIONAL_ROW_FIELDS = ["capabilities", "trustedCapabilities", "depsIntegrity"];
+
+/** Normalize a configured package path to its canonical form, or throw.
+ *
+ * Canonical form is a POSIX-relative path with no redundant or trailing
+ * separators; every spelling of the repository root ("", ".", "./", "./.")
+ * normalizes to the single canonical "." so a root selection round-trips
+ * identically through spec → lock → JSON → doctor/list/update (contract §4).
+ *
+ * Fail-closed: absolute paths, Windows drive paths, host-ambient "~" spellings,
+ * backslash separators (ambiguous — a backslash is a legal POSIX filename
+ * character, so accepting it as a separator would make containment checks
+ * disagree with the filesystem) and NUL are rejected as invalid-source; ".."
+ * traversal is path-escape. Returns undefined ONLY for an absent value, so the
+ * caller can apply the source-appropriate default. */
+export function normalizePackagePath(raw, { where = "package path", code = "invalid-source" } = {}) {
+  // ABSENT means absent. A present `null` (JSON's way of spelling a malformed
+  // value) is a violation, not a fall-through to the caller's default — a
+  // catalog entry that says `"path": null` must fail, not silently install
+  // DEFAULT_PACKAGE_PATH.
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "string") throw oatsError(code, `${where} must be a string (got ${Array.isArray(raw) ? "array" : raw === null ? "null" : typeof raw})`);
+  const s = raw.trim();
+  if (s.includes("\0")) throw oatsError(code, `${where} contains a NUL byte`);
+  if (s.startsWith("~")) throw oatsError(code, `${where} "${s}" is a host-ambient path — package paths are repository-relative`);
+  if (s.includes("\\")) throw oatsError(code, `${where} "${s}" uses backslashes — package paths are POSIX-relative (use "/")`);
+  if (/^[A-Za-z]:[/\\]/.test(s)) throw oatsError(code, `${where} "${s}" is an absolute drive path — package paths are repository-relative`);
+  if (isAbsolute(s)) throw oatsError(code, `${where} "${s}" is absolute — package paths are repository-relative`);
+  const segments = s.split("/").filter((seg) => seg !== "" && seg !== ".");
+  if (segments.includes("..")) throw oatsError("path-escape", `${where} "${s}" escapes the source root with ".."`);
+  return segments.length ? segments.join("/") : ".";
+}
+
+/** Parse a lock entry's `source` against the EXACT normalized grammar the
+ * writer produces. Strict on purpose: `updatePackage` turns this back into a
+ * source spec, so a payload that merely "starts with catalog:" but is not a
+ * valid catalog id gets RECLASSIFIED downstream — `catalog:../evil` would be
+ * re-parsed as a host-relative local path and acquired from the operator's
+ * filesystem. A lock also never carries a `#<path>` fragment: the selected
+ * root is the entry's own `path` field, and a fragment here would produce a
+ * double-fragment spec on update. */
+export function parseLockSource(src) {
+  const s = String(src || "");
+  const bad = (why) => oatsError("invalid-source", `unknown lock source "${src}" — ${why}`);
+  if (s.includes("#")) throw bad(`lock sources carry no "#<path>" fragment; the selected package root is the entry's "path" field`);
+  if (s.startsWith("path:")) {
+    const p = s.slice(5);
+    if (!p) throw bad("empty path source");
+    if (!isAbsolute(p)) throw bad("path source must be an absolute directory (the writer always resolves it)");
+    return { kind: "path", path: p, normalized: s };
+  }
+  if (s.startsWith("catalog:")) {
+    const body = s.slice(8);
+    // Split at the FIRST "@", mirroring the public parser's regex: the catalog
+    // id grammar cannot contain "@", so everything after the first one is the
+    // selector. Splitting at the LAST "@" misreads a legitimate ref spelling
+    // such as `oats.okf@release@candidate` — which the writer does produce —
+    // as the id `oats.okf@release`.
+    const at = body.indexOf("@");
+    const id = at > 0 ? body.slice(0, at) : body;
+    const selector = at > 0 ? body.slice(at + 1) : undefined;
+    if (!PACKAGE_ID_RE.test(id)) throw bad(`"${id}" is not a valid official catalog id`);
+    if (at > 0 && !selector) throw bad("empty catalog selector");
+    return { kind: "catalog", id, selector, normalized: s };
+  }
+  if (s.startsWith("git:")) {
+    const body = s.slice(4);
+    const at = body.lastIndexOf("@") > body.lastIndexOf("/") ? body.lastIndexOf("@") : -1;
+    const url = at > 0 ? body.slice(0, at) : body;
+    const ref = at > 0 ? body.slice(at + 1) : undefined;
+    if (!url) throw bad("empty git url");
+    if (at > 0 && !ref) throw bad("empty git ref");
+    if (!/^(https?:\/\/|file:\/\/|git@|ssh:\/\/|git:\/\/)/.test(url)) throw bad(`"${url}" is not an http(s)/ssh/file/git URL`);
+    return { kind: "git", url, ref, normalized: s };
+  }
+  throw oatsError("invalid-source", `unknown lock source "${src}"`);
+}
+
+/** Semantic lock-entry validation for a PACKAGE row (runtime API addendum §4):
+ * source/commit pairing, canonical path, dependency references (incl. self and
+ * cycle over the locked graph), digest shapes, uniqueness. Run BEFORE restore,
+ * trust/approval, update/remove/migration planning, the locked-template reader,
+ * and doctor/list consumption. Fails closed with code "invalid-lock" carrying
+ * file/package provenance; never normalizes or auto-repairs on read. */
+export function validateLockEntry(packageId, entry, allPackages = {}, opts = {}) {
+  const where = opts.file ? ` (${opts.file})` : "";
+  const bad = (msg) => oatsError("invalid-lock", `lock entry for package "${packageId}"${where} is invalid: ${msg}`, [{ package: packageId, file: opts.file, violation: msg }]);
+  if (!entry || typeof entry !== "object") throw bad("not an object");
+  for (const k of ["source", "path", "version", "commit", "integrity"]) if (!entry[k] || typeof entry[k] !== "string") throw bad(`missing ${k}`);
+  // The selected package root is a STRICT separate field (contract §1.1) stored
+  // in canonical form only — a lock is never normalized or repaired on read, so
+  // a non-canonical spelling ("./sub", "sub/", "") is invalid, not silently
+  // accepted. That is what makes the root representation round-trip.
+  {
+    let canonical;
+    try { canonical = normalizePackagePath(entry.path, { where: "path", code: "invalid-lock" }); }
+    catch (e) { throw bad(`invalid path ${JSON.stringify(entry.path)} — ${e.message}`); }
+    if (canonical !== entry.path) throw bad(`path ${JSON.stringify(entry.path)} is not in canonical form (expected ${JSON.stringify(canonical)})`);
+  }
+  if (!/^sha256-[0-9a-f]{64}$/.test(entry.integrity)) throw bad(`malformed integrity "${entry.integrity}"`);
+  // Present-but-wrong-typed optional fields are invalid — default ONLY when absent.
+  // `dependencies` is ALWAYS recorded (empty array when none), so a reader never
+  // has to distinguish absent from empty.
+  if (!Array.isArray(entry.dependencies)) throw bad("dependencies must be an array (empty when the package has none)");
+  for (const d of entry.dependencies) if (typeof d !== "string" || !PACKAGE_ID_RE.test(d)) throw bad(`dependencies contains an invalid package id ${JSON.stringify(d)}`);
+  if (new Set(entry.dependencies).size !== entry.dependencies.length) throw bad("dependencies contains duplicates");
+  // Package rows lock transport only. A capability list, a trust list or a
+  // dependency-closure digest here is the unsupported transitional shape — the
+  // central parser rejects those documents outright (contract §4.1); this is
+  // the entry-level backstop for a row reaching validation another way.
+  for (const gone of TRANSITIONAL_ROW_FIELDS) {
+    if (Object.hasOwn(entry, gone)) throw bad(`"${gone}" is a transitional package-root field — package rows lock transport only (capabilities and trust live on capability rows)`);
+  }
+  let src;
+  try { src = parseLockSource(entry.source); } catch { throw bad(`unrecognized source "${entry.source}"`); }
+  if (src.kind === "path" && !src.path) throw bad("empty path source");
+  if (src.kind === "git" && !src.url) throw bad("empty git source");
+  if (src.kind === "catalog" && !src.id) throw bad("empty catalog source");
+  if (src.kind === "path") {
+    if (entry.commit !== "local") throw bad(`path source requires commit "local", got "${entry.commit}"`);
+    // Local acquisition is exact-directory: the source string already names the
+    // package root, so the only valid contained path is the root itself.
+    if (entry.path !== ".") throw bad(`path source requires path "." (local sources are exact directories), got ${JSON.stringify(entry.path)}`);
+  }
+  else if (!/^[0-9a-f]{40}$/.test(entry.commit)) throw bad(`${src.kind} source requires an exact 40-hex commit, got "${entry.commit}"`);
+  for (const d of entry.dependencies || []) {
+    if (d === packageId) throw bad(`self-dependency "${d}"`);
+    // Object.hasOwn: a dependency literally named "constructor"/"__proto__"
+    // must not pass via Object.prototype.
+    if (!Object.hasOwn(allPackages, d)) throw bad(`dependency "${d}" is not locked in the same packages map`);
+  }
+  // Cycle over the locked dependency graph reachable from this entry.
+  const visiting = new Set();
+  const visited = new Set();
+  const walk = (id, chain) => {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) throw bad(`dependency cycle in the locked graph: ${[...chain, id].join(" → ")}`);
+    visiting.add(id);
+    const deps = Object.hasOwn(allPackages, id) && Array.isArray(allPackages[id]?.dependencies) ? allPackages[id].dependencies : [];
+    for (const d of deps) if (Object.hasOwn(allPackages, d) || d === packageId) walk(d, [...chain, id]);
+    visiting.delete(id); visited.add(id);
+  };
+  walk(packageId, []);
+  return true;
+}
+
+/** Semantic validation of one CAPABILITY row against the whole document
+ * (contract §4). The `package` back-reference must name a locked package: it is
+ * the single provider truth, so a dangling reference would leave a materialized
+ * artifact with no provenance to restore or verify it from. */
+export function validateCapabilityLockEntry(capabilityId, entry, allPackages = {}, opts = {}) {
+  const where = opts.file ? ` (${opts.file})` : "";
+  const bad = (msg) => oatsError("invalid-lock", `capability lock entry for "${capabilityId}"${where} is invalid: ${msg}`, [{ package: capabilityId, file: opts.file, violation: msg }]);
+  if (typeof capabilityId !== "string" || !capabilityId) throw bad("empty capability id");
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw bad("not an object");
+  for (const k of ["version", "package", "path", "integrity"]) if (!entry[k] || typeof entry[k] !== "string") throw bad(`missing ${k}`);
+  if (!PACKAGE_ID_RE.test(entry.package)) throw bad(`provider package ${JSON.stringify(entry.package)} is not a valid package identity`);
+  if (!Object.hasOwn(allPackages, entry.package)) throw bad(`provider package "${entry.package}" is not locked in the same packages map`);
+  {
+    let canonical;
+    try { canonical = normalizePackagePath(entry.path, { where: "path", code: "invalid-lock" }); }
+    catch (e) { throw bad(`invalid path ${JSON.stringify(entry.path)} — ${e.message}`); }
+    if (canonical !== entry.path) throw bad(`path ${JSON.stringify(entry.path)} is not in canonical form (expected ${JSON.stringify(canonical)})`);
+  }
+  if (!/^sha256-[0-9a-f]{64}$/.test(entry.integrity)) throw bad(`malformed integrity "${entry.integrity}"`);
+  if (typeof entry.trusted !== "boolean") throw bad(`"trusted" must be a boolean (got ${JSON.stringify(entry.trusted)})`);
+  return true;
+}
+
+/** Read an artifact's provenance and check it AGREES with the lock rows it was
+ * projected from. Disagreement is invalid-lock: the artifact and the lock claim
+ * different origins, and neither may silently win. (A modified file also fails
+ * integrity, but this gives the precise diagnosis.) */
+export function verifyCapabilityInstallation(dir, capabilityId, capRow, pkgRow) {
+  const file = join(dir, CAPABILITY_INSTALLATION_FILE);
+  if (!existsSync(file)) throw oatsError("invalid-lock", `materialized capability ${capabilityId} has no ${CAPABILITY_INSTALLATION_FILE} provenance — reproject it with \`oats install\``, [{ package: capabilityId, file }]);
+  let doc;
+  try { doc = JSON.parse(readFileSync(file, "utf8")); }
+  catch (e) { throw oatsError("invalid-lock", `materialized capability ${capabilityId} has malformed ${CAPABILITY_INSTALLATION_FILE}: ${e.message}`, [{ package: capabilityId, file }]); }
+  const expected = {
+    schemaVersion: 1, capability: capabilityId, version: capRow.version, package: capRow.package,
+    packageVersion: pkgRow.version, source: pkgRow.source, commit: pkgRow.commit,
+    packagePath: pkgRow.path, capabilityPath: capRow.path,
+  };
+  for (const [k, want] of Object.entries(expected)) {
+    if (doc?.[k] !== want) throw oatsError("invalid-lock", `materialized capability ${capabilityId}: ${CAPABILITY_INSTALLATION_FILE} "${k}" is ${JSON.stringify(doc?.[k])} but the lock records ${JSON.stringify(want)}`, [{ package: capabilityId, file, violation: k }]);
+  }
+  return doc;
+}

package/lib/captured-action-shape.mjs

@@ -0,0 +1,21 @@
+/** The existing captured loader action wire, shared with provider invocation
+ * validation. This is a data codec, not a dispatch table or provider policy. */
+import { canonicalJson } from "./portable-values.mjs";
+import { objectAt, stringAt } from "./portable-shape.mjs";
+import { oatsError } from "./errors.mjs";
+
+export function validateCapturedAction(action) {
+  canonicalJson(action);
+  if (!["inspect", "compose", "command", "operation", "hook"].includes(action?.kind)) throw oatsError("unsupported-action", "captured action is not supported by this loader");
+  if (["inspect", "compose"].includes(action.kind)) objectAt(action, ["kind"], ["kind"]);
+  else if (action.kind === "command") {
+    objectAt(action, ["kind", "capability", "namespace", "name"], ["kind", "name"]);
+    if ((action.capability === undefined) === (action.namespace === undefined)) throw oatsError("invalid-declaration", "command needs exactly one capability or namespace");
+  } else {
+    const fields = action.kind === "hook" ? ["kind", "capability", "name"] : ["kind", "slot", "name"];
+    objectAt(action, fields, fields);
+  }
+  for (const key of ["name", "namespace", "capability", "slot"]) if (action[key] !== undefined) stringAt(action[key], `/action/${key}`);
+  if (action.kind === "operation" && !["knowledge", "messaging", "tasks"].includes(action.slot)) throw oatsError("invalid-declaration", "captured operation slot is invalid");
+  return action;
+}

package/lib/captured-admission-shape.mjs

@@ -0,0 +1,20 @@
+/** Generic incarnation/admitted-intent identities. Composition references are
+ * deliberately not accepted as incarnation or logical-request identities. */
+import { canonicalJson } from "./portable-values.mjs";
+import { objectAt, stringAt } from "./portable-shape.mjs";
+import { oatsError } from "./errors.mjs";
+
+export function validateIncarnationId(value) {
+  stringAt(value, "/incarnationId", { pattern: /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/ });
+  return value;
+}
+
+export function validateIntentRef(value) {
+  canonicalJson(value, { maxBytes: 4096, maxDepth: 4, maxEntries: 16 });
+  objectAt(value, ["schemaVersion", "executionId", "incarnationId", "attempt"], ["schemaVersion", "executionId", "incarnationId", "attempt"]);
+  if (value.schemaVersion !== 1) throw oatsError("unsupported-wire-version", "unsupported captured intent version");
+  stringAt(value.executionId, "/executionId", { pattern: /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/ });
+  validateIncarnationId(value.incarnationId);
+  if (!Number.isSafeInteger(value.attempt) || value.attempt < 1) throw oatsError("invalid-declaration", "intent attempt must be a positive integer");
+  return value;
+}