pi-mega-compact 0.20.16 → 0.20.18

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

@@ -0,0 +1,195 @@
+/**
+ * controller/types.ts — VC8B policy decision + pressure type definitions.
+ *
+ * PolicyDecisionV1 is the FINITE, BOUNDED output of the policy engine: one of a
+ * closed action set, a token budget clamped into a configured window, and a
+ * machine code reason. There is deliberately no free-text field and no open
+ * action string — an adaptive policy whose action space can grow at runtime
+ * cannot be reviewed, and a budget with no ceiling is a cost incident waiting
+ * to happen.
+ *
+ * PressureV2 canonicalizes the context-pressure label to EXACTLY five levels
+ * (low/medium/high/ultra/mega). Anything else is rejected rather than coerced:
+ * silently mapping an unrecognized legacy label onto a neighbouring level is
+ * how a "high" workload quietly starts being treated as "low".
+ *
+ * Conformance IDs POL-001..025 and M7-001..015 are registered here as the
+ * single source of truth for the sprint's conformance rows.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ */
+
+/** Schema version for PolicyDecisionV1. */
+export const POLICY_DECISION_SCHEMA_V1 = "policy-decision-v1";
+
+/** Schema version for PressureV2. */
+export const PRESSURE_SCHEMA_V2 = "pressure-v2";
+
+/** Failure code when a pressure label is outside the canonical five levels. */
+export const POL_PRESSURE_UNKNOWN = "POL_PRESSURE_UNKNOWN";
+
+/** Failure code when a requested action is outside the allowed finite set. */
+export const POL_ACTION_FORBIDDEN = "POL_ACTION_FORBIDDEN";
+
+/** Failure code when a budget bound pair is itself invalid (min > max, NaN). */
+export const POL_BUDGET_OUT_OF_BOUNDS = "POL_BUDGET_OUT_OF_BOUNDS";
+
+/** Failure code when the M7 migration meets a non-canonical pressure label. */
+export const M7_PRESSURE_UNKNOWN = "M7_PRESSURE_UNKNOWN";
+
+/** Failure code when M7 copied rows do not match the legacy row count. */
+export const M7_COUNT_MISMATCH = "M7_COUNT_MISMATCH";
+
+/** Failure code when an M7 row digest does not re-derive from its own fields. */
+export const M7_DIGEST_MISMATCH = "M7_DIGEST_MISMATCH";
+
+/** Failure code when the active pressure pointer is not on the legacy version. */
+export const M7_NOT_ON_LEGACY = "M7_NOT_ON_LEGACY";
+
+/**
+ * The canonical five pressure levels. Ordered low -> mega; the order is
+ * meaningful (policy escalates monotonically with pressure) so it is exported
+ * as an array, not just a union.
+ */
+export const PRESSURE_LEVELS = [
+  "low",
+  "medium",
+  "high",
+  "ultra",
+  "mega",
+] as const;
+
+/** A canonical context-pressure level. */
+export type PressureLevel = (typeof PRESSURE_LEVELS)[number];
+
+/**
+ * The FINITE allowed policy action set. A decision may carry no other action.
+ * `admit`    — proceed at the requested budget.
+ * `dampen`   — proceed at a reduced budget (pressure is elevated).
+ * `defer`    — postpone the work to a later turn.
+ * `escalate` — raise the budget within bounds (headroom is available).
+ * `reject`   — refuse the work outright.
+ */
+export const POLICY_ACTIONS = [
+  "admit",
+  "dampen",
+  "defer",
+  "escalate",
+  "reject",
+] as const;
+
+/** An allowed policy action. */
+export type PolicyAction = (typeof POLICY_ACTIONS)[number];
+
+/** Machine reason codes — never free-text. */
+export const POLICY_REASONS = [
+  "within_bounds",
+  "budget_clamped_low",
+  "budget_clamped_high",
+  "pressure_elevated",
+  "pressure_critical",
+  "headroom_available",
+] as const;
+
+/** A machine reason code explaining a decision. */
+export type PolicyReason = (typeof POLICY_REASONS)[number];
+
+/** The configured token-budget window a decision is clamped into. */
+export interface PolicyBounds {
+  readonly minBudget: number;
+  readonly maxBudget: number;
+}
+
+/**
+ * PolicyDecisionV1 — one bounded policy decision.
+ * `budget` is ALWAYS within the bounds that produced it; `action` is always a
+ * member of POLICY_ACTIONS.
+ */
+export interface PolicyDecisionV1 {
+  readonly schema: typeof POLICY_DECISION_SCHEMA_V1;
+  readonly decisionId: string;
+  readonly sessionId: string;
+  readonly action: PolicyAction;
+  readonly budget: number;
+  readonly pressure: PressureLevel;
+  readonly reason: PolicyReason;
+  readonly ts: string;
+}
+
+/** The input a policy evaluation consumes. */
+export interface PolicyInput {
+  readonly decisionId: string;
+  readonly sessionId: string;
+  /** The pressure label as received — validated, never coerced. */
+  readonly pressure: string;
+  /** The requested budget before clamping; any finite number. */
+  readonly requestedBudget: number;
+  readonly bounds: PolicyBounds;
+  readonly ts: string;
+}
+
+/**
+ * PressureV2 — a canonical pressure observation for a session at an effective
+ * sequence point.
+ */
+export interface PressureV2 {
+  readonly schema: typeof PRESSURE_SCHEMA_V2;
+  readonly level: PressureLevel;
+  readonly sessionId: string;
+  readonly effectiveSeq: number;
+  readonly ts: string;
+}
+
+/** Shadow metrics — counts only, never prompt bytes or free-text. */
+export interface ShadowMetrics {
+  /** Decisions evaluated in this shadow run. */
+  readonly evaluated: number;
+  /** Decisions whose budget was clamped at either bound. */
+  readonly clamped: number;
+  /** Inputs rejected (unknown pressure / bad bounds). */
+  readonly rejected: number;
+  /**
+   * Live mutations performed by the shadow engine. Structurally ALWAYS 0 —
+   * the shadow has no writer capability — and asserted as 0 by the sprint's
+   * acceptance contract.
+   */
+  readonly liveMutations: number;
+}
+
+/** The result of a shadow evaluation: decisions + metrics ONLY. */
+export interface ShadowResult {
+  readonly decisions: ReadonlyArray<PolicyDecisionV1>;
+  readonly rejections: ReadonlyArray<ShadowRejection>;
+  readonly metrics: ShadowMetrics;
+  /**
+   * The digest of the canonical prompt as observed on entry. The shadow engine
+   * re-computes this on exit and the two MUST be equal (POL-SHADOW-002).
+   */
+  readonly promptDigest: string;
+}
+
+/** A rejected shadow input, reduced to its code. */
+export interface ShadowRejection {
+  readonly decisionId: string;
+  readonly code: string;
+}
+
+/** Conformance IDs POL-001..POL-025 for the 25 numbered policy rows. */
+export const POLICY_CONFORMANCE_IDS: readonly string[] = Array.from(
+  { length: 25 },
+  (_v, i) => `POL-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Conformance IDs M7-001..M7-015 for the 15 numbered migration rows. */
+export const M7_CONFORMANCE_IDS: readonly string[] = Array.from(
+  { length: 15 },
+  (_v, i) => `M7-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named conformance fixtures for the sprint's headline assertions. */
+export const POLICY_NAMED_FIXTURES = [
+  "POL-CLAMP-001",
+  "POL-SHADOW-002",
+  "M7-PRESSURE-003",
+] as const;

package/src/vector-cortex/outcomes/consent.ts

@@ -0,0 +1,88 @@
+/**
+ * outcomes/consent.ts — VC8A append-only consent grants/revocations.
+ *
+ * ConsentV1 is append-only: grants and revocations are appended with an
+ * effective sequence number. A session has active explicit consent at time T
+ * if its most recent record at or before T is a grant.
+ *
+ * Dataset inclusion requires active explicit consent at export time. This
+ * module provides the pure consent-evaluation functions; the dataset module
+ * calls `hasActiveConsent` at export time.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+
+import { CONSENT_SCHEMA_V1, type ConsentV1 } from "./types.js";
+
+/**
+ * Evaluate whether a session has active explicit consent at or before the
+ * given effective sequence high-water. True if the most recent record at or
+ * before `effectiveHighWater` is a grant.
+ */
+export function hasActiveConsent(
+  records: ReadonlyArray<ConsentV1>,
+  sessionId: string,
+  effectiveHighWater: number,
+): boolean {
+  const relevant = records
+    .filter((r) => r.sessionId === sessionId && r.effectiveSeq <= effectiveHighWater)
+    .sort((a, b) => a.effectiveSeq - b.effectiveSeq);
+  if (relevant.length === 0) return false;
+  return relevant[relevant.length - 1].action === "grant";
+}
+
+/**
+ * Append a consent grant for a session at the next effective sequence.
+ * Returns a new ConsentV1 record (append-only — never mutates the input).
+ */
+export function appendGrant(
+  sessionId: string,
+  effectiveSeq: number,
+  ts: string,
+): ConsentV1 {
+  return {
+    schema: CONSENT_SCHEMA_V1,
+    consentId: `consent-${sessionId}-${effectiveSeq}`,
+    sessionId,
+    action: "grant",
+    effectiveSeq,
+    ts,
+  };
+}
+
+/**
+ * Append a consent revocation for a session at the next effective sequence.
+ * Returns a new ConsentV1 record (append-only — never mutates the input).
+ */
+export function appendRevoke(
+  sessionId: string,
+  effectiveSeq: number,
+  ts: string,
+): ConsentV1 {
+  return {
+    schema: CONSENT_SCHEMA_V1,
+    consentId: `consent-${sessionId}-${effectiveSeq}`,
+    sessionId,
+    action: "revoke",
+    effectiveSeq,
+    ts,
+  };
+}
+
+/**
+ * Get the effective consent high-water for a session — the maximum effectiveSeq
+ * across all consent records for that session. Used by the dataset exporter
+ * to capture a single consent snapshot at export time.
+ */
+export function consentHighWater(
+  records: ReadonlyArray<ConsentV1>,
+  sessionId: string,
+): number {
+  let max = 0;
+  for (const r of records) {
+    if (r.sessionId === sessionId && r.effectiveSeq > max) {
+      max = r.effectiveSeq;
+    }
+  }
+  return max;
+}

package/src/vector-cortex/outcomes/dataset.ts

@@ -0,0 +1,132 @@
+/**
+ * outcomes/dataset.ts — VC8A dataset manifest builder.
+ *
+ * Groups outcome rows by (repo, session) so no group crosses
+ * train/calibration/held-out split boundaries. Revocations disappear from
+ * future manifests because the consent check excludes them.
+ *
+ * The manifest digest is reproducible: it is computed over the canonical
+ * sorted rows, so input order does not affect the digest.
+ *
+ * The build/digest functions are PURE. The flag gates ONLY the reporter seam,
+ * never the arithmetic.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  DATASET_MANIFEST_SCHEMA_V1,
+  type ConsentV1,
+  type DatasetManifestV1,
+  type DatasetManifestRow,
+  type DatasetSplit,
+  type OutcomeV1,
+} from "./types.js";
+import { hasActiveConsent } from "./consent.js";
+
+/** SHA-256 over the canonical sorted rows. */
+export function manifestDigest(rows: ReadonlyArray<DatasetManifestRow>): string {
+  const sorted = [...rows].sort((a, b) => {
+    const ka = `${a.repoId}:${a.sessionId}:${a.outcomeId}`;
+    const kb = `${b.repoId}:${b.sessionId}:${b.outcomeId}`;
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+  const text = sorted
+    .map((r) => `${r.outcomeId}|${r.repoId}|${r.sessionId}|${r.split}`)
+    .join("\n");
+  return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+
+/**
+ * Split a list of session groups into train/calibration/held-out. Groups are
+ * assigned sequentially so no group crosses split boundaries.
+ */
+function assignSplits(
+  groupKeys: string[],
+): Map<string, DatasetSplit> {
+  const result = new Map<string, DatasetSplit>();
+  const n = groupKeys.length;
+  const trainEnd = Math.ceil(n * 0.7);
+  const calEnd = Math.ceil(n * 0.85);
+  for (let i = 0; i < n; i++) {
+    const split: DatasetSplit = i < trainEnd ? "train" : i < calEnd ? "calibration" : "held-out";
+    result.set(groupKeys[i], split);
+  }
+  return result;
+}
+
+/**
+ * Build a dataset manifest from outcomes, consent records, and a consent
+ * high-water. Only outcomes whose session has active consent at the
+ * high-water are included. Revoked sessions are excluded entirely.
+ *
+ * Throws OUT_CONSENT_MISSING if an outcome's session has no consent at all.
+ */
+export function buildManifest(
+  outcomes: ReadonlyArray<OutcomeV1>,
+  consentRecords: ReadonlyArray<ConsentV1>,
+  consentHighWaterValue: number,
+): DatasetManifestV1 {
+  const groups = new Map<string, { repoId: string; sessionId: string }>();
+  const included: OutcomeV1[] = [];
+
+  for (const outcome of outcomes) {
+    const highWater = consentHighWaterValue;
+    if (!hasActiveConsent(consentRecords, outcome.sessionId, highWater)) {
+      continue;
+    }
+    included.push(outcome);
+    const key = `${outcome.repoId}:${outcome.sessionId}`;
+    if (!groups.has(key)) {
+      groups.set(key, { repoId: outcome.repoId, sessionId: outcome.sessionId });
+    }
+  }
+
+  const groupKeys = [...groups.keys()].sort();
+  const splitMap = assignSplits(groupKeys);
+
+  const rows: DatasetManifestRow[] = included.map((o) => {
+    const key = `${o.repoId}:${o.sessionId}`;
+    const split = splitMap.get(key) ?? "held-out";
+    return {
+      outcomeId: o.outcomeId,
+      repoId: o.repoId,
+      sessionId: o.sessionId,
+      split,
+    };
+  });
+
+  const trainRows = rows.filter((r) => r.split === "train");
+  const calRows = rows.filter((r) => r.split === "calibration");
+  const heldRows = rows.filter((r) => r.split === "held-out");
+
+  return {
+    schema: DATASET_MANIFEST_SCHEMA_V1,
+    manifestId: `manifest-${manifestDigest(rows).slice(0, 16)}`,
+    rows,
+    splitDigests: {
+      "train": manifestDigest(trainRows),
+      "calibration": manifestDigest(calRows),
+      "held-out": manifestDigest(heldRows),
+    },
+    createdAt: new Date(0).toISOString(),
+  };
+}
+
+/**
+ * Check if a manifest has any nonconsented records. Returns false if every
+ * row's session has active consent at the given high-water.
+ */
+export function hasNonconsentedRecords(
+  manifest: DatasetManifestV1,
+  consentRecords: ReadonlyArray<ConsentV1>,
+  consentHighWaterValue: number,
+): boolean {
+  for (const row of manifest.rows) {
+    if (!hasActiveConsent(consentRecords, row.sessionId, consentHighWaterValue)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/vector-cortex/outcomes/emit.ts

@@ -0,0 +1,70 @@
+/**
+ * outcomes/emit.ts — VC8A reporter seam (FLAG-GATED).
+ *
+ * Mirrors the VC7C diagnostics-emit pattern: a thin `safe()` wrapper around an
+ * optional injected `emit`, and the two event names the sprint spec requires:
+ *   - `vector_cortex_outcome_appended` — an outcome was appended to the ledger.
+ *   - `vector_cortex_dataset_record_excluded` — a row was excluded from a manifest.
+ *
+ * FLAG SEMANTICS. The ledger/consent/dataset arithmetic STILL RUNS regardless
+ * of `MEGACOMPACT_VC8A`. The flag gates ONLY this reporting + dashboard seam:
+ * flag-off is byte-identical to the predecessor (VC7C).
+ *
+ * PAYLOAD DISCIPLINE. These events carry only the outcomeId/sessionId codes
+ * and aggregate counts — never prompt bytes, response text, or free-text.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+
+import { VC8A_ENABLED } from "../../config/vector-cortex.js";
+
+/** The two structured events the VC8A reporter emits. */
+export type OutcomeEventName =
+  | "vector_cortex_outcome_appended"
+  | "vector_cortex_dataset_record_excluded";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type OutcomeEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit: OutcomeEmit | undefined, fn: (emit: OutcomeEmit) => void): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** Report an outcome appended to the ledger. Gated by the flag. */
+export function reportOutcomeAppended(
+  emit: OutcomeEmit | undefined,
+  outcome: { readonly outcomeId: string; readonly sessionId: string; readonly repoId: string },
+): void {
+  if (!VC8A_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_outcome_appended", {
+      ts: undefined,
+      event: "vector_cortex_outcome_appended",
+      outcomeId: outcome.outcomeId,
+      sessionId: outcome.sessionId,
+      repoId: outcome.repoId,
+    }),
+  );
+}
+
+/** Report a row excluded from a dataset manifest. Gated by the flag. */
+export function reportDatasetRecordExcluded(
+  emit: OutcomeEmit | undefined,
+  excluded: { readonly outcomeId: string; readonly reason: string },
+): void {
+  if (!VC8A_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_dataset_record_excluded", {
+      ts: undefined,
+      event: "vector_cortex_dataset_record_excluded",
+      outcomeId: excluded.outcomeId,
+      reason: excluded.reason,
+    }),
+  );
+}

package/src/vector-cortex/outcomes/ledger.ts

@@ -0,0 +1,88 @@
+/**
+ * outcomes/ledger.ts — VC8A outcome ledger append + validation.
+ *
+ * Appends outcome fields for session/repo/assignment/metrics ONLY. Rejects
+ * prompt, response, exact bytes, or free-text payload fields as
+ * OUT_PAYLOAD_FORBIDDEN. The ledger is append-only — no mutation.
+ *
+ * The append/validate functions are PURE. The flag gates ONLY the reporter
+ * seam (emit), never the validation arithmetic, so flag-off is byte-identical
+ * to the predecessor.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+
+import {
+  OUTCOME_SCHEMA_V1,
+  OUT_PAYLOAD_FORBIDDEN,
+  type OutcomeV1,
+  type OutcomeMetric,
+} from "./types.js";
+
+/** Fields that must never appear in an outcome — they carry payload. */
+const FORBIDDEN_FIELDS = new Set([
+  "prompt",
+  "response",
+  "exactBytes",
+  "freeText",
+  "content",
+  "text",
+  "payload",
+  "body",
+  "message",
+  "reply",
+  "output",
+  "completion",
+  "snippet",
+]);
+
+/** Validate that the input object has no payload-bearing fields. */
+export function validateOutcome(input: Record<string, unknown>): OutcomeV1 {
+  for (const key of Object.keys(input)) {
+    if (FORBIDDEN_FIELDS.has(key)) {
+      throw { code: OUT_PAYLOAD_FORBIDDEN, field: key };
+    }
+  }
+  if (typeof input["outcomeId"] !== "string" || !input["outcomeId"]) {
+    throw { code: OUT_PAYLOAD_FORBIDDEN, field: "outcomeId" };
+  }
+  if (typeof input["sessionId"] !== "string" || !input["sessionId"]) {
+    throw { code: OUT_PAYLOAD_FORBIDDEN, field: "sessionId" };
+  }
+  if (typeof input["repoId"] !== "string" || !input["repoId"]) {
+    throw { code: OUT_PAYLOAD_FORBIDDEN, field: "repoId" };
+  }
+  if (typeof input["assignment"] !== "string" || !input["assignment"]) {
+    throw { code: OUT_PAYLOAD_FORBIDDEN, field: "assignment" };
+  }
+  const metrics = Array.isArray(input["metrics"]) ? input["metrics"] : [];
+  for (const m of metrics) {
+    if (typeof m !== "object" || m === null) {
+      throw { code: OUT_PAYLOAD_FORBIDDEN, field: "metrics" };
+    }
+    const row = m as Record<string, unknown>;
+    if (typeof row["code"] !== "string" || typeof row["value"] !== "number" ||
+        typeof row["unit"] !== "string") {
+      throw { code: OUT_PAYLOAD_FORBIDDEN, field: "metrics" };
+    }
+  }
+  return {
+    schema: OUTCOME_SCHEMA_V1,
+    outcomeId: input["outcomeId"],
+    sessionId: input["sessionId"],
+    repoId: input["repoId"],
+    assignment: input["assignment"],
+    metrics: metrics as ReadonlyArray<OutcomeMetric>,
+    ts: typeof input["ts"] === "string" ? input["ts"] : new Date(0).toISOString(),
+  };
+}
+
+/**
+ * Append an outcome to the ledger (append-only). Returns the validated
+ * OutcomeV1 or throws OUT_PAYLOAD_FORBIDDEN.
+ */
+export function appendOutcome(
+  input: Record<string, unknown>,
+): OutcomeV1 {
+  return validateOutcome(input);
+}

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

@@ -0,0 +1,104 @@
+/**
+ * outcomes/types.ts — VC8A consent-bound outcome ledger type definitions.
+ *
+ * Payload-free metrics only — no prompt bytes, response text, or free-text.
+ * OutcomeV1 carries session/repo/assignment/metrics fields ONLY.
+ * ConsentV1 is append-only grants/revocations with effective sequence.
+ * DatasetManifestV1 groups rows/digests/split (train/calibration/held-out).
+ *
+ * Conformance IDs OUT-001..OUT-025 are registered here as the single source of
+ * truth for the sprint's conformance rows.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type.
+ */
+
+/** Schema version for OutcomeV1. */
+export const OUTCOME_SCHEMA_V1 = "outcome-v1";
+
+/** Schema version for ConsentV1. */
+export const CONSENT_SCHEMA_V1 = "consent-v1";
+
+/** Schema version for DatasetManifestV1. */
+export const DATASET_MANIFEST_SCHEMA_V1 = "dataset-manifest-v1";
+
+/** Failure code when a payload-bearing field is passed to the ledger. */
+export const OUT_PAYLOAD_FORBIDDEN = "OUT_PAYLOAD_FORBIDDEN";
+
+/** Failure code when consent is missing at export time. */
+export const OUT_CONSENT_MISSING = "OUT_CONSENT_MISSING";
+
+/** Failure code when a group would cross split boundaries. */
+export const OUT_SPLIT_VIOLATION = "OUT_SPLIT_VIOLATION";
+
+/**
+ * OutcomeV1 — a single payload-free outcome metric row.
+ * Contains session/repo/assignment/metrics ONLY — never prompt, response,
+ * exact bytes, or free-text payload fields.
+ */
+export interface OutcomeV1 {
+  readonly schema: typeof OUTCOME_SCHEMA_V1;
+  readonly outcomeId: string;
+  readonly sessionId: string;
+  readonly repoId: string;
+  readonly assignment: string;
+  readonly metrics: ReadonlyArray<OutcomeMetric>;
+  readonly ts: string;
+}
+
+/** A single numeric metric with a named code — never free-text. */
+export interface OutcomeMetric {
+  readonly code: string;
+  readonly value: number;
+  readonly unit: string;
+}
+
+/**
+ * ConsentV1 — append-only consent record (grant or revocation).
+ * An outcome is included in a dataset manifest only if its session has an
+ * active explicit grant at export time (no revocation after the grant).
+ */
+export interface ConsentV1 {
+  readonly schema: typeof CONSENT_SCHEMA_V1;
+  readonly consentId: string;
+  readonly sessionId: string;
+  readonly action: "grant" | "revoke";
+  readonly effectiveSeq: number;
+  readonly ts: string;
+}
+
+/** A split assignment for a dataset row group. */
+export type DatasetSplit = "train" | "calibration" | "held-out";
+
+/**
+ * DatasetManifestV1 — a frozen snapshot of consented outcome rows grouped
+ * by (repo, session) into train/calibration/held-out splits.
+ */
+export interface DatasetManifestV1 {
+  readonly schema: typeof DATASET_MANIFEST_SCHEMA_V1;
+  readonly manifestId: string;
+  readonly rows: ReadonlyArray<DatasetManifestRow>;
+  readonly splitDigests: Readonly<Record<DatasetSplit, string>>;
+  readonly createdAt: string;
+}
+
+/** A single row in a dataset manifest. */
+export interface DatasetManifestRow {
+  readonly outcomeId: string;
+  readonly repoId: string;
+  readonly sessionId: string;
+  readonly split: DatasetSplit;
+}
+
+/** Conformance IDs OUT-001..OUT-025 for the 25 numbered rows. */
+export const OUTCOMES_CONFORMANCE_IDS: readonly string[] = Array.from(
+  { length: 25 },
+  (_, i) => `OUT-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named conformance fixtures for the sprint's headline assertions. */
+export const OUTCOMES_NAMED_FIXTURES = [
+  "OUT-CONSENT-001",
+  "OUT-REVOKE-002",
+  "OUT-SPLIT-003",
+] as const;