@nanobpm/urban 0.57.0 → 0.58.0

package/dist/context/schema/index.js

@@ -1 +1,330 @@
-export {};
+// Slice S2 (schema) — the memory-record schema for the Urban context layer.
+//
+// This module is the RECORD HALF of the published `@nanobpm/urban/context`
+// contract (imported as `@nanobpm/urban/context/schema`). The consumer repo
+// (`nanobpm/nano-workforce#291`), the git substrate/governance slice (S3), and
+// the adversarial slice (S7) all build against the types + validator exported
+// here, so the surface is deliberately small, stable, and versioned-friendly.
+//
+// The central design goal is a FORGERY-RESISTANT-BY-CONSTRUCTION encoding of the
+// "hypothesis-never-fix" invariant: an unratified / agent-retrospective prior
+// can never be *represented* as a measured / authoritative fact. This is not a
+// runtime policy layered on top — it is baked into the controlled vocabulary and
+// the cross-field validation rules below, so no code path (governance, retrieval,
+// or a hostile caller) can construct a record that launders a hypothesis into a
+// fact. S3 relies on this to gate its write path; S7 attacks it directly.
+// ---------------------------------------------------------------------------
+// Versioning
+// ---------------------------------------------------------------------------
+/**
+ * The only schema version this module accepts. Records must carry it explicitly
+ * so a future producer can bump the shape while old consumers reject-with-reason
+ * instead of silently mis-reading a newer record.
+ */
+export const MEMORY_RECORD_SCHEMA_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Controlled vocabulary
+// ---------------------------------------------------------------------------
+/**
+ * The scope ladder — the granularity a record is attached to, from the most
+ * specific (a single ladder `element`) up to the whole `corpus`. The array
+ * order IS the ladder order (specific → general) and is exported so callers can
+ * reason about containment without re-deriving it.
+ */
+export const SCOPE_LADDER = ["element", "instance", "epic", "repo", "corpus"];
+/**
+ * Whether the record asserts a norm (`normative` — "this is how it should be")
+ * or an observation (`empirical` — "this is what was measured/seen").
+ */
+export const MEMORY_MODES = ["normative", "empirical"];
+/**
+ * Where the record came from:
+ *  - `human`       — authored by a person.
+ *  - `agent-retro` — a retrospective prior PROPOSED by an agent. Always a
+ *                    hypothesis until ratified by governance (S3: merge of a bot
+ *                    PR). By construction it can never be authoritative here.
+ *  - `measured`    — produced by an empirical measurement. Authoritative fact.
+ *  - `instance`    — observed directly from a concrete instance run. Fact.
+ */
+export const PROVENANCES = ["human", "agent-retro", "measured", "instance"];
+/**
+ * The authority tier — the forgery target. `hypothesis` is a not-yet-ratified
+ * claim; `authoritative` is a ratified fact/fix. The invariants below make it
+ * impossible for an `agent-retro` (or otherwise unratified) record to carry the
+ * `authoritative` tier. Governance (S3) is the ONLY thing that legitimately
+ * mints `authoritative` records, via the ratification transition it owns.
+ */
+export const AUTHORITIES = ["hypothesis", "authoritative"];
+// ---------------------------------------------------------------------------
+// Small, assertion-free narrowing helpers
+// ---------------------------------------------------------------------------
+// A "plain object" is one whose untrusted properties we can read WITHOUT risking
+// a throw: it must carry `Object.prototype` (or a null prototype) and expose only
+// own data properties. Objects with accessor properties (getters/setters) or
+// exotic prototypes are rejected, because reading such a property could throw
+// (e.g. `{ get id() { throw ... } }`) and break `validateMemoryRecord`'s "never
+// throws" contract for hostile inputs. Any reflection error is likewise swallowed
+// as a rejection rather than allowed to propagate.
+function isPlainObject(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    try {
+        const proto = Object.getPrototypeOf(v);
+        if (proto !== Object.prototype && proto !== null)
+            return false;
+        for (const key of Reflect.ownKeys(v)) {
+            const descriptor = Object.getOwnPropertyDescriptor(v, key);
+            if (descriptor === undefined || descriptor.get !== undefined || descriptor.set !== undefined) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+function includes(vocabulary, v) {
+    return typeof v === "string" && vocabulary.some((entry) => entry === v);
+}
+// Single source of truth for how a controlled-vocabulary field fails: absent is
+// `missing-field`, a non-string is `wrong-type` (so callers can tell a bad type
+// apart from a drifted value), and a string outside the ladder is
+// `invalid-vocabulary`. Shared by scope/mode/provenance/authority.
+function vocabularyCode(value) {
+    if (value === undefined)
+        return "missing-field";
+    if (typeof value !== "string")
+        return "wrong-type";
+    return "invalid-vocabulary";
+}
+// Single source of truth for how a non-empty-string field fails: absent is
+// `missing-field`, an empty string is `empty-string` (a valid type callers can
+// surface distinctly in UX), and any other non-string is `wrong-type`. Shared by
+// required (`id`, `statement`) and optional (`scopeRef`, `supersedes`) fields;
+// optional callers guard `undefined` before calling so it never surfaces.
+function nonEmptyStringCode(value) {
+    if (value === undefined)
+        return "missing-field";
+    if (value === "")
+        return "empty-string";
+    return "wrong-type";
+}
+function isIsoTimestamp(v) {
+    if (typeof v !== "string" || v.length === 0)
+        return false;
+    // Require a real, round-trippable ISO-8601 instant (date + time + zone).
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(v)) {
+        return false;
+    }
+    return Number.isFinite(Date.parse(v));
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((entry) => typeof entry === "string");
+}
+/**
+ * Enumerates every invariant violation in `ctx`. An empty array means the
+ * (mode, provenance, authority) triple is internally consistent.
+ *
+ * The rules, together, guarantee the hypothesis-never-fix invariant:
+ *   R1  agent-retro ⇒ hypothesis          (a proposed prior is never a fact)
+ *   R2  measured    ⇒ authoritative       (a measurement is a fact, not a guess)
+ *   R3  measured    ⇒ empirical           (you cannot "measure" a norm)
+ *   R4  instance    ⇒ authoritative       (a real observation is a fact)
+ *   R5  instance    ⇒ empirical           (an observation is not a norm)
+ *   R6  normative   ⇒ human | agent-retro (only people/agents author norms)
+ *
+ * A consequence worth stating explicitly (and tested by S7): the ONLY way to
+ * reach `authoritative` is provenance ∈ {human, measured, instance}; agent-retro
+ * is structurally excluded, so an unratified prior can never be laundered into a
+ * fact by any field permutation.
+ */
+export function checkInvariants(ctx) {
+    const errors = [];
+    // Cross-field invariants are whole-record violations (they constrain the
+    // mode/provenance/authority triple jointly), so report them at the empty
+    // (whole-record) path rather than mis-pointing consumers at `authority`.
+    const push = (message) => errors.push({ path: "", code: "invariant-violation", message });
+    if (ctx.provenance === "agent-retro" && ctx.authority === "authoritative") {
+        push("hypothesis-never-fix: an 'agent-retro' prior is unratified and can never be 'authoritative'. Ratification is governance's job (S3: merge of the proposing PR).");
+    }
+    if (ctx.provenance === "measured" && ctx.authority !== "authoritative") {
+        push("a 'measured' record is an empirical fact and must be 'authoritative'.");
+    }
+    if (ctx.provenance === "measured" && ctx.mode !== "empirical") {
+        push("a 'measured' record is an observation and must have mode 'empirical', not 'normative'.");
+    }
+    if (ctx.provenance === "instance" && ctx.authority !== "authoritative") {
+        push("an 'instance' observation is a fact and must be 'authoritative'.");
+    }
+    if (ctx.provenance === "instance" && ctx.mode !== "empirical") {
+        push("an 'instance' observation must have mode 'empirical', not 'normative'.");
+    }
+    if (ctx.mode === "normative" && !(ctx.provenance === "human" || ctx.provenance === "agent-retro")) {
+        push("a 'normative' record asserts a norm and may only be authored by 'human' or proposed by 'agent-retro'.");
+    }
+    return errors;
+}
+/** Convenience predicate: is this a ratified, authoritative fact/fix? */
+export function isAuthoritative(record) {
+    return record.authority === "authoritative";
+}
+// ---------------------------------------------------------------------------
+// The validator
+// ---------------------------------------------------------------------------
+/**
+ * Validate an untrusted value as a MemoryRecord. On success returns the record
+ * narrowed to `MemoryRecord`; on failure returns EVERY error found (not just the
+ * first) so callers can surface all problems at once. Never throws.
+ */
+export function validateMemoryRecord(input) {
+    const errors = [];
+    if (!isPlainObject(input)) {
+        return {
+            ok: false,
+            errors: [{ path: "", code: "not-an-object", message: "record must be a plain object." }],
+        };
+    }
+    // Version first — a wrong version means the rest of the shape is unreliable.
+    // Distinguish an absent version (missing-field, like every other required
+    // field), a wrong-typed version (wrong-type, e.g. a string), and a
+    // present-but-unsupported numeric version (unsupported-schema-version) so the
+    // structured error is honest and consistent with the other required fields.
+    if (input.schemaVersion !== MEMORY_RECORD_SCHEMA_VERSION) {
+        const version = input.schemaVersion;
+        const versionCode = version === undefined ? "missing-field" : typeof version !== "number" ? "wrong-type" : "unsupported-schema-version";
+        errors.push({
+            path: "schemaVersion",
+            code: versionCode,
+            message: versionCode === "missing-field"
+                ? "schemaVersion is required."
+                : versionCode === "wrong-type"
+                    ? "schemaVersion must be a number."
+                    : `unsupported schemaVersion; expected ${MEMORY_RECORD_SCHEMA_VERSION}.`,
+        });
+    }
+    // Capture fields into const locals: TypeScript's aliased-condition narrowing
+    // persists a type-guard result across statements only for `const` references,
+    // not for repeated property accesses. This lets us build the typed record at
+    // the end WITHOUT any `as` cast (forbidden by the biome plugin).
+    const idVal = input.id;
+    const statementVal = input.statement;
+    const createdAtVal = input.createdAt;
+    const scopeVal = input.scope;
+    const modeVal = input.mode;
+    const provenanceVal = input.provenance;
+    const authorityVal = input.authority;
+    const idOk = isNonEmptyString(idVal);
+    if (!idOk) {
+        errors.push({
+            path: "id",
+            code: nonEmptyStringCode(idVal),
+            message: "id must be a non-empty string.",
+        });
+    }
+    const statementOk = isNonEmptyString(statementVal);
+    if (!statementOk) {
+        errors.push({
+            path: "statement",
+            code: nonEmptyStringCode(statementVal),
+            message: "statement must be a non-empty string.",
+        });
+    }
+    const createdAtOk = isIsoTimestamp(createdAtVal);
+    if (!createdAtOk) {
+        errors.push({
+            path: "createdAt",
+            code: createdAtVal === undefined ? "missing-field" : "invalid-timestamp",
+            message: "createdAt must be an ISO-8601 timestamp with a timezone.",
+        });
+    }
+    const scopeOk = includes(SCOPE_LADDER, scopeVal);
+    if (!scopeOk) {
+        errors.push({ path: "scope", code: vocabularyCode(scopeVal), message: `scope must be one of: ${SCOPE_LADDER.join(", ")}.` });
+    }
+    const modeOk = includes(MEMORY_MODES, modeVal);
+    if (!modeOk) {
+        errors.push({ path: "mode", code: vocabularyCode(modeVal), message: `mode must be one of: ${MEMORY_MODES.join(", ")}.` });
+    }
+    const provenanceOk = includes(PROVENANCES, provenanceVal);
+    if (!provenanceOk) {
+        errors.push({ path: "provenance", code: vocabularyCode(provenanceVal), message: `provenance must be one of: ${PROVENANCES.join(", ")}.` });
+    }
+    const authorityOk = includes(AUTHORITIES, authorityVal);
+    if (!authorityOk) {
+        errors.push({ path: "authority", code: vocabularyCode(authorityVal), message: `authority must be one of: ${AUTHORITIES.join(", ")}.` });
+    }
+    // Optional fields: reject wrong types, ignore when absent.
+    const scopeRefVal = input.scopeRef;
+    const subjectVal = input.subject;
+    const evidenceVal = input.evidence;
+    const supersedesVal = input.supersedes;
+    if (scopeRefVal !== undefined && !isNonEmptyString(scopeRefVal)) {
+        errors.push({ path: "scopeRef", code: nonEmptyStringCode(scopeRefVal), message: "scopeRef, if present, must be a non-empty string." });
+    }
+    if (subjectVal !== undefined && typeof subjectVal !== "string") {
+        errors.push({ path: "subject", code: "wrong-type", message: "subject, if present, must be a string." });
+    }
+    if (evidenceVal !== undefined && !isStringArray(evidenceVal)) {
+        errors.push({ path: "evidence", code: "wrong-type", message: "evidence, if present, must be an array of strings." });
+    }
+    if (supersedesVal !== undefined && !isNonEmptyString(supersedesVal)) {
+        errors.push({ path: "supersedes", code: nonEmptyStringCode(supersedesVal), message: "supersedes, if present, must be a non-empty string." });
+    }
+    // Cross-field invariants can only run once the vocabulary fields are sound.
+    if (modeOk && provenanceOk && authorityOk) {
+        for (const err of checkInvariants({ mode: modeVal, provenance: provenanceVal, authority: authorityVal })) {
+            errors.push(err);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // All guards passed; aliased narrowing makes the const locals fully typed here.
+    if (!scopeOk || !modeOk || !provenanceOk || !authorityOk || !idOk || !statementOk || !createdAtOk) {
+        return { ok: false, errors: [{ path: "", code: "wrong-type", message: "internal: unexpected narrowing failure." }] };
+    }
+    const record = {
+        schemaVersion: MEMORY_RECORD_SCHEMA_VERSION,
+        id: idVal,
+        scope: scopeVal,
+        mode: modeVal,
+        provenance: provenanceVal,
+        authority: authorityVal,
+        statement: statementVal,
+        createdAt: createdAtVal,
+        ...(isNonEmptyString(scopeRefVal) ? { scopeRef: scopeRefVal } : {}),
+        ...(typeof subjectVal === "string" ? { subject: subjectVal } : {}),
+        ...(isStringArray(evidenceVal) ? { evidence: evidenceVal } : {}),
+        ...(isNonEmptyString(supersedesVal) ? { supersedes: supersedesVal } : {}),
+    };
+    return { ok: true, record };
+}
+/** Type guard form of {@link validateMemoryRecord}. */
+export function isMemoryRecord(input) {
+    return validateMemoryRecord(input).ok;
+}
+/** Error thrown by {@link assertMemoryRecord}. Carries the structured errors. */
+export class MemoryRecordValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`invalid memory record: ${errors.map((e) => `${e.path || "<record>"}: ${e.message}`).join("; ")}`);
+        this.name = "MemoryRecordValidationError";
+        this.errors = errors;
+    }
+}
+/**
+ * Throwing form: returns the validated record or throws
+ * {@link MemoryRecordValidationError}. Handy for governance/write paths that
+ * treat an invalid record as a hard failure.
+ */
+export function assertMemoryRecord(input) {
+    const result = validateMemoryRecord(input);
+    if (!result.ok) {
+        throw new MemoryRecordValidationError(result.errors);
+    }
+    return result.record;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.57.0",
+	"version": "0.58.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/context/conformance/index.ts

@@ -1,2 +1,285 @@
-// Slice S2 (conformance corpus + fixtures) — owner replaces this placeholder barrel.
-export {};
+// Slice S2 (conformance) — the shared conformance corpus + a reusable runner.
+//
+// Published as `@nanobpm/urban/context/conformance`. This subpath IS the
+// contract: BOTH the producer (this repo) and the consumer
+// (`nanobpm/nano-workforce#291`) are held to the SAME corpus, and the
+// adversarial slice (S7) imports the corpus + runner from here directly. It is
+// intentionally self-contained — it does NOT re-export the schema module, so a
+// consumer can import it without pulling the whole schema surface, and the top
+// barrel never sees a duplicate symbol.
+//
+// The runner is a PURE function over a validator callback (no test framework),
+// so any party can point it at their own validator and get a structured report.
+// The `.conformance.ts` sibling wires it into `node:test` for `test:conformance`.
+
+import { MEMORY_RECORD_SCHEMA_VERSION, SCOPE_LADDER } from "../schema/index.ts";
+
+// ---------------------------------------------------------------------------
+// Public shapes
+// ---------------------------------------------------------------------------
+
+/** Whether the corpus expects a validator to accept or reject an input. */
+export type ConformanceExpectation = "accept" | "reject";
+
+/** A single corpus entry: an input and the outcome every conformant validator must produce. */
+export interface ConformanceCase {
+  /** Unique, stable, human-readable case name. */
+  readonly name: string;
+  /** The required outcome. */
+  readonly expect: ConformanceExpectation;
+  /** The (untrusted) value fed to the validator. */
+  readonly input: unknown;
+  /** Why this case exists / what rule it exercises. */
+  readonly note: string;
+}
+
+/**
+ * The minimal validator contract the corpus tests. A conformant validator maps
+ * an untrusted value to an accept/reject decision via `{ ok }`.
+ * `validateMemoryRecord` (result form) adapts to this shape via
+ * {@link fromResultValidator}; the boolean `isMemoryRecord` conforms by wrapping
+ * its result — `(input) => ({ ok: isMemoryRecord(input) })`.
+ */
+export type ConformanceValidator = (input: unknown) => { readonly ok: boolean };
+
+/** The outcome of running one case through a validator. */
+export interface ConformanceCaseResult {
+  readonly case: ConformanceCase;
+  readonly expected: ConformanceExpectation;
+  readonly actual: ConformanceExpectation;
+  readonly passed: boolean;
+}
+
+/** The aggregate report from {@link runConformance}. */
+export interface ConformanceReport {
+  readonly total: number;
+  readonly passed: number;
+  readonly failed: number;
+  readonly results: readonly ConformanceCaseResult[];
+  readonly failures: readonly ConformanceCaseResult[];
+}
+
+// ---------------------------------------------------------------------------
+// Corpus construction
+// ---------------------------------------------------------------------------
+
+interface Triple {
+  readonly mode: string;
+  readonly provenance: string;
+  readonly authority: string;
+}
+
+/**
+ * Every (provenance, mode, authority) triple that is VALID by the schema
+ * invariants. Instantiated across all scopes below, this covers every
+ * scope × provenance × mode combination that a well-formed record can take.
+ */
+const VALID_TRIPLES: readonly Triple[] = [
+  { provenance: "human", mode: "normative", authority: "hypothesis" },
+  { provenance: "human", mode: "normative", authority: "authoritative" },
+  { provenance: "human", mode: "empirical", authority: "hypothesis" },
+  { provenance: "human", mode: "empirical", authority: "authoritative" },
+  { provenance: "agent-retro", mode: "normative", authority: "hypothesis" },
+  { provenance: "agent-retro", mode: "empirical", authority: "hypothesis" },
+  { provenance: "measured", mode: "empirical", authority: "authoritative" },
+  { provenance: "instance", mode: "empirical", authority: "authoritative" },
+];
+
+/**
+ * Every (provenance, mode, authority) triple that MUST be rejected by the
+ * invariants, with the rule it violates. The first two are the headline
+ * hypothesis-never-fix invariant (agent-retro can never be authoritative).
+ */
+const INVALID_TRIPLES: readonly (Triple & { readonly why: string })[] = [
+  { provenance: "agent-retro", mode: "normative", authority: "authoritative", why: "hypothesis-never-fix: agent-retro can never be authoritative" },
+  { provenance: "agent-retro", mode: "empirical", authority: "authoritative", why: "hypothesis-never-fix: agent-retro can never be authoritative" },
+  { provenance: "measured", mode: "empirical", authority: "hypothesis", why: "measured must be authoritative" },
+  { provenance: "measured", mode: "normative", authority: "authoritative", why: "measured must be empirical, not normative" },
+  { provenance: "instance", mode: "empirical", authority: "hypothesis", why: "instance must be authoritative" },
+  { provenance: "instance", mode: "normative", authority: "authoritative", why: "instance must be empirical, not normative" },
+];
+
+function baseRecord(scope: string, triple: Triple): Record<string, unknown> {
+  return {
+    schemaVersion: MEMORY_RECORD_SCHEMA_VERSION,
+    id: `rec-${scope}-${triple.provenance}-${triple.mode}-${triple.authority}`,
+    scope,
+    mode: triple.mode,
+    provenance: triple.provenance,
+    authority: triple.authority,
+    statement: `example ${triple.mode} ${triple.provenance} record at ${scope} scope`,
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+function buildCombinationalCases(): readonly ConformanceCase[] {
+  const cases: ConformanceCase[] = [];
+  for (const scope of SCOPE_LADDER) {
+    for (const triple of VALID_TRIPLES) {
+      cases.push({
+        name: `accept ${scope}/${triple.mode}/${triple.provenance}/${triple.authority}`,
+        expect: "accept",
+        input: baseRecord(scope, triple),
+        note: "well-formed record; valid vocabulary + consistent invariants",
+      });
+    }
+    for (const triple of INVALID_TRIPLES) {
+      cases.push({
+        name: `reject ${scope}/${triple.mode}/${triple.provenance}/${triple.authority}`,
+        expect: "reject",
+        input: baseRecord(scope, triple),
+        note: triple.why,
+      });
+    }
+  }
+  return cases;
+}
+
+/** Structural / vocabulary-drift rejects that are independent of scope. */
+const STRUCTURAL_CASES: readonly ConformanceCase[] = [
+  { name: "reject non-object (number)", expect: "reject", input: 42, note: "record must be an object" },
+  { name: "reject non-object (null)", expect: "reject", input: null, note: "record must be an object" },
+  { name: "reject non-object (array)", expect: "reject", input: [], note: "record must be a plain object, not an array" },
+  {
+    name: "reject unsupported schemaVersion",
+    expect: "reject",
+    input: { schemaVersion: 2, id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "schemaVersion must be exactly 1",
+  },
+  {
+    name: "reject missing schemaVersion",
+    expect: "reject",
+    input: { id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "schemaVersion is required",
+  },
+  {
+    name: "reject missing id",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "id is required",
+  },
+  {
+    name: "reject empty statement",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "statement must be non-empty",
+  },
+  {
+    name: "reject drifted scope vocabulary",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "galaxy", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "scope must be in the ladder vocabulary",
+  },
+  {
+    name: "reject drifted mode vocabulary",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "prescriptive", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "mode must be normative|empirical",
+  },
+  {
+    name: "reject drifted provenance vocabulary",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "robot", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "provenance must be in the vocabulary",
+  },
+  {
+    name: "reject drifted authority vocabulary",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "supreme", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "authority must be hypothesis|authoritative",
+  },
+  {
+    name: "reject non-ISO timestamp",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "yesterday" },
+    note: "createdAt must be ISO-8601",
+  },
+  {
+    name: "reject wrong-typed id",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: 123, scope: "repo", mode: "empirical", provenance: "human", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z" },
+    note: "id must be a string",
+  },
+  {
+    name: "reject wrong-typed evidence",
+    expect: "reject",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "repo", mode: "empirical", provenance: "measured", authority: "authoritative", statement: "s", createdAt: "2026-01-01T00:00:00.000Z", evidence: "not-an-array" },
+    note: "evidence, if present, must be a string array",
+  },
+  {
+    name: "accept well-formed measured record with evidence + optionals",
+    expect: "accept",
+    input: { schemaVersion: MEMORY_RECORD_SCHEMA_VERSION, id: "x", scope: "instance", scopeRef: "elem-7", subject: "latency", mode: "empirical", provenance: "measured", authority: "authoritative", statement: "p99 improved", createdAt: "2026-01-01T00:00:00.000Z", evidence: ["run-1", "run-2"], supersedes: "rec-old" },
+    note: "optional fields accepted when well-typed",
+  },
+];
+
+/**
+ * The full conformance corpus: exhaustive scope × valid/invalid triples, plus
+ * structural and vocabulary-drift cases. Deterministic and stable — treat it as
+ * the versioned contract fixture both producer and consumer are held to.
+ */
+export const corpus: readonly ConformanceCase[] = [...buildCombinationalCases(), ...STRUCTURAL_CASES];
+
+/** The subset of the corpus that must be accepted. */
+export const validFixtures: readonly ConformanceCase[] = corpus.filter((c) => c.expect === "accept");
+
+/** The subset of the corpus that must be rejected. */
+export const invalidFixtures: readonly ConformanceCase[] = corpus.filter((c) => c.expect === "reject");
+
+// ---------------------------------------------------------------------------
+// The runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Adapt a `{ ok } | { ... }`-returning validator (like `validateMemoryRecord`)
+ * to the {@link ConformanceValidator} shape. Any function returning an object
+ * with a boolean `ok` already conforms; this is a typed identity helper.
+ */
+export function fromResultValidator(validate: (input: unknown) => { readonly ok: boolean }): ConformanceValidator {
+  return (input: unknown) => ({ ok: validate(input).ok });
+}
+
+/**
+ * Run `validate` against the corpus (or a supplied subset) and return a
+ * structured report. Pure: does not throw and does not depend on a test runner.
+ */
+export function runConformance(
+  validate: ConformanceValidator,
+  cases: readonly ConformanceCase[] = corpus,
+): ConformanceReport {
+  const results: ConformanceCaseResult[] = cases.map((c) => {
+    // A validator that throws (even accidentally) must not crash the run: treat
+    // a throw as a rejection so the runner stays pure and the doc above holds.
+    let ok: boolean;
+    try {
+      ok = validate(c.input).ok;
+    } catch {
+      ok = false;
+    }
+    const actual: ConformanceExpectation = ok ? "accept" : "reject";
+    return { case: c, expected: c.expect, actual, passed: actual === c.expect };
+  });
+  const failures = results.filter((r) => !r.passed);
+  return {
+    total: results.length,
+    passed: results.length - failures.length,
+    failed: failures.length,
+    results,
+    failures,
+  };
+}
+
+/**
+ * Assert full conformance: throws with a readable summary if any case fails.
+ * Consumers can call this in their own test suite to be held to the contract.
+ */
+export function assertConformance(validate: ConformanceValidator, cases: readonly ConformanceCase[] = corpus): void {
+  const report = runConformance(validate, cases);
+  if (report.failed > 0) {
+    const detail = report.failures
+      .map((f) => `  - ${f.case.name}: expected ${f.expected}, got ${f.actual} (${f.case.note})`)
+      .join("\n");
+    throw new Error(`conformance failed: ${report.failed}/${report.total} case(s):\n${detail}`);
+  }
+}