@brainervirus/workit-core 1.0.10 → 1.0.12

package/src/core/external-action.ts

@@ -14,6 +14,7 @@ import {
 } from "./task-contract";
 import { WorkitCore } from "./task-engine";
 import { TaskStore } from "./task-store";
+import { chainStepKey, normalizeChainSteps, type ChainStep } from "./authority";
 import * as z from "zod";
 import { execFileSync } from "node:child_process";
 
@@ -323,33 +324,58 @@ export const priorExternalAction = (
 /** Parse a plan-commit authorization descriptor (one approved list per plan). */
 export const planCommitDescriptor = (
   content: string,
-): { steps: string[]; branch: string } | null => {
+): { steps: ChainStep[]; branch: string; snapshotHead: string | null } | null => {
   try {
     const value = JSON.parse(content) as {
       operation?: unknown;
-      payload?: { plan_steps?: unknown; plan_branch?: unknown };
+      payload?: {
+        plan_steps?: unknown;
+        plan_branch?: unknown;
+        resolved?: { head?: unknown; branch?: unknown };
+      };
     };
     if (value.operation !== "git.commit" || !value.payload) return null;
-    const steps = value.payload.plan_steps;
+    const steps = normalizeChainSteps(value.payload.plan_steps);
     const branch = value.payload.plan_branch;
-    if (
-      !Array.isArray(steps) ||
-      steps.some((step) => typeof step !== "string" || !step) ||
-      typeof branch !== "string" ||
-      !branch
-    )
-      return null;
-    return { steps: steps as string[], branch };
+    if (!steps || typeof branch !== "string" || !branch) return null;
+    const head = value.payload.resolved?.head;
+    return { steps, branch, snapshotHead: typeof head === "string" ? head : null };
   } catch {
     return null;
   }
 };
 
+/**
+ * Chain lease: the recorded head must still be an ancestor of the current
+ * HEAD — history only moved forward. Rebase/reset underneath an approved
+ * chain invalidates it instead of executing on rewritten history.
+ */
+export const chainLeaseValid = (store: TaskStore, snapshotHead: string | null): boolean => {
+  if (!snapshotHead) return true;
+  try {
+    const head = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: store.root,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (head === snapshotHead) return true;
+    execFileSync("git", ["merge-base", "--is-ancestor", snapshotHead, head], {
+      cwd: store.root,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 export type PlanCommitAuthorization = {
   task: TaskRecord;
   entry: Entry<Decision>;
-  steps: string[];
+  steps: ChainStep[];
   branch: string;
+  snapshotHead: string | null;
   completed: string[];
 };
 
@@ -357,7 +383,10 @@ export type PlanCommitAuthorization = {
  * Find the single active plan-commit authorization whose next unconsumed step
  * is this exact commit message. Consumption order is enforced so each listed
  * commit executes once, in plan order; unlisted or replayed messages find no
- * authorization and require a fresh exact approval.
+ * authorization and require a fresh exact approval. Typed chain positions
+ * never match messages (a pathological message falls through to a fresh
+ * approval instead of consuming the wrong step), and a rewritten history
+ * breaks the lease.
  */
 export const approvedPlanCommit = (
   store: TaskStore,
@@ -395,8 +424,19 @@ export const approvedPlanCommit = (
       const completed =
         task.actionProgress?.find((progress) => progress.decisionId === entry.id)?.completedSteps ??
         [];
-      if (plan.steps[completed.length] !== message) return [];
-      return [{ task, entry, steps: plan.steps, branch: plan.branch, completed: [...completed] }];
+      const next = plan.steps[completed.length];
+      if (!next || next.kind !== "commit" || next.message !== message) return [];
+      if (!chainLeaseValid(store, plan.snapshotHead)) return [];
+      return [
+        {
+          task,
+          entry,
+          steps: plan.steps,
+          branch: plan.branch,
+          snapshotHead: plan.snapshotHead,
+          completed: [...completed],
+        },
+      ];
     });
   });
   if (matches.length !== 1)
@@ -409,6 +449,80 @@ export const approvedPlanCommit = (
   return success(workspace.data.revision, null, matches[0]);
 };
 
+export type ChainStepQuery =
+  | { operation: "git.branch_setup"; target: string }
+  | { operation: "hosting.pull_request" };
+
+/**
+ * Match one branch or PR step of a chain authorization: same session-bound
+ * search as plan commits, next unconsumed step of the right kind, lease
+ * intact. Commit steps stay on the plan path; this covers the steps plans
+ * could never express.
+ */
+export const approvedChainStep = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  query: ChainStepQuery,
+): Result<PlanCommitAuthorization> => {
+  const listed = store.listTasks();
+  const workspace = store.readWorkspace();
+  if (!listed.ok || !workspace.ok)
+    return failure("storage_error", "external action state is unavailable");
+  if (!workspace.data) return failure("not_found", "workspace not found");
+  const matches = listed.data.flatMap((task) => {
+    if (task.status !== "active" || task.workspaceId !== workspace.data!.id) return [];
+    if (
+      task.intent.provenance.session?.kind !== "host" ||
+      task.intent.provenance.session.host !== host ||
+      task.intent.provenance.session.handle !== actor
+    )
+      return [];
+    return task.decisions.flatMap((entry) => {
+      const decision = entry.data;
+      if (
+        decision.purpose !== "action" ||
+        decision.response !== "approved" ||
+        decision.revoked !== null
+      )
+        return [];
+      if (entry.provenance.kind !== "host_observed" || entry.provenance.receipts.length === 0)
+        return [];
+      const plan = planCommitDescriptor(decision.binding.approvedContent);
+      if (!plan) return [];
+      const completed =
+        task.actionProgress?.find((progress) => progress.decisionId === entry.id)?.completedSteps ??
+        [];
+      const next = plan.steps[completed.length];
+      if (!next) return [];
+      if (query.operation === "git.branch_setup") {
+        if (next.kind !== "branch" || next.target !== query.target) return [];
+      } else if (next.kind !== "pr") {
+        return [];
+      }
+      if (!chainLeaseValid(store, plan.snapshotHead)) return [];
+      return [
+        {
+          task,
+          entry,
+          steps: plan.steps,
+          branch: plan.branch,
+          snapshotHead: plan.snapshotHead,
+          completed: [...completed],
+        },
+      ];
+    });
+  });
+  if (matches.length !== 1)
+    return failure(
+      "permission_denied",
+      matches.length === 0
+        ? "no chain authorization matches this step"
+        : "multiple chain authorizations match this step",
+    );
+  return success(workspace.data.revision, null, matches[0]);
+};
+
 export const commitMessageFromDescriptor = (operation: string): string | undefined => {
   try {
     const descriptor = JSON.parse(operation) as {
@@ -423,6 +537,69 @@ export const commitMessageFromDescriptor = (operation: string): string | undefin
   }
 };
 
+/** Resolve a chain authorization into the exact binding an adapter needs
+ * to run one branch or PR step under the approved chain. Commit steps stay
+ * on the plan path; this covers the steps plans could never express. */
+export const chainStepBinding = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+): {
+  taskId: Id;
+  decisionId: Id;
+  binding: Decision["binding"];
+  expectedRevision: Revision;
+  expectedWorkspaceRevision: Revision;
+  step: string;
+} | null => {
+  let descriptor: { operation?: unknown; payload?: Record<string, unknown> };
+  try {
+    descriptor = JSON.parse(operation) as {
+      operation?: unknown;
+      payload?: Record<string, unknown>;
+    };
+  } catch {
+    return null;
+  }
+  const query: ChainStepQuery | null =
+    descriptor.operation === "git.branch_setup" &&
+    typeof descriptor.payload?.target_branch === "string"
+      ? { operation: "git.branch_setup", target: descriptor.payload.target_branch as string }
+      : descriptor.operation === "hosting.pull_request"
+        ? { operation: "hosting.pull_request" }
+        : null;
+  if (!query) return null;
+  const chain = approvedChainStep(store, host, actor, query);
+  if (!chain.ok) return null;
+  // PR steps run on the chain branch; the branch step itself creates it.
+  if (query.operation === "hosting.pull_request") {
+    let branch: string;
+    try {
+      branch = execFileSync("git", ["branch", "--show-current"], {
+        cwd: store.root,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch {
+      return null;
+    }
+    if (!branch || branch !== chain.data.branch) return null;
+  }
+  const workspace = store.readWorkspace();
+  if (!workspace.ok || !workspace.data) return null;
+  const next = chain.data.steps[chain.data.completed.length];
+  if (!next) return null;
+  return {
+    taskId: chain.data.task.id,
+    decisionId: chain.data.entry.id,
+    binding: chain.data.entry.data.binding,
+    expectedRevision: chain.data.task.revision,
+    expectedWorkspaceRevision: workspace.data.revision,
+    step: chainStepKey(next),
+  };
+};
+
 /** Resolve a plan-commit authorization into the exact binding an adapter needs
  * to run one listed commit under the approved list. */
 export const planCommitBinding = (
@@ -472,24 +649,131 @@ export const approvedExternalAction = (
   operation: string,
 ) => {
   const selected = externalActionState(store, host, actor, operation);
-  if (!selected.ok) return selected;
-  if (selected.data.entry.data.consumption !== null)
+  if (selected.ok) {
+    if (selected.data.entry.data.consumption !== null)
+      return failure(
+        selected.data.entry.data.consumption.state === "uncertain"
+          ? "external_outcome_unknown"
+          : "permission_denied",
+        selected.data.entry.data.consumption.state === "uncertain"
+          ? "previous external action outcome is unknown"
+          : "external action was already settled",
+      );
+    return selected;
+  }
+  // Intent carry for branch setup: an approval binds (target, base) intent,
+  // so unrelated HEAD or dirt moves between approval and execution re-resolve
+  // instead of demanding re-approval. Remote, existence, and target drift
+  // still fail closed through priorResolvedDrift.
+  const intent = approvedBranchSetupIntent(store, host, actor, operation);
+  if (intent.ok) {
+    if (intent.data.entry.data.consumption !== null)
+      return failure(
+        intent.data.entry.data.consumption.state === "uncertain"
+          ? "external_outcome_unknown"
+          : "permission_denied",
+        intent.data.entry.data.consumption.state === "uncertain"
+          ? "previous external action outcome is unknown"
+          : "external action was already settled",
+      );
+    return intent;
+  }
+  return selected;
+};
+
+/** Intent identity for a branch-setup descriptor: target and base bind the
+ * effect; head and dirt are execution-time state that re-resolves. */
+export const branchSetupIntent = (
+  descriptor: string,
+): { target: string; base: string; remoteBase: string | null; targetExists: boolean } | null => {
+  try {
+    const value = JSON.parse(descriptor) as {
+      operation?: unknown;
+      payload?: {
+        target_branch?: unknown;
+        resolved?: {
+          base_branch?: unknown;
+          remote_base?: unknown;
+          target_exists?: unknown;
+        };
+      };
+    };
+    if (value.operation !== "git.branch_setup" || !value.payload) return null;
+    const { target_branch, resolved } = value.payload;
+    if (typeof target_branch !== "string" || !target_branch || !resolved) return null;
+    if (typeof resolved.base_branch !== "string" || typeof resolved.target_exists !== "boolean")
+      return null;
+    return {
+      target: target_branch,
+      base: resolved.base_branch,
+      remoteBase: typeof resolved.remote_base === "string" ? resolved.remote_base : null,
+      targetExists: resolved.target_exists,
+    };
+  } catch {
+    return null;
+  }
+};
+
+/** Find the single unconsumed branch-setup approval with the same intent as
+ * the current descriptor, regardless of head or dirt moves since approval. */
+export const approvedBranchSetupIntent = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+) => {
+  const current = branchSetupIntent(operation);
+  if (!current) return failure("permission_denied", "no approved action is bound to this session");
+  const listed = store.listTasks();
+  const workspace = store.readWorkspace();
+  if (!listed.ok || !workspace.ok)
+    return failure("storage_error", "external action state is unavailable");
+  if (!workspace.data) return failure("not_found", "workspace not found");
+  const candidates = listed.data.flatMap((task) => {
+    if (
+      task.status !== "active" ||
+      task.workspaceId !== workspace.data!.id ||
+      task.intent.provenance.session?.kind !== "host" ||
+      task.intent.provenance.session.host !== host ||
+      task.intent.provenance.session.handle !== actor
+    )
+      return [];
+    return task.decisions
+      .filter(
+        (entry) =>
+          entry.data.purpose === "action" &&
+          entry.data.response === "approved" &&
+          entry.data.revoked === null,
+      )
+      .map((entry) => ({ task, entry }));
+  });
+  const matches = candidates.filter(({ entry }) => {
+    const intent = branchSetupIntent(entry.data.binding.approvedContent);
+    return (
+      intent !== null &&
+      intent.target === current.target &&
+      intent.base === current.base &&
+      intent.remoteBase === current.remoteBase &&
+      intent.targetExists === current.targetExists
+    );
+  });
+  if (matches.length !== 1)
     return failure(
-      selected.data.entry.data.consumption.state === "uncertain"
-        ? "external_outcome_unknown"
-        : "permission_denied",
-      selected.data.entry.data.consumption.state === "uncertain"
-        ? "previous external action outcome is unknown"
-        : "external action was already settled",
+      "permission_denied",
+      matches.length === 0
+        ? "no approved action is bound to this session"
+        : "multiple approved actions match this session",
     );
-  return selected;
+  return success(workspace.data.revision, null, { ...matches[0], workspace: workspace.data });
 };
 
 /**
  * Re-resolve guard: when a prior approval exists for the same requested
- * operation/payload, the freshly resolved baseline (source state and remote
- * base) must still match the approved descriptor. Drift returns not_started so
- * the agent re-presents the current state instead of executing a stale effect.
+ * operation/payload, the intent baseline must still match. For branch setup
+ * only (target, base, remote base, existence) bind the effect — head and
+ * dirt moves re-resolve instead of demanding re-approval. Drift names the
+ * moved element and returns not_started so the agent re-presents the
+ * current state instead of executing a stale effect.
  */
 export const priorResolvedDrift = (
   store: TaskStore,
@@ -511,6 +795,38 @@ export const priorResolvedDrift = (
     return success(null, null, null);
   }
   if (baseline === undefined || baseline === null) return success(null, null, null);
+  if (operation === "git.branch_setup") {
+    const before = branchSetupIntent(prior.data.entry.data.binding.approvedContent);
+    let after: ReturnType<typeof branchSetupIntent> = null;
+    try {
+      after = branchSetupIntent(
+        JSON.stringify({
+          operation,
+          payload: { ...(payload as Record<string, unknown>), resolved: currentResolved },
+        }),
+      );
+    } catch {
+      after = null;
+    }
+    if (before && after) {
+      const moved =
+        before.target !== after.target
+          ? "target_branch"
+          : before.base !== after.base
+            ? "base_branch"
+            : before.remoteBase !== after.remoteBase
+              ? "remote_base"
+              : before.targetExists !== after.targetExists
+                ? "target_exists"
+                : null;
+      if (moved === null) return success(null, null, null);
+      return failure(
+        "invalid_input",
+        `repository state changed since approval (${moved} moved); show the current state and approve the action again`,
+        { outcome: "not_started", operation },
+      );
+    }
+  }
   if (canonicalJson(baseline) === canonicalJson(currentResolved)) return success(null, null, null);
   return failure(
     "invalid_input",

package/src/core/methods.ts

@@ -17,12 +17,14 @@ type MethodDefinition = {
 
 export const METHODS: Readonly<Record<MethodId, MethodDefinition>> = {
   "workit-challenge": { dimensions: ["challenge", "decisions"] },
-  "workit-behavioral-tdd": { dimensions: ["testing"] },
-  "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review"] },
+  "workit-behavioral-tdd": { dimensions: ["testing"], ruleIds: ["mechanical-existing-checks"] },
+  "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review", "self-review"] },
   "workit-plan": { dimensions: ["artifacts", "continuity"] },
   "workit-implement": { dimensions: ["delegation"] },
-  "workit-debug": { ruleIds: ["root-cause-investigation"] },
-  "workit-handoff": { ruleIds: ["durable-handoff"] },
+  // workit-debug and workit-handoff stay slash-invoked: no generated rule
+  // routes to them, so they never appear spuriously in method selection.
+  "workit-debug": {},
+  "workit-handoff": {},
   "workit-deslop": { ruleIds: ["pre-pr-cleanup"] },
 };
 
@@ -33,12 +35,10 @@ export type SelectedMethod = {
 };
 
 const methodMatches = (
-  id: MethodId,
   definition: MethodDefinition,
   requirement: Policy["requirements"][number],
 ): boolean =>
-  (definition.dimensions?.includes(requirement.dimension) === true &&
-    !(id === "workit-review" && requirement.ruleId === "self-review")) ||
+  definition.dimensions?.includes(requirement.dimension) === true ||
   definition.ruleIds?.includes(requirement.ruleId) === true;
 
 const assuranceFor = (
@@ -71,7 +71,7 @@ const assuranceFor = (
 export function selectMethods(policy: Policy, capabilities: Capability[]): SelectedMethod[] {
   return (Object.entries(METHODS) as [MethodId, MethodDefinition][]).flatMap(([id, definition]) => {
     const requirements = policy.requirements.filter((requirement) =>
-      methodMatches(id, definition, requirement),
+      methodMatches(definition, requirement),
     );
     if (requirements.length === 0) return [];
     const capability = assuranceFor(id, definition, capabilities);

package/src/core/route-intent.ts

@@ -1,3 +1,5 @@
+import { TaskStore } from "./task-store";
+
 export type ShellRouteIntent = {
   route: "git.branch_setup" | "hosting.pull_request";
   guidance: string;
@@ -49,3 +51,29 @@ export function shellRouteIntent(command: string): ShellRouteIntent | null {
   }
   return null;
 }
+
+/**
+ * Session-scoped enforcement: the denial protects live Workit coordination,
+ * so it fires only where an active or paused task exists. Any filesystem or
+ * storage failure means "no live task" — never deny on uncertainty.
+ */
+export function hasLiveWorkitTask(dir: string): boolean {
+  try {
+    if (typeof dir !== "string" || dir === "") return false;
+    const listed = new TaskStore(dir).listTasks();
+    if (!listed.ok) return false;
+    return listed.data.some((task) => task.status === "active" || task.status === "paused");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Single core gate for the shell route denial. Adapters pass their
+ * session/project directory and delete local deny duplication; outside
+ * attributed sessions the command is silently allowed.
+ */
+export function shouldDenyShellRoute(dir: string, command: string): ShellRouteIntent | null {
+  if (!hasLiveWorkitTask(dir)) return null;
+  return shellRouteIntent(command);
+}

package/src/core/runtime-identity.ts

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+/** sha256 of the exact bytes, lowercase hex. */
+export const sha256Hex = (bytes: string | Uint8Array): string =>
+  createHash("sha256").update(bytes).digest("hex");
+
+/** sha256 of a bundle file's bytes, or null when it cannot be read. */
+export const bundleHashOfFile = (file: string): string | null => {
+  try {
+    return sha256Hex(readFileSync(file));
+  } catch {
+    return null;
+  }
+};
+
+// Segments of package-manager ephemeral caches (pnpm dlx, npx, pacquet).
+// Installs resolving through these break when the cache is cleared; one
+// table here replaces the per-callsite substring lists.
+const EPHEMERAL_CACHE_SEGMENTS = [
+  "/caches/pnpm/dlx/",
+  "/.cache/pnpm/dlx/",
+  "/_npx/",
+  "/.pacquet/",
+  "/library/caches/pnpm/",
+];
+
+/** True when the entry resolves through a package-manager ephemeral cache. */
+export const isEphemeralCachePath = (entry: string): boolean => {
+  if (!entry) return false;
+  const normalized = entry.replaceAll("\\", "/").toLowerCase();
+  return EPHEMERAL_CACHE_SEGMENTS.some((segment) => normalized.includes(segment));
+};

package/src/core/task-contract.ts

@@ -147,6 +147,113 @@ export const refSchema = z.discriminatedUnion("kind", [
 ]);
 export type Ref = z.infer<typeof refSchema>;
 
+/** Maps one reference during record traversal. Returning null marks the
+ * reference unportable: arrays drop it, nullable fields null it, and
+ * non-nullable positions propagate the drop to their owner. */
+export type RefMap = (ref: Ref) => Ref | null;
+
+type RewriteOutcome = { drop: boolean; value?: unknown };
+
+const rewriteUnknown = (value: unknown, map: RefMap): RewriteOutcome => {
+  if (Array.isArray(value)) {
+    const out: unknown[] = [];
+    for (const item of value) {
+      const rewritten = rewriteUnknown(item, map);
+      if (!rewritten.drop) out.push(rewritten.value);
+    }
+    return { drop: false, value: out };
+  }
+  if (typeof value === "object" && value !== null) {
+    if (refSchema.safeParse(value).success) {
+      const mapped = map(value as Ref);
+      return mapped === null ? { drop: true } : { drop: false, value: mapped };
+    }
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      const rewritten = rewriteUnknown(item, map);
+      out[key] = rewritten.drop ? null : rewritten.value;
+    }
+    return { drop: false, value: out };
+  }
+  return { drop: false, value };
+};
+
+const rewriteNode = (value: unknown, schema: z.ZodType, map: RefMap): RewriteOutcome => {
+  // Note: this zod version's classic accessors return core types, hence the
+  // casts below. Runtime behavior is identical; only the annotations differ.
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    refSchema.safeParse(value).success
+  ) {
+    const mapped = map(value as Ref);
+    return mapped === null ? { drop: true } : { drop: false, value: mapped };
+  }
+  let node: z.ZodType = schema;
+  while (
+    node instanceof z.ZodNullable ||
+    node instanceof z.ZodOptional ||
+    node instanceof z.ZodDefault
+  ) {
+    node = node.unwrap() as z.ZodType;
+  }
+  if (node === refSchema) {
+    if (!refSchema.safeParse(value).success) return { drop: false, value };
+    const mapped = map(value as Ref);
+    return mapped === null ? { drop: true } : { drop: false, value: mapped };
+  }
+  if (node instanceof z.ZodArray) {
+    if (!Array.isArray(value)) return { drop: false, value };
+    const out: unknown[] = [];
+    for (const item of value) {
+      const rewritten = rewriteNode(item, node.element as z.ZodType, map);
+      if (!rewritten.drop) out.push(rewritten.value);
+    }
+    return { drop: false, value: out };
+  }
+  if (node instanceof z.ZodObject) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+      return { drop: false, value };
+    const shape = node.shape as Record<string, z.ZodType>;
+    const record = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(record)) {
+      if (!(key in shape)) {
+        const scrubbed = rewriteUnknown(item, map);
+        out[key] = scrubbed.drop ? null : scrubbed.value;
+        continue;
+      }
+      const child = shape[key];
+      const rewritten = rewriteNode(item, child, map);
+      if (rewritten.drop) {
+        if (child instanceof z.ZodOptional || child instanceof z.ZodDefault) continue;
+        if (child instanceof z.ZodNullable) {
+          out[key] = null;
+          continue;
+        }
+        return { drop: true };
+      }
+      out[key] = rewritten.value;
+    }
+    return { drop: false, value: out };
+  }
+  return { drop: false, value };
+};
+
+/**
+ * Schema-driven reference rewrite over an already-validated record subtree.
+ * Every `Ref` anywhere in the value is mapped; unportable references are
+ * dropped from arrays, nulled in nullable fields, and propagated upward
+ * anywhere else — so a new ref-bearing field can never silently slip
+ * through export or import. Unknown (schema-absent) keys are scrubbed the
+ * same way. Returns null only when the root itself is an unportable ref.
+ */
+export const rewriteRecordRefs = (value: unknown, schema: z.ZodType, map: RefMap): unknown => {
+  const rewritten = rewriteNode(value, schema, map);
+  return rewritten.drop ? null : rewritten.value;
+};
+
 export const provenanceSchema = z
   .object({
     kind: z.enum(["host_observed", "agent_reported", "imported"]),
@@ -455,10 +562,11 @@ export const decisionSchema = z
         approvedContent: text,
         displayed: text.optional(),
         contentRefs: z.array(refSchema),
+        statedChoice: z.object({ ref: text, text: text }).strict().optional(),
       })
       .strict(),
     digest,
-    response: z.enum(["approved", "rejected"]),
+    response: z.enum(["approved", "rejected", "stated"]),
     requirementIds: z.array(digest),
     revoked: z.object({ at: utc, reason: text }).strict().nullable(),
     consumption: z