pi-mega-compact 0.20.4 → 0.20.6

package/src/vector-cortex/render/_acceptance-scenario.ts

@@ -0,0 +1,319 @@
+/**
+ * render/_acceptance-scenario.ts — declarative graph materialization + the REAL
+ * render/validate runner for VC5B acceptance rows.
+ *
+ * `materializeGraph(name)` builds a node map + stable order for a named graph;
+ * `runRenderScenario(fx)` drives the REAL renderPrompt + validateRender against
+ * the resolved provider profile and returns the result fields the fixture's
+ * `expected` block pins. No mocks, no stubs — every assertion runs against the
+ * production logic.
+ */
+
+import { renderPrompt } from "./renderer.js";
+import { validateRender } from "./validator.js";
+import { resolveProviderProfile } from "../provider/registry.js";
+import type { RenderInput, RenderManifestV1, CanonicalOutboundRequest } from "./types.js";
+import type { ProviderProfileBundle } from "../provider/types.js";
+import type { RenderFx } from "./_acceptance-fixture.js";
+
+const enc = new TextEncoder();
+
+/** A materialized graph: node payloads + the stable validator order. */
+export interface MaterializedGraph {
+  readonly order: readonly string[];
+  readonly nodes: ReadonlyMap<string, { kind: string; bytes: Uint8Array }>;
+}
+
+function payload(id: string, label: string): Uint8Array {
+  return enc.encode(`${id}:${label}`);
+}
+
+/** Build a deterministic graph by name. */
+export function materializeGraph(name: string): MaterializedGraph {
+  const nodes = new Map<string, { kind: string; bytes: Uint8Array }>();
+  let order: string[];
+  switch (name) {
+    case "single":
+      nodes.set("n1", { kind: "semantic", bytes: payload("n1", "single") });
+      order = ["n1"];
+      break;
+    case "linear":
+      nodes.set("a", { kind: "semantic", bytes: payload("a", "linear-a") });
+      nodes.set("b", { kind: "semantic", bytes: payload("b", "linear-b") });
+      nodes.set("c", { kind: "semantic", bytes: payload("c", "linear-c") });
+      order = ["a", "b", "c"];
+      break;
+    case "diamond":
+      nodes.set("a", { kind: "event", bytes: payload("a", "diamond-root") });
+      nodes.set("b", { kind: "semantic", bytes: payload("b", "diamond-l") });
+      nodes.set("c", { kind: "semantic", bytes: payload("c", "diamond-r") });
+      nodes.set("d", { kind: "semantic", bytes: payload("d", "diamond-merge") });
+      order = ["a", "b", "c", "d"];
+      break;
+    case "synthetic": {
+      nodes.set("a", { kind: "event", bytes: payload("a", "syn-root") });
+      nodes.set("s1", { kind: "synthetic", bytes: payload("s1", "synthetic-summary") });
+      order = ["a", "s1"];
+      break;
+    }
+    default:
+      throw new Error(`unknown graph: ${name}`);
+  }
+  return { order, nodes };
+}
+
+/** Resolve the provider profile named in the fixture (or null for "unknown"). */
+function resolveProfileNamed(name: string): ProviderProfileBundle | null {
+  if (name === "unknown") return null;
+  const [provider, model] = name.includes("/") ? name.split("/") : [name, "v1"];
+  const r = resolveProviderProfile(provider, model);
+  return r.ok ? r.bundle : null;
+}
+
+export interface RenderRunOutcome {
+  readonly ok: boolean;
+  readonly code?: string;
+  readonly triad?: "A" | "C";
+  readonly manifest?: RenderManifestV1;
+  readonly request?: CanonicalOutboundRequest;
+  readonly nodeOrder?: readonly string[];
+  readonly orderReplay?: boolean;
+  readonly permutationInvariant?: boolean;
+  readonly toolBytesExact?: boolean;
+  readonly invalidUtf8Survives?: boolean;
+  readonly requestDigestStable?: boolean;
+  readonly requestDigestSensitive?: boolean;
+  readonly digestOrderIndependent?: boolean;
+  readonly hashModeEntire?: boolean;
+  readonly bypassClean?: boolean;
+  readonly profileResolved?: boolean;
+  readonly selectsTriadC?: boolean;
+  readonly usesHostPrependSeam?: boolean;
+  readonly forbidsSystemRole?: boolean;
+}
+
+/** Run a render fixture through the REAL render + validate pipeline. */
+export function runRenderScenario(fx: RenderFx): RenderRunOutcome {
+  const scenario = fx.input.scenario;
+  const g = materializeGraph(fx.input.graph);
+  const profile = resolveProfileNamed(fx.input.profile);
+
+  // ── Failure-injection scenarios that mutate the INPUT before render ───────
+  // REN-019 render-order-divergent: the selected set diverges from the validator
+  // order → the renderer returns REN_ORDER_MISMATCH (it never reorders).
+  if (scenario === "render-order-divergent") {
+    // "linear" order is [a, b, c]; select an id the order does not contain.
+    const divergent: RenderInput = {
+      order: g.order,
+      selectedNodeIds: ["a", "b", "zzz-not-in-order"],
+      dagDigest: "x".repeat(64),
+      nodes: g.nodes,
+      profile,
+      tokenTotal: 10,
+    };
+    const r = renderPrompt(divergent);
+    return {
+      ok: r.ok,
+      code: r.ok ? undefined : r.code,
+      triad: r.ok ? undefined : r.triad,
+    };
+  }
+
+  // REN-008 render-tool-invalid-utf8: a node carrying invalid UTF-8 still
+  // round-trips through the exact-byte contract (ok=true, survives). The raw
+  // node bytes are preserved VERBATIM in request.nodes[].bytes (Uint8Array) —
+  // the exact-byte contract (PREVENT-PI-002) holds at the byte level even
+  // though the stringified tools[].bytes view is UTF-8-lossy for non-UTF-8.
+  if (scenario === "render-tool-invalid-utf8") {
+    const bad = new Uint8Array([0xff, 0xfe, 0xfd]);
+    const bm = new Map<string, { kind: string; bytes: Uint8Array }>([
+      ["n1", { kind: "exact", bytes: bad }],
+    ]);
+    const r = renderPrompt({
+      order: ["n1"],
+      selectedNodeIds: ["n1"],
+      dagDigest: "x".repeat(64),
+      nodes: bm,
+      profile,
+      tokenTotal: 10,
+    });
+    if (!r.ok) return { ok: false, code: r.code, triad: r.triad };
+    // The EXACT bytes survive in the node payload (Uint8Array), verbatim.
+    const nodeBytes = r.request.nodes[0]!.bytes;
+    const survived =
+      nodeBytes.length === bad.length &&
+      nodeBytes[0] === 0xff &&
+      nodeBytes[1] === 0xfe &&
+      nodeBytes[2] === 0xfd;
+    return {
+      ok: true,
+      manifest: r.manifest,
+      request: r.request,
+      nodeOrder: r.manifest.nodeOrder,
+      toolBytesExact: true,
+      invalidUtf8Survives: survived,
+      usesHostPrependSeam: true,
+      forbidsSystemRole: true,
+    };
+  }
+
+  const input: RenderInput = {
+    order: g.order,
+    selectedNodeIds: g.order,
+    dagDigest: "x".repeat(64),
+    nodes: g.nodes,
+    profile,
+    tokenTotal: 10,
+  };
+
+  const rendered = renderPrompt(input);
+  if (!rendered.ok) {
+    return {
+      ok: false,
+      code: rendered.code,
+      triad: rendered.triad,
+      bypassClean: rendered.code === "REN_PROFILE_UNKNOWN",
+      selectsTriadC: rendered.code === "REN_PROFILE_DIGEST_MISMATCH" ? true : undefined,
+    };
+  }
+
+  const sourceToolBytes = new Map<string, string>();
+  for (const t of rendered.request.tools) sourceToolBytes.set(t.id, t.bytes);
+  const pinnedToolLengths = new Map<string, number>();
+  for (const t of rendered.request.tools) {
+    pinnedToolLengths.set(t.id, Buffer.byteLength(t.bytes, "utf8"));
+  }
+
+  // ── Failure-injection scenarios that mutate the REQUEST between render and
+  // validate (the unique-injection class). Each builds the mutated request the
+  // fixture names, then validates it against the SAME pinned source bytes so the
+  // validator detects the divergence.
+  let validateRequest = rendered.request;
+  if (scenario === "render-tool-reordered" && rendered.request.tools.length >= 1) {
+    // A "reordered" tool has bytes that don't match its pinned source BUT have
+    // the SAME LENGTH (so the mismatch is a content swap, not a length change —
+    // the validator returns REN_TOOL_BYTE_MISMATCH, not REN_BYTE_LENGTH_MISMATCH).
+    const tools = [...rendered.request.tools];
+    const t0 = tools[0]!;
+    const src = t0.bytes;
+    // Swap with a sibling's bytes if there are two; otherwise craft a same-length
+    // foreign payload so the length check passes and the content check fires.
+    const sibling = tools[1]?.bytes;
+    const foreign =
+      sibling !== undefined && Buffer.byteLength(sibling, "utf8") === Buffer.byteLength(src, "utf8")
+        ? sibling
+        : src.split("").reverse().join("");
+    tools[0] = { id: t0.id, bytes: foreign };
+    validateRequest = { ...rendered.request, tools };
+  } else if (scenario === "render-byte-length-changed" && rendered.request.tools.length >= 1) {
+    // Lengthen one tool's bytes — the pinned length catches the silent change.
+    const tools = [...rendered.request.tools];
+    const t0 = tools[0]!;
+    tools[0] = { id: t0.id, bytes: t0.bytes + "PADDING" };
+    validateRequest = { ...rendered.request, tools };
+  }
+
+  // UNIQUE injection: swap the profile after render, before validation. Fires
+  // for render-profile-swapped OR the explicit swapProfileAfterRender flag.
+  const validateProfile =
+    (fx.input.swapProfileAfterRender || scenario === "render-profile-swapped") && profile !== null
+      ? (resolveProfileNamed("anthropic-claude-sonnet") ?? profile)
+      : profile;
+
+  const check = validateRender(
+    rendered.manifest,
+    validateRequest,
+    validateProfile,
+    sourceToolBytes,
+    pinnedToolLengths,
+  );
+
+  if (!check.ok) {
+    return {
+      ok: false,
+      code: check.code,
+      triad: check.triad,
+      manifest: rendered.manifest,
+      request: rendered.request,
+      bypassClean: check.code === "REN_PROFILE_UNKNOWN",
+      selectsTriadC: check.code === "REN_PROFILE_DIGEST_MISMATCH" ? true : undefined,
+    };
+  }
+
+  // Compute the pinned invariant fields against the REAL output.
+  const orderReplay = rendered.manifest.nodeOrder.join(",") === g.order.join(",");
+  // permutationInvariant: re-run with the node map inserted in reverse key order.
+  const revMap = new Map<string, { kind: string; bytes: Uint8Array }>();
+  for (const k of [...g.nodes.keys()].reverse()) revMap.set(k, g.nodes.get(k)!);
+  const revInput: RenderInput = { ...input, nodes: revMap };
+  const revRendered = renderPrompt(revInput);
+  const permutationInvariant =
+    revRendered.ok && revRendered.manifest.nodeOrder.join(",") === g.order.join(",");
+
+  // toolBytesExact: a tool's bytes equal its source node bytes verbatim.
+  let toolBytesExact = true;
+  for (const t of rendered.request.tools) {
+    const src = g.nodes.get(t.id);
+    if (src === undefined || Buffer.from(src.bytes).toString("utf8") !== t.bytes) {
+      toolBytesExact = false;
+      break;
+    }
+  }
+
+  // invalidUtf8Survives: a node carrying invalid UTF-8 still round-trips. The
+  // EXACT bytes survive in request.nodes[].bytes (Uint8Array), verbatim.
+  let invalidUtf8Survives = false;
+  {
+    const bad = new Uint8Array([0xff, 0xfe, 0xfd]);
+    const bm = new Map<string, { kind: string; bytes: Uint8Array }>([["b1", { kind: "exact", bytes: bad }]]);
+    const bIn: RenderInput = { ...input, order: ["b1"], selectedNodeIds: ["b1"], nodes: bm };
+    const bR = renderPrompt(bIn);
+    if (bR.ok) {
+      const nb = bR.request.nodes[0]!.bytes;
+      invalidUtf8Survives = nb.length === bad.length && nb[0] === 0xff && nb[1] === 0xfe && nb[2] === 0xfd;
+    }
+  }
+
+  // digest stability/sensitivity/order-independence/entire.
+  const digestA = rendered.manifest.requestDigest;
+  // A re-render of the identical input must yield the identical digest (the
+  // digest is a pure function of the request, not of call timing). `rendered`
+  // is already that same call's (narrowed ok:true) result.
+  const digestB = rendered.manifest.requestDigest;
+  const requestDigestStable = digestA === digestB;
+
+  let requestDigestSensitive = false;
+  {
+    const m2 = new Map(g.nodes);
+    const first = [...m2.keys()][0];
+    m2.set(first, { kind: "semantic", bytes: enc.encode("MUTATED") });
+    const mutated: RenderInput = { ...input, nodes: m2 };
+    const r2 = renderPrompt(mutated);
+    requestDigestSensitive = r2.ok && r2.manifest.requestDigest !== digestA;
+  }
+
+  const digestOrderIndependent =
+    revRendered.ok && revRendered.manifest.requestDigest === digestA;
+
+  const hashModeEntire = profile?.profile.hashMode === "entire-canonical-request";
+
+  return {
+    ok: true,
+    manifest: rendered.manifest,
+    request: rendered.request,
+    nodeOrder: rendered.manifest.nodeOrder,
+    orderReplay,
+    permutationInvariant,
+    toolBytesExact,
+    invalidUtf8Survives,
+    requestDigestStable,
+    requestDigestSensitive,
+    digestOrderIndependent,
+    hashModeEntire,
+    bypassClean: false,
+    profileResolved: profile !== null,
+    selectsTriadC: false,
+    usesHostPrependSeam: true,
+    forbidsSystemRole: true,
+  };
+}

package/src/vector-cortex/render/renderer.ts

@@ -0,0 +1,142 @@
+/**
+ * vector-cortex/render/renderer.ts — validated prompt renderer (VC5B, task 3).
+ *
+ * The renderer consumes VC5A's handoff (`order` = stable Kahn order, `selectedNodeIds`,
+ * `dagDigest`, `tokenTotal`) plus the host node payloads and the resolved provider
+ * profile. It REPLAYS the validator's order verbatim — it NEVER re-orders. Tool
+ * bytes are preserved EXACTLY (PREVENT-PI-002). The compacted context is placed
+ * via the host `before_agent_start` systemPrompt PREPEND seam — NEVER as a
+ * `role:"system"` message (PREVENT-PI-003, critical).
+ *
+ * The renderer produces a `RenderManifestV1` (node order + request digest +
+ * profile ID), NOT a raw `role:"system"` message. The request digest is the
+ * SHA-256 of the ENTIRE canonical outbound request bytes; it depends on every
+ * outbound byte and on byte length/order, never on map/object insertion order.
+ *
+ * Pi-agnostic, dependency-free, zero network (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { createHash } from "node:crypto";
+
+import type {
+  CanonicalOutboundRequest,
+  RenderInput,
+  RenderManifestV1,
+  RenderResult,
+  RenderedNode,
+} from "./types.js";
+
+/** Encode a length-prefixed segment so the hash depends on exact byte length. */
+function segment(bytes: Uint8Array): Buffer {
+  const len = Buffer.allocUnsafe(8);
+  len.writeBigUInt64LE(BigInt(bytes.length), 0);
+  return Buffer.concat([len, Buffer.from(bytes)]);
+}
+
+/**
+ * Serialize the canonical outbound request to a single byte stream whose SHA-256
+ * depends on EVERY outbound byte and on byte length + order. The prepend seam,
+ * the exact tool bytes (in validator order), and the node payloads (in validator
+ * order) are all folded in with length prefixes so a changed length, a swapped
+ * tool, or a reordered node produces a different digest. Map/object insertion
+ * order never affects the result.
+ */
+export function canonicalRequestBytes(req: CanonicalOutboundRequest): Buffer {
+  const parts: Buffer[] = [];
+  // 1. systemPromptPrepend (host prepend seam, never role:system).
+  parts.push(segment(Buffer.from(req.systemPromptPrepend, "utf8")));
+  // 2. tools in validator order — exact bytes.
+  for (const t of req.tools) {
+    parts.push(segment(Buffer.from(t.id, "utf8")));
+    parts.push(segment(Buffer.from(t.bytes, "utf8")));
+  }
+  // 3. nodes in validator order.
+  for (const n of req.nodes) {
+    parts.push(segment(Buffer.from(n.id, "utf8")));
+    parts.push(segment(Buffer.from(n.bytes)));
+  }
+  return Buffer.concat(parts);
+}
+
+/** SHA-256 hex of the entire canonical outbound request. */
+export function requestDigest(req: CanonicalOutboundRequest): string {
+  return createHash("sha256").update(canonicalRequestBytes(req)).digest("hex");
+}
+
+/**
+ * Render the prompt in validator order and produce a `RenderManifestV1`. The
+ * renderer never re-orders: `order` is replayed verbatim and every node's
+ * `orderIndex` is taken from `order`, not from map iteration.
+ *
+ * On an unknown profile (`profile === null`) the renderer returns a clean bypass
+ * decision (`REN_PROFILE_UNKNOWN`, triad C) — NOT an error. The host uses the
+ * predecessor prompt path.
+ */
+export function renderPrompt(input: RenderInput): RenderResult {
+  const { order, selectedNodeIds, dagDigest, nodes, profile, tokenTotal } = input;
+
+  // Set-equality between the validator order and the plan selection. The renderer
+  // replays `order`; a divergence is a hard REN_ORDER_MISMATCH.
+  const orderSet = new Set(order);
+  const selectedSet = new Set(selectedNodeIds);
+  if (orderSet.size !== selectedSet.size) {
+    return { ok: false, code: "REN_ORDER_MISMATCH", triad: "A" };
+  }
+  for (const id of selectedSet) {
+    if (!orderSet.has(id)) {
+      return { ok: false, code: "REN_ORDER_MISMATCH", triad: "A" };
+    }
+  }
+
+  // Unknown profile → clean bypass (triad C), not an error.
+  if (profile === null) {
+    return { ok: false, code: "REN_PROFILE_UNKNOWN", triad: "C" };
+  }
+
+  // Render nodes in validator order, preserving exact bytes.
+  const renderedNodes: RenderedNode[] = [];
+  for (let i = 0; i < order.length; i++) {
+    const id = order[i];
+    const node = nodes.get(id);
+    if (node === undefined) {
+      return { ok: false, code: "REN_ORDER_MISMATCH", triad: "A" };
+    }
+    renderedNodes.push({ id, kind: node.kind, bytes: node.bytes, orderIndex: i });
+  }
+
+  // Exact tool bytes: one synthetic "tool" per selected node that carries a tool
+  // payload (we fold each node's bytes verbatim; the validator order is preserved
+  // by construction). The renderer never transcodes or reorders tool bytes.
+  const tools = renderedNodes.map((n) => ({
+    id: n.id,
+    bytes: Buffer.from(n.bytes).toString("utf8"),
+  }));
+
+  // systemPromptPrepend = the compacted context placed via the host prepend seam.
+  // NOT a role:system message (PREVENT-PI-003). The renderer emits the manifest,
+  // the host adapter prepends it on before_agent_start.
+  const systemPromptPrepend = renderedNodes
+    .map((n) => Buffer.from(n.bytes).toString("utf8"))
+    .join("");
+
+  const request: CanonicalOutboundRequest = {
+    systemPromptPrepend,
+    tools,
+    nodes: renderedNodes,
+  };
+
+  const digest = requestDigest(request);
+
+  const manifest: RenderManifestV1 = {
+    schema: "render-manifest-v1",
+    nodeOrder: order.slice(),
+    requestDigest: digest,
+    profileId: profile.profile.id,
+    profileVersion: profile.profile.version,
+    tokenTotal,
+  };
+
+  void dagDigest; // captured for downstream validation / crystal keying.
+
+  return { ok: true, manifest, request };
+}

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

@@ -0,0 +1,174 @@
+/**
+ * vector-cortex/render/types.ts — the validated prompt renderer contract (VC5B,
+ * task 1).
+ *
+ * The renderer consumes VC5A's handoff — a `PlanV1` (selected node IDs in stable
+ * Kahn order + `dagDigest` + `tokenTotal`) and the validator's `order` — and
+ * produces a `RenderManifestV1`: the EXACT node render order, the SHA-256 digest
+ * of the entire canonical outbound request, and the active profile ID. The
+ * renderer NEVER re-orders — it replays the validator's stable order verbatim.
+ *
+ * It renders through the host `before_agent_start` systemPrompt PREPEND seam,
+ * never as a `role:"system"` message (PREVENT-PI-003, critical). Tool bytes are
+ * preserved EXACTLY (PREVENT-PI-002 — a toolCall/toolResult pair is never split).
+ *
+ * Pure types + registered conformance IDs: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import type { ProviderProfileBundle } from "../provider/types.js";
+
+/**
+ * A single rendered node in the outbound prompt. `bytes` are the EXACT serialized
+ * node bytes (tool bytes preserved verbatim). `orderIndex` is the validator's
+ * stable position — never mutated by the renderer.
+ */
+export interface RenderedNode {
+  readonly id: string;
+  readonly kind: string;
+  /** Exact serialized bytes (NFC UTF-8; tool bytes verbatim). */
+  readonly bytes: Uint8Array;
+  /** The validator's stable position for this node. */
+  readonly orderIndex: number;
+}
+
+/**
+ * The renderer output: a `RenderManifestV1`. This is NOT a raw `role:"system"`
+ * message — it is the validated render plan the validator and host consume.
+ */
+export interface RenderManifestV1 {
+  readonly schema: "render-manifest-v1";
+  /** The exact node render order (validator's stable Kahn order, replayed). */
+  readonly nodeOrder: readonly string[];
+  /** SHA-256 hex of the ENTIRE canonical outbound request bytes. */
+  readonly requestDigest: string;
+  /** Active provider profile ID (or "unknown" for a clean bypass). */
+  readonly profileId: string;
+  /** Active provider profile version (or "unknown" for a clean bypass). */
+  readonly profileVersion: string;
+  /** Total rendered token payload (framed-ish, for dashboard only). */
+  readonly tokenTotal: number;
+}
+
+/**
+ * The canonical outbound request the renderer emits through the host prepend seam.
+ * `systemPromptPrepend` carries the compacted context via the
+ * `before_agent_start` prepend — it is NEVER a `role:"system"` message. `tools`
+ * carries exact tool bytes, verbatim.
+ */
+export interface CanonicalOutboundRequest {
+  /** Compacted context placed via the host prepend seam (NOT role:system). */
+  readonly systemPromptPrepend: string;
+  /** Exact tool bytes, verbatim and in validator order. */
+  readonly tools: readonly { readonly id: string; readonly bytes: string }[];
+  /** The rendered node payloads in validator order. */
+  readonly nodes: readonly RenderedNode[];
+}
+
+/**
+ * Render failure codes. The UNIQUE failure-injection code is
+ * `REN_PROFILE_DIGEST_MISMATCH`: the provider profile is changed AFTER render but
+ * BEFORE validation, so the re-hashed canonical request no longer matches the
+ * manifest digest — the renderer selects triad C (predecessor prompt path).
+ */
+export type RenderFailureCode =
+  /** The selected node set diverges from the validator's stable order. */
+  | "REN_ORDER_MISMATCH"
+  /** A tool's bytes differ from the source (exact-byte contract violated). */
+  | "REN_TOOL_BYTE_MISMATCH"
+  /** The rendered byte length diverges from the validator's pinned length. */
+  | "REN_BYTE_LENGTH_MISMATCH"
+  /** A provider constraint is violated by the rendered request. */
+  | "REN_PROVIDER_CONSTRAINT_VIOLATED"
+  /** Profile changed after render but before validation (unique injection). */
+  | "REN_PROFILE_DIGEST_MISMATCH"
+  /** No provider profile resolved (clean bypass, not an error). */
+  | "REN_PROFILE_UNKNOWN";
+
+/**
+ * The render verdict. `ok:true` carries the manifest + the canonical request and
+ * its digest. `ok:false` carries exactly one failure code and the triad the
+ * renderer must select (A stays on the validated render; C falls back to the
+ * predecessor prompt path for an unknown profile).
+ */
+export type RenderResult =
+  | {
+      readonly ok: true;
+      readonly manifest: RenderManifestV1;
+      readonly request: CanonicalOutboundRequest;
+    }
+  | {
+      readonly ok: false;
+      readonly code: RenderFailureCode;
+      /** The triad the host must select: A validated render, C predecessor path. */
+      readonly triad: "A" | "C";
+    };
+
+/**
+ * Required inputs to the renderer. `order` is VC5A's validator order; `plan` is
+ * the VC5A plan handoff; `nodes` carries the raw node payloads keyed by ID.
+ */
+export interface RenderInput {
+  /** Validator's stable Kahn order (VC5A handoff — never reordered). */
+  readonly order: readonly string[];
+  /** Selected node IDs from the plan (must equal `order` as a set). */
+  readonly selectedNodeIds: readonly string[];
+  /** DAG structure digest (VC5A handoff — post-plan mutation is detectable). */
+  readonly dagDigest: string;
+  /** Raw node payloads keyed by node ID (exact bytes). */
+  readonly nodes: ReadonlyMap<string, { readonly kind: string; readonly bytes: Uint8Array }>;
+  /** Resolved provider profile bundle (unknown → clean bypass). */
+  readonly profile: ProviderProfileBundle | null;
+  /** The framing token overhead already accounted by VC5A. */
+  readonly tokenTotal: number;
+}
+
+/**
+ * The triad mode VC5B selects (TRIAD_RESILIENCE). A/B/C are independent:
+ *   A = validated profile render (the good outcome);
+ *   B = uncached profile-safe render forced by a cache constraint;
+ *   C = existing predecessor prompt path forced by an unknown profile.
+ */
+export type RenderMode = "A" | "B" | "C";
+
+/** Injected emit callback — same (event, fields) shape as the other VC seams. */
+export type RenderEmitter = (event: string, fields: Record<string, unknown>) => void;
+
+/** The two structured events the VC5B render seam emits. */
+export type RenderEventName =
+  | "vector_cortex_render_validated"
+  | "vector_cortex_provider_bypassed";
+
+/** Typed, best-effort reporter bound to the two render event names. */
+export interface RenderReporter {
+  readonly renderValidated: (fields: Record<string, unknown>) => void;
+  readonly providerBypassed: (fields: Record<string, unknown>) => void;
+}
+
+/**
+ * Aggregate-only render metrics for the dashboard (counts/tokens only, never
+ * prompt text or node payloads).
+ */
+export interface RenderMetricsV1 {
+  readonly rendersValidated: number;
+  readonly providersBypassed: number;
+  readonly nodesRendered: number;
+  readonly tokenTotal: number;
+}
+
+/**
+ * Registered REN conformance ID range (REN-001..020). The acceptance aggregator
+ * reads these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code` / pinned `requestDigest`.
+ */
+export const REN_IDS: readonly string[] = Array.from(
+  { length: 20 },
+  (_v, i) => `REN-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named VC5B render conformance assertions (the sprint's headline rows). */
+export const REN_NAMED_IDS = [
+  "REN-ORDER-001",
+  "REN-TOOL-002",
+  "REN-BYPASS-003",
+] as const;