@mgiles/perk 2.3.0 → 3.1.0

package/extension/waves/dreamReport.ts

@@ -0,0 +1,1494 @@
+// The learn-dream report layer — the pure interior module that turns the two-level dream wave
+// outcome into ONE checkable, savable final report (contracts.md §8.62). Three pieces: the
+// structured dream-report model (the trust split — the model supplies ONLY the parent's
+// decisions; everything factual is injected from trusted caller context), the validation that
+// proves the parent's judgment obeys the pinned curation policy (downgrade-only, the
+// destructive evidence bar, merge-target survival, the exact unit partition, surviving
+// follow-up destinations), and the deterministic Markdown renderer that owns the CANONICAL
+// report bytes, split into parts under a backend-neutral size budget. Pure domain code: no fs,
+// no tool registration, no `ExtensionAPI` — imports only the two dream siblings plus nothing
+// else. The input is untrusted DATA, never instructions.
+
+import {
+  DREAM_REDUCER_ANGLES,
+  type DreamReducerAnalysis,
+  type DreamReducerAngle,
+} from "./dreamReducerWave.ts";
+import {
+  codePointLength,
+  DREAM_DISPOSITIONS,
+  type DreamDisposition,
+  type DreamDocAssessment,
+  type DreamLaneAnalysis,
+  type DreamManifest,
+} from "./dreamWave.ts";
+
+/** The dream report's own schema version line (independent of the manifest's). */
+export const DREAM_REPORT_SCHEMA_VERSION = "1";
+
+/** The cap on DISTINCT `roadmap_node` values across the selected units — the ≤12-node
+ * selection cap checked at review time (many-to-one unit→node mapping is allowed). */
+export const DREAM_REPORT_MAX_ROADMAP_NODES = 12;
+
+/**
+ * The per-part cap on the rendered report, measured in Unicode CODE POINTS (matching Python's
+ * `len()` in the `journal.py` `JOURNAL_EVENT_MAX_CHARS` precedent) — under GitHub's 65,536-char
+ * comment limit with margin for the persistence-side storage markers (the renderer never emits
+ * marker HTML).
+ */
+export const DREAM_REPORT_PART_MAX_CHARS = 60_000;
+
+/** The fixed per-part packing allowance for the part header line. */
+export const DREAM_REPORT_PART_HEADER_RESERVE = 200;
+
+/** The bounded semantic-detail collection cap: overflow appends ONE synthetic count detail. */
+export const DREAM_REPORT_MAX_VALIDATION_DETAILS = 25;
+
+/**
+ * The SSOT for EVERY capped model-supplied field: the input schema's `maxItems`/`maxLength`
+ * and the structural decode both read from this one object (the `DREAM_ANALYST_CAPS` pattern).
+ * String caps are measured in Unicode code points (JSON Schema `maxLength` semantics — the
+ * shared `codePointLength`). `rows`/`selectedUnits`/`overflowUnits` are static schema bounds;
+ * the real gates are the validator's exact path-set equality, the ≤12-distinct-node cap, and
+ * the exact unit partition.
+ */
+export const DREAM_REPORT_CAPS = {
+  rows: 512,
+  rowRationaleChars: 300,
+  fallbackReasonChars: 300,
+  uncertainties: 12,
+  uncertaintyChars: 300,
+  selectedUnits: 64,
+  overflowUnits: 64,
+  unitTitleChars: 150,
+  unitDocs: 32,
+  unitRationaleChars: 400,
+  unitNodeChars: 32,
+  harvestFollowups: 12,
+  followupTitleChars: 150,
+  followupPointerChars: 250,
+  followupEvidenceChars: 250,
+  followupDestinationChars: 400,
+  predictedNoteChars: 300,
+} as const;
+
+// ------------------------------------------------------------------ the model-facing input
+
+/** One final per-doc disposition row (model-supplied). */
+export interface DreamReportInputRow {
+  path: string;
+  disposition: DreamDisposition;
+  merge_target: string | null;
+  rationale: string;
+  /** Required non-empty exactly when the final disposition differs from the analyst proposal. */
+  fallback_reason: string | null;
+}
+
+/** One selected curation unit (rank = input position; several units MAY share a node). */
+export interface DreamReportSelectedUnit {
+  title: string;
+  roadmap_node: string;
+  docs: string[];
+  rationale: string;
+}
+
+/** One overflow curation unit (rank = input position; carries no roadmap node). */
+export interface DreamReportOverflowUnit {
+  title: string;
+  docs: string[];
+  rationale: string;
+}
+
+/** One harvest follow-up citing a SURVIVING destination (a keep/revise doc or its cluster). */
+export interface DreamReportFollowup {
+  title: string;
+  destination: string;
+  pointer: string;
+  evidence: string;
+}
+
+/** The model-supplied prediction — TYPE sanity only, deliberately no directional/quota rule. */
+export interface DreamReportPredictedEffectsInput {
+  docs_after: number;
+  bytes_after: number;
+  note: string | null;
+}
+
+/** The untrusted, model-supplied input: ONLY the decisions the design assigns to the parent. */
+export interface DreamReportInput {
+  rows: DreamReportInputRow[];
+  uncertainties: string[];
+  selected_units: DreamReportSelectedUnit[];
+  overflow_units: DreamReportOverflowUnit[];
+  harvest_followups: DreamReportFollowup[];
+  predicted_effects: DreamReportPredictedEffectsInput;
+}
+
+/** The trusted, caller-supplied context the report is composed FROM — everything factual
+ * (snapshot identity, coverage, analyst evidence, reducer stances, uncertainties, counters)
+ * is injected from here, never accepted from the model. */
+export interface DreamReportContext {
+  manifest: DreamManifest;
+  analyses: DreamLaneAnalysis[];
+  reducers: DreamReducerAnalysis[];
+  run_id: string;
+  generated_at: string;
+}
+
+/**
+ * The model-facing input schema (exported for the review path's param embedding — the
+ * `DREAM_ANALYST_REPORT_SCHEMA` discipline): closed shape at every level, all fields required
+ * (optional semantics via `null`), enums, every `maxItems`/`maxLength` read from the ONE
+ * `DREAM_REPORT_CAPS` SSOT, no if/then, no `pattern` — the composed defensive validation
+ * enforces everything the schema cannot (the single-line rule included).
+ */
+export const DREAM_REPORT_INPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "rows",
+    "uncertainties",
+    "selected_units",
+    "overflow_units",
+    "harvest_followups",
+    "predicted_effects",
+  ],
+  properties: {
+    rows: {
+      type: "array",
+      maxItems: DREAM_REPORT_CAPS.rows,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["path", "disposition", "merge_target", "rationale", "fallback_reason"],
+        properties: {
+          path: { type: "string" },
+          disposition: { type: "string", enum: [...DREAM_DISPOSITIONS] },
+          merge_target: { type: ["string", "null"] },
+          rationale: { type: "string", maxLength: DREAM_REPORT_CAPS.rowRationaleChars },
+          fallback_reason: {
+            type: ["string", "null"],
+            maxLength: DREAM_REPORT_CAPS.fallbackReasonChars,
+          },
+        },
+      },
+    },
+    uncertainties: {
+      type: "array",
+      maxItems: DREAM_REPORT_CAPS.uncertainties,
+      items: { type: "string", maxLength: DREAM_REPORT_CAPS.uncertaintyChars },
+    },
+    selected_units: {
+      type: "array",
+      maxItems: DREAM_REPORT_CAPS.selectedUnits,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["title", "roadmap_node", "docs", "rationale"],
+        properties: {
+          title: { type: "string", maxLength: DREAM_REPORT_CAPS.unitTitleChars },
+          roadmap_node: { type: "string", maxLength: DREAM_REPORT_CAPS.unitNodeChars },
+          docs: {
+            type: "array",
+            maxItems: DREAM_REPORT_CAPS.unitDocs,
+            items: { type: "string" },
+          },
+          rationale: { type: "string", maxLength: DREAM_REPORT_CAPS.unitRationaleChars },
+        },
+      },
+    },
+    overflow_units: {
+      type: "array",
+      maxItems: DREAM_REPORT_CAPS.overflowUnits,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["title", "docs", "rationale"],
+        properties: {
+          title: { type: "string", maxLength: DREAM_REPORT_CAPS.unitTitleChars },
+          docs: {
+            type: "array",
+            maxItems: DREAM_REPORT_CAPS.unitDocs,
+            items: { type: "string" },
+          },
+          rationale: { type: "string", maxLength: DREAM_REPORT_CAPS.unitRationaleChars },
+        },
+      },
+    },
+    harvest_followups: {
+      type: "array",
+      maxItems: DREAM_REPORT_CAPS.harvestFollowups,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["title", "destination", "pointer", "evidence"],
+        properties: {
+          title: { type: "string", maxLength: DREAM_REPORT_CAPS.followupTitleChars },
+          destination: {
+            type: "string",
+            maxLength: DREAM_REPORT_CAPS.followupDestinationChars,
+          },
+          pointer: { type: "string", maxLength: DREAM_REPORT_CAPS.followupPointerChars },
+          evidence: { type: "string", maxLength: DREAM_REPORT_CAPS.followupEvidenceChars },
+        },
+      },
+    },
+    predicted_effects: {
+      type: "object",
+      additionalProperties: false,
+      required: ["docs_after", "bytes_after", "note"],
+      properties: {
+        docs_after: { type: "integer", minimum: 0 },
+        bytes_after: { type: "integer", minimum: 0 },
+        note: { type: ["string", "null"], maxLength: DREAM_REPORT_CAPS.predictedNoteChars },
+      },
+    },
+  },
+};
+
+// ------------------------------------------------------------------- the composed report
+
+/** One injected reducer stance record, joined onto its doc's row (angle order). */
+export interface DreamReportStanceRecord {
+  angle: DreamReducerAngle;
+  stance: "endorse" | "challenge";
+  reason: string;
+  evidence_checked: string[];
+}
+
+/** One composed per-doc row: the model's final decision joined with the injected analyst
+ * evidence and reducer stances (manifest lane/doc order). */
+export interface DreamReportRow {
+  path: string;
+  lane: string;
+  cluster: string | null;
+  analyst_disposition: DreamDisposition;
+  analyst_merge_target: string | null;
+  analyst_rationale: string;
+  analyst_preserve: string[];
+  analyst_evidence_checked: string[];
+  analyst_confidence: "high" | "medium" | "low";
+  final_disposition: DreamDisposition;
+  final_merge_target: string | null;
+  rationale: string;
+  fallback_reason: string | null;
+  stances: DreamReportStanceRecord[];
+}
+
+/** One analyst lane's coverage line (complete by construction — rendered for verification). */
+export interface DreamReportAnalystCoverage {
+  lane: string;
+  docs: number;
+  overlap_signals_omitted: number;
+  harvest_followups_omitted: number;
+  uncertainties_omitted: number;
+}
+
+/** One reducer angle's coverage line. */
+export interface DreamReportReducerCoverage {
+  angle: DreamReducerAngle;
+  stances: number;
+  stances_omitted: number;
+  angle_findings_omitted: number;
+  uncertainties_omitted: number;
+}
+
+/** The composed dream report — a plain JSON-serializable join of validated input with
+ * injected trusted context. The renderer is a pure function of this value. */
+export interface DreamReport {
+  snapshot: {
+    schema_version: string;
+    run_id: string;
+    generated_at: string;
+    commit_sha: string;
+    registry_mode: "clusters" | "categories";
+    doc_count: number;
+    total_bytes: number;
+  };
+  findings: {
+    structural: { family: string; count: number }[];
+    advisory: { family: string; count: number }[];
+  };
+  coverage: {
+    analysts: DreamReportAnalystCoverage[];
+    reducers: DreamReportReducerCoverage[];
+  };
+  rows: DreamReportRow[];
+  uncertainties: {
+    parent: string[];
+    analysts: { lane: string; items: string[] }[];
+    reducers: { angle: DreamReducerAngle; items: string[] }[];
+  };
+  reducer_findings: { angle: DreamReducerAngle; items: string[] }[];
+  selected_units: DreamReportSelectedUnit[];
+  overflow_units: DreamReportOverflowUnit[];
+  harvest_followups: DreamReportFollowup[];
+  predicted_effects: {
+    docs_before: number;
+    bytes_before: number;
+    docs_after: number;
+    bytes_after: number;
+    note: string | null;
+  };
+}
+
+// --------------------------------------------------------------------------- shared bits
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function isDisposition(value: unknown): value is DreamDisposition {
+  return typeof value === "string" && (DREAM_DISPOSITIONS as readonly string[]).includes(value);
+}
+
+/** Destructiveness levels for the downgrade-only rule — the two destructive dispositions
+ * share a level and are INCOMPARABLE (a merge↔retire swap is never a downgrade). */
+const DISPOSITION_LEVEL: Record<DreamDisposition, number> = {
+  keep: 0,
+  revise: 1,
+  "merge-into": 2,
+  retire: 2,
+};
+
+function isDestructive(disposition: DreamDisposition): boolean {
+  return DISPOSITION_LEVEL[disposition] === 2;
+}
+
+/** Name the first line-structure violation in a model-supplied string, or null. The renderer
+ * places these strings in table cells and bullets — line structure stays renderer-owned, so
+ * `\r`/`\n` and every other C0 control character refuse with a named detail. */
+function singleLineViolation(s: string): string | null {
+  for (const ch of s) {
+    const cp = ch.codePointAt(0) as number;
+    if (cp < 0x20) {
+      if (cp === 0x0a) return "a newline";
+      if (cp === 0x0d) return "a carriage return";
+      return `a C0 control character (U+${cp.toString(16).toUpperCase().padStart(4, "0")})`;
+    }
+  }
+  return null;
+}
+
+/** `merge-into → docs/x.md` / `retire` — the proposal spelling used in named details. */
+function describeProposal(disposition: DreamDisposition, target: string | null): string {
+  return target === null ? disposition : `${disposition} → ${target}`;
+}
+
+type Refusal = { ok: false; details: string[] };
+
+function refuse(detail: string): Refusal {
+  return { ok: false, details: [detail] };
+}
+
+// ------------------------------------------------------------- the structural input decode
+
+type StringField = { ok: true; value: string } | { ok: false; detail: string };
+
+/** Decode one capped single-line model string (code-point cap + the single-line rule). */
+function decodeReportString(value: unknown, maxChars: number | null, what: string): StringField {
+  if (typeof value !== "string") {
+    return { ok: false, detail: `${what} is not a string` };
+  }
+  if (maxChars !== null && codePointLength(value) > maxChars) {
+    return { ok: false, detail: `${what} exceeds ${maxChars} code points` };
+  }
+  const violation = singleLineViolation(value);
+  if (violation !== null) {
+    return {
+      ok: false,
+      detail: `${what} contains ${violation} — model-supplied strings must be single-line`,
+    };
+  }
+  return { ok: true, value };
+}
+
+/** Decode one capped array of single-line model strings. */
+function decodeReportStringArray(
+  raw: unknown,
+  maxItems: number,
+  maxChars: number | null,
+  what: string,
+): { ok: true; items: string[] } | { ok: false; detail: string } {
+  if (!Array.isArray(raw)) {
+    return { ok: false, detail: `${what} is not an array` };
+  }
+  if (raw.length > maxItems) {
+    return { ok: false, detail: `${what} carries more than ${maxItems} items (${raw.length})` };
+  }
+  const items: string[] = [];
+  for (const item of raw) {
+    const decoded = decodeReportString(item, maxChars, `a ${what} item`);
+    if (!decoded.ok) return decoded;
+    items.push(decoded.value);
+  }
+  return { ok: true, items };
+}
+
+/**
+ * The fail-fast structural decode (whitelisted construction — an extra input key never
+ * survives; the first named detail wins): the schema-equivalent shape plus the code-enforced
+ * caps and the single-line rule. Relational/semantic rules (path sets, downgrade-only, the
+ * evidence bar, survival, partition, destinations) are collected afterwards — construction
+ * cannot proceed over malformed input, so those misses fail fast here.
+ */
+function decodeDreamReportInput(
+  raw: unknown,
+): { ok: true; input: DreamReportInput } | { ok: false; detail: string } {
+  if (!isRecord(raw)) {
+    return { ok: false, detail: "dream report input is not an object" };
+  }
+  const caps = DREAM_REPORT_CAPS;
+
+  if (!Array.isArray(raw.rows)) {
+    return { ok: false, detail: "input rows is not an array" };
+  }
+  if (raw.rows.length > caps.rows) {
+    return {
+      ok: false,
+      detail: `input rows carries more than ${caps.rows} rows (${raw.rows.length})`,
+    };
+  }
+  const rows: DreamReportInputRow[] = [];
+  for (const rawRow of raw.rows) {
+    if (!isRecord(rawRow)) {
+      return { ok: false, detail: "a disposition row is not an object" };
+    }
+    const path = decodeReportString(rawRow.path, null, "a disposition row path");
+    if (!path.ok) return path;
+    const what = `row '${path.value}'`;
+    if (!isDisposition(rawRow.disposition)) {
+      return {
+        ok: false,
+        detail: `${what} disposition ${JSON.stringify(rawRow.disposition)} is outside the vocabulary`,
+      };
+    }
+    let mergeTarget: string | null = null;
+    if (rawRow.merge_target !== null) {
+      const decoded = decodeReportString(rawRow.merge_target, null, `${what} merge_target`);
+      if (!decoded.ok) return decoded;
+      mergeTarget = decoded.value;
+    }
+    const rationale = decodeReportString(
+      rawRow.rationale,
+      caps.rowRationaleChars,
+      `${what} rationale`,
+    );
+    if (!rationale.ok) return rationale;
+    let fallbackReason: string | null = null;
+    if (rawRow.fallback_reason !== null) {
+      const decoded = decodeReportString(
+        rawRow.fallback_reason,
+        caps.fallbackReasonChars,
+        `${what} fallback_reason`,
+      );
+      if (!decoded.ok) return decoded;
+      fallbackReason = decoded.value;
+    }
+    rows.push({
+      path: path.value,
+      disposition: rawRow.disposition,
+      merge_target: mergeTarget,
+      rationale: rationale.value,
+      fallback_reason: fallbackReason,
+    });
+  }
+
+  const uncertainties = decodeReportStringArray(
+    raw.uncertainties,
+    caps.uncertainties,
+    caps.uncertaintyChars,
+    "input uncertainties",
+  );
+  if (!uncertainties.ok) return uncertainties;
+
+  if (!Array.isArray(raw.selected_units)) {
+    return { ok: false, detail: "input selected_units is not an array" };
+  }
+  if (raw.selected_units.length > caps.selectedUnits) {
+    return {
+      ok: false,
+      detail:
+        `input selected_units carries more than ${caps.selectedUnits} units ` +
+        `(${raw.selected_units.length})`,
+    };
+  }
+  const selectedUnits: DreamReportSelectedUnit[] = [];
+  for (const [index, rawUnit] of raw.selected_units.entries()) {
+    const what = `selected unit ${index + 1}`;
+    if (!isRecord(rawUnit)) {
+      return { ok: false, detail: `${what} is not an object` };
+    }
+    const title = decodeReportString(rawUnit.title, caps.unitTitleChars, `${what} title`);
+    if (!title.ok) return title;
+    const node = decodeReportString(
+      rawUnit.roadmap_node,
+      caps.unitNodeChars,
+      `${what} roadmap_node`,
+    );
+    if (!node.ok) return node;
+    const docs = decodeReportStringArray(rawUnit.docs, caps.unitDocs, null, `${what} docs`);
+    if (!docs.ok) return docs;
+    const rationale = decodeReportString(
+      rawUnit.rationale,
+      caps.unitRationaleChars,
+      `${what} rationale`,
+    );
+    if (!rationale.ok) return rationale;
+    selectedUnits.push({
+      title: title.value,
+      roadmap_node: node.value,
+      docs: docs.items,
+      rationale: rationale.value,
+    });
+  }
+
+  if (!Array.isArray(raw.overflow_units)) {
+    return { ok: false, detail: "input overflow_units is not an array" };
+  }
+  if (raw.overflow_units.length > caps.overflowUnits) {
+    return {
+      ok: false,
+      detail:
+        `input overflow_units carries more than ${caps.overflowUnits} units ` +
+        `(${raw.overflow_units.length})`,
+    };
+  }
+  const overflowUnits: DreamReportOverflowUnit[] = [];
+  for (const [index, rawUnit] of raw.overflow_units.entries()) {
+    const what = `overflow unit ${index + 1}`;
+    if (!isRecord(rawUnit)) {
+      return { ok: false, detail: `${what} is not an object` };
+    }
+    const title = decodeReportString(rawUnit.title, caps.unitTitleChars, `${what} title`);
+    if (!title.ok) return title;
+    const docs = decodeReportStringArray(rawUnit.docs, caps.unitDocs, null, `${what} docs`);
+    if (!docs.ok) return docs;
+    const rationale = decodeReportString(
+      rawUnit.rationale,
+      caps.unitRationaleChars,
+      `${what} rationale`,
+    );
+    if (!rationale.ok) return rationale;
+    overflowUnits.push({ title: title.value, docs: docs.items, rationale: rationale.value });
+  }
+
+  if (!Array.isArray(raw.harvest_followups)) {
+    return { ok: false, detail: "input harvest_followups is not an array" };
+  }
+  if (raw.harvest_followups.length > caps.harvestFollowups) {
+    return {
+      ok: false,
+      detail:
+        `input harvest_followups carries more than ${caps.harvestFollowups} follow-ups ` +
+        `(${raw.harvest_followups.length})`,
+    };
+  }
+  const harvestFollowups: DreamReportFollowup[] = [];
+  for (const [index, rawFollowup] of raw.harvest_followups.entries()) {
+    const what = `harvest follow-up ${index + 1}`;
+    if (!isRecord(rawFollowup)) {
+      return { ok: false, detail: `${what} is not an object` };
+    }
+    const title = decodeReportString(rawFollowup.title, caps.followupTitleChars, `${what} title`);
+    if (!title.ok) return title;
+    const destination = decodeReportString(
+      rawFollowup.destination,
+      caps.followupDestinationChars,
+      `${what} destination`,
+    );
+    if (!destination.ok) return destination;
+    const pointer = decodeReportString(
+      rawFollowup.pointer,
+      caps.followupPointerChars,
+      `${what} pointer`,
+    );
+    if (!pointer.ok) return pointer;
+    const evidence = decodeReportString(
+      rawFollowup.evidence,
+      caps.followupEvidenceChars,
+      `${what} evidence`,
+    );
+    if (!evidence.ok) return evidence;
+    harvestFollowups.push({
+      title: title.value,
+      destination: destination.value,
+      pointer: pointer.value,
+      evidence: evidence.value,
+    });
+  }
+
+  if (!isRecord(raw.predicted_effects)) {
+    return { ok: false, detail: "input predicted_effects is not an object" };
+  }
+  const effects = raw.predicted_effects;
+  if (!nonNegativeInteger(effects.docs_after)) {
+    return { ok: false, detail: "predicted_effects docs_after is not a non-negative integer" };
+  }
+  if (!nonNegativeInteger(effects.bytes_after)) {
+    return { ok: false, detail: "predicted_effects bytes_after is not a non-negative integer" };
+  }
+  let note: string | null = null;
+  if (effects.note !== null) {
+    const decoded = decodeReportString(
+      effects.note,
+      caps.predictedNoteChars,
+      "predicted_effects note",
+    );
+    if (!decoded.ok) return decoded;
+    note = decoded.value;
+  }
+
+  return {
+    ok: true,
+    input: {
+      rows,
+      uncertainties: uncertainties.items,
+      selected_units: selectedUnits,
+      overflow_units: overflowUnits,
+      harvest_followups: harvestFollowups,
+      predicted_effects: {
+        docs_after: effects.docs_after,
+        bytes_after: effects.bytes_after,
+        note,
+      },
+    },
+  };
+}
+
+// --------------------------------------------------------------- the context re-verification
+
+/**
+ * Re-verify the trusted context BEFORE any input judgment: a report can only be built from
+ * COMPLETE waves — `analyses` must cover the manifest's lanes exactly (one per lane, manifest
+ * order, each covering its lane's docs exactly) and `reducers` must carry exactly the three
+ * `DREAM_REDUCER_ANGLES` in fixed order. Incomplete coverage is never described as complete.
+ */
+function contextViolation(context: DreamReportContext): string | null {
+  if (typeof context.run_id !== "string" || context.run_id === "") {
+    return "context run_id must be a non-empty string";
+  }
+  if (singleLineViolation(context.run_id) !== null) {
+    return "context run_id must be a single-line string";
+  }
+  if (typeof context.generated_at !== "string" || context.generated_at === "") {
+    return "context generated_at must be a non-empty string";
+  }
+  if (singleLineViolation(context.generated_at) !== null) {
+    return "context generated_at must be a single-line string";
+  }
+  const expectedLanes = context.manifest.lanes.map((lane) => lane.id);
+  const gotLanes = context.analyses.map((analysis) => analysis.lane);
+  if (
+    expectedLanes.length !== gotLanes.length ||
+    expectedLanes.some((id, i) => id !== gotLanes[i])
+  ) {
+    return (
+      "context analyses must cover the manifest's lanes exactly in manifest order " +
+      `(expected: ${expectedLanes.join(", ")}; got: ${gotLanes.join(", ") || "none"})`
+    );
+  }
+  for (const [index, lane] of context.manifest.lanes.entries()) {
+    const analysis = context.analyses[index] as DreamLaneAnalysis;
+    const expectedDocs = lane.docs.map((doc) => doc.path);
+    const gotDocs = analysis.report.docs.map((doc) => doc.path);
+    if (expectedDocs.length !== gotDocs.length || expectedDocs.some((p, i) => p !== gotDocs[i])) {
+      return `context analysis for lane '${lane.id}' does not cover the lane's docs exactly`;
+    }
+  }
+  const gotAngles = context.reducers.map((reducer) => reducer.angle);
+  if (
+    gotAngles.length !== DREAM_REDUCER_ANGLES.length ||
+    DREAM_REDUCER_ANGLES.some((angle, i) => angle !== gotAngles[i])
+  ) {
+    return (
+      "context reducers must carry exactly the three reducer angles in fixed order " +
+      `(expected: ${DREAM_REDUCER_ANGLES.join(", ")}; got: ${gotAngles.join(", ") || "none"})`
+    );
+  }
+  return null;
+}
+
+// ------------------------------------------------------------------------- the validation
+
+/** The gate angles whose explicit endorsement a destructive final row requires. */
+const EVIDENCE_BAR_GATE_ANGLES: readonly DreamReducerAngle[] = [
+  "consolidation-preservation",
+  "currency-accuracy",
+];
+
+interface JoinedRow {
+  input: DreamReportInputRow;
+  analyst: DreamDocAssessment;
+  /** The downgrade rule passed — later phases (evidence bar, survival) only run then. */
+  downgradeOk: boolean;
+}
+
+/**
+ * Validate the model-supplied input against the pinned curation policy and compose the full
+ * typed `DreamReport` by joining it with the injected trusted context. Two-stage error
+ * reporting (the interactive-redraft deviation from the fail-fast decoder posture): context
+ * re-verification and structural decode fail FAST (first named detail, one-element `details`);
+ * the semantic rules collect up to `DREAM_REPORT_MAX_VALIDATION_DETAILS` named details in
+ * deterministic order (validation phase order, then manifest doc order within a phase),
+ * overflow appending one final synthetic detail counting the omitted violations.
+ */
+export function validateDreamReport(
+  input: unknown,
+  context: DreamReportContext,
+): { ok: true; report: DreamReport } | Refusal {
+  const contextDetail = contextViolation(context);
+  if (contextDetail !== null) return refuse(contextDetail);
+  const decoded = decodeDreamReportInput(input);
+  if (!decoded.ok) return refuse(decoded.detail);
+  const typed = decoded.input;
+
+  const manifest = context.manifest;
+  const manifestPaths: string[] = manifest.lanes.flatMap((lane) =>
+    lane.docs.map((doc) => doc.path),
+  );
+  const corpusSet = new Set(manifestPaths);
+  const assessmentByPath = new Map<string, DreamDocAssessment>();
+  for (const analysis of context.analyses) {
+    for (const doc of analysis.report.docs) assessmentByPath.set(doc.path, doc);
+  }
+
+  const details: string[] = [];
+
+  // Phase 1 (D4) — exact path-set equality: no duplicate, no extra, no missing rows.
+  const rowByPath = new Map<string, DreamReportInputRow>();
+  for (const row of typed.rows) {
+    if (rowByPath.has(row.path)) {
+      details.push(`duplicate disposition row for '${row.path}'`);
+      continue;
+    }
+    if (!corpusSet.has(row.path)) {
+      details.push(`disposition row path '${row.path}' is not an authored doc in the manifest`);
+      continue;
+    }
+    rowByPath.set(row.path, row);
+  }
+  for (const path of manifestPaths) {
+    if (!rowByPath.has(path)) {
+      details.push(`missing disposition row for authored doc '${path}'`);
+    }
+  }
+
+  // Phase 2 (D4) — per-row rules in manifest doc order: rationale non-empty, the
+  // merge-target shape, downgrade-only against the analyst proposal, the fallback rule.
+  const joined = new Map<string, JoinedRow>();
+  for (const path of manifestPaths) {
+    const row = rowByPath.get(path);
+    if (row === undefined) continue;
+    const analyst = assessmentByPath.get(path) as DreamDocAssessment;
+    const state: JoinedRow = { input: row, analyst, downgradeOk: true };
+    joined.set(path, state);
+    if (row.rationale === "") {
+      details.push(`row '${path}' rationale must be non-empty`);
+    }
+    if (row.disposition === "merge-into") {
+      if (row.merge_target === null) {
+        details.push(`row '${path}' has disposition 'merge-into' but a null merge_target`);
+        state.downgradeOk = false;
+        continue;
+      }
+    } else if (row.merge_target !== null) {
+      details.push(
+        `row '${path}' carries a merge_target on a '${row.disposition}' disposition (must be null)`,
+      );
+      state.downgradeOk = false;
+      continue;
+    }
+    // Downgrade-only: final level ≤ analyst level; a destructive final must match the analyst
+    // proposal EXACTLY (same disposition AND byte-identical merge_target — the reducers
+    // stanced that specific proposal; anything else is an unendorsed new action).
+    if (isDestructive(row.disposition)) {
+      if (!isDestructive(analyst.disposition)) {
+        details.push(
+          `row '${path}' escalates the analyst proposal '${analyst.disposition}' to ` +
+            `'${row.disposition}' — the parent never resolves upward`,
+        );
+        state.downgradeOk = false;
+      } else if (
+        row.disposition !== analyst.disposition ||
+        row.merge_target !== analyst.merge_target
+      ) {
+        details.push(
+          `row '${path}' final '${describeProposal(row.disposition, row.merge_target)}' does ` +
+            `not match the analyst proposal ` +
+            `'${describeProposal(analyst.disposition, analyst.merge_target)}' exactly — an ` +
+            "unendorsed destructive action is refused (downgrade to 'revise' or 'keep' with a " +
+            "fallback_reason instead)",
+        );
+        state.downgradeOk = false;
+      }
+    } else if (row.disposition === "revise" && analyst.disposition === "keep") {
+      details.push(
+        `row '${path}' escalates the analyst proposal 'keep' to 'revise' — the parent never ` +
+          "resolves upward",
+      );
+      state.downgradeOk = false;
+    }
+    if (!state.downgradeOk) continue;
+    const changed = row.disposition !== analyst.disposition;
+    if (changed && (row.fallback_reason === null || row.fallback_reason === "")) {
+      details.push(
+        `row '${path}' departs from the analyst proposal ('${analyst.disposition}' → ` +
+          `'${row.disposition}') and requires a non-empty fallback_reason`,
+      );
+    } else if (!changed && row.fallback_reason !== null) {
+      details.push(
+        `row '${path}' matches the analyst proposal and must carry fallback_reason: null`,
+      );
+    }
+  }
+
+  // Phase 3 (D5) — the destructive evidence bar, computed ONLY from context stances: an
+  // explicit endorse from BOTH gate angles and no challenge from ANY angle; silence counts as
+  // non-endorsement. The bar is necessary, not sufficient — an eligible proposal MAY still be
+  // downgraded by parent judgment.
+  const stancesByDoc = new Map<string, DreamReportStanceRecord[]>();
+  for (const reducer of context.reducers) {
+    for (const stance of reducer.report.stances) {
+      const records = stancesByDoc.get(stance.doc) ?? [];
+      records.push({
+        angle: reducer.angle,
+        stance: stance.stance,
+        reason: stance.reason,
+        evidence_checked: stance.evidence_checked,
+      });
+      stancesByDoc.set(stance.doc, records);
+    }
+  }
+  for (const path of manifestPaths) {
+    const state = joined.get(path);
+    if (state === undefined || !state.downgradeOk) continue;
+    if (!isDestructive(state.input.disposition)) continue;
+    const records = stancesByDoc.get(path) ?? [];
+    const blockers: string[] = [];
+    for (const gate of EVIDENCE_BAR_GATE_ANGLES) {
+      const endorsed = records.some((r) => r.angle === gate && r.stance === "endorse");
+      if (!endorsed) blockers.push(`no '${gate}' endorsement (silence is non-endorsement)`);
+    }
+    for (const record of records) {
+      if (record.stance === "challenge") blockers.push(`a '${record.angle}' challenge`);
+    }
+    if (blockers.length > 0) {
+      details.push(
+        `destructive row '${path}' ('${state.input.disposition}') fails the evidence bar: ` +
+          `${blockers.join("; ")} — the only legal moves are downgrading to 'revise' or ` +
+          "'keep' with a fallback_reason",
+      );
+    }
+  }
+
+  // Phase 4 (D6) — merge-target existence + survival over FINAL dispositions. Survival
+  // structurally forbids merge chains and cycles (a merge-into doc can never be a target).
+  for (const path of manifestPaths) {
+    const state = joined.get(path);
+    if (state === undefined || !state.downgradeOk) continue;
+    if (state.input.disposition !== "merge-into") continue;
+    const target = state.input.merge_target as string;
+    if (!corpusSet.has(target)) {
+      details.push(`row '${path}' merge_target '${target}' is not a member of the manifest corpus`);
+      continue;
+    }
+    const targetRow = rowByPath.get(target);
+    if (targetRow === undefined) continue; // the missing-row detail already covers the target
+    if (targetRow.disposition !== "keep" && targetRow.disposition !== "revise") {
+      details.push(
+        `row '${path}' merge_target '${target}' does not survive (final disposition ` +
+          `'${targetRow.disposition}') — a merge target must end keep or revise`,
+      );
+    }
+  }
+
+  // Phase 5 (D7) — curation units: corpus membership, no doc in two units, no empty unit, no
+  // final-keep doc in a unit, the exact partition over the final non-keep set, non-empty
+  // roadmap nodes, and the ≤12-distinct-node cap (many-to-one node mapping is allowed).
+  const claimedBy = new Set<string>();
+  const allUnits: { what: string; docs: string[] }[] = [
+    ...typed.selected_units.map((unit, i) => ({
+      what: `selected unit ${i + 1} ('${unit.title}')`,
+      docs: unit.docs,
+    })),
+    ...typed.overflow_units.map((unit, i) => ({
+      what: `overflow unit ${i + 1} ('${unit.title}')`,
+      docs: unit.docs,
+    })),
+  ];
+  for (const unit of allUnits) {
+    if (unit.docs.length === 0) {
+      details.push(`${unit.what} has no docs — empty units are refused`);
+    }
+    for (const doc of unit.docs) {
+      if (!corpusSet.has(doc)) {
+        details.push(`${unit.what} doc '${doc}' is not a member of the manifest corpus`);
+        continue;
+      }
+      if (claimedBy.has(doc)) {
+        details.push(`doc '${doc}' appears in more than one curation unit`);
+        continue;
+      }
+      claimedBy.add(doc);
+      const row = rowByPath.get(doc);
+      if (row !== undefined && row.disposition === "keep") {
+        details.push(
+          `${unit.what} doc '${doc}' has final disposition 'keep' — final-keep docs appear ` +
+            "in no unit",
+        );
+      }
+    }
+  }
+  for (const path of manifestPaths) {
+    const row = rowByPath.get(path);
+    if (row === undefined || row.disposition === "keep") continue;
+    if (!claimedBy.has(path)) {
+      details.push(
+        `non-keep doc '${path}' is not covered by any curation unit — selected + overflow ` +
+          "units must partition the non-keep docs exactly",
+      );
+    }
+  }
+  const distinctNodes = new Set<string>();
+  for (const [index, unit] of typed.selected_units.entries()) {
+    if (unit.roadmap_node === "") {
+      details.push(`selected unit ${index + 1} ('${unit.title}') roadmap_node must be non-empty`);
+      continue;
+    }
+    distinctNodes.add(unit.roadmap_node);
+  }
+  if (distinctNodes.size > DREAM_REPORT_MAX_ROADMAP_NODES) {
+    details.push(
+      `selected units name ${distinctNodes.size} distinct roadmap nodes — the cap is ` +
+        `${DREAM_REPORT_MAX_ROADMAP_NODES}`,
+    );
+  }
+
+  // Phase 6 (D8) — harvest follow-ups cite SURVIVING destinations: a keep/revise corpus doc,
+  // or a cluster named by at least one keep/revise doc.
+  const survivingDocs = new Set<string>();
+  for (const path of manifestPaths) {
+    const row = rowByPath.get(path);
+    if (row !== undefined && (row.disposition === "keep" || row.disposition === "revise")) {
+      survivingDocs.add(path);
+    }
+  }
+  const allClusters = new Set<string>();
+  const survivingClusters = new Set<string>();
+  for (const lane of manifest.lanes) {
+    for (const doc of lane.docs) {
+      if (doc.cluster === null) continue;
+      allClusters.add(doc.cluster);
+      if (survivingDocs.has(doc.path)) survivingClusters.add(doc.cluster);
+    }
+  }
+  for (const [index, followup] of typed.harvest_followups.entries()) {
+    const what = `harvest follow-up ${index + 1} ('${followup.title}')`;
+    if (followup.pointer === "") {
+      details.push(`${what} pointer must be non-empty`);
+    }
+    if (corpusSet.has(followup.destination)) {
+      if (!survivingDocs.has(followup.destination)) {
+        const row = rowByPath.get(followup.destination);
+        details.push(
+          `${what} destination '${followup.destination}' is a corpus doc that does not ` +
+            `survive (final disposition '${row?.disposition ?? "missing"}') — repoint the ` +
+            "follow-up at a survivor",
+        );
+      }
+    } else if (allClusters.has(followup.destination)) {
+      if (!survivingClusters.has(followup.destination)) {
+        details.push(
+          `${what} destination '${followup.destination}' is a cluster with no surviving ` +
+            "keep/revise member",
+        );
+      }
+    } else {
+      details.push(
+        `${what} destination '${followup.destination}' is neither a surviving corpus doc ` +
+          "nor a cluster named by a surviving doc",
+      );
+    }
+  }
+
+  // Phase 7 (D9) — predicted effects carry deliberately NO directional/quota rule: a growth
+  // prediction is valid (type sanity was structural).
+
+  if (details.length > 0) {
+    if (details.length > DREAM_REPORT_MAX_VALIDATION_DETAILS) {
+      const omitted = details.length - DREAM_REPORT_MAX_VALIDATION_DETAILS;
+      return {
+        ok: false,
+        details: [
+          ...details.slice(0, DREAM_REPORT_MAX_VALIDATION_DETAILS),
+          `…and ${omitted} more validation detail(s) omitted ` +
+            `(cap ${DREAM_REPORT_MAX_VALIDATION_DETAILS})`,
+        ],
+      };
+    }
+    return { ok: false, details };
+  }
+
+  // Compose — whitelisted construction, manifest lane/doc order throughout.
+  const rows: DreamReportRow[] = [];
+  for (const lane of manifest.lanes) {
+    for (const doc of lane.docs) {
+      const state = joined.get(doc.path) as JoinedRow;
+      rows.push({
+        path: doc.path,
+        lane: lane.id,
+        cluster: doc.cluster,
+        analyst_disposition: state.analyst.disposition,
+        analyst_merge_target: state.analyst.merge_target,
+        analyst_rationale: state.analyst.rationale,
+        analyst_preserve: state.analyst.preserve,
+        analyst_evidence_checked: state.analyst.evidence_checked,
+        analyst_confidence: state.analyst.confidence,
+        final_disposition: state.input.disposition,
+        final_merge_target: state.input.merge_target,
+        rationale: state.input.rationale,
+        fallback_reason: state.input.fallback_reason,
+        stances: stancesByDoc.get(doc.path) ?? [],
+      });
+    }
+  }
+  const report: DreamReport = {
+    snapshot: {
+      schema_version: DREAM_REPORT_SCHEMA_VERSION,
+      run_id: context.run_id,
+      generated_at: context.generated_at,
+      commit_sha: manifest.commit_sha,
+      registry_mode: manifest.registry_mode,
+      doc_count: manifest.doc_count,
+      total_bytes: manifest.total_bytes,
+    },
+    findings: {
+      structural: [
+        { family: "stale_pointers", count: manifest.findings.structural.stale_pointers.length },
+        {
+          family: "broken_doc_paths",
+          count: manifest.findings.structural.broken_doc_paths.length,
+        },
+        { family: "duplicate_cues", count: manifest.findings.structural.duplicate_cues.length },
+        {
+          family: "missing_frontmatter",
+          count: manifest.findings.structural.missing_frontmatter.length,
+        },
+      ],
+      advisory: [
+        {
+          family: "distillation_issues",
+          count: manifest.findings.advisory.distillation_issues.length,
+        },
+        {
+          family: "source_code_blocks",
+          count: manifest.findings.advisory.source_code_blocks.length,
+        },
+        { family: "overlong_cues", count: manifest.findings.advisory.overlong_cues.length },
+        { family: "cue_hazards", count: manifest.findings.advisory.cue_hazards.length },
+        { family: "empty_clusters", count: manifest.findings.advisory.empty_clusters.length },
+      ],
+    },
+    coverage: {
+      analysts: manifest.lanes.map((lane, index) => {
+        const analysis = context.analyses[index] as DreamLaneAnalysis;
+        return {
+          lane: lane.id,
+          docs: lane.docs.length,
+          overlap_signals_omitted: analysis.report.overlap_signals_omitted,
+          harvest_followups_omitted: analysis.report.harvest_followups_omitted,
+          uncertainties_omitted: analysis.report.uncertainties_omitted,
+        };
+      }),
+      reducers: context.reducers.map((reducer) => ({
+        angle: reducer.angle,
+        stances: reducer.report.stances.length,
+        stances_omitted: reducer.report.stances_omitted,
+        angle_findings_omitted: reducer.report.angle_findings_omitted,
+        uncertainties_omitted: reducer.report.uncertainties_omitted,
+      })),
+    },
+    rows,
+    uncertainties: {
+      parent: typed.uncertainties,
+      analysts: context.analyses.map((analysis) => ({
+        lane: analysis.lane,
+        items: analysis.report.uncertainties,
+      })),
+      reducers: context.reducers.map((reducer) => ({
+        angle: reducer.angle,
+        items: reducer.report.uncertainties,
+      })),
+    },
+    reducer_findings: context.reducers.map((reducer) => ({
+      angle: reducer.angle,
+      items: reducer.report.angle_findings,
+    })),
+    selected_units: typed.selected_units,
+    overflow_units: typed.overflow_units,
+    harvest_followups: typed.harvest_followups,
+    predicted_effects: {
+      docs_before: manifest.doc_count,
+      bytes_before: manifest.total_bytes,
+      docs_after: typed.predicted_effects.docs_after,
+      bytes_after: typed.predicted_effects.bytes_after,
+      note: typed.predicted_effects.note,
+    },
+  };
+  return { ok: true, report };
+}
+
+// --------------------------------------------------------------------------- the renderer
+
+/** One packable Markdown block: same-group consecutive blocks join with `\n` (consecutive
+ * table or bullet lines); a table-row block carries its table's header for re-emission after
+ * a mid-table split (`null` for non-table groups — bullet lines split without re-emission). */
+interface RenderBlock {
+  text: string;
+  groupId: number | null;
+  tableHeader: string | null;
+}
+
+/** Deterministic table-cell/bullet sanitization: `|` escaped, internal newline runs collapsed
+ * to a single space — injected (analyst/reducer) prose may carry newlines/pipes; model strings
+ * are single-line by validation, so the collapse is idempotent for them. Line structure stays
+ * renderer-owned; the typed report retains the exact strings. */
+function sanitize(s: string): string {
+  return s.replace(/\|/g, "\\|").replace(/[\r\n]+/g, " ");
+}
+
+/** `a; b; c` or an em-dash for an empty list (inside a table cell or bullet). */
+function joinOrDash(items: string[]): string {
+  return items.length === 0 ? "—" : items.map(sanitize).join("; ");
+}
+
+/**
+ * Render the composed report to CANONICAL Markdown bytes in parts — a pure function of the
+ * report (no clock, no locale, no environment): an ordered stream of blocks greedily packed
+ * under `DREAM_REPORT_PART_MAX_CHARS − DREAM_REPORT_PART_HEADER_RESERVE` code points, splits
+ * only at block boundaries (bullet-list sections pack per bullet line, so a block group
+ * splits at line boundaries), a table split re-emitting the table header row in the next part,
+ * every part prefixed with its header after packing. A single block exceeding the budget is a
+ * defensive refusal (structurally unreachable under the caps arithmetic — named, never
+ * truncated).
+ */
+export function renderDreamReport(
+  report: DreamReport,
+): { ok: true; parts: string[] } | { ok: false; detail: string } {
+  const blocks: RenderBlock[] = [];
+  let nextGroupId = 0;
+  const push = (text: string): void => {
+    blocks.push({ text, groupId: null, tableHeader: null });
+  };
+  /** Push each line as its own block sharing ONE fresh group: unsplit output joins with `\n`
+   * (byte-identical to a single joined block); an oversized section splits at line
+   * boundaries with no header re-emission. */
+  const pushLines = (lines: string[]): void => {
+    const groupId = nextGroupId;
+    nextGroupId += 1;
+    for (const line of lines) {
+      blocks.push({ text: line, groupId, tableHeader: null });
+    }
+  };
+  const pushTable = (headerCells: string[], rows: string[][]): void => {
+    const groupId = nextGroupId;
+    nextGroupId += 1;
+    const header =
+      `| ${headerCells.join(" | ")} |\n` + `| ${headerCells.map(() => "---").join(" | ")} |`;
+    blocks.push({ text: header, groupId, tableHeader: null });
+    for (const row of rows) {
+      blocks.push({
+        text: `| ${row.map(sanitize).join(" | ")} |`,
+        groupId,
+        tableHeader: header,
+      });
+    }
+  };
+  const stanceBullets = (stances: DreamReportStanceRecord[]): string =>
+    stances.length === 0
+      ? "- No reducer stances recorded (silence is non-endorsement)."
+      : stances
+          .map(
+            (s) =>
+              `- ${s.angle}: ${s.stance} — ${sanitize(s.reason)} ` +
+              `(checked: ${joinOrDash(s.evidence_checked)})`,
+          )
+          .join("\n");
+
+  // 1 — Snapshot.
+  push("## Snapshot");
+  push(
+    [
+      `- Run: ${sanitize(report.snapshot.run_id)}`,
+      `- Report schema version: ${sanitize(report.snapshot.schema_version)}`,
+      `- Commit: ${sanitize(report.snapshot.commit_sha)}`,
+      `- Generated at: ${sanitize(report.snapshot.generated_at)}`,
+      `- Registry mode: ${report.snapshot.registry_mode}`,
+      `- Docs: ${report.snapshot.doc_count}`,
+      `- Total bytes: ${report.snapshot.total_bytes}`,
+    ].join("\n"),
+  );
+
+  // 2 — Findings summary.
+  push("## Findings summary");
+  pushTable(
+    ["Family", "Count"],
+    [
+      ...report.findings.structural.map((f) => [`structural.${f.family}`, String(f.count)]),
+      ...report.findings.advisory.map((f) => [`advisory.${f.family}`, String(f.count)]),
+    ],
+  );
+
+  // 3 — Wave coverage (complete by construction; rendered so a reviewer can verify it).
+  push("## Wave coverage");
+  push("### Analyst lanes");
+  pushTable(
+    [
+      "Lane",
+      "Docs",
+      "Overlap signals omitted",
+      "Harvest follow-ups omitted",
+      "Uncertainties omitted",
+    ],
+    report.coverage.analysts.map((c) => [
+      c.lane,
+      String(c.docs),
+      String(c.overlap_signals_omitted),
+      String(c.harvest_followups_omitted),
+      String(c.uncertainties_omitted),
+    ]),
+  );
+  push("### Reducer angles");
+  pushTable(
+    ["Angle", "Stances", "Stances omitted", "Angle findings omitted", "Uncertainties omitted"],
+    report.coverage.reducers.map((c) => [
+      c.angle,
+      String(c.stances),
+      String(c.stances_omitted),
+      String(c.angle_findings_omitted),
+      String(c.uncertainties_omitted),
+    ]),
+  );
+
+  // 4 — Dispositions: ONE table, one row per authored doc in manifest order.
+  push("## Dispositions");
+  pushTable(
+    ["Doc", "Cluster", "Analyst", "Final", "Merge target", "Confidence", "Rationale"],
+    report.rows.map((row) => [
+      row.path,
+      row.cluster ?? "—",
+      describeProposal(row.analyst_disposition, row.analyst_merge_target),
+      row.final_disposition,
+      row.final_merge_target ?? "—",
+      row.analyst_confidence,
+      row.rationale,
+    ]),
+  );
+
+  // 5 — Non-keep evidence: one subsection per FINAL non-keep doc (manifest order) — the
+  // injected analyst evidence plus every injected reducer stance for that doc's proposal.
+  push("## Non-keep evidence");
+  const nonKeepRows = report.rows.filter((row) => row.final_disposition !== "keep");
+  if (nonKeepRows.length === 0) {
+    push("_None._");
+  }
+  for (const row of nonKeepRows) {
+    push(`### ${row.path}`);
+    push(
+      [
+        `- Analyst rationale: ${sanitize(row.analyst_rationale)}`,
+        `- Preserve: ${joinOrDash(row.analyst_preserve)}`,
+        `- Evidence checked: ${joinOrDash(row.analyst_evidence_checked)}`,
+      ].join("\n"),
+    );
+    push(stanceBullets(row.stances));
+  }
+
+  // 6 — Fallbacks: the recorded non-destructive departures, rendered directly from the rows
+  // carrying a non-null fallback_reason (manifest order). A fallback doc whose final is keep
+  // renders its injected stances HERE (its proposal never reaches §5), so every reducer
+  // stance renders exactly once — §5 (final non-keep) or §6 (final keep).
+  push("## Fallbacks");
+  const fallbackRows = report.rows.filter((row) => row.fallback_reason !== null);
+  if (fallbackRows.length === 0) {
+    push("_None._");
+  }
+  for (const row of fallbackRows) {
+    push(`### ${row.path}`);
+    push(
+      [
+        `- Analyst proposal: ${sanitize(
+          describeProposal(row.analyst_disposition, row.analyst_merge_target),
+        )}`,
+        `- Final: ${row.final_disposition}`,
+        `- Reason: ${sanitize(row.fallback_reason as string)}`,
+      ].join("\n"),
+    );
+    if (row.final_disposition === "keep") {
+      push(stanceBullets(row.stances));
+    }
+  }
+
+  // 7 — Uncertainties, labeled by source: the parent's input first, then the injected
+  // analyst (by lane) and reducer (by angle) uncertainties.
+  push("## Uncertainties");
+  const uncertaintyLines: string[] = [
+    ...report.uncertainties.parent.map((item) => `- Parent: ${sanitize(item)}`),
+    ...report.uncertainties.analysts.flatMap((entry) =>
+      entry.items.map((item) => `- Analyst ${sanitize(entry.lane)}: ${sanitize(item)}`),
+    ),
+    ...report.uncertainties.reducers.flatMap((entry) =>
+      entry.items.map((item) => `- Reducer ${entry.angle}: ${sanitize(item)}`),
+    ),
+  ];
+  if (uncertaintyLines.length === 0) {
+    push("_None._");
+  } else {
+    pushLines(uncertaintyLines);
+  }
+
+  // 8 — Reducer findings: the injected per-angle `angle_findings` (bounded cross-corpus
+  // value — a deliberate minor addition beyond the node's section list).
+  push("## Reducer findings");
+  const findingLines: string[] = report.reducer_findings.flatMap((entry) =>
+    entry.items.map((item) => `- ${entry.angle}: ${sanitize(item)}`),
+  );
+  if (findingLines.length === 0) {
+    push("_None._");
+  } else {
+    pushLines(findingLines);
+  }
+
+  // 9 — Selected curation units (rank = position).
+  push("## Selected curation units");
+  if (report.selected_units.length === 0) {
+    push("_None._");
+  }
+  for (const [index, unit] of report.selected_units.entries()) {
+    push(
+      [
+        `**${index + 1}. ${sanitize(unit.title)}** — node \`${sanitize(unit.roadmap_node)}\``,
+        `- Docs: ${joinOrDash(unit.docs)}`,
+        `- Rationale: ${sanitize(unit.rationale)}`,
+      ].join("\n"),
+    );
+  }
+
+  // 10 — Overflow (rank = position, no node).
+  push("## Overflow");
+  if (report.overflow_units.length === 0) {
+    push("_None._");
+  }
+  for (const [index, unit] of report.overflow_units.entries()) {
+    push(
+      [
+        `**${index + 1}. ${sanitize(unit.title)}**`,
+        `- Docs: ${joinOrDash(unit.docs)}`,
+        `- Rationale: ${sanitize(unit.rationale)}`,
+      ].join("\n"),
+    );
+  }
+
+  // 11 — Harvest follow-ups.
+  push("## Harvest follow-ups");
+  if (report.harvest_followups.length === 0) {
+    push("_None._");
+  } else {
+    pushTable(
+      ["Title", "Destination", "Pointer", "Evidence"],
+      report.harvest_followups.map((f) => [f.title, f.destination, f.pointer, f.evidence]),
+    );
+  }
+
+  // 12 — Predicted effects (with the explicit not-quotas line).
+  push("## Predicted effects");
+  push(
+    [
+      `- Docs: ${report.predicted_effects.docs_before} → ${report.predicted_effects.docs_after}`,
+      `- Bytes: ${report.predicted_effects.bytes_before} → ` +
+        `${report.predicted_effects.bytes_after}`,
+      `- Note: ${report.predicted_effects.note === null ? "—" : sanitize(report.predicted_effects.note)}`,
+    ].join("\n"),
+  );
+  push("_Predictions are not quotas._");
+
+  // Greedy block packing under the reserve-adjusted budget.
+  const budget = DREAM_REPORT_PART_MAX_CHARS - DREAM_REPORT_PART_HEADER_RESERVE;
+  const oversize = (length: number): { ok: false; detail: string } => ({
+    ok: false,
+    detail:
+      `a single rendered block of ${length} code points exceeds the part packing budget ` +
+      `(${budget}) — refusing to truncate`,
+  });
+  const bodies: string[] = [];
+  let current = "";
+  let prevGroupId: number | null = null;
+  for (const block of blocks) {
+    if (current === "") {
+      const length = codePointLength(block.text);
+      if (length > budget) return oversize(length);
+      current = block.text;
+    } else {
+      const separator = block.groupId !== null && block.groupId === prevGroupId ? "\n" : "\n\n";
+      const candidate = current + separator + block.text;
+      if (codePointLength(candidate) <= budget) {
+        current = candidate;
+      } else {
+        bodies.push(current);
+        const opener =
+          block.tableHeader === null ? block.text : `${block.tableHeader}\n${block.text}`;
+        const length = codePointLength(opener);
+        if (length > budget) return oversize(length);
+        current = opener;
+      }
+    }
+    prevGroupId = block.groupId;
+  }
+  if (current !== "") bodies.push(current);
+
+  const total = bodies.length;
+  const parts = bodies.map((body, index) => {
+    const header =
+      index === 0
+        ? `# Dream report — ${report.snapshot.run_id}`
+        : `# Dream report — ${report.snapshot.run_id} (continued, part ${index + 1} of ${total})`;
+    return `${header}\n\n${body}\n`;
+  });
+  for (const part of parts) {
+    const length = codePointLength(part);
+    if (length > DREAM_REPORT_PART_MAX_CHARS) {
+      // Defensive: reachable only when the run id outgrows the fixed header reserve.
+      return {
+        ok: false,
+        detail:
+          `a rendered part of ${length} code points exceeds the part cap ` +
+          `(${DREAM_REPORT_PART_MAX_CHARS}) — refusing to truncate`,
+      };
+    }
+  }
+  return { ok: true, parts };
+}
+
+// ------------------------------------------------------------------------ the entry point
+
+/**
+ * Validate, compose, render, and enforce the part budget in ONE call — the draft path
+ * validates BEFORE review, so an approved report is always savable. `validateDreamReport`'s
+ * two-stage `details` shape passes through; the renderer's single-detail defensive arm is
+ * wrapped into a one-element `details`.
+ */
+export function buildDreamReport(
+  input: unknown,
+  context: DreamReportContext,
+): { ok: true; report: DreamReport; parts: string[] } | Refusal {
+  const validated = validateDreamReport(input, context);
+  if (!validated.ok) return validated;
+  const rendered = renderDreamReport(validated.report);
+  if (!rendered.ok) return refuse(rendered.detail);
+  return { ok: true, report: validated.report, parts: rendered.parts };
+}