@aldus-runtime/regression 0.1.0

package/src/blindspots.ts

@@ -0,0 +1,199 @@
+/**
+ * The known-blind-spot registry (architecture contract §12.1, §9.3).
+ *
+ * §12.1 lists "known blind spots" among what evaluator promotion must consider, and §9.3 makes
+ * negative knowledge first-class: "Known failed approaches, unsafe transformations, evaluator
+ * blind spots, and provider limitations SHOULD be first-class pack content. Learning does not
+ * mean storing only successful examples."
+ *
+ * A blind spot is a failure mode an evaluator is *known* not to catch. It matters to promotion
+ * precisely because the corpus does not contain it — so metrics computed over the corpus are not
+ * evidence against a blind spot, they are evidence that the corpus did not look. An evaluator
+ * with an open blind spot in a slice should never read as promotable in that slice, however good
+ * its numbers are.
+ *
+ * ### Relationship to Knowledge Packs
+ *
+ * `KnowledgePackManifest.negativeKnowledge` (WP-09) holds *resource paths* — Core indexes them
+ * and never parses what is behind them (§1.2, §9.1). This registry holds the structured,
+ * machine-checkable records that gate promotion. They are complementary: a pack points at the
+ * prose describing a blind spot, and this registry carries the part a policy can evaluate.
+ */
+
+import { actorRefSchema } from "@aldus-runtime/core";
+import { z } from "zod";
+
+import { findingCategory, scopeDimensions, severityLevel } from "./corpus.js";
+import { RegressionErrorCodes, regressionError } from "./errors.js";
+import { scopeMatches, type ScopeSelector } from "./scope.js";
+
+/** How a blind spot has been dealt with. */
+export const BLIND_SPOT_STATUSES = [
+  /** Demonstrated and unaddressed. Disqualifies promotion in scope. */
+  "open",
+  /** Addressed, with the mitigation recorded. */
+  "mitigated",
+  /**
+   * Known, unmitigated, and deliberately tolerated.
+   *
+   * Distinct from `mitigated` because it is a decision, not a fix — and it must stay visible in
+   * the promotion report so tolerating it is a standing choice rather than a forgotten one.
+   */
+  "accepted",
+] as const;
+
+/** @see BLIND_SPOT_STATUSES */
+export type BlindSpotStatus = (typeof BLIND_SPOT_STATUSES)[number];
+
+/** A failure mode an evaluator is known not to catch. */
+export const blindSpotSchema = z
+  .object({
+    /** Identity of this record. */
+    blindSpotId: z.string().min(1).max(200),
+    /** Evaluator the blind spot belongs to. */
+    evaluatorId: z.string().min(1).max(200),
+    /** What the evaluator fails to catch. Prose, for a human reading the promotion report. */
+    description: z.string().min(1).max(4000),
+    /**
+     * Scope the blind spot applies to.
+     *
+     * An empty scope means it applies everywhere. A scoped blind spot disqualifies only the
+     * slices it covers — an evaluator blind to one voice's artefacts is not thereby disqualified
+     * for every other voice.
+     */
+    scope: scopeDimensions,
+    /** Category from the adopter's taxonomy, where the blind spot maps to one (§12.3). */
+    category: findingCategory.optional(),
+    /** Severity of what goes undetected. */
+    severity: severityLevel.optional(),
+    /** Current status. */
+    status: z.enum(BLIND_SPOT_STATUSES),
+    /**
+     * Cases that demonstrate it, where the corpus contains any.
+     *
+     * Often empty, and that is the point: a blind spot the corpus can demonstrate is a
+     * measurable false negative, while one it cannot is invisible to every metric here.
+     */
+    evidenceCaseIds: z.array(z.string().min(1).max(200)).max(1024),
+    /** What was done about it. Required in spirit when `mitigated`; prose either way. */
+    mitigation: z.string().max(4000).optional(),
+    /** Who recorded it (contract §19.2). */
+    recordedBy: actorRefSchema,
+    /** When it was recorded. */
+    recordedAt: z.iso.datetime({ offset: true }),
+  })
+  .meta({
+    id: "BlindSpot",
+    title: "BlindSpot",
+    description:
+      "A failure mode an evaluator is known not to catch (architecture contract §12.1, §9.3). " +
+      "Corpus metrics are not evidence against a blind spot — a blind spot is by definition " +
+      "something the corpus did not sample. An `open` blind spot in scope disqualifies promotion " +
+      "there regardless of metrics.",
+  });
+
+/** @see blindSpotSchema */
+export type BlindSpot = z.infer<typeof blindSpotSchema>;
+
+/**
+ * An in-memory, serialisable set of blind-spot records.
+ *
+ * Deliberately not file-backed. Persistence is the caller's choice — these records belong
+ * alongside an adopter's Knowledge Packs (§9.3), and binding the registry to one storage
+ * implementation would put a storage dependency in a package that only needs to read a list.
+ */
+export class BlindSpotRegistry {
+  readonly #records = new Map<string, BlindSpot>();
+
+  /** Build a registry from records, validating each. */
+  static from(records: readonly unknown[]): BlindSpotRegistry {
+    const registry = new BlindSpotRegistry();
+    for (const record of records) registry.record(record);
+    return registry;
+  }
+
+  /**
+   * Validate and add one record.
+   *
+   * @throws {AldusError} `ALDUS_BLIND_SPOT_MALFORMED` or `ALDUS_BLIND_SPOT_DUPLICATE`.
+   */
+  record(input: unknown): BlindSpot {
+    const result = blindSpotSchema.safeParse(input);
+    if (!result.success) {
+      // Paths and issue codes only — never the received value (contract §19.2).
+      throw regressionError(
+        RegressionErrorCodes.BLIND_SPOT_MALFORMED,
+        "The blind-spot record does not validate.",
+        {
+          category: "validation",
+          details: {
+            issues: result.error.issues.map((issue) => ({
+              path: issue.path.join("."),
+              code: issue.code,
+            })),
+          },
+        },
+      );
+    }
+    if (this.#records.has(result.data.blindSpotId)) {
+      throw regressionError(
+        RegressionErrorCodes.BLIND_SPOT_DUPLICATE,
+        `A blind spot with id "${result.data.blindSpotId}" is already registered.`,
+        { category: "conflict", details: { blindSpotId: result.data.blindSpotId } },
+      );
+    }
+    this.#records.set(result.data.blindSpotId, result.data);
+    return result.data;
+  }
+
+  /** Every record, in insertion order. */
+  list(): BlindSpot[] {
+    return [...this.#records.values()];
+  }
+
+  /** Every record for one evaluator. */
+  forEvaluator(evaluatorId: string): BlindSpot[] {
+    return this.list().filter((record) => record.evaluatorId === evaluatorId);
+  }
+
+  /**
+   * Open blind spots for an evaluator that apply within a scope slice.
+   *
+   * A blind spot applies to a slice when everything it scopes itself to is either held at the
+   * same value by the slice, or not held by the slice at all. The second half matters: a blind
+   * spot scoped to one voice applies to the whole-corpus slice, because the whole corpus
+   * includes that voice.
+   */
+  openFor(evaluatorId: string, selector: ScopeSelector): BlindSpot[] {
+    return this.forEvaluator(evaluatorId).filter((record) => {
+      if (record.status !== "open") return false;
+      return Object.entries(record.scope).every(([dimension, value]) => {
+        const held = selector.values[dimension];
+        return held === undefined || held === value;
+      });
+    });
+  }
+
+  /** Blind spots demonstrated by at least one case in a corpus subset. */
+  demonstratedBy(evaluatorId: string, caseIds: ReadonlySet<string>): BlindSpot[] {
+    return this.forEvaluator(evaluatorId).filter((record) =>
+      record.evidenceCaseIds.some((caseId) => caseIds.has(caseId)),
+    );
+  }
+
+  /** Serialisable form. */
+  toJSON(): BlindSpot[] {
+    return this.list();
+  }
+}
+
+/** True when a blind spot's own scope is satisfied by a case's scope. */
+export function blindSpotCoversCase(
+  record: BlindSpot,
+  scope: Readonly<Record<string, string>>,
+): boolean {
+  return scopeMatches(scope, {
+    dimensions: Object.keys(record.scope),
+    values: record.scope,
+  });
+}

package/src/corpus.ts

@@ -0,0 +1,311 @@
+/**
+ * The defect corpus (architecture contract §22 WP-10, §12.1, §12.3, §24).
+ *
+ * §12.1 permits an evaluator to become blocking "only after it is calibrated against
+ * human-labeled examples", and §24 requires that "a representative defect corpus is executed
+ * during regression testing". This module defines what such a corpus is.
+ *
+ * Two shapes here are deliberately open rather than enumerated:
+ *
+ * - **Finding categories.** §12.3 presents its taxonomy as "for example", and §4.2 keeps
+ *   adopter concepts out of the runtime. A category is an opaque caller-supplied string.
+ * - **Severity levels.** Likewise named by the caller. The *weights* live in the promotion
+ *   policy, so an adopter can say a missed pronunciation error costs less than a missed
+ *   unsupported claim without Core deciding that for them.
+ *
+ * The human label is the oracle (§12 level 4). Nothing in this module treats an evaluator's
+ * output as ground truth.
+ *
+ * Zod is the single source of truth; TypeScript types are inferred (ADR-0002).
+ */
+
+import { actorRefSchema, SCHEMA_VERSION } from "@aldus-runtime/core";
+import { z } from "zod";
+
+import { RegressionErrorCodes, regressionError } from "./errors.js";
+
+/** A short opaque identifier. */
+const identifier = z.string().min(1).max(200);
+
+/**
+ * A finding category, structured per contract §12.3.
+ *
+ * An OPEN string, never a Core-defined enum. §12.3 introduces its taxonomy with "for example",
+ * and §4.2 forbids Core from owning an adopter's diagnosis vocabulary. Do not narrow this to a
+ * union.
+ */
+export const findingCategory = z.string().min(1).max(200);
+
+/**
+ * A severity level, named by the caller.
+ *
+ * An OPEN string for the same reason as {@link findingCategory}. Ordering and weighting are
+ * supplied by the promotion policy, not inferred from the name — a package that decided
+ * `"critical"` outranks `"major"` would be guessing at an adopter's scale.
+ */
+export const severityLevel = z.string().min(1).max(100);
+
+/**
+ * Scope dimensions a case belongs to (contract §12.1 "show, host, voice, model, and
+ * script-form scope").
+ *
+ * `Record<string, string>`, consistent with Knowledge Pack scope (§9.2, ADR-0006). §12.1's list
+ * is illustrative and §4.2 forbids naming a provider, so dimensions stay caller-supplied.
+ */
+export const scopeDimensions = z.record(z.string().min(1).max(100), z.string().min(1).max(200));
+
+/** @see scopeDimensions */
+export type ScopeDimensions = z.infer<typeof scopeDimensions>;
+
+/** One defect a human labeller identified in a case. */
+export const humanFindingSchema = z
+  .object({
+    /** Category from the adopter's taxonomy (contract §12.3). */
+    category: findingCategory,
+    /** Severity from the adopter's scale; weighted by the promotion policy. */
+    severity: severityLevel,
+    /** What the labeller saw. Prose, never parsed. */
+    note: z.string().max(4000).optional(),
+  })
+  .meta({ id: "HumanFinding", title: "HumanFinding" });
+
+/** @see humanFindingSchema */
+export type HumanFinding = z.infer<typeof humanFindingSchema>;
+
+/**
+ * One labelled case: an input, and what a human said about it.
+ *
+ * The case does not carry the input itself. §8.1 makes artifacts addressable by ID and hash, and
+ * a corpus that embedded audio or scripts would be unreviewable and would risk carrying private
+ * source material into a test fixture (§19.2). `subjectRef` points at the subject; what it
+ * points into is the caller's business.
+ */
+export const defectCaseSchema = z
+  .object({
+    /** Identity of this case within its corpus. */
+    caseId: identifier,
+    /** Reference to the material under test — an artifact ID, hash, or adopter-defined locator. */
+    subjectRef: z.string().min(1).max(1024),
+    /** Scope this case belongs to (contract §12.1). */
+    scope: scopeDimensions,
+    /**
+     * Whether a human judged the subject defective. **This is the oracle** (§12 level 4).
+     *
+     * Stored separately from `findings` so a case can be labelled clean explicitly. An empty
+     * findings array on a case nobody reviewed is not the same claim as "a human looked and
+     * found nothing", and conflating them would inflate the true-negative count with unreviewed
+     * material.
+     */
+    defective: z.boolean(),
+    /** What the labeller found. Empty when `defective` is false. */
+    findings: z.array(humanFindingSchema).max(256),
+    /**
+     * Overall severity of the case, used for severity-weighted metrics (contract §12.1).
+     *
+     * Required when `defective`, absent otherwise — enforced by refinement below.
+     */
+    severity: severityLevel.optional(),
+    /**
+     * Correction class this case would trigger if a blocking evaluator flagged it.
+     *
+     * §12.1 names "asymmetric harm caused by unnecessary automatic correction" as its own
+     * consideration, and §12.4 makes the repair layer explicit — regenerating one TTS segment
+     * and revising narration with cascading approval invalidation are not the same act. This
+     * names which one a flag would trigger here; the policy assigns the harm weight. Absent
+     * means the policy's default class applies.
+     */
+    correctionOnFlag: identifier.optional(),
+    /** Who labelled the case (contract §19.2: a decision without an actor is not a decision). */
+    labelledBy: actorRefSchema,
+    /** When the label was recorded. */
+    labelledAt: z.iso.datetime({ offset: true }),
+  })
+  .refine((value) => value.defective === (value.severity !== undefined), {
+    message:
+      "a defective case must carry a severity, and a clean case must not (architecture contract §12.1 requires severity-weighted metrics)",
+    path: ["severity"],
+  })
+  .refine((value) => value.defective || value.findings.length === 0, {
+    message: "a case labelled clean must carry no findings",
+    path: ["findings"],
+  })
+  .meta({
+    id: "DefectCase",
+    title: "DefectCase",
+    description:
+      "One human-labelled case in a defect corpus (architecture contract §12.1, §24). The human " +
+      "label is the oracle; nothing treats an evaluator's output as ground truth. `category` and " +
+      "`severity` are open strings because §12.3's taxonomy is illustrative and §4.2 keeps " +
+      "adopter vocabularies out of the runtime. ADDITIONAL CONSTRAINTS NOT EXPRESSIBLE IN JSON " +
+      "SCHEMA: a defective case must carry a severity and a clean case must not, and a clean " +
+      "case must carry no findings.",
+  });
+
+/** @see defectCaseSchema */
+export type DefectCase = z.infer<typeof defectCaseSchema>;
+
+/** A named, versioned set of labelled cases. */
+export const defectCorpusSchema = z
+  .object({
+    /** Schema version of this record (ADR-0003). */
+    schemaVersion: z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)$/),
+    /** Identity of this corpus. */
+    corpusId: identifier,
+    /** Human-readable purpose. */
+    description: z.string().max(2000).optional(),
+    /** The labelled cases. */
+    cases: z.array(defectCaseSchema).max(100_000),
+  })
+  .meta({
+    id: "DefectCorpus",
+    title: "DefectCorpus",
+    description:
+      "A defect corpus: human-labelled cases an evaluator is calibrated against (architecture " +
+      "contract §12.1, §24). ADDITIONAL CONSTRAINT NOT EXPRESSIBLE IN JSON SCHEMA: `caseId` " +
+      "must be unique within the corpus.",
+  });
+
+/** @see defectCorpusSchema */
+export type DefectCorpus = z.infer<typeof defectCorpusSchema>;
+
+/** One finding an evaluator reported. */
+export const evaluatorFindingSchema = z
+  .object({
+    /** Category the evaluator assigned, from the same taxonomy as {@link humanFindingSchema}. */
+    category: findingCategory,
+    /** Severity the evaluator assigned, where it assigns one. */
+    severity: severityLevel.optional(),
+    /** Evaluator confidence in `[0, 1]`, where it reports one. */
+    confidence: z.number().min(0).max(1).optional(),
+  })
+  .meta({ id: "EvaluatorFinding", title: "EvaluatorFinding" });
+
+/** @see evaluatorFindingSchema */
+export type EvaluatorFinding = z.infer<typeof evaluatorFindingSchema>;
+
+/** What an evaluator said about one case. */
+export const evaluatorOutcomeSchema = z
+  .object({
+    /** Case this outcome reports on. */
+    caseId: identifier,
+    /** Whether the evaluator flagged the subject. */
+    flagged: z.boolean(),
+    /** What it reported. Empty when not flagged. */
+    findings: z.array(evaluatorFindingSchema).max(256),
+  })
+  .meta({ id: "EvaluatorOutcome", title: "EvaluatorOutcome" });
+
+/** @see evaluatorOutcomeSchema */
+export type EvaluatorOutcome = z.infer<typeof evaluatorOutcomeSchema>;
+
+/**
+ * One evaluator's outcomes over one corpus.
+ *
+ * This package does **not** run evaluators (contract §22 WP-10 scope). A run is produced
+ * elsewhere and handed here for comparison.
+ */
+export const evaluatorRunSchema = z
+  .object({
+    /** Schema version of this record (ADR-0003). */
+    schemaVersion: z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)$/),
+    /** Which evaluator produced these outcomes. */
+    evaluatorId: identifier,
+    /** Version of the evaluator. Metrics from different versions are not comparable. */
+    evaluatorVersion: identifier,
+    /** Corpus the outcomes are against. */
+    corpusId: identifier,
+    /** The outcomes. */
+    outcomes: z.array(evaluatorOutcomeSchema).max(100_000),
+    /** When the run was executed. */
+    executedAt: z.iso.datetime({ offset: true }),
+  })
+  .meta({
+    id: "EvaluatorRun",
+    title: "EvaluatorRun",
+    description:
+      "One evaluator's outcomes over one defect corpus (architecture contract §22 WP-10). This " +
+      "package consumes runs; it does not execute evaluators. ADDITIONAL CONSTRAINT NOT " +
+      "EXPRESSIBLE IN JSON SCHEMA: `caseId` must be unique within `outcomes`.",
+  });
+
+/** @see evaluatorRunSchema */
+export type EvaluatorRun = z.infer<typeof evaluatorRunSchema>;
+
+/** Schema version this package stamps on records it constructs. */
+export const REGRESSION_SCHEMA_VERSION = SCHEMA_VERSION;
+
+/**
+ * Validate a corpus and check the uniqueness constraint Zod cannot express.
+ *
+ * @throws {AldusError} `ALDUS_CORPUS_MALFORMED` or `ALDUS_CORPUS_DUPLICATE_CASE`.
+ */
+export function parseDefectCorpus(input: unknown): DefectCorpus {
+  const result = defectCorpusSchema.safeParse(input);
+  if (!result.success) {
+    // Paths and issue codes only — never the received value (contract §19.2, ADR-0002).
+    throw regressionError(
+      RegressionErrorCodes.CORPUS_MALFORMED,
+      "The defect corpus does not validate.",
+      {
+        category: "validation",
+        details: {
+          issues: result.error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            code: issue.code,
+          })),
+        },
+      },
+    );
+  }
+
+  const seen = new Set<string>();
+  for (const entry of result.data.cases) {
+    if (seen.has(entry.caseId)) {
+      throw regressionError(
+        RegressionErrorCodes.CORPUS_DUPLICATE_CASE,
+        `Corpus "${result.data.corpusId}" contains more than one case with id "${entry.caseId}". ` +
+          "Duplicate ids would let one case be counted twice and silently reweight every metric.",
+        { category: "validation", details: { corpusId: result.data.corpusId } },
+      );
+    }
+    seen.add(entry.caseId);
+  }
+  return result.data;
+}
+
+/**
+ * Validate an evaluator run and check uniqueness.
+ *
+ * @throws {AldusError} `ALDUS_CORPUS_MALFORMED` or `ALDUS_OUTCOME_DUPLICATE`.
+ */
+export function parseEvaluatorRun(input: unknown): EvaluatorRun {
+  const result = evaluatorRunSchema.safeParse(input);
+  if (!result.success) {
+    throw regressionError(
+      RegressionErrorCodes.CORPUS_MALFORMED,
+      "The evaluator run does not validate.",
+      {
+        category: "validation",
+        details: {
+          issues: result.error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            code: issue.code,
+          })),
+        },
+      },
+    );
+  }
+
+  const seen = new Set<string>();
+  for (const outcome of result.data.outcomes) {
+    if (seen.has(outcome.caseId)) {
+      throw regressionError(
+        RegressionErrorCodes.OUTCOME_DUPLICATE,
+        `Evaluator run for "${result.data.evaluatorId}" reports twice on case "${outcome.caseId}".`,
+        { category: "validation", details: { evaluatorId: result.data.evaluatorId } },
+      );
+    }
+    seen.add(outcome.caseId);
+  }
+  return result.data;
+}

package/src/errors.ts

@@ -0,0 +1,49 @@
+/**
+ * Failures specific to the regression harness.
+ *
+ * Aldus Core deliberately keeps no central error-code registry, so a package can name a new
+ * failure without forking Core. These codes carry the same `ALDUS_` prefix and
+ * `SCREAMING_SNAKE_CASE` shape so production trace (contract §20) stays uniform across packages.
+ */
+
+import { AldusError, type ErrorCategory } from "@aldus-runtime/core";
+
+/** Error codes raised by the regression harness. */
+export const RegressionErrorCodes = {
+  /** A defect corpus contained a case that does not validate. */
+  CORPUS_MALFORMED: "ALDUS_CORPUS_MALFORMED",
+  /** Two cases in one corpus share a `caseId`. */
+  CORPUS_DUPLICATE_CASE: "ALDUS_CORPUS_DUPLICATE_CASE",
+  /** An evaluator outcome referenced a `caseId` the corpus does not contain. */
+  OUTCOME_UNKNOWN_CASE: "ALDUS_OUTCOME_UNKNOWN_CASE",
+  /** Two outcomes in one run reported on the same `caseId`. */
+  OUTCOME_DUPLICATE: "ALDUS_OUTCOME_DUPLICATE",
+  /**
+   * A case carries a severity the policy assigns no weight to.
+   *
+   * Refused rather than defaulted: silently weighting an unknown severity as zero would drop a
+   * missed defect out of the severity-weighted recall that contract §12.1 requires be
+   * considered, and the metric would still report a number.
+   */
+  SEVERITY_UNWEIGHTED: "ALDUS_SEVERITY_UNWEIGHTED",
+  /** A correction class was referenced that the policy assigns no harm weight to. */
+  CORRECTION_CLASS_UNWEIGHTED: "ALDUS_CORRECTION_CLASS_UNWEIGHTED",
+  /** A blind-spot record does not validate. */
+  BLIND_SPOT_MALFORMED: "ALDUS_BLIND_SPOT_MALFORMED",
+  /** Two blind spots share a `blindSpotId`. */
+  BLIND_SPOT_DUPLICATE: "ALDUS_BLIND_SPOT_DUPLICATE",
+  /** A promotion policy is internally inconsistent — a threshold outside its valid range. */
+  POLICY_INVALID: "ALDUS_POLICY_INVALID",
+} as const;
+
+/** @see RegressionErrorCodes */
+export type RegressionErrorCode = (typeof RegressionErrorCodes)[keyof typeof RegressionErrorCodes];
+
+/** Construct an {@link AldusError} with a regression-harness code. */
+export function regressionError(
+  code: RegressionErrorCode,
+  message: string,
+  options: { category: ErrorCategory; retryable?: boolean; details?: Record<string, unknown> },
+): AldusError {
+  return new AldusError(code, message, options);
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+/**
+ * `@aldus-runtime/regression` — the regression harness (architecture contract §22 WP-10).
+ *
+ * §12.1 permits an evaluator to become blocking "only after it is calibrated against
+ * human-labeled examples". This package is what makes that an evidence-based decision instead of
+ * a judgement call: it holds the defect corpus, compares an evaluator's outcomes against human
+ * labels, computes the metrics §12.1 names, and reports whether the bar is met — **per scope**.
+ *
+ * It does **not** run evaluators. Outcomes are produced elsewhere and handed here.
+ *
+ * Two things are load-bearing and easy to lose in a refactor:
+ *
+ * - **Promotion is scoped.** No API here returns "this evaluator is promotable". §12.1 lists
+ *   show, host, voice, model, and script-form scope because calibration does not generalise.
+ * - **The aggregate never decides.** The whole-corpus figure is descriptive; no threshold is
+ *   applied to it (ADR-0010).
+ *
+ * @packageDocumentation
+ */
+
+// --- Defect corpus (§12.1, §12.3, §24) --------------------------------------------------------
+export {
+  REGRESSION_SCHEMA_VERSION,
+  defectCaseSchema,
+  defectCorpusSchema,
+  evaluatorFindingSchema,
+  evaluatorOutcomeSchema,
+  evaluatorRunSchema,
+  findingCategory,
+  humanFindingSchema,
+  parseDefectCorpus,
+  parseEvaluatorRun,
+  scopeDimensions,
+  severityLevel,
+  type DefectCase,
+  type DefectCorpus,
+  type EvaluatorFinding,
+  type EvaluatorOutcome,
+  type EvaluatorRun,
+  type HumanFinding,
+  type ScopeDimensions,
+} from "./corpus.js";
+
+// --- Scope slicing (§12.1) --------------------------------------------------------------------
+export {
+  WHOLE_CORPUS_SLICE,
+  deriveScopeSelectors,
+  observedDimensions,
+  scopeKey,
+  scopeLabel,
+  scopeMatches,
+  type ScopeSelector,
+} from "./scope.js";
+
+// --- Promotion policy (§12.1, §25.9; ADR-0010) ------------------------------------------------
+export {
+  DEFAULT_CORRECTION_HARM_WEIGHTS,
+  DEFAULT_PROMOTION_THRESHOLDS,
+  assertPolicyValid,
+  correctionHarm,
+  defaultPromotionPolicy,
+  severityWeight,
+  type CorrectionHarmWeights,
+  type PolicyOrigin,
+  type PromotionPolicy,
+  type PromotionThresholds,
+  type SeverityWeights,
+} from "./policy.js";
+
+// --- Comparison and metrics (§12.1) -----------------------------------------------------------
+export {
+  compareRun,
+  type CaseComparison,
+  type CaseVerdict,
+  type CompareOptions,
+  type ComparisonReport,
+  type SliceMetrics,
+} from "./metrics.js";
+
+// --- Known blind spots (§12.1, §9.3) ----------------------------------------------------------
+export {
+  BLIND_SPOT_STATUSES,
+  BlindSpotRegistry,
+  blindSpotCoversCase,
+  blindSpotSchema,
+  type BlindSpot,
+  type BlindSpotStatus,
+} from "./blindspots.js";
+
+// --- Promotion verdict (§12.1; ADR-0010) ------------------------------------------------------
+export {
+  assessPromotion,
+  isPromotableEverywhereMeasured,
+  type PromotionShortfall,
+  type PromotionShortfallCode,
+  type PromotionVerdict,
+  type SliceVerdict,
+} from "./promotion.js";
+
+// --- Report rendering (§12) -------------------------------------------------------------------
+export { REPORT_CAVEAT, forbiddenClaimWords, renderPromotionReport } from "./report.js";
+
+// --- Errors -----------------------------------------------------------------------------------
+export { RegressionErrorCodes, regressionError, type RegressionErrorCode } from "./errors.js";