@mgiles/perk 3.1.0 → 3.3.0

package/extension/{waves → learning}/dreamReport.ts

@@ -9,11 +9,6 @@
 // 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,
@@ -21,14 +16,19 @@ import {
   type DreamDocAssessment,
   type DreamLaneAnalysis,
   type DreamManifest,
-} from "./dreamWave.ts";
+} from "./dream.ts";
+import {
+  DREAM_REDUCER_ANGLES,
+  type DreamReducerAnalysis,
+  type DreamReducerAngle,
+} from "./dreamReducer.ts";
 
 /** The dream report's own schema version line (independent of the manifest's). */
-export const DREAM_REPORT_SCHEMA_VERSION = "1";
+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;
+const DREAM_REPORT_MAX_ROADMAP_NODES = 12;
 
 /**
  * The per-part cap on the rendered report, measured in Unicode CODE POINTS (matching Python's
@@ -36,13 +36,13 @@ export const DREAM_REPORT_MAX_ROADMAP_NODES = 12;
  * 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;
+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;
+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;
+const DREAM_REPORT_MAX_VALIDATION_DETAILS = 25;
 
 /**
  * The SSOT for EVERY capped model-supplied field: the input schema's `maxItems`/`maxLength`
@@ -52,7 +52,7 @@ export const DREAM_REPORT_MAX_VALIDATION_DETAILS = 25;
  * 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 = {
+const DREAM_REPORT_CAPS = {
   rows: 512,
   rowRationaleChars: 300,
   fallbackReasonChars: 300,
@@ -75,7 +75,7 @@ export const DREAM_REPORT_CAPS = {
 // ------------------------------------------------------------------ the model-facing input
 
 /** One final per-doc disposition row (model-supplied). */
-export interface DreamReportInputRow {
+interface DreamReportInputRow {
   path: string;
   disposition: DreamDisposition;
   merge_target: string | null;
@@ -85,7 +85,7 @@ export interface DreamReportInputRow {
 }
 
 /** One selected curation unit (rank = input position; several units MAY share a node). */
-export interface DreamReportSelectedUnit {
+interface DreamReportSelectedUnit {
   title: string;
   roadmap_node: string;
   docs: string[];
@@ -93,14 +93,14 @@ export interface DreamReportSelectedUnit {
 }
 
 /** One overflow curation unit (rank = input position; carries no roadmap node). */
-export interface DreamReportOverflowUnit {
+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 {
+interface DreamReportFollowup {
   title: string;
   destination: string;
   pointer: string;
@@ -108,14 +108,14 @@ export interface DreamReportFollowup {
 }
 
 /** The model-supplied prediction — TYPE sanity only, deliberately no directional/quota rule. */
-export interface DreamReportPredictedEffectsInput {
+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 {
+interface DreamReportInput {
   rows: DreamReportInputRow[];
   uncertainties: string[];
   selected_units: DreamReportSelectedUnit[];
@@ -249,7 +249,7 @@ export const DREAM_REPORT_INPUT_SCHEMA = {
 // ------------------------------------------------------------------- the composed report
 
 /** One injected reducer stance record, joined onto its doc's row (angle order). */
-export interface DreamReportStanceRecord {
+interface DreamReportStanceRecord {
   angle: DreamReducerAngle;
   stance: "endorse" | "challenge";
   reason: string;
@@ -258,7 +258,7 @@ export interface DreamReportStanceRecord {
 
 /** 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 {
+interface DreamReportRow {
   path: string;
   lane: string;
   cluster: string | null;
@@ -276,7 +276,7 @@ export interface DreamReportRow {
 }
 
 /** One analyst lane's coverage line (complete by construction — rendered for verification). */
-export interface DreamReportAnalystCoverage {
+interface DreamReportAnalystCoverage {
   lane: string;
   docs: number;
   overlap_signals_omitted: number;
@@ -285,7 +285,7 @@ export interface DreamReportAnalystCoverage {
 }
 
 /** One reducer angle's coverage line. */
-export interface DreamReportReducerCoverage {
+interface DreamReportReducerCoverage {
   angle: DreamReducerAngle;
   stances: number;
   stances_omitted: number;
@@ -736,8 +736,10 @@ interface JoinedRow {
  * 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.
+ * Module-private: `buildDreamReport` is the one entry — the whole matrix is exercised
+ * through it.
  */
-export function validateDreamReport(
+function validateDreamReport(
   input: unknown,
   context: DreamReportContext,
 ): { ok: true; report: DreamReport } | Refusal {
@@ -759,7 +761,7 @@ export function validateDreamReport(
 
   const details: string[] = [];
 
-  // Phase 1 (D4) — exact path-set equality: no duplicate, no extra, no missing rows.
+  // Phase 1 — 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)) {
@@ -778,7 +780,7 @@ export function validateDreamReport(
     }
   }
 
-  // Phase 2 (D4) — per-row rules in manifest doc order: rationale non-empty, the
+  // Phase 2 — 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) {
@@ -847,7 +849,7 @@ export function validateDreamReport(
     }
   }
 
-  // Phase 3 (D5) — the destructive evidence bar, computed ONLY from context stances: an
+  // Phase 3 — 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.
@@ -886,7 +888,7 @@ export function validateDreamReport(
     }
   }
 
-  // Phase 4 (D6) — merge-target existence + survival over FINAL dispositions. Survival
+  // Phase 4 — 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);
@@ -907,7 +909,7 @@ export function validateDreamReport(
     }
   }
 
-  // Phase 5 (D7) — curation units: corpus membership, no doc in two units, no empty unit, no
+  // Phase 5 — 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>();
@@ -969,7 +971,7 @@ export function validateDreamReport(
     );
   }
 
-  // Phase 6 (D8) — harvest follow-ups cite SURVIVING destinations: a keep/revise corpus doc,
+  // Phase 6 — 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) {
@@ -1016,7 +1018,7 @@ export function validateDreamReport(
     }
   }
 
-  // Phase 7 (D9) — predicted effects carry deliberately NO directional/quota rule: a growth
+  // Phase 7 — predicted effects carry deliberately NO directional/quota rule: a growth
   // prediction is valid (type sanity was structural).
 
   if (details.length > 0) {
@@ -1176,8 +1178,10 @@ function joinOrDash(items: string[]): string {
  * 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).
+ * Module-private: `buildDreamReport` is the one entry (it returns both the typed report and
+ * the rendered parts).
  */
-export function renderDreamReport(
+function renderDreamReport(
   report: DreamReport,
 ): { ok: true; parts: string[] } | { ok: false; detail: string } {
   const blocks: RenderBlock[] = [];