@awebai/oats 0.41.1 → 0.42.1

package/lib/capability-contract.mjs

@@ -86,9 +86,65 @@ export function manifestContractProblems(m) {
     else if (isObject(value) && value.required === true && event !== "spawn") bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn hook is enforced (retire, launch and soul-scaffold run outside a spawn transaction)`);
     if (hookScriptEscapes(command)) bad(isObject(value) ? `${at}/command` : at, `hook "${event}" script ${JSON.stringify(command.trim().split(/\s+/)[0])} escapes the capability directory; a hook script is a path inside it`);
   }
+
+  if (m.retirement !== undefined) {
+    if (!isObject(m.retirement) || !isObject(m.retirement.disposable)) bad("/retirement", "manifest retirement must contain a disposable map");
+    else {
+      const unknown = Object.keys(m.retirement).filter((key) => key !== "disposable");
+      const scopes = Object.keys(m.retirement.disposable).filter((key) => !["home", "work"].includes(key));
+      if (unknown.length || scopes.length) bad("/retirement", `manifest retirement has unsupported keys: ${[...unknown, ...scopes].join(", ")}`);
+      for (const scope of ["home", "work"]) {
+        const roots = m.retirement.disposable[scope];
+        if (roots === undefined) continue;
+        const at = `/retirement/disposable/${scope}`;
+        if (!Array.isArray(roots) || roots.some((root) => typeof root !== "string")) { bad(at, `manifest retirement.disposable.${scope} must be an array of relative roots`); continue; }
+        if (scope !== "home") continue;
+        roots.forEach((root, i) => {
+          const problem = disposableHomeRootProblem(root);
+          if (problem === "shape") bad(`${at}/${i}`, `manifest retirement.disposable.home entry ${JSON.stringify(root)} must name one hidden top-level home entry (".name", or ".prefix-*")`);
+          else if (problem === "kernel-owned") bad(`${at}/${i}`, `manifest retirement.disposable.home entry ${JSON.stringify(root)} covers a kernel-owned home entry`);
+        });
+      }
+    }
+  }
   return problems;
 }
 
+/** `retirement.disposable.home`: provider-owned top-level entries of an instance
+ *  home that retirement neither fingerprints nor copies to recovery. An entry is
+ *  one hidden top-level name (`.aw`) or a prefix (`.aweb-identity-*`: every
+ *  top-level name starting with the text before `*`). No separator, no
+ *  traversal, no other glob, and nothing that covers a name the kernel owns in
+ *  a home. The published schema (docs/capability-manifest.schema.json) states
+ *  the same grammar. */
+const DISPOSABLE_HOME_EXACT_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
+/** The top-level entries the KERNEL writes in an instance home, as a
+ *  declaration may not cover them: these exact names, and every exact name
+ *  starting with one of these prefixes (the events log; the stop, restart and
+ *  start receipts and locks; the rollback marker; AGENTS.md backups; the
+ *  attachments directory). This is the one list: a new kernel-written top-level
+ *  home entry MUST be added here and to the `not` patterns of
+ *  `retirement.disposable.home` in docs/capability-manifest.schema.json. A
+ *  prefix declaration can reach none of them except through `.oats-`, which is
+ *  refused whole; `.oats-<provider>` as an exact name stays declarable. */
+const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
+const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments"];
+
+/** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
+ *  name or prefix), "kernel-owned", or undefined when it is sound. */
+export function disposableHomeRootProblem(root) {
+  if (typeof root !== "string") return "shape";
+  if (DISPOSABLE_HOME_PREFIX_RE.test(root)) return root.startsWith(".oats-") ? "kernel-owned" : undefined;
+  if (!DISPOSABLE_HOME_EXACT_RE.test(root)) return "shape";
+  return KERNEL_HOME_NAMES.has(root) || KERNEL_HOME_NAME_PREFIXES.some((prefix) => root.startsWith(prefix)) ? "kernel-owned" : undefined;
+}
+
+/** Whether the declared `root` (already sound) covers the top-level home entry `name`. */
+export function disposableHomeRootMatches(root, name) {
+  return root.endsWith("*") ? name.startsWith(root.slice(0, -1)) : name === root;
+}
+
 /** The setting keys a manifest declares (`settings.<key>`), sorted: names only, never their
  *  descriptions or defaults. The spawn preview and inspect expose them so a client can gate
  *  a choice on a declared key (e.g. a messaging provider's `join`). */