@mgiles/perk 3.1.0 → 3.3.0

package/extension/authoring/objective/draft.ts

@@ -0,0 +1,345 @@
+// The objective working-draft feature: the fixed artifact constant and the draft operations
+// over the WorkflowSession seam — the objective-flavored sibling of `authoring/plan/draft.ts`,
+// JSON-envelope flavored (deliberately unshared shapes: a generic envelope would share syntax
+// while erasing each flow's recovery semantics).
+//
+// Carve-out doctrine: the ops take NO path/name parameter — the artifact name is the fixed
+// constant `OBJECTIVE_DRAFT_ARTIFACT` and every byte flows through the session seam (file +
+// verified `session_artifacts` pointer), so the only thing they can ever touch is the one
+// working-objective artifact in the current run's data dir (gitignored scratch). Full rewrite
+// per call, never a save — `objective_save`/`/objective-save` still persist to GitHub.
+//
+// Format doctrine: JSON is the storage/transport format, NEVER the human review surface. The
+// artifact carries `{schema_version, title?, prose, roadmap}` (plus, in a perk learn dream
+// session, the gate-written `dream_report` block — contracts §8.63) — the structured roadmap
+// rides verbatim (node-shape validation stays with the Python plane at save time, the
+// `parse_structured_roadmap` path). The review surface reads the draft via
+// `resumeObjectiveDraft` (digest-validated, classified valid/absent/refused) and renders markdown via
+// `renderObjectiveDraft` (the prose + a roadmap table) — never raw JSON; the
+// approval→`objective_save` orchestration feeds the recovered roadmap back as structured JSON.
+//
+// The §8.63 dream gate arrives INJECTED (`resolveDreamGate` — ctx-bound by the adapter) so the
+// module stays session-pure; `dreamReportGate.ts` owns the matrix.
+
+import type { SessionArtifactReceipt, WorkflowSession } from "../../session/workflowSession.ts";
+import {
+  type DreamReportGateOutcome,
+  decodeDreamReportBlock,
+  type ObjectiveDreamReportBlock,
+} from "./dreamReportGate.ts";
+
+/**
+ * The reviewed objective delivery vocabulary (contracts §8.45) — the ONE authority every
+ * layer derives from: the `DeliveryChoice` union, the tool schema's enum, and the decoder's
+ * narrowing all read these values, so a new variant cannot drift between them.
+ */
+export const DELIVERY_CHOICES = ["incremental", "stacked"] as const;
+
+/** The reviewed objective delivery choice (contracts §8.45). */
+export type DeliveryChoice = (typeof DELIVERY_CHOICES)[number];
+
+/** Whether `value` is a member of the §8.45 delivery vocabulary (the decoder's narrowing). */
+export function isDeliveryChoice(value: string): value is DeliveryChoice {
+  return (DELIVERY_CHOICES as readonly string[]).includes(value);
+}
+
+/** The fixed working-objective artifact name (one JSON file: prose + the structured roadmap). */
+export const OBJECTIVE_DRAFT_ARTIFACT = "objective-draft.json";
+
+/** The typed revise input — decode owns the shape at the tool boundary (pi/v1). */
+export interface ObjectiveDraftInput {
+  prose: string;
+  title?: string;
+  roadmap?: unknown[];
+  /** The objective's target branch; omitted to use the repo default. */
+  base?: string;
+  /** The reviewed delivery choice; omitted ⇒ incremental (the §8.42 absence rule). */
+  delivery?: DeliveryChoice;
+  /** The dream-report input (perk learn dream only — §8.63); deep validation is the gate's. */
+  dream_report?: unknown;
+}
+
+/**
+ * The revise outcome (the `RevisePlanDraftResult` mirror, plus the §8.63 gate arm). `rejected`
+ * splits by `reason` AND carries the exact `errorType` the adapter reports (`gate_refused` is
+ * the dynamic arm — the resolver's own `invalid_input`/`bad_state`); `unverified` means an
+ * effect may have landed but the read-back proof failed. `problem` carries the caller-facing
+ * message bytes. `roadmapNodes` rides so the adapter's rendered twin ("… N roadmap nodes")
+ * needs no re-parse.
+ */
+export type ReviseObjectiveDraftResult =
+  | { status: "revised"; receipt: SessionArtifactReceipt; bytes: number; roadmapNodes: number }
+  | { status: "unchanged"; receipt: SessionArtifactReceipt; bytes: number; roadmapNodes: number }
+  | {
+      status: "rejected";
+      reason: "blank_prose" | "no_identity" | "gate_refused" | "write_refused";
+      problem: string;
+      errorType: "invalid_input" | "no_run_id" | "bad_state" | "write_failed";
+    }
+  | { status: "unverified"; problem: string };
+
+/**
+ * Rewrite the working objective draft (a whole-value replacement) through the session seam:
+ * serialize the explicit-literal payload (deterministic key order; `title`/`base`/`delivery`
+ * omitted when blank/absent; `schema_version` stays 1 — an additive optional field, fail-open
+ * readers), gate `dream_report` at write time (§8.63 — validated here so a report-less dream
+ * bundle can never reach review), then write. Diagnostic precedence preserved: blank prose →
+ * identity → the dream gate → the write. A byte-identical rewrite short-circuits `unchanged`
+ * (the session engine owns the probe). Never throws.
+ */
+export function reviseObjectiveDraft(
+  input: ObjectiveDraftInput,
+  deps: {
+    session: WorkflowSession;
+    /** The §8.63 gate, adapter-bound (`resolveDreamReportGate` over the production recovery capability). */
+    resolveDreamGate: (input: unknown, generatedAt: string) => DreamReportGateOutcome;
+  },
+): ReviseObjectiveDraftResult {
+  if (!input.prose.trim()) {
+    return {
+      status: "rejected",
+      reason: "blank_prose",
+      problem: "no objective prose to write (pass the full working draft)",
+      errorType: "invalid_input",
+    };
+  }
+  if (deps.session.runId === null) {
+    return {
+      status: "rejected",
+      reason: "no_identity",
+      problem: "session has no run_id — cannot write the objective-draft artifact",
+      errorType: "no_run_id",
+    };
+  }
+
+  // The §8.63 gate: validated at draft-write time via buildDreamReport, the ONE stamp stored
+  // with the block; `absent` keeps the payload byte-identical (every non-dream path unchanged).
+  const gate = deps.resolveDreamGate(input.dream_report, new Date().toISOString());
+  if (gate.kind === "refuse") {
+    return {
+      status: "rejected",
+      reason: "gate_refused",
+      problem: gate.detail,
+      errorType: gate.errorType,
+    };
+  }
+
+  const title = input.title?.trim();
+  const base = input.base?.trim();
+  const delivery = input.delivery;
+  const roadmap = input.roadmap ?? [];
+  const payload = {
+    schema_version: 1,
+    ...(title ? { title } : {}),
+    ...(base ? { base } : {}),
+    ...(delivery ? { delivery } : {}),
+    ...(gate.kind === "block" ? { dream_report: gate.block } : {}),
+    prose: input.prose,
+    roadmap,
+  };
+  const content = `${JSON.stringify(payload, null, 2)}\n`;
+  const bytes = Buffer.byteLength(content, "utf8");
+
+  const written = deps.session.writeArtifact(OBJECTIVE_DRAFT_ARTIFACT, content);
+  switch (written.status) {
+    case "applied":
+      return { status: "revised", receipt: written.receipt, bytes, roadmapNodes: roadmap.length };
+    case "unchanged":
+      return {
+        status: "unchanged",
+        receipt: written.receipt,
+        bytes,
+        roadmapNodes: roadmap.length,
+      };
+    case "rejected":
+      return {
+        status: "rejected",
+        reason: "write_refused",
+        problem: `could not write the ${OBJECTIVE_DRAFT_ARTIFACT} artifact (see warnings)`,
+        errorType: "write_failed",
+      };
+    case "unverified":
+      return {
+        status: "unverified",
+        problem: `could not write the ${OBJECTIVE_DRAFT_ARTIFACT} artifact (see warnings)`,
+      };
+  }
+}
+
+// ------------------------------------------------------------------- the reader + the renderer
+
+/** The validated working-objective draft shape consumers receive from `resumeObjectiveDraft`. */
+export interface ObjectiveDraft {
+  title?: string;
+  prose: string;
+  roadmap: unknown[];
+  /** The objective's target branch; kept only when a non-blank string in the artifact. */
+  base?: string;
+  /** The reviewed delivery choice; kept only when exactly the enum (junk → absent, like `base`). */
+  delivery?: DeliveryChoice;
+  /** The dream-report block (§8.63); a present-but-malformed block refuses the WHOLE draft. */
+  dream_report?: ObjectiveDreamReportBlock;
+}
+
+/**
+ * The classified resume outcome: a refused draft is a fail-closed STOP at every consumer —
+ * it never takes the no-draft fallbacks' side effects (gate exit, driven turn). `raw` is the
+ * artifact bytes the draft was decoded from — the reviewed-bytes baseline; consumers that
+ * render and fence must use this one read for both (a second read could be newer than what
+ * the human saw).
+ */
+export type ResumeObjectiveDraftResult =
+  | { kind: "valid"; draft: ObjectiveDraft; raw: string }
+  | { kind: "absent" }
+  | { kind: "refused"; problem: string };
+
+/**
+ * Resume + validate the working-objective draft artifact from the session, classified: seam
+ * `absent` → `absent` (the genuine no-draft arm); seam `invalid` → `refused` carrying the
+ * seam's problem (a corrupted artifact is truthfully rendered at the edge — the seam's own
+ * stderr tier is untouched); decoder refusals (`decodeObjectiveDraft`) pass through. Never
+ * throws.
+ */
+export function resumeObjectiveDraft(session: WorkflowSession): ResumeObjectiveDraftResult {
+  const read = session.readArtifact(OBJECTIVE_DRAFT_ARTIFACT);
+  if (read.status === "absent") return { kind: "absent" };
+  if (read.status === "invalid") return { kind: "refused", problem: read.problem };
+  return decodeObjectiveDraft(read.content);
+}
+
+/**
+ * Decode + validate working-objective artifact bytes (the content half of
+ * `resumeObjectiveDraft`, for consumers that already hold the seam-validated bytes — e.g. the
+ * browser door, whose stale-guard baseline and decode input must be the SAME read): malformed
+ * JSON, a non-object payload, an unsupported `schema_version`, or blank prose → `refused`
+ * with the decoder's problem. `roadmap` defaults to `[]` when absent/non-array; `title` is
+ * kept only when a non-blank string. A present-but-malformed `dream_report` block refuses the
+ * WHOLE draft — deliberately stricter than the lenient junk→absent handling of
+ * `base`/`delivery`, because silently dropping a malformed report is exactly what §8.63
+ * forbids. Never throws.
+ */
+export function decodeObjectiveDraft(
+  content: string,
+): Exclude<ResumeObjectiveDraftResult, { kind: "absent" }> {
+  const refuse = (why: string): { kind: "refused"; problem: string } => ({
+    kind: "refused",
+    problem: `${OBJECTIVE_DRAFT_ARTIFACT} ${why} — refusing the draft`,
+  });
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return refuse("is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return refuse("is not a JSON object");
+  }
+  const payload = parsed as Record<string, unknown>;
+  if (payload.schema_version !== 1) {
+    return refuse(`has an unsupported schema_version (${JSON.stringify(payload.schema_version)})`);
+  }
+  const prose = payload.prose;
+  if (typeof prose !== "string" || !prose.trim()) {
+    return refuse("has no prose");
+  }
+  const roadmap = Array.isArray(payload.roadmap) ? payload.roadmap : [];
+  const title =
+    typeof payload.title === "string" && payload.title.trim() ? payload.title : undefined;
+  const base = typeof payload.base === "string" && payload.base.trim() ? payload.base : undefined;
+  const delivery =
+    typeof payload.delivery === "string" && isDeliveryChoice(payload.delivery)
+      ? payload.delivery
+      : undefined;
+  let dreamReport: ObjectiveDreamReportBlock | undefined;
+  if ("dream_report" in payload) {
+    const block = decodeDreamReportBlock(payload.dream_report);
+    if (block === null) {
+      return refuse("carries a malformed dream_report block");
+    }
+    dreamReport = block;
+  }
+  return {
+    kind: "valid",
+    draft: {
+      ...(title !== undefined ? { title } : {}),
+      ...(base !== undefined ? { base } : {}),
+      ...(delivery !== undefined ? { delivery } : {}),
+      ...(dreamReport !== undefined ? { dream_report: dreamReport } : {}),
+      prose,
+      roadmap,
+    },
+    raw: content,
+  };
+}
+
+/** Sanitize a table cell: `|` escaped, newlines collapsed to a single space. */
+function tableCell(value: string): string {
+  return value.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
+}
+
+/** Read a string field off an unknown-shaped roadmap node (`""` when absent/mistyped). */
+function nodeString(node: unknown, key: string): string {
+  if (typeof node !== "object" || node === null) return "";
+  const value = (node as Record<string, unknown>)[key];
+  return typeof value === "string" ? value : "";
+}
+
+/** Render a node's `depends_on` as a `", "`-join of its string members; `-` when empty/absent. */
+function nodeDependsOn(node: unknown): string {
+  if (typeof node !== "object" || node === null) return "-";
+  const value = (node as Record<string, unknown>).depends_on;
+  if (!Array.isArray(value)) return "-";
+  const deps = value.filter((d): d is string => typeof d === "string");
+  return deps.length > 0 ? deps.join(", ") : "-";
+}
+
+/** The always-present prominent `**Delivery:**` review line (contracts §8.45). */
+function deliveryLine(draft: ObjectiveDraft): string {
+  if (draft.delivery === "stacked") {
+    return (
+      "**Delivery: STACKED** — all non-skipped roadmap nodes land as ONE atomic pull-request " +
+      "train (capability-checked at save)"
+    );
+  }
+  return "**Delivery: incremental** (the default — each plan lands independently)";
+}
+
+/**
+ * Render the draft as the markdown review surface (JSON is storage/transport only — contracts
+ * §8.1): the optional `# title` heading, the prose verbatim, and (when the roadmap is non-empty)
+ * a `## Roadmap` section with ONE markdown table. A prominent `**Delivery:**` line renders
+ * directly under the title unconditionally (the reviewed choice must be visible either way —
+ * contracts §8.45). The `Phase` column appears only when some node carries a non-blank string
+ * `phase`. When the draft carries a `dream_report` block, the stored CANONICAL parts append as
+ * the final section — the review surface IS the approval bundle: the objective and its report
+ * review (and are approved or denied) together (§8.63); the parts carry their own
+ * `# Dream report — <run_id>` headers. Pure; never throws.
+ */
+export function renderObjectiveDraft(draft: ObjectiveDraft): string {
+  let out = "";
+  if (draft.title) out += `# ${draft.title}\n\n`;
+  out += `${deliveryLine(draft)}\n\n`;
+  out += draft.prose;
+
+  if (draft.roadmap.length > 0) {
+    const withPhase = draft.roadmap.some((node) => nodeString(node, "phase").trim().length > 0);
+    const header = withPhase
+      ? "| Node | Phase | Description | Depends On | Status |\n| --- | --- | --- | --- | --- |"
+      : "| Node | Description | Depends On | Status |\n| --- | --- | --- | --- |";
+    const rows = draft.roadmap.map((node) => {
+      const cells = [
+        tableCell(nodeString(node, "id")),
+        ...(withPhase ? [tableCell(nodeString(node, "phase"))] : []),
+        tableCell(nodeString(node, "description")),
+        tableCell(nodeDependsOn(node)),
+        tableCell(nodeString(node, "status") || "pending"),
+      ];
+      return `| ${cells.join(" | ")} |`;
+    });
+    out = `${out.trimEnd()}\n\n## Roadmap\n\n${header}\n${rows.join("\n")}\n`;
+  }
+
+  if (draft.dream_report === undefined) return out;
+  // The approval bundle: objective first, then the stored CANONICAL report parts.
+  return `${out.trimEnd()}\n\n${draft.dream_report.parts.join("\n\n")}\n`;
+}

package/extension/{factories/objectiveDreamReport.ts → authoring/objective/dreamReportGate.ts}

@@ -1,9 +1,9 @@
 // The `dream_report` gate for the objective draft/review/save path (contracts.md §8.63).
 //
-// ONE resolver implements the whole gate matrix — `writeObjectiveDraft` (objectiveDraft.ts)
-// and `saveObjective` (objectiveSave.ts) both consume its typed outcome, so no parallel
-// branch/message implementation can drift. "Dream session" is detected structurally, exactly
-// like `run_dream_wave` (doors/dreamWaveTools.ts): the session's claimed `run_id` plus the
+// ONE resolver implements the whole gate matrix — `reviseObjectiveDraft` (draft.ts) and
+// `saveObjective` (save.ts) both consume its typed outcome, so no parallel branch/message
+// implementation can drift. "Dream session" is detected structurally, exactly
+// like `run_dream_wave` (pi/v1/learning/dream.ts): the session's claimed `run_id` plus the
 // existence of the run-scoped dream manifest (no claimed run counts as non-dream). The gate is
 // fail-closed in BOTH directions: a dream session refuses a report-less objective (the
 // objective and its report review as ONE bundle — an approval is always savable), and a
@@ -13,28 +13,25 @@
 // Trusted-context recovery follows the session-artifacts digest-pointer doctrine: the bare
 // run-scratch bundle is never trusted — the `dream_bundle_digest` workflow-state marker
 // (cleared at wave entry, set to the finalized bytes' digest after a successful finalize) is
-// the freshness/integrity authority, and the bundle is strictly re-decoded through
-// `decodeFinalizedDreamBundle` on every recovery read (untrusted-at-rest posture). After a
-// successful recovery the revalidation bracket (contracts.md §8.65) re-proves HEAD-unchanged +
-// tree-clean against the manifest's stamped `commit_sha` — at draft-write AND save, since both
-// consumers flow through the one resolver; drift refuses `bad_state` (the analysis is stale).
+// the freshness/integrity authority, and the bundle is strictly re-decoded through the
+// finalized-bundle decoder on every recovery read (untrusted-at-rest posture). The recovery
+// MECHANICS are edge-owned: the resolver consumes the runtime-minted `DreamGateRecovery`
+// capability (production: `pi/v1/objectiveDreamGate.ts`), so this module stays storage-free.
+// After a successful recovery the revalidation bracket (contracts.md §8.65) re-proves
+// HEAD-unchanged + tree-clean against the manifest's stamped `commit_sha` — at draft-write AND
+// save, since both consumers flow through the one resolver; drift refuses `bad_state` (the
+// analysis is stale).
 //
-// Imports only the dream wave siblings, the substrate seams, and node builtins — cycle-free
-// (nothing in `waves/` imports factories) and loadable under `node --test`.
+// Imports only the dream wave siblings — cycle-free (nothing in `waves/` imports `authoring/`)
+// and loadable under `node --test`.
 
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { runScratchDir } from "../substrate/cache.ts";
-import { revalidationBracket } from "../substrate/git.ts";
-import { digestSessionData, type SessionDataCtx } from "../substrate/sessionData.ts";
-import { branchOf, rebuildWorkflowState, type WorkflowState } from "../substrate/workflowState.ts";
-import { DREAM_ANALYSES_FILENAME, decodeFinalizedDreamBundle } from "../waves/dreamReducerWave.ts";
-import { buildDreamReport, type DreamReportContext } from "../waves/dreamReport.ts";
 import {
   codePointLength,
-  DREAM_MANIFEST_FILENAME,
-  decodeDreamManifest,
-} from "../waves/dreamWave.ts";
+  type DreamLaneAnalysis,
+  type DreamManifest,
+} from "../../learning/dream.ts";
+import type { DreamReducerAnalysis } from "../../learning/dreamReducer.ts";
+import { buildDreamReport, type DreamReportContext } from "../../learning/dreamReport.ts";
 
 /**
  * The shared part-invariance + size rule's comment-body cap (contracts §8.64) — the full
@@ -152,91 +149,35 @@ export function decodeDreamReportBlock(value: unknown): ObjectiveDreamReportBloc
 }
 
 /**
- * Recover the trusted `DreamReportContext` from the claimed run's scratch state — every arm
- * fail-closed with a named detail (the caller maps them to `bad_state`):
- *
- *  1. the run-scoped manifest: read + parse + `decodeDreamManifest` (the strict §8.60 decoder,
- *     path bound at decode time). No `verifyDocContainment` — this path reads no doc files;
- *     the lexical decode suffices (resolved containment is the wave tool's pre-spawn concern);
- *  2. the freshness check: the `dream_bundle_digest` marker (read from the caller's ONE
- *     workflow-state snapshot) must be present, non-empty, and equal the digest of the bundle
- *     bytes just read — a bare file is never trusted (missing marker = no finalized wave;
- *     empty = invalidated by a newer attempt, including a cleanup-failure residue; mismatch =
- *     stale/tampered bytes);
- *  3. the strict finalized decode (`decodeFinalizedDreamBundle` over the digest of the
- *     manifest bytes just read — the marker authenticates the bundle bytes and the bundle's
- *     `manifest_digest` extends that authority to the manifest, so an at-rest manifest edit
- *     refuses; the analyses-only mid-wave shape refuses here too).
+ * The narrow per-operation trusted-context recovery capability the Pi/session edge mints
+ * (production: `productionDreamGateRecovery` in `pi/v1/objectiveDreamGate.ts`; tests inject
+ * fakes). ANTI-PROOF-OBJECT CONTRACT: the decode/digest/revalidation checks behind
+ * `recoverContext` and `bracket` are runtime verification executed on EVERY consuming
+ * operation (draft-write and save), never replaced by a structural type, assertion, or
+ * previously computed proof object.
  */
-function recoverDreamReportContext(
-  ctx: SessionDataCtx,
-  runId: string,
-  marker: string | undefined,
-  generatedAt: string,
-): { ok: true; context: DreamReportContext } | { ok: false; detail: string } {
-  const manifestPath = join(runScratchDir(ctx.cwd, runId), DREAM_MANIFEST_FILENAME);
-  let manifestBytes: string;
-  let rawManifest: unknown;
-  try {
-    manifestBytes = readFileSync(manifestPath, "utf8");
-    rawManifest = JSON.parse(manifestBytes);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    return { ok: false, detail: `dream manifest unreadable at '${manifestPath}': ${detail}` };
-  }
-  const manifest = decodeDreamManifest(rawManifest, manifestPath);
-  if (!manifest.ok) {
-    return { ok: false, detail: `dream manifest invalid: ${manifest.detail}` };
-  }
-
-  const bundlePath = join(dirname(manifestPath), DREAM_ANALYSES_FILENAME);
-  let bundleBytes: string;
-  try {
-    bundleBytes = readFileSync(bundlePath, "utf8");
-  } catch {
-    return {
-      ok: false,
-      detail: `no dream bundle at '${bundlePath}' — re-run the dream wave`,
-    };
-  }
-  if (marker === undefined || marker === "") {
-    return {
-      ok: false,
-      detail: "no finalized dream wave for this session — re-run the dream wave",
-    };
-  }
-  if (digestSessionData(bundleBytes) !== marker) {
-    return {
-      ok: false,
-      detail:
-        "the dream bundle does not match the session's finalized digest — re-run the dream wave",
-    };
-  }
-  let rawBundle: unknown;
-  try {
-    rawBundle = JSON.parse(bundleBytes);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    return { ok: false, detail: `dream bundle is not valid JSON: ${detail}` };
-  }
-  const decoded = decodeFinalizedDreamBundle(
-    rawBundle,
-    manifest.manifest,
-    digestSessionData(manifestBytes),
-  );
-  if (!decoded.ok) {
-    return { ok: false, detail: `${decoded.detail} — re-run the dream wave` };
-  }
-  return {
-    ok: true,
-    context: {
-      manifest: manifest.manifest,
-      analyses: decoded.analyses,
-      reducers: decoded.reducers,
-      run_id: runId,
-      generated_at: generatedAt,
-    },
-  };
+export interface DreamGateRecovery {
+  /** ONE fresh workflow-state snapshot per gate resolution (run identity + freshness marker + dream detection).
+   *  `detail` is always the RAW CAUSE (a caught message or a fixed cause literal) — the resolver
+   *  owns the one rendering prefix; the capability never pre-renders. */
+  readSession():
+    | { kind: "unreadable"; detail: string }
+    | { kind: "read"; runId: string | null; dream: boolean; marker: string | undefined };
+  /** Fresh manifest+bundle read + the full decode/digest ladder — re-executed on EVERY call, never cached.
+   *  `detail` here IS the final text (today's recovery details are complete sentences; byte-preserved). */
+  recoverContext(
+    runId: string,
+    marker: string | undefined,
+  ):
+    | {
+        ok: true;
+        manifest: DreamManifest;
+        analyses: DreamLaneAnalysis[];
+        reducers: DreamReducerAnalysis[];
+      }
+    | { ok: false; detail: string };
+  /** The §8.65 revalidation bracket against the recovered manifest's stamped commit_sha. */
+  bracket(expectedSha: string): { ok: boolean; detail: string | null };
 }
 
 /** The typed gate outcome both consumers branch on — the whole matrix, one vocabulary. */
@@ -257,40 +198,34 @@ export type DreamReportGateOutcome =
  * | dream     | absent         | refuse `invalid_input` (one approval bundle) |
  * | dream     | present        | recover context → `buildDreamReport` → refuse or `block` |
  *
- * An UNREADABLE workflow state (a throwing branch read) refuses `bad_state` BEFORE the matrix —
- * it is never conflated with a confirmed non-dream session (the `activeSessionRunId`
+ * An UNREADABLE workflow state (`readSession()`'s `unreadable` arm — a throwing branch read,
+ * or the capability's fail-closed run-id/marker narrowing) refuses `bad_state` BEFORE the
+ * matrix — it is never conflated with a confirmed non-dream session (the `activeSessionRunId`
  * null-on-throw sentinel would otherwise let a transient read failure surface as `absent`).
+ * The capability's `detail` is the RAW CAUSE; this resolver owns the one rendering prefix.
  *
  * Failure taxonomy: gate violations + `buildDreamReport` refusals → `invalid_input` (the
  * bounded ≤25 named details newline-joined); an unreadable workflow state and
- * context-recovery failures → `bad_state`.
+ * context-recovery failures → `bad_state` (recovery details pass through UNPREFIXED).
  */
 export function resolveDreamReportGate(
-  ctx: SessionDataCtx,
+  recovery: DreamGateRecovery,
   input: unknown,
   generatedAt: string,
-  bracket: (
-    cwd: string,
-    expectedSha: string,
-  ) => { ok: boolean; detail: string | null } = revalidationBracket,
 ): DreamReportGateOutcome {
-  // ONE workflow-state snapshot for the whole gate (run identity + the freshness marker),
-  // read with error distinction: unreadable state fails closed, never "non-dream".
-  let state: WorkflowState;
-  try {
-    state = rebuildWorkflowState(branchOf(ctx));
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+  // ONE workflow-state snapshot for the whole gate (run identity + the freshness marker +
+  // dream detection), read with error distinction: unreadable state fails closed, never
+  // "non-dream".
+  const session = recovery.readSession();
+  if (session.kind === "unreadable") {
     return {
       kind: "refuse",
       errorType: "bad_state",
-      detail: `session workflow state is unreadable — cannot resolve the dream_report gate: ${detail}`,
+      detail: `session workflow state is unreadable — cannot resolve the dream_report gate: ${session.detail}`,
     };
   }
-  const runId = typeof state.run_id === "string" && state.run_id.length > 0 ? state.run_id : null;
-  const dream =
-    runId !== null && existsSync(join(runScratchDir(ctx.cwd, runId), DREAM_MANIFEST_FILENAME));
-  if (runId === null || !dream) {
+  const runId = session.runId;
+  if (runId === null || !session.dream) {
     if (input === undefined) return { kind: "absent" };
     return {
       kind: "refuse",
@@ -309,17 +244,25 @@ export function resolveDreamReportGate(
         "report review as one bundle",
     };
   }
-  const recovered = recoverDreamReportContext(ctx, runId, state.dream_bundle_digest, generatedAt);
+  // The marker rides the SAME snapshot as the run identity (the one-snapshot rule); the
+  // capability re-executes the full read+decode+digest ladder on every call, never caching.
+  const recovered = recovery.recoverContext(runId, session.marker);
   if (!recovered.ok) {
     return { kind: "refuse", errorType: "bad_state", detail: recovered.detail };
   }
+  const context: DreamReportContext = {
+    manifest: recovered.manifest,
+    analyses: recovered.analyses,
+    reducers: recovered.reducers,
+    run_id: runId,
+    generated_at: generatedAt,
+  };
   // The revalidation-bracket re-check (contracts.md §8.65): the manifest — with its stamped
   // commit_sha — is now decoded and authenticated, so re-prove HEAD-unchanged + tree-clean
   // against it. Both `writeObjectiveDraft` and `saveObjective` flow through this resolver, so
   // the bracket re-fires at draft-write AND save; non-dream paths never reach it (the matrix
-  // above returned already). The parameter default is the production bracket — tests inject
-  // stubs.
-  const drift = bracket(ctx.cwd, recovered.context.manifest.commit_sha);
+  // above returned already).
+  const drift = recovery.bracket(context.manifest.commit_sha);
   if (!drift.ok) {
     return {
       kind: "refuse",
@@ -329,7 +272,7 @@ export function resolveDreamReportGate(
         "stale; re-run perk learn dream",
     };
   }
-  const built = buildDreamReport(input, recovered.context);
+  const built = buildDreamReport(input, context);
   if (!built.ok) {
     return { kind: "refuse", errorType: "invalid_input", detail: built.details.join("\n") };
   }