@awebai/oats 0.23.1 → 0.24.0

package/lib/artifact-approvals.mjs

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

@@ -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;
+}