mirror-mind 0.0.1 → 0.33.0

package/ts/src/builder/plan.ts

@@ -0,0 +1,408 @@
+// CV22.DS7.US8 plateau 3 — Plan: the checkpoint that blocks implementation.
+//
+// Port of `plan_lifecycle_item` and `render_plan_checkpoint` from
+// `src/memory/builder/lifecycle.py`.
+//
+// Three behaviors carry the meaning, and two of them are invisible in the surface:
+//
+//   1. **The receipt argument is always EXPLICIT.** Plan passes the receipt it
+//      resolved — new, or the existing one — which bypasses the cursor's
+//      coordinate-change invalidation. That is what lets a freshly recorded receipt
+//      survive the very write that records it; passing the KEEP sentinel here would
+//      invalidate it on arrival.
+//   2. **The generation does NOT advance.** Plan is a checkpoint on the item Pull
+//      committed to, and a bump would invalidate the receipt it just wrote.
+//   3. **The scaffold is composed here, from one vocabulary (CR111 D3).** Plan fills
+//      `PRODUCT_PLAN` with the caller's title, else the title Pull recorded, else the
+//      item's code (D5), and names the siblings the caller read from the roadmap as
+//      Non-Goals. A caller may set only the objective (`--objective`). Python took each
+//      section as an argument and fell back, per field, to a second set of sentences
+//      no product path wrote; the recorded corpus graded that set.
+//
+// CR111: the card prints what the runtime knows, and no section of the plan. It used
+// to print the scaffold's sentences as the plan -- scope, acceptance, validation,
+// checked off -- even over a plan.md a person had written. It now names the story
+// files, each with its state and the sections it still needs, in the rows `build show`
+// prints, judged once here, right after the write, so the command and the recorded
+// corpus print the same card.
+//
+// CR082: the card names the package relative to the project, and the four `*_path=`
+// lines, the agent's, stay absolute and print below the surface's end marker (D1).
+
+import { dirname } from "node:path";
+import type { WritableDatabase } from "#db/database.ts";
+import { STORY_SCOPED_COMMIT_RULE, writeStoryPackage } from "./artifacts/planArtifacts.ts";
+import {
+  fill,
+  fillPlanVocabulary,
+  type PlanVocabulary,
+  PRODUCT_PLAN,
+  SIBLING_NON_GOAL,
+} from "./artifacts/scaffoldSections.ts";
+import type { ArtifactVerdict } from "./artifacts/scaffoldState.ts";
+import { judgeStoryFiles, storyFileLines } from "./artifacts/storyFiles.ts";
+import { cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import { isImplementableByDefault, normalizeRequired } from "./cursorTransitions.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  getDeliveryCursor,
+  type PlanPreauthorizationReceipt,
+  setDeliveryCursor,
+  setTo,
+} from "./deliveryCursor.ts";
+import { effectiveNavigatorFlowUnit, FLOW_UNIT_STORY_BY_STORY } from "./flowUnit.ts";
+import { LifecycleRefusal, refuseIfAlreadyComplete } from "./lifecycleRefusal.ts";
+import { renderLifecycleRibbon } from "./lifecycleRibbon.ts";
+import type { ContractDefinition, MethodDefinition } from "./methodDefinition.ts";
+import {
+  createPlanPreauthorizationReceipt,
+  PREAUTHORIZATION_STOP,
+  STORY_PLAN_CONTRACT,
+} from "./planPreauthorization.ts";
+import { displayPath } from "./projectPaths.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+/** Python `BuilderPlanReport`. */
+export interface BuilderPlanReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly activeItem: string;
+  readonly activeItemTitle: string | null;
+  readonly activeItemLevel: string | null;
+  readonly implementableByDefault: boolean;
+  readonly planContract: ContractDefinition;
+  readonly implementContract: ContractDefinition;
+  readonly validationContract: ContractDefinition;
+  readonly localRules: readonly string[];
+  readonly cursor: BuilderDeliveryCursor;
+  readonly planArtifactPath: string | null;
+  /** The project Plan wrote under: the card names the package relative to it (CR082). */
+  readonly projectRoot: string | null;
+  /**
+   * The package's `index.md`, `plan.md`, and `test-guide.md`, judged right after Plan
+   * wrote what was missing (CR111); `null` when the journey has no project, so nothing
+   * was written.
+   */
+  readonly storyFiles: readonly ArtifactVerdict[] | null;
+  /**
+   * An `--objective` given where nothing is written: with no project there is no
+   * plan.md to hold it, and the card says so rather than drop it silently (CR111's
+   * handoff review, finding 2).
+   */
+  readonly unrecordedObjective: boolean;
+  readonly preauthorizationRecorded: boolean;
+  readonly nextEvent: string;
+}
+
+/** Python `_contract_for`: a missing contract is a method-definition defect, not a default. */
+function contractFor(method: MethodDefinition, contractId: string): ContractDefinition {
+  const contract = method.contracts.find((candidate) => candidate.id === contractId);
+  if (contract === undefined) {
+    throw new Error(`method ${method.id} is missing contract ${contractId}`);
+  }
+  return contract;
+}
+
+/**
+ * Python `_cadence_preauthorizes_story_plan`.
+ *
+ * Keyed on the profile's POLICY, not on its name. `accelerated` is the profile that
+ * carries `bounded_story_authority` today, but a method that renames it or adds
+ * another profile with the same policy gets the same behavior — which is why the
+ * Python test asserts the policy rather than the profile id.
+ */
+function cadencePreauthorizesStoryPlan(
+  method: MethodDefinition,
+  cadenceProfile: string | null,
+): boolean {
+  if (cadenceProfile === null) return false;
+  const profile = method.cadenceProfiles.find((candidate) => candidate.id === cadenceProfile);
+  return profile !== undefined && profile.planApprovalPolicy === "bounded_story_authority";
+}
+
+export interface PlanOptions {
+  readonly journey: string;
+  readonly method: MethodDefinition;
+  /** `--objective`: the one section a caller may write. Authored by construction. */
+  readonly objective?: string | null;
+  /**
+   * The item's title as the roadmap names it. Without one, the scaffold takes the
+   * title Pull recorded on the cursor, and only then the item's code (CR111 D5).
+   */
+  readonly title?: string | null;
+  /** The titles of the item's siblings in the roadmap, named as Non-Goals. */
+  readonly siblings?: readonly string[];
+  readonly localRules?: readonly string[];
+  readonly planArtifactPath?: string | null;
+  /** The project the package must stay inside (CR079). */
+  readonly projectRoot?: string | null;
+  readonly preauthorize?: boolean;
+  readonly stopBoundary?: string;
+}
+
+/**
+ * The sentences Plan writes where no file exists: `PRODUCT_PLAN`, filled with the
+ * caller's title, else the title Pull recorded, else the item's code (CR111 D5), with
+ * the roadmap's siblings as Non-Goals and the caller's objective when it gave one.
+ */
+function composeScaffold(
+  options: PlanOptions,
+  recordedTitle: string | null,
+  code: string,
+): PlanVocabulary {
+  const vocabulary = fillPlanVocabulary(PRODUCT_PLAN, {
+    title: options.title || recordedTitle || code,
+  });
+  const siblings = (options.siblings ?? []).map((sibling) =>
+    fill(SIBLING_NON_GOAL, { title: sibling }),
+  );
+  return {
+    ...vocabulary,
+    objective: options.objective || vocabulary.objective,
+    nonGoals: siblings.length > 0 ? siblings : vocabulary.nonGoals,
+  };
+}
+
+/** Python `plan_lifecycle_item`. */
+export function planLifecycleItem(
+  db: WritableDatabase,
+  options: PlanOptions,
+  deps: CursorWriteDeps,
+): BuilderPlanReport {
+  const journey = normalizeRequired(options.journey, "journey");
+  const method = options.method;
+
+  const existing = getDeliveryCursor(db, journey);
+  if (existing === null) throw new Error("delivery cursor is required before plan");
+  if (!existing.activeItem) throw new Error("active item is required before plan");
+  refuseIfAlreadyComplete("plan", existing);
+  if (existing.lastDeliveryEvent !== "prepare") {
+    throw new LifecycleRefusal("plan", "not_reached", "Prepare must be completed before Plan");
+  }
+
+  const implementable = isImplementableByDefault(existing.activeItemLevel);
+  if (!implementable) {
+    throw new LifecycleRefusal(
+      "plan",
+      "not_reached",
+      "Plan requires a User Story or Technical Story; expand the Delivery Story first",
+    );
+  }
+
+  const stopBoundary = options.stopBoundary ?? PREAUTHORIZATION_STOP;
+  const artifactPath = options.planArtifactPath ?? null;
+  let flowUnit = existing.navigatorFlowUnit;
+  let receipt: PlanPreauthorizationReceipt | null = existing.planPreauthorization;
+  const preauthorizationRecorded =
+    (options.preauthorize ?? false) ||
+    cadencePreauthorizesStoryPlan(method, existing.cadenceProfile);
+
+  if (preauthorizationRecorded) {
+    flowUnit = effectiveNavigatorFlowUnit(existing).flowUnit;
+    if (flowUnit !== FLOW_UNIT_STORY_BY_STORY) {
+      // Reachable only through a cursor written before CR117, when Pull carried a Delivery
+      // Story's unit to the story after it: the remedy is the Pull that no longer carries.
+      throw new Error(
+        "story Plan preauthorization requires story_by_story flow; the cursor holds " +
+          "delivery_story from a Delivery Story pulled before this story. Pull the story " +
+          "again to start it in story_by_story flow.",
+      );
+    }
+    receipt = createPlanPreauthorizationReceipt(
+      { ...existing, navigatorFlowUnit: flowUnit },
+      {
+        method: method.id,
+        planContractVersion: STORY_PLAN_CONTRACT,
+        stopBoundary,
+      },
+    );
+  }
+
+  const cursor = setDeliveryCursor(
+    db,
+    {
+      journey,
+      method: method.id,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      activeCheckpoint: "after_plan",
+      pendingConfirmation: "navigator_approval",
+      lastDeliveryEvent: "plan",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      granularityDecision: null,
+      navigatorFlowUnit: flowUnit,
+      childWorkItems: existing.childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+      cursorGeneration: existing.cursorGeneration,
+      planPreauthorization: setTo(receipt),
+    },
+    deps,
+  );
+
+  const report: Omit<BuilderPlanReport, "storyFiles" | "unrecordedObjective"> = {
+    journey,
+    method: method.id,
+    activeItem: existing.activeItem,
+    activeItemTitle: existing.activeItemTitle,
+    activeItemLevel: existing.activeItemLevel,
+    implementableByDefault: implementable,
+    planContract: contractFor(method, "plan_contract"),
+    implementContract: contractFor(method, "implement_contract"),
+    validationContract: contractFor(method, "validation_contract"),
+    localRules: options.localRules ?? [],
+    cursor,
+    planArtifactPath: artifactPath,
+    projectRoot: options.projectRoot ?? null,
+    preauthorizationRecorded,
+    nextEvent: "implement",
+  };
+
+  if (artifactPath !== null) {
+    const scaffold = composeScaffold(options, existing.activeItemTitle, existing.activeItem);
+    writeStoryPackage(dirname(artifactPath), options.projectRoot, {
+      activeItem: report.activeItem,
+      activeItemTitle: report.activeItemTitle,
+      activeItemLevel: report.activeItemLevel,
+      ...scaffold,
+      localRules: report.localRules,
+      implementContract: report.implementContract,
+      activeCheckpoint: cursor.activeCheckpoint,
+      pendingConfirmation: cursor.pendingConfirmation,
+    });
+  }
+  // Judged after the write, so the verdict describes the files as they now stand:
+  // the scaffold Plan just wrote, or the file a person wrote before it (CR111).
+  const storyFiles = artifactPath === null ? null : judgeStoryFiles(dirname(artifactPath));
+  return {
+    ...report,
+    storyFiles,
+    unrecordedObjective: artifactPath === null && Boolean(options.objective),
+  };
+}
+
+/** Python `_granularity_message`. */
+function granularityMessage(report: BuilderPlanReport): string {
+  return report.implementableByDefault
+    ? `${report.activeItemLevel ?? "item"} is implementable by default.`
+    : "Delivery Story must expand into User Stories and/or Technical Stories before Plan.";
+}
+
+/**
+ * Python `_plan_next_action`, told by the file (CR111). The words are the skill's:
+ * the Driver authors and presents, the Navigator approves. None of them names passing
+ * the structural check as the goal. With no project nothing was written, so there is
+ * no file to name and the line stays what it was.
+ */
+function planNextAction(report: BuilderPlanReport): string {
+  if (report.storyFiles === null) {
+    return report.preauthorizationRecorded
+      ? "Driver completes Plan and consumes bounded authority."
+      : "Navigator approves the Plan or requests changes.";
+  }
+  const authored = report.storyFiles.find((file) => file.name === "plan.md")?.state === "authored";
+  if (report.preauthorizationRecorded) {
+    return authored
+      ? "Driver consumes bounded authority."
+      : "Driver authors plan.md, then consumes bounded authority.";
+  }
+  return authored
+    ? "Navigator reads plan.md and approves it or requests changes."
+    : "Driver authors plan.md and presents it; the Navigator approves it or requests changes.";
+}
+
+/**
+ * The story files block: `build show`'s rows for the same files. With no project
+ * nothing was written; the package row says why, and this one says what that cost.
+ */
+function storyFilesBlock(report: BuilderPlanReport): string[] {
+  if (report.storyFiles !== null) return report.storyFiles.flatMap(storyFileLines);
+  return cardWrapped(
+    report.unrecordedObjective
+      ? "none written, so the --objective given was recorded nowhere"
+      : "none written",
+  );
+}
+
+/** Python `_plan_boundary`. */
+function planBoundary(report: BuilderPlanReport): string {
+  return report.preauthorizationRecorded
+    ? "No additional Navigator approval turn is expected."
+    : "Implementation remains blocked until approval.";
+}
+
+/**
+ * Python `render_plan_checkpoint`, without the plan (CR111).
+ *
+ * The card prints no section of the plan: not the objective, scope, non-goals,
+ * acceptance, or validation, which it used to fill from the scaffold's sentences.
+ * In their place it names the story files, each with its state and the sections it
+ * still needs, in the rows `build show` prints. The implementation contract stays:
+ * its lines are Ariad's rules and the project's own, true whatever the plan says.
+ *
+ * The card names the package relative to the project, as every card names a path
+ * (CR082). The four `*_path=` lines are the agent's: absolute, because an agent often
+ * works from a directory that is not the project, and printed only when an artifact
+ * path exists. They follow the surface's end marker, where the transport rule that
+ * copies a surface into the reply does not carry the owner's home directory (D1), the
+ * way `build load` prints `project_path=` outside its card.
+ */
+export function renderPlanCheckpoint(report: BuilderPlanReport): string {
+  const written = report.planArtifactPath !== null;
+  const packagePath = written ? dirname(report.planArtifactPath as string) : "not written";
+
+  const card = [
+    "Delivery",
+    renderLifecycleRibbon("plan", report.activeItemLevel),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🧭■  PLAN CHECKPOINT                            │",
+    "│                                                        │",
+    cardText("item"),
+    cardText(`🟦[${report.activeItem}]`),
+    cardText(`level: ${report.activeItemLevel ?? "unknown"}`),
+    "│                                                        │",
+    cardText("story package"),
+    ...cardWrapped(
+      written
+        ? displayPath(packagePath, report.projectRoot)
+        : "none: the journey has no project path",
+    ),
+    "│                                                        │",
+    cardText("story files"),
+    ...storyFilesBlock(report),
+    "│                                                        │",
+    cardText("granularity"),
+    ...cardWrapped(granularityMessage(report)),
+    "│                                                        │",
+    cardText("implementation contract"),
+    ...cardWrapped("TDD/characterization tests when behavior is testable."),
+    ...cardWrapped("Keep changes scoped to the active story."),
+    ...cardWrapped(STORY_SCOPED_COMMIT_RULE),
+    // A project without a guide adds nothing, not the card's usual `none` (CR019).
+    ...(report.localRules.length > 0 ? cardPrefixed(report.localRules, "✓") : []),
+    "│                                                        │",
+    cardText("approval gate"),
+    cardText(`checkpoint: ${report.cursor.activeCheckpoint}`),
+    cardText(`pending: ${report.cursor.pendingConfirmation}`),
+    "│                                                        │",
+    cardText("next action"),
+    ...cardWrapped(planNextAction(report)),
+    "│                                                        │",
+    cardText("boundary"),
+    ...cardWrapped(planBoundary(report)),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n");
+
+  const trailer = written
+    ? [
+        `story_package_path=${packagePath}\n`,
+        `index_artifact_path=${packagePath}/index.md\n`,
+        `plan_artifact_path=${report.planArtifactPath as string}\n`,
+        `test_guide_artifact_path=${packagePath}/test-guide.md\n`,
+      ].join("")
+    : "";
+  return wrapAriadSurface("plan_checkpoint", card) + trailer;
+}

package/ts/src/builder/planPreauthorization.ts

@@ -0,0 +1,265 @@
+// CV22.DS7.US8 plateau 3 — bounded authority for conditional Plan approval.
+//
+// Port of `src/memory/builder/plan_preauthorization.py`.
+//
+// This is the security-sensitive module of the plateau. A receipt lets the Driver
+// approve its own Plan once, without another Navigator turn, so every property
+// that bounds it is load-bearing:
+//
+//   * the receipt is **payload-free** — it carries coordinates and a hash, never
+//     Plan prose, so it cannot smuggle scope past the Navigator;
+//   * it is **generation-bound**, so any cursor movement invalidates it;
+//   * it is **single-use**, consumed atomically by a compare-and-swap;
+//   * a mismatch **falls back to ordinary approval** rather than failing open.
+//
+// The fingerprint is an equality test on authority. If the two engines
+// canonicalize its payload differently, a receipt Python recorded cannot be
+// consumed by TypeScript — the Navigator is asked to approve a Plan they already
+// authorized, which is the safe direction but still a defect. It never fails the
+// other way, because a hash mismatch can only refuse.
+
+import { createHash } from "node:crypto";
+
+import type { WritableDatabase } from "#db/database.ts";
+import { pythonJsonDumpsCanonical } from "#util/pyGenerators.ts";
+import { pyStrip, sortByCodePoint } from "#util/pythonText.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  DeliveryCursorConflict,
+  type PlanPreauthorizationReceipt,
+  setDeliveryCursor,
+  setTo,
+} from "./deliveryCursor.ts";
+
+/** Python module constants. */
+export const PREAUTHORIZATION_POLICY = "exact_scope";
+export const PREAUTHORIZATION_STOP = "navigator_validation";
+export const DELIVERY_STORY_PLAN_CONTRACT = "delivery_story_plan@1";
+export const STORY_PLAN_CONTRACT = "story_plan@1";
+
+/** Python `PlanPreauthorizationMismatch`. */
+export class PlanPreauthorizationMismatch extends Error {
+  readonly reason: string;
+  /**
+   * For `plan_incomplete`, the sections still to author (CR112). The surface names
+   * them; the receipt keeps only the reason token, so a persisted cursor reads back as
+   * it always did.
+   */
+  readonly sections: readonly string[];
+
+  constructor(reason: string, sections: readonly string[] = []) {
+    super(reason);
+    this.name = "PlanPreauthorizationMismatch";
+    this.reason = reason;
+    this.sections = sections;
+  }
+}
+
+export interface ScopeFingerprintInput {
+  readonly journey: string;
+  readonly method: string;
+  readonly cursorGeneration: number;
+  readonly activeItem: string;
+  readonly activeItemLevel: string;
+  readonly flowUnit: string;
+  readonly childWorkItems: readonly string[];
+  readonly planContractVersion: string;
+  readonly stopBoundary: string;
+}
+
+/** Python `scope_fingerprint`: sha256 over canonical sorted-compact ASCII JSON. */
+export function scopeFingerprint(input: ScopeFingerprintInput): string {
+  const payload = {
+    journey: input.journey,
+    method: input.method,
+    cursor_generation: input.cursorGeneration,
+    active_item: input.activeItem,
+    active_item_level: input.activeItemLevel,
+    flow_unit: input.flowUnit,
+    child_work_items: [...input.childWorkItems],
+    plan_contract_version: input.planContractVersion,
+    policy: PREAUTHORIZATION_POLICY,
+    stop_boundary: input.stopBoundary,
+  };
+  return createHash("sha256").update(pythonJsonDumpsCanonical(payload), "utf8").digest("hex");
+}
+
+/**
+ * Python `canonical_child_scope`: compare as a SET, store deterministically.
+ *
+ * Sorted and de-duplicated, so child ORDER is presentational while addition or
+ * removal is a mismatch — the distinction the Delivery Story flow depends on.
+ */
+export function canonicalChildScope(items: readonly string[]): string[] {
+  const trimmed = new Set<string>();
+  for (const item of items) {
+    const normalized = pyStrip(item);
+    if (normalized) trimmed.add(normalized);
+  }
+  return sortByCodePoint([...trimmed]);
+}
+
+export interface CreateReceiptOptions {
+  readonly method: string;
+  readonly planContractVersion: string;
+  readonly childWorkItems?: readonly string[];
+  readonly stopBoundary?: string;
+}
+
+/** Python `create_plan_preauthorization_receipt`. */
+export function createPlanPreauthorizationReceipt(
+  cursor: BuilderDeliveryCursor,
+  options: CreateReceiptOptions,
+): PlanPreauthorizationReceipt {
+  if (!cursor.activeItem || !cursor.activeItemLevel || !cursor.navigatorFlowUnit) {
+    throw new Error("complete active Plan coordinates are required");
+  }
+  const stopBoundary = options.stopBoundary ?? PREAUTHORIZATION_STOP;
+  if (stopBoundary !== PREAUTHORIZATION_STOP) {
+    throw new Error("unsupported Plan preauthorization stop boundary");
+  }
+  const children = canonicalChildScope(options.childWorkItems ?? []);
+  return {
+    journey: cursor.journey,
+    method: options.method,
+    cursorGeneration: cursor.cursorGeneration,
+    activeItem: cursor.activeItem,
+    activeItemLevel: cursor.activeItemLevel,
+    flowUnit: cursor.navigatorFlowUnit,
+    childWorkItems: children,
+    planContractVersion: options.planContractVersion,
+    policy: PREAUTHORIZATION_POLICY,
+    stopBoundary,
+    scopeFingerprint: scopeFingerprint({
+      journey: cursor.journey,
+      method: options.method,
+      cursorGeneration: cursor.cursorGeneration,
+      activeItem: cursor.activeItem,
+      activeItemLevel: cursor.activeItemLevel,
+      flowUnit: cursor.navigatorFlowUnit,
+      childWorkItems: children,
+      planContractVersion: options.planContractVersion,
+      stopBoundary,
+    }),
+    status: "pending",
+    reason: null,
+  };
+}
+
+export interface MismatchInput {
+  readonly journey: string;
+  readonly method: string;
+  readonly flowUnit: string;
+  readonly childWorkItems: readonly string[];
+  readonly planContractVersion: string;
+  readonly unfilledSections?: readonly string[];
+}
+
+/**
+ * Python `plan_preauthorization_mismatch_reason`: ONE bounded reason, or null.
+ *
+ * The checks run in Python's order and the FIRST failure wins, because the reason
+ * is Navigator-visible: a receipt that is both stale and cross-level reports
+ * `cursor_generation_changed`, not `active_item_changed`. The fingerprint is
+ * verified last, after the fields it hashes, so a tampered receipt whose fields
+ * still agree is caught by the hash rather than by a field comparison.
+ */
+export function planPreauthorizationMismatchReason(
+  cursor: BuilderDeliveryCursor,
+  input: MismatchInput,
+): string | null {
+  const receipt = cursor.planPreauthorization;
+  if (receipt === null) return "authorization_missing";
+  if (receipt.status !== "pending") return receipt.reason || "authorization_not_pending";
+
+  const expectedChildren = canonicalChildScope(input.childWorkItems);
+  const checks: [boolean, string][] = [
+    [receipt.journey === input.journey, "journey_changed"],
+    [receipt.method === input.method, "method_changed"],
+    [receipt.cursorGeneration === cursor.cursorGeneration, "cursor_generation_changed"],
+    [receipt.activeItem === cursor.activeItem, "active_item_changed"],
+    [receipt.activeItemLevel === cursor.activeItemLevel, "active_item_level_changed"],
+    // Python's chained comparison: the receipt, the cursor, and the caller's flow
+    // unit must ALL agree, not just the receipt and the caller.
+    [
+      receipt.flowUnit === cursor.navigatorFlowUnit && cursor.navigatorFlowUnit === input.flowUnit,
+      "flow_unit_changed",
+    ],
+    [sameScope(receipt.childWorkItems, expectedChildren), "child_scope_changed"],
+    [receipt.planContractVersion === input.planContractVersion, "plan_contract_changed"],
+    [receipt.policy === PREAUTHORIZATION_POLICY, "policy_changed"],
+    [receipt.stopBoundary === PREAUTHORIZATION_STOP, "stop_boundary_changed"],
+  ];
+  for (const [matches, reason] of checks) {
+    if (!matches) return reason;
+  }
+
+  const expectedFingerprint = scopeFingerprint({
+    journey: receipt.journey,
+    method: receipt.method,
+    cursorGeneration: receipt.cursorGeneration,
+    activeItem: receipt.activeItem,
+    activeItemLevel: receipt.activeItemLevel,
+    flowUnit: receipt.flowUnit,
+    childWorkItems: receipt.childWorkItems,
+    planContractVersion: receipt.planContractVersion,
+    stopBoundary: receipt.stopBoundary,
+  });
+  if (receipt.scopeFingerprint !== expectedFingerprint) return "scope_fingerprint_changed";
+  if ((input.unfilledSections ?? []).length > 0) return "plan_incomplete";
+  return null;
+}
+
+function sameScope(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+
+/**
+ * Python `invalidate_plan_preauthorization`.
+ *
+ * Swallows a `DeliveryCursorConflict` and returns the cursor unchanged: this runs
+ * on a refusal path, and failing to record WHY authority was refused must not turn
+ * a clean refusal into an error.
+ */
+export function invalidatePlanPreauthorization(
+  db: WritableDatabase,
+  cursor: BuilderDeliveryCursor,
+  reason: string,
+  deps: CursorWriteDeps,
+): BuilderDeliveryCursor {
+  const receipt = cursor.planPreauthorization;
+  if (receipt === null || receipt.status !== "pending") return cursor;
+  try {
+    return setDeliveryCursor(
+      db,
+      {
+        journey: cursor.journey,
+        method: cursor.method,
+        activeItem: cursor.activeItem,
+        activeItemTitle: cursor.activeItemTitle,
+        activeItemLevel: cursor.activeItemLevel,
+        activeCheckpoint: cursor.activeCheckpoint,
+        pendingConfirmation: cursor.pendingConfirmation,
+        lastDeliveryEvent: cursor.lastDeliveryEvent,
+        cadenceProfile: cursor.cadenceProfile,
+        cadenceLimits: cursor.cadenceLimits,
+        granularityDecision: cursor.granularityDecision,
+        navigatorFlowUnit: cursor.navigatorFlowUnit,
+        childWorkItems: cursor.childWorkItems,
+        aggregateCheckpointStatus: cursor.aggregateCheckpointStatus,
+        cursorGeneration: cursor.cursorGeneration,
+        planPreauthorization: setTo({ ...receipt, status: "invalidated", reason }),
+        expectedCursor: cursor,
+      },
+      deps,
+    );
+  } catch (error) {
+    if (error instanceof DeliveryCursorConflict) return cursor;
+    throw error;
+  }
+}
+
+// The sections a Plan approval requires, `PLAN_APPROVAL_SECTIONS`, and the reader that
+// judges them live in `artifacts/` since CR111: one answer for every surface that says
+// what a `plan.md` still needs, approval included.