@mgiles/perk 3.2.0 → 3.3.0

package/extension/delivery/stackConflict.ts

@@ -0,0 +1,361 @@
+// The §8.51 warm sync-conflict state machine (the stacked-delivery conflict half of the
+// delivery family), Pi-free.
+//
+// The warm layer owns the DECISION tier only: fail-closed corroboration over the untrusted cold
+// status projection, the bounded dispatch pipeline (`decideSyncResolution`), the auto-fire
+// predicate, and the episode-settling reset rule. The real train state machine — journal,
+// cascade, continuation manifests, recovery, landing — is Python-owned (contracts.md
+// §8.42/§8.43/§8.49/§8.51); exterior effects reach TypeScript only as typed cold-door outcomes
+// composed by the adapters in `pi/v1/delivery/`. No warm journal writes, no ref mutations, no
+// readiness re-derivation.
+//
+// The warm transition table (contracts-grounded; the reconcile decision rows live in
+// `delivery/stackReconcile.ts`):
+//
+// | Operation | Persisted facts (authority) | Warm gesture → cold effect | Consent | Typed arms | Recovery |
+// |---|---|---|---|---|---|
+// | SYNC cascade (§8.49) | Journal SYNC prepared/completed/abandoned; checkpoints; continuation manifest on conflict (Python-written) | `objective_stack_sync {}`/`{base}` → `sync --yes`; `{dry_run}` → no consent, no journal | human gesture = `--yes` | no-op (± base-advanced hint) / declined / synchronized N / dry-run preview; failure: `rebase_conflict` (continuation retained) et al. | `/objective-recover` classifies; conflict → continue/abort/resolve |
+// | SYNC continue/abort (§8.49/§8.51) | Continuation manifest + temp refs + retained worktree | `{continue}`/`{abort}` → `--continue/--abort --yes` | human gesture | continued N / continuation declined / aborted-discarded | abandoned continuations self-clean; recover sweeps residue |
+// | ADOPT (§8.49) | Same journal; adopted node's remote head | `objective_stack_adopt {node, confirm}`; dry-run previews | `confirm: true` + dry-run-first | adopted + cascade rendered | never enters this dispatch pipeline (adapter-pinned) |
+// | Conflict dispatch (§8.51, warm-only) | Continuation manifest (containment-validated by the cold projection — `targets_contained`); fresh status projection; `conflict_resolution_attempts`; resolver lock dir | auto-fire on eligible refusal, or `{resolve: true}` | auto: the human's mutating gesture; resolve: explicit request | `dispatched(attempt/cap)` / `no_continuation` / `attempt_cap` / `resolver_busy` / `state_error` (total boundary) | increment verified BEFORE execution; unpersisted/thrown → withhold + release this call's claim |
+//
+// Progress is recorded only after verified effects: the counter reset fires only on a clean
+// cold completion; the increment is persisted-and-verified before native execution.
+
+import { basename, dirname } from "node:path";
+import {
+  booleanField,
+  type ColdJson,
+  numberField,
+  objectField,
+  objectListField,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import type { LeaseAcquisition } from "../substrate/resolverLease.ts";
+import { type ConflictAttempts, inspectConflictBudget } from "./submit.ts";
+
+/** The sync-tool invocation mode (which control flags the call carried) — decline wording and
+ * the completion verb depend on it, and the flags do not fully disambiguate the envelope.
+ * Deliberately narrow: adopt is NOT a `SyncMode` — its no-dispatch behavior is pinned at the
+ * adopt adapter, never through a widened predicate. */
+export type SyncMode = "sync" | "continue" | "abort";
+
+// --- the interpolation vocabularies (module-private, fail-closed) --------------------------------
+// Containment (`targets_contained`) is the cold plane's filesystem-truth validation; these
+// lexical vocabularies confine task/guidance facts independently of filesystem containment.
+// Defensive shell quoting does not widen this deliberately narrow accepted vocabulary.
+
+/** The identifier vocabulary for node/objective ids — whitelist validation doubles as
+ * control-character/line-break exclusion, so a poisoned projection string can never break out
+ * of task/guidance data. Alphanumeric-first excludes option-shaped identifiers. */
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** The ONE lineage predicate — the exact warm twin of the Python `_SAFE_LINEAGE_RE` vocabulary. */
+const LINEAGE_RE = /^[0-9A-Za-z][0-9A-Za-z_-]{0,63}$/;
+/** A canonical 26-char Crockford ULID operation id (`validated_targets`' shape, warm side). */
+const OPERATION_ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+/**
+ * The shell-inert absolute-path vocabulary: no space or shell metacharacter. Task construction
+ * quotes defensively but does not relax this policy. Legitimate exotic roots (e.g. spaces)
+ * still degrade to report-only.
+ */
+const SHELL_INERT_ABS_PATH_RE = /^\/[A-Za-z0-9._/-]+$/;
+/** Branch names interpolate as unquoted git arguments — alphanumeric-first (option-shaped
+ * `-`-leading refs are refused; git itself rejects them, so nothing legitimate is lost). */
+const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/;
+
+function hasDotDotSegment(path: string): boolean {
+  return path.split("/").includes("..");
+}
+
+/** The sanitized dispatch facts — every string is whitelist-validated before it gets here. */
+export interface SyncConflictDispatch {
+  operationId: string;
+  manifestPath: string;
+  objective: string;
+  node: string;
+  branch: string;
+  pr: number;
+  worktree: string;
+}
+
+/**
+ * Corroborate a retained sync conflict against the fresh status projection (§8.51): the
+ * continuation facts, the cold projection's containment verdict (`targets_contained` — the
+ * canonical Python `validated_targets` check relayed by §8.44; absent under version skew fails
+ * closed), the refusal-message freshness token, lineage/worktree containment, the conflicting
+ * layer's identity, and the interpolation vocabularies. Fail-closed: any miss is ineligible
+ * with the specific reason. `refusalMessage === null` skips ONLY the freshness-token clause
+ * (the explicit `resolve` path — there is no refusal; the human's request against the CURRENT
+ * projection is the trigger).
+ */
+export function corroborateSyncConflict(
+  payload: ColdJson,
+  refusalMessage: string | null,
+): { eligible: true; dispatch: SyncConflictDispatch } | { eligible: false; reason: string } {
+  const ineligible = (reason: string) => ({ eligible: false as const, reason });
+  const continuation = objectField(payload, "continuation");
+  if (continuation === undefined) {
+    return ineligible(
+      "the status projection reports no pending continuation — nothing was retained (a failed " +
+        "manifest write cleans its residue); fix the underlying issue and rerun the sync",
+    );
+  }
+  if (booleanField(continuation, "parseable") !== true) {
+    return ineligible(
+      "the pending continuation manifest is UNPARSEABLE — automated resolution cannot " +
+        "corroborate it; discard the retained continuation via objective_stack_sync " +
+        "{ abort: true } and rerun the sync",
+    );
+  }
+  // The containment gate: the cold projection computes the canonical `validated_targets`
+  // containment (Python filesystem truth — symlink-safe). A poisoned or symlinked manifest
+  // worktree can never mint a dispatch; an older CLI omits the field and fails closed.
+  if (booleanField(continuation, "targets_contained") !== true) {
+    return ineligible(
+      "the pending continuation's targets are not containment-validated by the cold status " +
+        "projection — resolve the rebase by hand in the retained worktree, or discard via " +
+        "objective_stack_sync { abort: true } (an older perk CLI never validates; update so " +
+        "both planes match).",
+    );
+  }
+  const operationId = stringField(continuation, "operation_id");
+  const node = stringField(continuation, "conflict_node_id");
+  const worktree = stringField(continuation, "worktree_path");
+  const manifestPath = stringField(continuation, "manifest_path");
+  if (
+    operationId === undefined ||
+    node === undefined ||
+    worktree === undefined ||
+    manifestPath === undefined
+  ) {
+    return ineligible(
+      "the pending continuation is missing operation/layer/path facts — resolve the rebase by " +
+        "hand in the retained worktree, or discard via objective_stack_sync { abort: true }",
+    );
+  }
+  if (!ID_RE.test(node)) {
+    return ineligible(
+      "the continuation's conflict node id falls outside the identifier vocabulary — refusing " +
+        "to dispatch; resolve by hand in the retained worktree",
+    );
+  }
+  // Freshness: every `rebase_conflict` arm names the layer whose rebase actually STOPPED as
+  // `for layer <node_id> ` (trailing space — `2.2` never matches `2.22`). On the continue-time
+  // failed-rewrite arm the PRESERVED manifest names the OLD layer while the message names the
+  // NEW one — the mismatch keeps the drive report-only over stale layer facts.
+  if (refusalMessage !== null && !refusalMessage.includes(`for layer ${node} `)) {
+    return ineligible(
+      `the refusal does not name the manifest's conflict layer ${node} — the retained ` +
+        "manifest may be a stale snapshot (a failed progress rewrite preserves the previous " +
+        "one); resolve the in-progress rebase by hand in the retained worktree, or discard via " +
+        "objective_stack_sync { abort: true }",
+    );
+  }
+  const train = objectField(payload, "train") ?? {};
+  const lineage = stringField(train, "delivery_lineage");
+  if (lineage === undefined || !LINEAGE_RE.test(lineage)) {
+    return ineligible(
+      "the train reports no vocabulary-valid delivery lineage — refusing to derive the claim " +
+        "path; dispatch the resolution by hand",
+    );
+  }
+  if (
+    basename(manifestPath) !== `${lineage}.json` ||
+    basename(dirname(manifestPath)) !== "sync-continuations"
+  ) {
+    return ineligible(
+      "the continuation manifest path is not sync-continuations/<lineage>.json — refusing to " +
+        "claim it; dispatch the resolution by hand",
+    );
+  }
+  if (!OPERATION_ULID_RE.test(operationId)) {
+    return ineligible(
+      "the continuation's operation id is not a canonical ULID — refusing to dispatch; resolve " +
+        "by hand in the retained worktree",
+    );
+  }
+  if (
+    !SHELL_INERT_ABS_PATH_RE.test(worktree) ||
+    hasDotDotSegment(worktree) ||
+    basename(worktree) !== `sync-${operationId}`
+  ) {
+    return ineligible(
+      "the retained worktree path falls outside the shell-inert containment vocabulary " +
+        "(absolute, sync-<operation-id>, no spaces or shell metacharacters) — dispatch the " +
+        "resolution by hand in the retained worktree the status names",
+    );
+  }
+  const layer = objectListField(train, "layers").find(
+    (row) => stringField(row, "node_id") === node,
+  );
+  if (layer === undefined) {
+    return ineligible(
+      "the conflicting layer is missing from the train projection — refusing to dispatch; " +
+        "inspect the train and resolve by hand",
+    );
+  }
+  const branch = stringField(layer, "branch");
+  const pr = numberField(layer, "pr_number");
+  if (branch === undefined || pr === undefined) {
+    return ineligible(
+      "the conflicting layer carries no branch/PR identity — the resolver's retained mode " +
+        "requires the PR; resolve by hand in the retained worktree",
+    );
+  }
+  if (!BRANCH_RE.test(branch) || branch.startsWith("/") || hasDotDotSegment(branch)) {
+    return ineligible(
+      "the conflicting layer's branch falls outside the interpolation vocabulary — refusing " +
+        "to dispatch; resolve by hand in the retained worktree",
+    );
+  }
+  // The redirect-resolved ACTIVE objective id — never the requested one (the
+  // driveStackReconcile rule): out-of-vocabulary → never drive.
+  const objective = stringField(objectField(payload, "objective") ?? {}, "id");
+  if (objective === undefined || !ID_RE.test(objective)) {
+    return ineligible(
+      "the projection's objective id falls outside the identifier vocabulary — refusing to " +
+        "dispatch; resolve by hand in the retained worktree",
+    );
+  }
+  return {
+    eligible: true,
+    dispatch: { operationId, manifestPath, objective, node, branch, pr, worktree },
+  };
+}
+
+/**
+ * The §8.51 auto-fire rule: a MUTATING sync/continue — never dry-run, never abort (adopt never
+ * reaches this predicate; its no-dispatch behavior is adapter-pinned) — refusing
+ * `rebase_conflict` is dispatch-eligible (the human's mutating gesture is the approval).
+ */
+export function autoDispatchEligible(
+  mode: SyncMode,
+  dryRun: boolean,
+  failure: { errorType: string } | null,
+): boolean {
+  if (failure === null || failure.errorType !== "rebase_conflict") return false;
+  if (dryRun) return false;
+  return mode === "sync" || mode === "continue";
+}
+
+/**
+ * The episode-settling reset rule: any clean, non-declined MUTATING completion re-opens the
+ * shared bounded conflict budget (write 0, preserving the equal-value short-circuit — an
+ * already-zero counter appends nothing). Never throws: a thrown or `false` write returns
+ * `false`, and the ADAPTER reports the reset-failure warning — a stale counter must be visible,
+ * never fatal to an already-verified cold completion.
+ */
+export function settleSyncEpisode(
+  attempts: ConflictAttempts,
+  outcome: { mutating: boolean; declined: boolean },
+): boolean {
+  if (!outcome.mutating || outcome.declined) return true;
+  try {
+    if (attempts.read() === 0) return true;
+    return attempts.write(0);
+  } catch {
+    return false;
+  }
+}
+
+/** The resolver-claim port — production = `acquireResolverLease`/`releaseResolverClaim`
+ * (substrate/resolverLease.ts), composed module-privately by the sync adapter. */
+export interface ResolverClaim {
+  acquire(manifestPath: string, operationId: string): LeaseAcquisition;
+  release(manifestPath: string, token: string): void;
+}
+
+/** The dispatch pipeline's ports — action-specific, never a facade. `readProjection` is the
+ * corroborating `perk objective stack status --json` re-read (module-private in the adapter). */
+export interface SyncResolutionDeps {
+  readProjection: () => Promise<{ ok: true; payload: ColdJson } | { ok: false; message: string }>;
+  claim: ResolverClaim;
+  attempts: ConflictAttempts;
+}
+
+/** The closed dispatch outcome — kinds map 1:1 onto the tool-surface `errorType`s. */
+export type SyncResolutionOutcome =
+  | { kind: "dispatched"; dispatch: SyncConflictDispatch; attempt: number; cap: number }
+  | { kind: "no_continuation" | "attempt_cap" | "resolver_busy" | "state_error"; reason: string };
+
+function releaseQuietly(claim: ResolverClaim, held: { manifestPath: string; token: string }): void {
+  try {
+    claim.release(held.manifestPath, held.token);
+  } catch {
+    // best-effort — leftover claim residue self-heals via the lease's reclaim rules
+  }
+}
+
+/**
+ * The shared dispatch pipeline (auto-drive AND the explicit `resolve` request), in pinned
+ * order: re-read the status projection → corroborate (containment + vocabularies) → inspect the
+ * shared bounded budget → take the resolver claim → persist the verified increment (a
+ * precondition for dispatch — an unverifiable counter must never bypass the cap; a `false`
+ * commit withholds and releases THIS call's claim, token-fenced) → `dispatched`. Rendering and
+ * execution/delivery stay adapter-side. Resolve-and-stop: nothing here publishes — the native
+ * classifier owns the outcome gate and the human's `continue` stays the publication gesture.
+ *
+ * Total boundary: every thrown port failure — a throwing projection read, claim port, or
+ * counter read/write — is caught and translated to the typed `state_error` arm (reason prefixed
+ * `conflict-dispatch state failure:`), releasing this call's claim when one was acquired. The
+ * closed union is honest; nothing escapes as a rejection.
+ */
+export async function decideSyncResolution(
+  deps: SyncResolutionDeps,
+  refusalMessage: string | null,
+): Promise<SyncResolutionOutcome> {
+  let held: { manifestPath: string; token: string } | null = null;
+  try {
+    const projection = await deps.readProjection();
+    if (!projection.ok) {
+      return {
+        kind: "no_continuation",
+        reason: `the corroborating status re-read failed — ${projection.message}`,
+      };
+    }
+    const corroborated = corroborateSyncConflict(projection.payload, refusalMessage);
+    if (!corroborated.eligible) {
+      return { kind: "no_continuation", reason: corroborated.reason };
+    }
+    const dispatch = corroborated.dispatch;
+    const budget = inspectConflictBudget(deps.attempts);
+    if (budget.kind === "exhausted") {
+      return {
+        kind: "attempt_cap",
+        reason:
+          `the rebase conflict persists after ${budget.attempts} resolution attempt(s) — ` +
+          `resolve manually in the retained worktree ${dispatch.worktree} ` +
+          "(`git rebase --continue`), then resume via objective_stack_sync { continue: true } " +
+          "or discard via { abort: true }.",
+      };
+    }
+    const lease = deps.claim.acquire(dispatch.manifestPath, dispatch.operationId);
+    if (!lease.acquired) {
+      return {
+        kind: lease.kind === "busy" ? "resolver_busy" : "state_error",
+        reason: lease.reason,
+      };
+    }
+    held = { manifestPath: dispatch.manifestPath, token: lease.token };
+    if (!deps.attempts.write(budget.next)) {
+      // The seam's strict read-back boolean passes through unsoftened: the verified increment
+      // is a precondition for dispatch — without it the cap is unenforceable. Release the
+      // claim acquired in THIS call so the withheld dispatch leaves no phantom holder —
+      // token-fenced, so a successor's raced-in claim is never deleted.
+      releaseQuietly(deps.claim, held);
+      held = null;
+      return {
+        kind: "state_error",
+        reason: "the attempt counter could not be persisted — dispatch withheld",
+      };
+    }
+    // Dispatched: the claim deliberately stays held (fire-and-forget dispatch; the lease
+    // self-heals — see substrate/resolverLease.ts).
+    held = null;
+    return { kind: "dispatched", dispatch, attempt: budget.next, cap: budget.cap };
+  } catch (error) {
+    if (held !== null) releaseQuietly(deps.claim, held);
+    const message = error instanceof Error ? error.message : String(error);
+    return { kind: "state_error", reason: `conflict-dispatch state failure: ${message}` };
+  }
+}

package/extension/delivery/stackObjective.ts

@@ -0,0 +1,16 @@
+// The stack surfaces' shared command vocabulary: the objective-argument parse and the
+// no-objective refusal prose. Stack-OWNED (not substrate): these are binding concerns — how a
+// stack slash-command reads its argument and what its soft-fail says — so they live with the
+// delivery feature family, imported by the status adapter and the mutating stack doors alike.
+// The state-resolution primitive they pair with (`resolveStackObjective`) stays in
+// `substrate/workflowState.ts` — that half IS workflow-state read-back. Pi-free.
+
+/** The shared no-objective refusal every stack surface emits (soft fail / warning text). */
+export const STACK_NO_OBJECTIVE_MESSAGE =
+  "no objective given and none active or linked — pass the objective explicitly.";
+
+/** The first command-arg token as the explicit objective (leading `#` stripped); null if none. */
+export function parseStackObjectiveArg(args: string): string | null {
+  const token = args.trim().split(/\s+/)[0]?.replace(/^#/, "") ?? "";
+  return token.length > 0 ? token : null;
+}

package/extension/delivery/stackReconcile.ts

@@ -0,0 +1,165 @@
+// The §8.56 evidence-gated reconcile decision (the stacked-delivery close half), Pi-free.
+//
+// After a mutating stack land/recover whose envelope carries journal-assembled reconcile
+// evidence (≥1 layer), the session is driven into the reconcile pass. This module owns the
+// DECISION + the evidence mint; rendering and injection stay adapter-side
+// (`pi/v1/delivery/stackDrive.ts`). The gate is EVIDENCE PRESENCE, never `objective_closed` or
+// the invocation's action rows: the Python plane attaches evidence on a real close transition
+// AND on recover's already-closed journal-complete re-emission (the death-after-close repair —
+// an `objective_closed: false` envelope with evidence must still drive, or the crash window
+// would suppress the drive permanently). At-least-once: duplicate cross-machine drives are
+// possible and harmless — the reconcile pass is idempotent ("skip if nothing stale").
+//
+// The warm transition rows this decision serves (the conflict rows live in
+// `delivery/stackConflict.ts`):
+//
+// | Operation | Persisted facts (authority) | Warm gesture → cold effect | Consent | Typed arms | Recovery |
+// |---|---|---|---|---|---|
+// | RECOVER (§8.51) | Journal fold + fresh product-state proof (Python) | `{dry_run}` classify-only; `{}` concludes all-after; `{abandon,confirm}`/`{accept_prefix,confirm}` | confirm for conclusions | classification rows / landed layers / sweep report / evidence (may drive) | recover IS the recovery surface; at-least-once evidence re-emission (reconcile idempotent) |
+// | STACK LAND (§8.55/§8.56) | Readiness composed from the train (Python); LAND journal op | `{dry_run}` preview; `{confirm}` → `land --yes` | `confirm: true` + dry-run-first | merged (+close+evidence→drive) / pending / unexpected_enqueued (UNRESOLVED — report and STOP) / completed_without_merge closed/NOT-closed / declined | `/objective-recover` concludes against fresh authority |
+
+import {
+  booleanField,
+  type ColdJson,
+  numberField,
+  objectField,
+  objectListField,
+  stringField,
+} from "../substrate/coldDoor.ts";
+
+/** The identifier vocabulary for evidence interpolation (objective/node/plan ids) —
+ * whitelist validation doubles as control-character/line-break exclusion, so a poisoned
+ * journal string can never break out of its evidence row. Alphanumeric-first: the objective
+ * id renders as an unquoted CLI argument in the injected guidance, so an option-shaped
+ * `-`-leading id (or a dotfile-shaped one) never passes. */
+const EVIDENCE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const EVIDENCE_SHA_RE = /^[0-9a-fA-F]{4,64}$/;
+/** The printable-https vocabulary the minted URL must reconstruct into. */
+const PRINTABLE_HTTPS_RE = /^https:\/\/[\x21-\x7e]+$/;
+
+/** One sanitized evidence row — every field is a validated primitive (failures render `"?"`). */
+export interface StackReconcileEvidenceRow {
+  node: string;
+  plan: string;
+  /** The PR rendered for the row: a positive safe integer's decimal form, else `"?"`. */
+  pr: string;
+  baseSha: string;
+  headSha: string;
+  mergeSha: string;
+}
+
+/**
+ * The validated drive evidence — NOMINAL and mint-only (the ReadyDriveEvidence precedent): the
+ * `#private` field makes structural forgery impossible, the constructor is unreachable outside
+ * this module, and `decideStackReconcile` mints it ONLY after per-field sanitization. Every
+ * field is a validated primitive SNAPSHOTTED (frozen) at mint time — the evidence never aliases
+ * the caller-reachable payload, so post-decision payload mutation cannot reach the drive
+ * render. The drive template interpolates exclusively from this type.
+ */
+class StackReconcileEvidence {
+  // The ONE `#private` field supplies the nominal guarantee; the getter below reads it.
+  readonly #objective: string;
+  /** The validated https URL (`""` when the payload's url failed validation). */
+  readonly url: string;
+  readonly rows: readonly Readonly<StackReconcileEvidenceRow>[];
+  readonly finalBaseSha: string;
+
+  constructor(
+    objective: string,
+    url: string,
+    rows: StackReconcileEvidenceRow[],
+    finalBaseSha: string,
+  ) {
+    this.#objective = objective;
+    this.url = url;
+    this.rows = Object.freeze(rows.map((row) => Object.freeze({ ...row })));
+    this.finalBaseSha = finalBaseSha;
+  }
+
+  get objective(): string {
+    return this.#objective;
+  }
+}
+
+export type { StackReconcileEvidence };
+
+function evidenceToken(source: ColdJson, key: string): string {
+  const value = stringField(source, key);
+  return value !== undefined && EVIDENCE_ID_RE.test(value) ? value : "?";
+}
+
+function evidenceSha(source: ColdJson, key: string): string {
+  const value = stringField(source, key);
+  return value !== undefined && EVIDENCE_SHA_RE.test(value) ? value : "?";
+}
+
+/** The PR render vocabulary: only a positive safe integer renders (a float, a negative, an
+ * unsafe magnitude, or a non-number degrades to `"?"` — never an exotic numeric form). */
+function evidencePr(source: ColdJson): string {
+  const value = numberField(source, "pr_number");
+  return value !== undefined && Number.isSafeInteger(value) && value > 0 ? String(value) : "?";
+}
+
+/**
+ * The URL mint: accepted only when `new URL(...)` parses with protocol `https:`, empty
+ * username/password, and the RECONSTRUCTED `href` inside the printable vocabulary — the minted
+ * value is the reconstruction, never the raw string; anything else is `""` (the drive renders
+ * without a link). The reconstruction must equal the raw input: a url the parser had to REPAIR
+ * (percent-encoding a space, a backtick, a control character) is refused rather than silently
+ * rewritten — the parser's escaping would otherwise launder interpolation-hostile bytes into a
+ * vocabulary-passing form.
+ */
+function evidenceUrl(raw: string | undefined): string {
+  if (raw === undefined) return "";
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return "";
+  }
+  if (parsed.protocol !== "https:") return "";
+  if (parsed.username !== "" || parsed.password !== "") return "";
+  if (!PRINTABLE_HTTPS_RE.test(parsed.href)) return "";
+  return parsed.href === raw ? parsed.href : "";
+}
+
+/** The reconcile decision: drive with minted evidence, or nothing. */
+export type StackReconcileDecision =
+  | { drive: false }
+  | { drive: true; evidence: StackReconcileEvidence };
+
+/**
+ * Decide the §8.56 reconcile drive over a mutating land/recover envelope (untrusted DATA). The
+ * gate: never dry-run; `reconcile_evidence` present with ≥1 layer; the redirect-resolved ACTIVE
+ * objective id (never the requested one) inside the identifier vocabulary. On drive, the
+ * evidence is minted from per-field-sanitized primitives — journal-originated strings are
+ * untrusted DATA headed for a steering message, so every field is whitelist-validated against
+ * its vocabulary; anything else renders as `"?"` (ids/SHAs/PR) or `""` (url).
+ */
+export function decideStackReconcile(payload: ColdJson): StackReconcileDecision {
+  if (booleanField(payload, "dry_run") === true) return { drive: false };
+  const evidence = objectField(payload, "reconcile_evidence");
+  if (evidence === undefined) return { drive: false };
+  const layers = objectListField(evidence, "layers");
+  if (layers.length === 0) return { drive: false };
+  const obj = objectField(payload, "objective") ?? {};
+  const id = stringField(obj, "id");
+  if (id === undefined || !EVIDENCE_ID_RE.test(id)) return { drive: false };
+  const rows = layers.map((layer) => ({
+    node: evidenceToken(layer, "node_id"),
+    plan: evidenceToken(layer, "plan_id"),
+    pr: evidencePr(layer),
+    baseSha: evidenceSha(layer, "base_sha"),
+    headSha: evidenceSha(layer, "head_sha"),
+    mergeSha: evidenceSha(layer, "merge_commit_sha"),
+  }));
+  return {
+    drive: true,
+    evidence: new StackReconcileEvidence(
+      id,
+      evidenceUrl(stringField(obj, "url")),
+      rows,
+      evidenceSha(evidence, "final_base_sha"),
+    ),
+  };
+}