@awebai/oats 0.25.9 → 0.26.0

package/injects/portable-instance-boundary.md

@@ -1,39 +0,0 @@
-## Captured instance: home, source and work
-
-**Your instance home** is the specific OATS instance directory supplied as
-`OATS_INSTANCE_HOME`, not your user home, source repository or work target.
-`instance.json.executionBinding` names the explicit captured **deployment and
-resolution**. Home-bound actions must also match this owned home's incarnation
-and recorded custody. Do not invent, copy or rewrite those identifiers to make
-another home or composition appear authorized.
-
-- **Home holds composed instructions and instance state.** `AGENTS.md` is the
-  canonical composed instruction file; `CLAUDE.md -> AGENTS.md` is its relative
-  compatibility alias, not a second instruction source. Preserve the generated
-  instructions, aliases and metadata; do not hand-edit them to change authority.
-  Task material and provider-managed state belong where their owning contract
-  specifies. The selected capabilities define any knowledge or memory protocol.
-- **`./soul` is a read-only retained source link, not your edit surface.** Reading
-  it must not depend on the publisher's current checkout. Never write through it
-  or modify retained artifacts. If a task authorizes source changes, use its
-  explicitly authorized tracked work surface and review path instead.
-- **`./work` is the task's work surface.** The work-mode instructions determine
-  whether it is an owned directory or another permitted repository view. Make
-  task edits only on that authorized surface, not in deployment stores or a
-  convenient source checkout. Reading an external input is not permission to
-  modify it or its owner.
-
-For supported captured commands, keep the explicit `--deployment` and
-`--resolution` pair from the recorded binding; supply the exact owned home when
-an action requires one. Running from home preserves the invocation's working
-location, but **cwd and a recorded `repo` path never select configuration or
-execution authority**. Source location, deployment, work target and team
-membership are separate facts. Do not fill missing inputs from a config cascade,
-a current lock, an alias match or another instance's environment.
-
-Load **oats-portable** for the running kernel's supported captured operations.
-A no-launch scaffold or `launchPending` receipt is not a running agent. Where
-captured launch, start/restart/wake/retire or recovery is unsupported, stop and
-report the limitation; do not strip selectors or use a legacy command as a
-workaround. Preserve work, knowledge, native history, identities and outstanding
-cleanup receipts. Missing authority is a hold, never permission to erase state.

package/injects/portable-work-directory.md

@@ -1,29 +0,0 @@
-## Portable work mode: owned directory
-
-Your `./work` is an **instance-owned execution directory**, not a Git worktree,
-a checkout, or a link to the source, deployment or another instance. No Git
-repository or branch is created by this mode. Do not initialize a fake repository
-to satisfy a workflow; a containing Git repository does not grant authority over
-its contents.
-
-- Do task work inside `./work`. External inputs and delivery destinations require
-  explicit task/capability authorization. Neither a source link nor a recorded
-  `repo` or work-target path grants permission to edit that external directory.
-- Execution uses the explicit captured deployment/resolution and, for home-bound
-  actions, the matching owned home/incarnation binding. Cwd does not resolve
-  configuration or select a provider; do not rebind from a current checkout,
-  config cascade, package lock or another instance.
-- Preserve home/work separation and canonical instruction aliases:
-  `AGENTS.md` in home, `CLAUDE.md -> AGENTS.md`, and the generated skill aliases.
-  The home's `./soul` link and retained software are read-only, not edit surfaces.
-- Deliver results using the task and selected capability's supported protocol.
-  This mode imposes no knowledge layout, harvester, storage backend or publication
-  policy. A recovery copy, if independently verified, is not publication or
-  accepted delivery.
-
-Keep nonempty work and its custody evidence intact. This mode does not promise
-implemented captured launch, start/restart/wake/retire or automatic recovery.
-Before any supported, explicitly authorized teardown, require verified
-preservation of outstanding work and receipts; if that capability is unavailable,
-hold and report rather than deleting or moving the home/work yourself. A
-`launchPending` result means runtime launch remains pending.

package/lib/artifact-approvals.mjs

@@ -1,120 +0,0 @@
-/** Exact-artifact local approval authority. Presence/catalog/legacy trust and
- * captured booleans never grant approval. No current selection-lock lookup. */
-import { join } from "node:path";
-import { canonicalJson, parseStrictJson } from "./portable-values.mjs";
-import { jsonIntegrity } from "./portable-digest.mjs";
-import { objectAt, versionAt } from "./portable-shape.mjs";
-import { validateArtifactRef, validateOrigin } from "./resolution-shape.mjs";
-import { verifyResolutionInputs, verifyRetainedCapability } from "./captured-resolutions.mjs";
-import { verifyPortableArtifact } from "./portable-artifacts.mjs";
-import { readLock3 } from "./portable-lock.mjs";
-import { executableSurfaceOf, hasExecutableSurface } from "./capability-execution.mjs";
-import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
-import { readPortableBytes } from "./portable-files.mjs";
-import { portableStateDirectory, withPortableStateWrite, writeGuardedPortableDocument } from "./portable-state.mjs";
-import { oatsError } from "./errors.mjs";
-
-const emptyLedger = () => ({ schemaVersion: 1, capabilities: Object.create(null) });
-const invalid = (message) => { throw oatsError("invalid-approval", message); };
-export function artifactApprovalKey(artifact) {
-  validateArtifactRef(artifact);
-  if (artifact.kind !== "capability") invalid("capability approval cannot authorize an unrelated resource bundle");
-  return `${artifact.integrity.format}:${artifact.integrity.value}`;
-}
-export function validateApprovalLedger(ledger) {
-  canonicalJson(ledger);
-  objectAt(ledger, ["schemaVersion", "capabilities"], ["schemaVersion", "capabilities"]);
-  versionAt(ledger.schemaVersion); objectAt(ledger.capabilities, null, []);
-  for (const [id, entries] of Object.entries(ledger.capabilities)) {
-    if (!isMaterializedCapabilityId(id)) invalid("invalid approval capability identity");
-    objectAt(entries, null, []);
-    for (const [key, entry] of Object.entries(entries)) {
-      objectAt(entry, ["artifact", "approved", "provenance"], ["artifact", "approved", "provenance"]);
-      if (artifactApprovalKey(entry.artifact) !== key || entry.artifact.capability !== id || entry.approved !== true) invalid("approval key, artifact or capability differs");
-      if (!Array.isArray(entry.provenance) || !entry.provenance.length) invalid("approval requires explicit operator provenance");
-      for (const origin of entry.provenance) {
-        validateOrigin(origin);
-        if (origin.kind !== "operator" || origin.document.kind !== "operator") invalid("approval cannot inherit source or legacy authority");
-      }
-    }
-  }
-  return ledger;
-}
-export function readApprovalLedger(scope) {
-  const root = portableStateDirectory(scope);
-  const bytes = root === null ? null : readPortableBytes(join(root, "approvals.json"), { allowMissing: true, invalidCode: "invalid-approval" });
-  if (bytes === null) return { ledger: emptyLedger(), integrity: null };
-  const ledger = parseStrictJson(bytes);
-  validateApprovalLedger(ledger);
-  if (!bytes.equals(Buffer.from(canonicalJson(ledger)))) invalid("approval ledger must use canonical JSON bytes");
-  return { ledger, integrity: jsonIntegrity(ledger) };
-}
-function approved(ledger, artifact) {
-  const key = artifactApprovalKey(artifact);
-  return Object.hasOwn(ledger.capabilities, artifact.capability) && Object.hasOwn(ledger.capabilities[artifact.capability], key);
-}
-function manifestFor(verified, id) {
-  return verified.manifests.get(id);
-}
-
-/** Diagnostic projection for this record's capabilities, not an action permit.
- * Dedicated helper records get their own approval check when used. */
-export function inspectCapturedApprovals(scope, reference) {
-  const verified = verifyResolutionInputs(scope, reference), { ledger } = readApprovalLedger(scope);
-  return { reference, capabilities: evaluateCapturedApprovals(verified, ledger) };
-}
-
-/** Shared evaluation over already verified inputs and a freshly read ledger.
- * This remains data; the action loader decides which surfaces the action uses. */
-export function evaluateCapturedApprovals(verified, ledger) {
-  validateApprovalLedger(ledger);
-  return Object.entries(verified.record.artifacts.capabilities).map(([id, row]) => {
-    const manifest = manifestFor(verified, id), required = hasExecutableSurface(manifest);
-    return { artifact: row.artifact, required, surface: executableSurfaceOf(manifest),
-      status: !required ? "not-required" : approved(ledger, row.artifact) ? "approved" : "approval-required" };
-  });
-}
-
-function grantApproval(context, artifact, manifest, origin) {
-  const key = artifactApprovalKey(artifact), id = artifact.capability;
-  const { ledger, integrity } = readApprovalLedger(context.deployment);
-  if (!hasExecutableSurface(manifest)) return { artifact, status: "not-required" };
-  if (approved(ledger, artifact)) return { artifact, status: "already-approved" };
-  if (!Object.hasOwn(ledger.capabilities, id)) ledger.capabilities[id] = Object.create(null);
-  ledger.capabilities[id][key] = { artifact, approved: true, provenance: [origin] };
-  validateApprovalLedger(ledger);
-  writeGuardedPortableDocument(context, join(context.root, "approvals.json"), ledger, { absent: integrity === null });
-  return { artifact, status: "approved" };
-}
-
-/** Prospective approval must be possible BEFORE running an executable provider
- * codec to complete a resolution. Address an exact retained artifact set, never
- * today's selected capability ID or a fabricated partial resolution. */
-export function approveAvailableCapability(scope, setKey, id, origin, validateManifest) {
-  validateOrigin(origin);
-  if (origin.kind !== "operator" || origin.document.kind !== "operator") invalid("approval requires an explicit operator input");
-  if (typeof setKey !== "string" || !/^sha256-[a-f0-9]{64}$/.test(setKey) || typeof id !== "string") invalid("invalid artifact-set approval target");
-  if (typeof validateManifest !== "function") throw new TypeError("prospective approval requires the complete kernel manifest codec");
-  return withPortableStateWrite(scope, (context) => {
-    const { lock } = readLock3(context.deployment);
-    const set = lock?.artifactSets[setKey];
-    if (!set || !Object.hasOwn(set.capabilities, id)) invalid("capability is not in that exact retained artifact set");
-    const artifact = set.capabilities[id].artifact;
-    const root = verifyPortableArtifact(context.deployment, artifact).dir;
-    const manifest = verifyRetainedCapability(root, set, id, validateManifest(root));
-    return grantApproval(context, artifact, manifest, origin);
-  });
-}
-
-/** Explicit approval writer. Called by the explicit operator approval operation,
- * not preparation/discovery. Approval still does not qualify provider/host readiness
- * or replace full manifest/launch compilation at the eventual action boundary. */
-export function approveCapturedCapability(scope, reference, id, origin) {
-  validateOrigin(origin);
-  if (origin.kind !== "operator" || origin.document.kind !== "operator") invalid("approval requires an explicit operator input");
-  return withPortableStateWrite(scope, (context) => {
-    const verified = verifyResolutionInputs(context.deployment, reference);
-    if (typeof id !== "string" || !Object.hasOwn(verified.record.artifacts.capabilities, id)) invalid("approval capability is not selected in this captured record");
-    return grantApproval(context, verified.record.artifacts.capabilities[id].artifact, manifestFor(verified, id), origin);
-  });
-}

package/lib/artifact-tree.mjs

@@ -1,141 +0,0 @@
-/** 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

@@ -1,179 +0,0 @@
-/** 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

@@ -1,15 +0,0 @@
-/** 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

@@ -1,39 +0,0 @@
-/** 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;
-}