pi-mega-compact 0.20.1 → 0.20.3

package/src/vector-cortex/reconstruct/closure.ts

@@ -0,0 +1,299 @@
+/**
+ * vector-cortex/reconstruct/closure.ts — mandatory conservative closure (VC4C).
+ *
+ * Task 2/3: a WORKLIST recursion that repeatedly adds every `depends`
+ * predecessor and every whole tool pair of an already-selected node until the
+ * selection stops growing (a FIXED POINT), tracking visited ids so a cyclic
+ * graph terminates instead of recursing forever. Task 3: contradictions are
+ * resolved by retaining the LATER exact source resolution; an explicit
+ * resolution event may name the loser directly; equal/unordered resolutions are
+ * an unresolved tie and return `CLO_CONTRADICTION_UNRESOLVED` so the candidate
+ * never goes live (CONTRACTS §plan and closure).
+ *
+ * Determinism: the worklist is drained in sorted id order and every returned
+ * array is sorted, so the closed set is identical regardless of the order seeds
+ * or edges were supplied in. Time is never read here — contradiction ordering
+ * uses the SOURCE `resolvedAtMs` fact carried on the node.
+ *
+ * OWNERSHIP: `mandatoryTokenEstimate` is CONTENT ONLY (no prompt framing) and is
+ * handed unchanged to VC5A, which owns framing + budget admission and returns
+ * `MANDATORY_CLOSURE_OVER_BUDGET` on overflow. Closure NEVER truncates a
+ * mandatory node.
+ *
+ * Pure/deterministic: no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011).
+ */
+
+import type {
+  ClosureEdge,
+  ClosureFailureCode,
+  ClosureGraph,
+  ClosureNode,
+  ClosureProofStep,
+  ClosureResult,
+} from "./types.js";
+
+/** Sorted copy (bytewise id order) — every closure output is order-stable. */
+function sortedIds(ids: Iterable<string>): string[] {
+  return [...ids].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** Index the graph's nodes by id (last wins is impossible — ids are unique). */
+function indexNodes(graph: ClosureGraph): Map<string, ClosureNode> {
+  const byId = new Map<string, ClosureNode>();
+  for (const n of graph.nodes) byId.set(n.id, n);
+  return byId;
+}
+
+/**
+ * Build the "requirement" adjacency: for a selected node `x`, which nodes must
+ * ALSO be selected. Edges point prerequisite `from` → dependent `to`, so:
+ *
+ *   - `depends`   — selecting `to` requires `from` (walk BACKWARD to the
+ *                   prerequisite; this is the transitive dependency closure);
+ *   - `tool-pair` — the pair is atomic, so selecting EITHER endpoint requires
+ *                   the other (walk BOTH directions — a pair is never split,
+ *                   PREVENT-PI-002).
+ *
+ * `contradicts` is deliberately absent: a contradiction never PULLS a node in,
+ * it removes one (resolved separately below).
+ */
+function buildRequirements(
+  edges: readonly ClosureEdge[],
+): Map<string, Array<{ id: string; rule: "depends" | "tool-pair" }>> {
+  const req = new Map<string, Array<{ id: string; rule: "depends" | "tool-pair" }>>();
+  const add = (key: string, id: string, rule: "depends" | "tool-pair"): void => {
+    const list = req.get(key);
+    if (list === undefined) req.set(key, [{ id, rule }]);
+    else list.push({ id, rule });
+  };
+  for (const e of edges) {
+    if (e.kind === "depends") {
+      add(e.to, e.from, "depends");
+      continue;
+    }
+    if (e.kind === "tool-pair") {
+      add(e.to, e.from, "tool-pair");
+      add(e.from, e.to, "tool-pair");
+    }
+  }
+  return req;
+}
+
+/**
+ * Resolve one contradiction pair. Returns the loser id, or `null` when the pair
+ * is an unresolved tie.
+ *
+ * Precedence (CONTRACTS §plan and closure):
+ *   1. An explicit resolution event naming the loser wins outright.
+ *   2. Otherwise the LATER exact source resolution supersedes the earlier claim.
+ *      "Exact" is required: a semantic node never supersedes an exact one, since
+ *      semantic vectors never claim to recover exact text (RESIDUAL_CODEC).
+ *   3. Equal timestamps, missing timestamps, or two non-exact claims are
+ *      UNORDERED — keep both and reject live use.
+ */
+function resolveContradiction(
+  a: ClosureNode,
+  b: ClosureNode,
+  explicit: ReadonlyMap<string, string>,
+): string | null {
+  // 1. Explicit resolution event names the loser directly.
+  const aLoses = explicit.get(a.id);
+  if (aLoses === b.id) return a.id;
+  const bLoses = explicit.get(b.id);
+  if (bLoses === a.id) return b.id;
+
+  // 2. Later EXACT source resolution supersedes the earlier claim. Both sides
+  //    must be exact and both must carry a source resolution time.
+  const aExact = a.kind === "exact";
+  const bExact = b.kind === "exact";
+  const aAt = a.resolvedAtMs;
+  const bAt = b.resolvedAtMs;
+  if (aExact && bExact && aAt !== undefined && bAt !== undefined && aAt !== bAt) {
+    return aAt < bAt ? a.id : b.id;
+  }
+
+  // 3. Equal / unordered / non-exact — unresolved tie.
+  return null;
+}
+
+/** Seeds for a closure run: the explicitly requested node ids. */
+export interface ClosureInput {
+  readonly graph: ClosureGraph;
+  /** The initially requested node ids (the selection to close over). */
+  readonly seeds: readonly string[];
+}
+
+/**
+ * Close a selection conservatively to a fixed point (task 2 + 3).
+ *
+ * Algorithm: seed the worklist with the requested ids (plus the anchor floor,
+ * which is always mandatory), then repeatedly pop the smallest id and add every
+ * node it requires. A `visited` set makes each node expand exactly once, so a
+ * cycle (`a depends b`, `b depends a`) terminates at the fixed point rather than
+ * recursing forever. Contradictions among the CLOSED set are then resolved; an
+ * unresolved tie fails the closure.
+ */
+export function closeSelection(input: ClosureInput): ClosureResult {
+  const { graph, seeds } = input;
+  const byId = indexNodes(graph);
+  const failures: ClosureFailureCode[] = [];
+
+  // Structural validation: every edge endpoint and every seed must exist.
+  for (const e of graph.edges) {
+    if (!byId.has(e.from) || !byId.has(e.to)) {
+      if (!failures.includes("CLO_MISSING_NODE")) failures.push("CLO_MISSING_NODE");
+    }
+  }
+  for (const s of seeds) {
+    if (!byId.has(s)) {
+      if (!failures.includes("CLO_UNKNOWN_SEED")) failures.push("CLO_UNKNOWN_SEED");
+    }
+  }
+  if (failures.length > 0) {
+    return {
+      ok: false,
+      selected: [],
+      addedDependencies: [],
+      removedContradictions: [],
+      unresolved: [],
+      proof: [],
+      failures,
+      mandatoryTokenEstimate: 0,
+    };
+  }
+
+  const requirements = buildRequirements(graph.edges);
+  const selected = new Set<string>();
+  const proof: ClosureProofStep[] = [];
+  const seedSet = new Set(seeds);
+
+  // The anchor floor is ALWAYS mandatory: an anchor is never dropped by closure
+  // (PREVENT-PI-001's anchor-floor discipline restated for the closed prompt).
+  const anchorIds = graph.nodes.filter((n) => n.anchor === true).map((n) => n.id);
+
+  // Seed the worklist deterministically (sorted), anchors after explicit seeds
+  // so the proof reads "what was asked for, then what the floor forced".
+  const worklist: string[] = [];
+  for (const id of sortedIds(seedSet)) {
+    if (selected.has(id)) continue;
+    selected.add(id);
+    proof.push({ added: id, rule: "seed" });
+    worklist.push(id);
+  }
+  for (const id of sortedIds(anchorIds)) {
+    if (selected.has(id)) continue;
+    selected.add(id);
+    proof.push({ added: id, rule: "anchor-floor" });
+    worklist.push(id);
+  }
+
+  // ── Worklist recursion to a FIXED POINT (visited = `selected`) ─────────────
+  // Each id is expanded at most once because it can only enter the worklist at
+  // the moment it is inserted into `selected`. A cyclic graph therefore
+  // terminates: the second traversal of the cycle finds every node already
+  // selected and adds nothing.
+  while (worklist.length > 0) {
+    // Drain in sorted order so the proof is deterministic across input orders.
+    worklist.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const current = worklist.shift();
+    if (current === undefined) break;
+    const required = requirements.get(current) ?? [];
+    // Sort the requirements of one node so sibling additions are ordered too.
+    const ordered = [...required].sort((x, y) =>
+      x.id < y.id ? -1 : x.id > y.id ? 1 : x.rule < y.rule ? -1 : x.rule > y.rule ? 1 : 0,
+    );
+    for (const { id, rule } of ordered) {
+      if (selected.has(id)) continue; // already at the fixed point for this node
+      selected.add(id);
+      proof.push({ added: id, requiredBy: current, rule });
+      worklist.push(id);
+    }
+  }
+
+  // ── Contradiction resolution over the CLOSED set (task 3) ─────────────────
+  const explicit = new Map<string, string>();
+  for (const r of graph.resolutions ?? []) explicit.set(r.loserId, r.winnerId);
+
+  const removed = new Set<string>();
+  const unresolved = new Set<string>();
+  for (const e of graph.edges) {
+    if (e.kind !== "contradicts") continue;
+    // Only contradictions BETWEEN TWO SELECTED nodes matter: an unselected claim
+    // cannot contradict the prompt that is actually being built.
+    if (!selected.has(e.from) || !selected.has(e.to)) continue;
+    const a = byId.get(e.from);
+    const b = byId.get(e.to);
+    if (a === undefined || b === undefined) continue;
+    // A pair already decided by an earlier edge (duplicate contradiction) is
+    // skipped so one resolution is not re-litigated into a false tie.
+    if (removed.has(a.id) || removed.has(b.id)) continue;
+    const loser = resolveContradiction(a, b, explicit);
+    if (loser === null) {
+      unresolved.add(a.id);
+      unresolved.add(b.id);
+      continue;
+    }
+    removed.add(loser);
+  }
+
+  // A node that lost a contradiction leaves the selection. An unresolved tie
+  // keeps BOTH (CONTRACTS: "ties keep both and reject live use") and fails.
+  for (const id of removed) selected.delete(id);
+
+  const selectedIds = sortedIds(selected);
+  const addedDependencies = selectedIds.filter((id) => !seedSet.has(id));
+  const mandatoryTokenEstimate = selectedIds.reduce(
+    (sum, id) => sum + (byId.get(id)?.tokenEstimate ?? 0),
+    0,
+  );
+
+  const ok = unresolved.size === 0;
+  return {
+    ok,
+    selected: selectedIds,
+    addedDependencies,
+    removedContradictions: sortedIds(removed),
+    unresolved: sortedIds(unresolved),
+    proof,
+    failures: ok ? [] : ["CLO_CONTRADICTION_UNRESOLVED"],
+    mandatoryTokenEstimate,
+  };
+}
+
+/**
+ * Whether a closure result is a genuine fixed point: re-running the closure over
+ * its own output adds nothing. Used by the acceptance invariant ("closure reaches
+ * a fixed point") — an independent CHECK rather than a restatement of the loop.
+ */
+export function isFixedPoint(graph: ClosureGraph, result: ClosureResult): boolean {
+  if (!result.ok) return true; // a rejected closure is not required to be closed
+  const again = closeSelection({ graph, seeds: result.selected });
+  if (!again.ok) return false;
+  return (
+    again.selected.length === result.selected.length &&
+    again.selected.every((id, i) => id === result.selected[i])
+  );
+}
+
+/**
+ * Mode B: a GREEDY EXACT-ONLY closure, forced when semantic validation fails.
+ * Independent of mode A by construction — it consults no semantic node and no
+ * semantic index, deriving purely from the exact/event source tiers
+ * (TRIAD_RESILIENCE: A/B must not share the same algorithm or index).
+ */
+export function closeExactOnly(input: ClosureInput): ClosureResult {
+  const exactGraph: ClosureGraph = {
+    sessionId: input.graph.sessionId,
+    nodes: input.graph.nodes.filter((n) => n.kind !== "semantic"),
+    edges: input.graph.edges.filter((e) => {
+      const kinds = new Map(input.graph.nodes.map((n) => [n.id, n.kind]));
+      return kinds.get(e.from) !== "semantic" && kinds.get(e.to) !== "semantic";
+    }),
+    resolutions: input.graph.resolutions,
+  };
+  const seeds = input.seeds.filter((id) =>
+    exactGraph.nodes.some((n) => n.id === id),
+  );
+  return closeSelection({ graph: exactGraph, seeds });
+}

package/src/vector-cortex/reconstruct/types.ts

@@ -0,0 +1,330 @@
+/**
+ * vector-cortex/reconstruct/types.ts — conservative closure + reconstruction
+ * fidelity contract (VC4C).
+ *
+ * Owns `ClosureResult` / `ReconstructionV1` — the contract of the sprint failure
+ * triad:
+ *
+ *   A = closed semantic + exact/residual reconstruction (the normal path);
+ *   B = greedy EXACT-only closure, forced when semantic validation fails;
+ *   C = legacy prompt, forced by an unresolved contradiction (states its loss of
+ *       old semantic context — TRIAD_RESILIENCE: C is continuity, NOT semantic
+ *       completeness).
+ *
+ * Closure is MANDATORY before VC5 (CONTRACTS §plan and closure): recursively add
+ * every `depends`/tool-pair predecessor until a fixed point; for contradictions
+ * keep the LATER exact source resolution unless an explicit resolution event
+ * names the loser; ties keep both and reject live use
+ * (`CLO_CONTRADICTION_UNRESOLVED`). The anchor floor is preserved, and the closed
+ * mandatory node set is returned with its deterministic token estimate.
+ *
+ * OWNERSHIP BOUNDARY (CONTRACTS §plan and closure): `mandatoryTokenEstimate`
+ * counts CONTENT ONLY — no prompt framing, no role tags, no separators, no
+ * budget admission. VC5A exclusively owns framing/budget: it adds framing cost
+ * to this estimate and returns `MANDATORY_CLOSURE_OVER_BUDGET` if the mandatory
+ * cost exceeds its `tokenBudget`. VC4C therefore NEVER truncates a mandatory
+ * node and never reasons about a budget.
+ *
+ * Consumes only reviewer-accepted predecessor contracts (VC1A `EventV2` byte
+ * authority, VC4A `ShardRange`/`ExactShardV1`, VC4B `ParityShardV1` residual
+ * decode) and the common contracts. Pure types + registered conformance IDs: no
+ * storage, no console, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import type { ShardRange } from "../shards/types.js";
+
+/**
+ * The kind of a closure graph node, mirroring `DagNode.kind`
+ * (CONTRACTS §PromptDagV1). `exact` nodes carry authoritative source bytes;
+ * `semantic` nodes are derived and never claim to recover exact text;
+ * `synthetic` nodes have no source span and order after their prerequisites.
+ */
+export type ClosureNodeKind = "event" | "exact" | "semantic" | "synthetic";
+
+/**
+ * One node in the closure graph. `span` is the half-open source byte range this
+ * node occupies (absent for `synthetic` nodes, which have no source position).
+ * `anchor` marks a node inside the preserved anchor floor — closure preserves it
+ * and the validator rejects a reconstruction that drops it (PREVENT-PI-001's
+ * anchor-floor discipline, restated for the closed prompt).
+ *
+ * `resolvedAtMs` is the source resolution TIME used only for contradiction
+ * ordering: the LATER exact resolution wins. It is a source fact (the event's
+ * `occurredAtMs`), never a wall clock read at closure time — closure is pure and
+ * deterministic (TRIAD_RESILIENCE: wall time for records, never for eligibility).
+ */
+export interface ClosureNode {
+  readonly id: string;
+  readonly kind: ClosureNodeKind;
+  /** Source span; absent only for `synthetic` nodes. */
+  readonly span?: ShardRange;
+  /** True when the node belongs to the preserved anchor floor. */
+  readonly anchor?: boolean;
+  /**
+   * Source resolution time for contradiction ordering (from the source event,
+   * never `Date.now()`). Two contradicting nodes with EQUAL or ABSENT
+   * resolutions are an unresolved tie.
+   */
+  readonly resolvedAtMs?: bigint;
+  /**
+   * Deterministic CONTENT token estimate for this node (no framing). Summed into
+   * `ClosureResult.mandatoryTokenEstimate` and handed unchanged to VC5A.
+   */
+  readonly tokenEstimate: number;
+}
+
+/**
+ * One directed closure edge. Edges point prerequisite/earlier **from →
+ * dependent/later to** (CONTRACTS §PromptDagV1).
+ *
+ *   - `depends`   — `to` requires `from`; closure pulls `from` in transitively;
+ *   - `tool-pair` — a tool call/result pair that must be selected WHOLE (never
+ *                   split at a compaction boundary — PREVENT-PI-002);
+ *   - `contradicts` — mutually exclusive claims; the later exact resolution wins.
+ */
+export type ClosureEdgeKind = "depends" | "tool-pair" | "contradicts";
+
+/** A directed closure edge (`from` is the prerequisite/earlier endpoint). */
+export interface ClosureEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly kind: ClosureEdgeKind;
+}
+
+/**
+ * An explicit resolution event that names the LOSER of a contradiction
+ * (CONTRACTS §plan and closure: "keep the later exact source unless an explicit
+ * resolution event names the loser"). An explicit resolution therefore
+ * OVERRIDES the later-wins time rule and breaks what would otherwise be a tie.
+ */
+export interface ContradictionResolution {
+  /** The node id explicitly superseded (dropped from the closure). */
+  readonly loserId: string;
+  /** The node id that survives. */
+  readonly winnerId: string;
+}
+
+/** The closure graph handed to `closeSelection`. */
+export interface ClosureGraph {
+  readonly sessionId: string;
+  readonly nodes: readonly ClosureNode[];
+  readonly edges: readonly ClosureEdge[];
+  /** Explicit resolutions naming contradiction losers (may be empty). */
+  readonly resolutions?: readonly ContradictionResolution[];
+}
+
+/**
+ * A single recorded closure step — the PROOF that the fixed point was reached by
+ * a defensible derivation rather than asserted. Each step names the node added
+ * and the edge/rule that forced it.
+ */
+export interface ClosureProofStep {
+  /** The node id added by this step. */
+  readonly added: string;
+  /** The already-selected node that required it (absent for a seed). */
+  readonly requiredBy?: string;
+  /** Why it was added. */
+  readonly rule: "seed" | "depends" | "tool-pair" | "anchor-floor";
+}
+
+/** Closure failure codes (registered CLO codes). */
+export type ClosureFailureCode =
+  /** A contradiction whose resolutions are equal/unordered — reject live use. */
+  | "CLO_CONTRADICTION_UNRESOLVED"
+  /** An edge names a node id that is not in the graph. */
+  | "CLO_MISSING_NODE"
+  /** A seed id is not in the graph. */
+  | "CLO_UNKNOWN_SEED";
+
+/**
+ * The closed mandatory node set (CONTRACTS §plan and closure). `ok:false` means
+ * the closure is NOT live-usable and the adapter demotes (C on an unresolved
+ * contradiction).
+ *
+ * `selected` is the fixed point: every seed plus every transitively required
+ * dependency and whole tool pair, sorted deterministically by node id so the
+ * result is stable across input permutations. `mandatoryTokenEstimate` is the
+ * CONTENT-ONLY sum handed UNCHANGED to VC5A (which adds framing and owns budget
+ * admission — VC4C never truncates a mandatory node).
+ */
+export interface ClosureResult {
+  readonly ok: boolean;
+  /** The closed selection (sorted by node id). */
+  readonly selected: readonly string[];
+  /** Dependencies/tool-pair members pulled in beyond the seeds (sorted). */
+  readonly addedDependencies: readonly string[];
+  /** Contradiction losers removed by the later-exact / explicit rule (sorted). */
+  readonly removedContradictions: readonly string[];
+  /** Contradictions that could not be resolved (sorted) — reject live use. */
+  readonly unresolved: readonly string[];
+  /** Ordered derivation proof of the fixed point. */
+  readonly proof: readonly ClosureProofStep[];
+  /** Failure codes; empty when `ok`. */
+  readonly failures: readonly ClosureFailureCode[];
+  /**
+   * Deterministic CONTENT-ONLY token estimate of the closed mandatory set.
+   * Contains NO prompt framing (VC5A adds that and owns budget admission).
+   */
+  readonly mandatoryTokenEstimate: number;
+}
+
+/**
+ * One assembled span of the reconstruction. `bytes` are the authoritative source
+ * bytes for `range` — either verbatim exact-shard bytes (`source:"exact"`), a
+ * byte-exact residual decode (`source:"residual"`), or a derived semantic
+ * rendering that NEVER claims to be the exact text (`source:"semantic"`).
+ * `protectedSpan` marks a span the validator requires to be present and exact.
+ */
+export interface ReconstructionSpan {
+  readonly nodeId: string;
+  readonly range: ShardRange;
+  readonly source: "exact" | "residual" | "semantic";
+  readonly bytes: Uint8Array;
+  /** SHA-256 of `bytes`, lowercase hex (no `sha256:` prefix). */
+  readonly digest: string;
+  /** True when this span must survive verbatim (tool pair / anchor / invalid UTF-8). */
+  readonly protectedSpan: boolean;
+}
+
+/**
+ * The assembled reconstruction (VC4C's outbound contract to VC5A). Spans are
+ * ordered SOLELY by source range (`byteStart`, then `seqStart`, then node id for
+ * a total order) — never by selection order, map iteration, or scoring, so the
+ * assembly is deterministic and replayable. `digest` is one SHA-256 over the
+ * ordered span digests plus their ranges.
+ */
+export interface ReconstructionV1 {
+  readonly schema: "reconstruction-v1";
+  readonly sessionId: string;
+  /** Spans in source order (the concatenation order). */
+  readonly spans: readonly ReconstructionSpan[];
+  /** Deterministic digest over the ordered spans. */
+  readonly digest: string;
+  /** Total assembled byte count. */
+  readonly byteTotal: number;
+  /**
+   * CONTENT-ONLY mandatory token estimate, carried UNCHANGED from the closure so
+   * VC5A receives exactly the number VC4C computed (no framing, no budget).
+   */
+  readonly mandatoryTokenEstimate: number;
+}
+
+/** Reconstruction/validation failure codes (registered REC codes). */
+export type ReconstructionFailureCode =
+  /** A required source shard is missing AND its residual fallback failed. */
+  | "REC_SOURCE_UNAVAILABLE"
+  /** A protected anchor span is absent from the reconstruction. */
+  | "REC_ANCHOR_MISSING"
+  /** A tool call/result pair was split (PREVENT-PI-002). */
+  | "REC_TOOL_PAIR_SPLIT"
+  /** A span's bytes do not hash to its recorded digest. */
+  | "REC_DIGEST_MISMATCH"
+  /** The closure carried an unresolved contradiction — never goes live. */
+  | "REC_CONTRADICTION_UNRESOLVED"
+  /** Two assembled spans overlap in the source byte stream. */
+  | "REC_SPAN_OVERLAP";
+
+/**
+ * Validation verdict. Reader-facing surface is SUMMARY + CODES ONLY — never span
+ * bytes, never prompt text (SECURITY_PRIVACY: the exact ledger is not training
+ * data and is never rendered through a diagnostic surface).
+ */
+export type ReconstructionValidation =
+  | { readonly ok: true; readonly summary: ReconstructionSummary }
+  | { readonly ok: false; readonly codes: readonly ReconstructionFailureCode[] };
+
+/**
+ * Aggregate-only reconstruction summary exposed to the dashboard. Counts, byte
+ * totals and the digest identity — NEVER payload bytes or prompt text.
+ */
+export interface ReconstructionSummary {
+  readonly sessionId: string;
+  readonly spanCount: number;
+  readonly protectedSpanCount: number;
+  readonly byteTotal: number;
+  readonly mandatoryTokenEstimate: number;
+  readonly digest: string;
+  /** Per-source span counts (exact / residual / semantic). */
+  readonly bySource: {
+    readonly exact: number;
+    readonly residual: number;
+    readonly semantic: number;
+  };
+}
+
+/** The two structured events the VC4C reporter emits. */
+export type ReconstructEventName =
+  | "vector_cortex_reconstruction_validated"
+  | "vector_cortex_closure_rejected";
+
+/** Injected emit callback — same (event, fields) shape as the other VC seams. */
+export type ReconstructEmitter = (
+  event: ReconstructEventName,
+  fields: Record<string, unknown>,
+) => void;
+
+/** Typed, best-effort reporter bound to the two reconstruction event names. */
+export interface ReconstructReporter {
+  readonly reconstructionValidated: (fields: Record<string, unknown>) => void;
+  readonly closureRejected: (fields: Record<string, unknown>) => void;
+}
+
+/**
+ * Aggregate-only reconstruction metrics for the dashboard (counts/bytes only).
+ */
+export interface ReconstructMetricsV1 {
+  readonly closureAttempts: number;
+  readonly closureRejections: number;
+  readonly validatedCount: number;
+  readonly invalidatedCount: number;
+  readonly spanTotal: number;
+  readonly byteTotal: number;
+}
+
+/**
+ * The triad mode VC4C selects (TRIAD_RESILIENCE). A/B/C use INDEPENDENT
+ * algorithms: A closes over semantic+exact/residual; B is a greedy EXACT-only
+ * closure that shares no semantic index with A; C abandons the closed prompt
+ * entirely and returns the legacy transcript, stating its semantic loss.
+ */
+export type ReconstructMode = "A" | "B" | "C";
+
+/**
+ * The outcome of the triad selection: the mode taken, the validated
+ * reconstruction (A/B) and the reason C was forced, if it was.
+ */
+export interface ReconstructTriadOutcome {
+  readonly mode: ReconstructMode;
+  readonly reconstruction: ReconstructionV1 | null;
+  readonly codes: readonly ReconstructionFailureCode[];
+  /**
+   * Set only in mode C: the explicit statement that old semantic context is lost
+   * (TRIAD_RESILIENCE — "C states its loss of old semantic context").
+   */
+  readonly semanticLossStated: boolean;
+}
+
+/**
+ * Registered CLO conformance ID range (CLO-001..030). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`.
+ */
+export const CLO_IDS: readonly string[] = Array.from(
+  { length: 30 },
+  (_v, i) => `CLO-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Registered REC conformance ID range (REC-001..030). */
+export const REC_IDS: readonly string[] = Array.from(
+  { length: 30 },
+  (_v, i) => `REC-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named VC4C conformance assertions (the sprint's headline rows). */
+export const RECONSTRUCT_NAMED_IDS = [
+  "CLO-TRANSITIVE-001",
+  "CLO-CONTRA-002",
+  "REC-ORDER-003",
+] as const;
+
+export type { ShardRange };