@mgiles/perk 3.0.0 → 3.1.0

package/extension/factories/objectiveDraft.ts

@@ -11,8 +11,9 @@
 // `objective_save`/`/objective-save` still persist the objective to GitHub.
 //
 // Format doctrine: JSON is the storage/transport format, NEVER the human review surface. The
-// artifact carries `{schema_version, title?, prose, roadmap}` — the structured roadmap rides
-// verbatim (node-shape validation stays with the Python plane at save time, the
+// artifact carries `{schema_version, title?, prose, roadmap}` (plus, in a perk learn dream
+// session, the tool-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
 // `readObjectiveDraft` (over `readSessionArtifact` — digest-validated, fail-open) and renders
 // markdown via `renderObjectiveDraft` (the prose + a roadmap table) — never raw JSON; the
@@ -20,9 +21,10 @@
 // back as structured JSON.
 //
 // Vocabulary ownership: this module owns the shared draft/save param vocabulary
-// (`ObjectiveSaveParams`, `decodeObjectiveSaveParams`, `ROADMAP_PARAM_SCHEMA`) — objectiveDraft is
-// the LEAF (mirroring planDraft←planSave's direction); objectiveSave.ts consumes it, so it may
-// value-import `readObjectiveDraft` cycle-free for the approval→save orchestration.
+// (`ObjectiveSaveParams`, `decodeObjectiveSaveParams`, `ROADMAP_PARAM_SCHEMA`,
+// `DREAM_REPORT_PARAM_SCHEMA`) — objectiveDraft is the LEAF (mirroring planDraft←planSave's
+// direction); objectiveSave.ts consumes it, so it may value-import `readObjectiveDraft`
+// cycle-free for the approval→save orchestration.
 //
 // Imports stay node builtins + sibling seams (sessionData.ts, result.ts) so the module loads
 // under `node --test`; no manual `scratch`/`runs` path segments (cacheGuard.test.ts).
@@ -37,9 +39,15 @@ import {
   type SessionDataCtx,
   writeSessionArtifact,
 } from "../substrate/sessionData.ts";
-import { arrayParam, paramsOf, stringParam } from "../substrate/toolParams.ts";
+import { arrayParam, objectParam, paramsOf, stringParam } from "../substrate/toolParams.ts";
 import type { EntrySink } from "../substrate/workflowState.ts";
 import type { ReportTarget } from "../surfaces/report.ts";
+import { DREAM_REPORT_INPUT_SCHEMA } from "../waves/dreamReport.ts";
+import {
+  decodeDreamReportBlock,
+  type ObjectiveDreamReportBlock,
+  resolveDreamReportGate,
+} from "./objectiveDreamReport.ts";
 
 /** The reviewed objective delivery choice (contracts §8.45). */
 export type DeliveryChoice = "incremental" | "stacked";
@@ -53,6 +61,9 @@ export interface ObjectiveSaveParams {
   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
+  // resolver's, so the decode keeps it opaque beyond the plain-object shape.
+  dream_report?: unknown;
 }
 
 /**
@@ -69,6 +80,20 @@ export const DELIVERY_PARAM_SCHEMA = {
     "one atomic PR train — capability-checked at save).",
 } as const;
 
+/**
+ * The `dream_report` property, shared between `objective_save` and `objective_draft` so the
+ * two tools' dream contracts cannot drift: the §8.62 `DREAM_REPORT_INPUT_SCHEMA` embedded by
+ * identifier (the `DELIVERY_PARAM_SCHEMA`/`ROADMAP_PARAM_SCHEMA` shared-schema pattern) plus
+ * the gate description. Structurally reachable only inside a `perk learn dream` session (the
+ * resolver refuses it outside one).
+ */
+export const DREAM_REPORT_PARAM_SCHEMA = {
+  ...DREAM_REPORT_INPUT_SCHEMA,
+  description:
+    "The perk learn dream session's final report input (the parent's decisions only) — " +
+    "required inside a dream session, refused outside one.",
+} as const;
+
 /**
  * The roadmap-node items JSON schema, shared between `objective_save` and `objective_draft`
  * so the two tools' roadmap contracts cannot drift.
@@ -116,12 +141,22 @@ export function decodeObjectiveSaveParams(params: unknown): ObjectiveSaveParams
   const roadmap = arrayParam(p, "roadmap");
   const base = stringParam(p, "base");
   const delivery = stringParam(p, "delivery");
-  if (prose === null || title === null || roadmap === null || base === null || delivery === null) {
+  // `dream_report` must be a plain object when present (absent → undefined); deep validation
+  // stays with the gate resolver (resolveDreamReportGate).
+  const dreamReport = objectParam(p, "dream_report");
+  if (
+    prose === null ||
+    title === null ||
+    roadmap === null ||
+    base === null ||
+    delivery === null ||
+    dreamReport === null
+  ) {
     return null;
   }
   // The delivery enum is strict beyond `string`: an off-enum value is present-but-mistyped.
   if (delivery !== undefined && delivery !== "incremental" && delivery !== "stacked") return null;
-  return { prose: prose ?? "", title, roadmap, base, delivery };
+  return { prose: prose ?? "", title, roadmap, base, delivery, dream_report: dreamReport };
 }
 
 /** The fixed working-objective artifact name (one JSON file: prose + the structured roadmap). */
@@ -144,7 +179,9 @@ export type ObjectiveDraftResult = Result<ObjectiveDraftOk>;
  * structured roadmap, verbatim — the draft never validates node shapes) as one JSON artifact and
  * write it through the accessor seam (file + `session_artifacts` provenance pointer). Soft
  * result, never throws — failure taxonomy: empty prose → `invalid_input`; no session run_id →
- * `no_run_id`; file-or-pointer write failure → `write_failed` (the seam already warned).
+ * `no_run_id`; a `dream_report` gate refusal → `invalid_input`/`bad_state` (the §8.63 matrix —
+ * validated at write time so a report-less dream bundle can never reach review);
+ * file-or-pointer write failure → `write_failed` (the seam already warned).
  */
 export function writeObjectiveDraft(
   sink: EntrySink,
@@ -155,6 +192,7 @@ export function writeObjectiveDraft(
     roadmap?: unknown[];
     base?: string;
     delivery?: DeliveryChoice;
+    dream_report?: unknown;
   },
 ): ObjectiveDraftResult {
   const fail = failFor(ctx, "objective-draft");
@@ -168,6 +206,13 @@ export function writeObjectiveDraft(
     return fail("session has no run_id — cannot write the objective-draft artifact", "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 = resolveDreamReportGate(ctx, opts.dream_report, new Date().toISOString());
+  if (gate.kind === "refuse") {
+    return fail(gate.detail, gate.errorType);
+  }
+
   // Deterministic key order via the explicit literal; `title`/`base`/`delivery` are omitted
   // when blank/absent (schema_version stays 1 — an additive optional field, fail-open readers).
   const title = opts.title?.trim();
@@ -179,6 +224,7 @@ export function writeObjectiveDraft(
     ...(title ? { title } : {}),
     ...(base ? { base } : {}),
     ...(delivery ? { delivery } : {}),
+    ...(gate.kind === "block" ? { dream_report: gate.block } : {}),
     prose: opts.prose,
     roadmap,
   };
@@ -216,6 +262,8 @@ export interface ObjectiveDraft {
   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;
 }
 
 /**
@@ -223,7 +271,10 @@ export interface ObjectiveDraft {
  * `readSessionArtifact`'s loud tier): no pointer/file/digest → `null` (the seam already spoke);
  * malformed JSON, a non-object payload, an unsupported `schema_version`, or blank prose → a
  * stderr warning + `null`. `roadmap` defaults to `[]` when absent/non-array; `title` is kept
- * only when a non-blank string. Never throws.
+ * only when a non-blank string. A present-but-malformed `dream_report` block refuses the WHOLE
+ * draft (warn + `null`) — 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 readObjectiveDraft(ctx: SessionDataCtx): ObjectiveDraft | null {
   const artifact = readSessionArtifact(ctx, OBJECTIVE_DRAFT_ARTIFACT);
@@ -258,10 +309,19 @@ export function readObjectiveDraft(ctx: SessionDataCtx): ObjectiveDraft | null {
     payload.delivery === "incremental" || payload.delivery === "stacked"
       ? 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 {
     ...(title !== undefined ? { title } : {}),
     ...(base !== undefined ? { base } : {}),
     ...(delivery !== undefined ? { delivery } : {}),
+    ...(dreamReport !== undefined ? { dream_report: dreamReport } : {}),
     prose,
     roadmap,
   };
@@ -294,7 +354,10 @@ function nodeDependsOn(node: unknown): string {
  * 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`. Pure; never throws.
+ * `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.
  */
 /** The always-present prominent `**Delivery:**` review line (contracts §8.45). */
 function deliveryLine(draft: ObjectiveDraft): string {
@@ -313,23 +376,27 @@ export function renderObjectiveDraft(draft: ObjectiveDraft): string {
   out += `${deliveryLine(draft)}\n\n`;
   out += draft.prose;
 
-  if (draft.roadmap.length === 0) return out;
+  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`;
+  }
 
-  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(" | ")} |`;
-  });
-  return `${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`;
 }
 
 const TOOL_GUIDELINES = [
@@ -371,6 +438,7 @@ export function registerObjectiveDraft(pi: ExtensionAPI): void {
             "Optional target branch for this objective's plans (omit to use the repo default).",
         },
         delivery: DELIVERY_PARAM_SCHEMA,
+        dream_report: DREAM_REPORT_PARAM_SCHEMA,
         roadmap: {
           type: "array",
           description:

package/extension/factories/objectiveDreamReport.ts

@@ -0,0 +1,347 @@
+// 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
+// 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
+// `dream_report` outside a dream session refuses rather than being silently dropped. Absence
+// on a non-dream path is byte-identical no-op behavior.
+//
+// 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).
+//
+// Imports only the dream wave siblings, the substrate seams, and node builtins — cycle-free
+// (nothing in `waves/` imports factories) 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";
+
+/**
+ * The shared part-invariance + size rule's comment-body cap (contracts §8.64) — the full
+ * rendered companion comment (marker + blank line + part) must fit with margin under GitHub's
+ * 65,536-char issue-comment limit. The Python twin is
+ * `perk.learn.dream_companion.COMPANION_COMMENT_MAX_CHARS` (parity-pinned fixtures).
+ */
+export const COMPANION_COMMENT_MAX_CHARS = 65_000;
+
+// The invariance shapes (the exact shapes the Linear transcoder `to_linear_markdown`
+// rewrites/drops — derived locally by the same rule, mirroring the Python twin).
+const MARKER_TEXT = "perk:learn-dream-report";
+const PERK_HTML_MARKER_RE = /<!--\s*\/?perk:[^>]+?\s*-->/;
+const DETAILS_OPEN_RE = /^<details><summary><code>[^<]*<\/code><\/summary>$/;
+const DETAILS_CLOSE = "</details>";
+// Every line boundary Python's `str.splitlines()` recognizes EXCEPT `\n` — the Linear
+// transcoder splits on all of them and rejoins with `\n`, so any other boundary form would be
+// normalized in the stored body and defeat the persistence-side byte comparison forever.
+const NON_CANONICAL_LINE_BOUNDARIES = [
+  "\r",
+  "\v",
+  "\f",
+  "\u001c",
+  "\u001d",
+  "\u001e",
+  "\u0085",
+  "\u2028",
+  "\u2029",
+];
+
+/**
+ * The TS mirror of Python's `validate_report_parts` (contracts §8.64) — run over the freshly
+ * rendered parts at draft-write AND save (both flow through `resolveDreamReportGate`), so an
+ * approved report is always Python-savable: no empty/blank part, no perk HTML-comment marker,
+ * no literal companion marker text, no perk-rendered `<details>` wrapper line (the shapes the
+ * Linear transcoder rewrites/drops — transcode-invariance keeps the persistence-side
+ * dual-candidate byte comparison exact), and every rendered comment body (marker + blank line +
+ * part) within `COMPANION_COMMENT_MAX_CHARS` code points. Returns named violations (`[]` =
+ * valid). Parity-pinned against the Python twin by the shared fixture set.
+ */
+export function reportPartInvarianceViolations(parts: string[], runId: string): string[] {
+  const violations: string[] = [];
+  parts.forEach((part, i) => {
+    const index = i + 1;
+    const where = `part ${index}`;
+    if (part.trim() === "") {
+      violations.push(`${where}: empty part`);
+      return;
+    }
+    if (part.includes(MARKER_TEXT)) {
+      violations.push(`${where}: carries the literal '${MARKER_TEXT}' marker text`);
+    }
+    if (PERK_HTML_MARKER_RE.test(part)) {
+      violations.push(
+        `${where}: carries a perk HTML-comment marker (<!-- perk:… --> is rewritten by the ` +
+          "Linear transcoder)",
+      );
+    }
+    if (
+      part.split(/\r\n|\r|\n/).some((line) => DETAILS_OPEN_RE.test(line) || line === DETAILS_CLOSE)
+    ) {
+      violations.push(
+        `${where}: carries a perk-rendered <details> wrapper line (dropped by the Linear ` +
+          "transcoder)",
+      );
+    }
+    if (NON_CANONICAL_LINE_BOUNDARIES.some((boundary) => part.includes(boundary))) {
+      violations.push(
+        `${where}: carries a line boundary other than \\n (normalized by the Linear transcoder)`,
+      );
+    }
+    const bodyLength = codePointLength(`<!-- ${MARKER_TEXT}:${runId}:${index} -->\n\n${part}`);
+    if (bodyLength > COMPANION_COMMENT_MAX_CHARS) {
+      violations.push(
+        `${where}: rendered comment body is ${bodyLength} chars (cap ${COMPANION_COMMENT_MAX_CHARS})`,
+      );
+    }
+  });
+  if (parts.length === 0) violations.push("parts: empty list");
+  return violations;
+}
+
+/**
+ * The `dream_report` block the objective-draft artifact carries (tool-written only — the model
+ * never writes the artifact): the validated model input, the ONE `generated_at` stamp that
+ * keeps re-rendering deterministic across review and save, and the stored CANONICAL parts the
+ * review surface renders and the save byte-compares.
+ */
+export interface ObjectiveDreamReportBlock {
+  input: unknown;
+  generated_at: string;
+  parts: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The artifact-side shape check `readObjectiveDraft` uses: a plain object carrying a
+ * plain-object `input`, a non-blank string `generated_at`, and a non-empty all-string `parts`.
+ * Deep validation stays with the resolver (the save re-runs the full gate); `null` = malformed.
+ */
+export function decodeDreamReportBlock(value: unknown): ObjectiveDreamReportBlock | null {
+  if (!isRecord(value)) return null;
+  if (!isRecord(value.input)) return null;
+  if (typeof value.generated_at !== "string" || !value.generated_at.trim()) return null;
+  if (!Array.isArray(value.parts) || value.parts.length === 0) return null;
+  const parts: string[] = [];
+  for (const part of value.parts) {
+    if (typeof part !== "string") return null;
+    parts.push(part);
+  }
+  return { input: value.input, generated_at: value.generated_at, parts };
+}
+
+/**
+ * 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).
+ */
+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,
+    },
+  };
+}
+
+/** The typed gate outcome both consumers branch on — the whole matrix, one vocabulary. */
+export type DreamReportGateOutcome =
+  | { kind: "absent" }
+  | { kind: "block"; block: ObjectiveDreamReportBlock }
+  | { kind: "refuse"; errorType: "invalid_input" | "bad_state"; detail: string };
+
+/**
+ * The ONE gate resolver (contracts §8.63) — identical at draft-write and save. `input` is the
+ * model-supplied `dream_report` value, or `undefined` for "no dream_report" (callers pass the
+ * value only when present; an `{input: undefined}` carrier is never constructed). The matrix:
+ *
+ * | session   | `dream_report` | outcome |
+ * | --------- | -------------- | ------- |
+ * | non-dream | absent         | `absent` — unchanged, byte-identical behavior |
+ * | non-dream | present        | refuse `invalid_input` (never silently dropped) |
+ * | 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`
+ * null-on-throw sentinel would otherwise let a transient read failure surface as `absent`).
+ *
+ * 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`.
+ */
+export function resolveDreamReportGate(
+  ctx: SessionDataCtx,
+  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);
+    return {
+      kind: "refuse",
+      errorType: "bad_state",
+      detail: `session workflow state is unreadable — cannot resolve the dream_report gate: ${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) {
+    if (input === undefined) return { kind: "absent" };
+    return {
+      kind: "refuse",
+      errorType: "invalid_input",
+      detail:
+        "dream_report is only valid inside a perk learn dream session — refusing rather than " +
+        "silently dropping it",
+    };
+  }
+  if (input === undefined) {
+    return {
+      kind: "refuse",
+      errorType: "invalid_input",
+      detail:
+        "this dream session's objective must carry dream_report — the objective and its " +
+        "report review as one bundle",
+    };
+  }
+  const recovered = recoverDreamReportContext(ctx, runId, state.dream_bundle_digest, generatedAt);
+  if (!recovered.ok) {
+    return { kind: "refuse", errorType: "bad_state", detail: recovered.detail };
+  }
+  // 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);
+  if (!drift.ok) {
+    return {
+      kind: "refuse",
+      errorType: "bad_state",
+      detail:
+        `the repository moved since the dream snapshot (${drift.detail}) — the analysis is ` +
+        "stale; re-run perk learn dream",
+    };
+  }
+  const built = buildDreamReport(input, recovered.context);
+  if (!built.ok) {
+    return { kind: "refuse", errorType: "invalid_input", detail: built.details.join("\n") };
+  }
+  // The §8.64 invariance mirror, at draft-write AND save (this resolver is both), so an
+  // approved report is always savable by the Python door's identical rule.
+  const violations = reportPartInvarianceViolations(built.parts, runId);
+  if (violations.length > 0) {
+    return {
+      kind: "refuse",
+      errorType: "invalid_input",
+      detail: `dream report parts violate the invariance rule: ${violations.join("; ")}`,
+    };
+  }
+  return { kind: "block", block: { input, generated_at: generatedAt, parts: built.parts } };
+}