eval-quality 0.1.0

package/dist/core/schemas/probe-policy.d.ts

@@ -0,0 +1,76 @@
+/** AD-35's default-deny target authorization, as a declared mapping. */
+import { z } from 'zod';
+/**
+ * One authorized target. AD-35: "An adapter denies by default and permits only
+ * what that mapping names." Every field is required and none has a default:
+ * an omitted cap is an unbounded cap, which is the failure this declaration
+ * exists to prevent.
+ */
+export declare const ProbeTargetAuthorization: z.ZodObject<{
+    interfaceId: z.ZodString;
+    scheme: z.ZodEnum<{
+        http: "http";
+        https: "https";
+    }>;
+    host: z.ZodString;
+    port: z.ZodInt;
+    addresses: z.ZodArray<z.ZodString>;
+    methods: z.ZodArray<z.ZodEnum<{
+        DELETE: "DELETE";
+        GET: "GET";
+        HEAD: "HEAD";
+        OPTIONS: "OPTIONS";
+        PATCH: "PATCH";
+        POST: "POST";
+        PUT: "PUT";
+    }>>;
+    safeMethods: z.ZodArray<z.ZodEnum<{
+        DELETE: "DELETE";
+        GET: "GET";
+        HEAD: "HEAD";
+        OPTIONS: "OPTIONS";
+        PATCH: "PATCH";
+        POST: "POST";
+        PUT: "PUT";
+    }>>;
+    maxRedirects: z.ZodInt;
+    maxElapsedMs: z.ZodInt;
+    maxRequestBytes: z.ZodInt;
+    maxResponseBytes: z.ZodInt;
+}, z.core.$strict>;
+export declare const ProbeTargetPolicy: z.ZodObject<{
+    authorizations: z.ZodArray<z.ZodObject<{
+        interfaceId: z.ZodString;
+        scheme: z.ZodEnum<{
+            http: "http";
+            https: "https";
+        }>;
+        host: z.ZodString;
+        port: z.ZodInt;
+        addresses: z.ZodArray<z.ZodString>;
+        methods: z.ZodArray<z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            HEAD: "HEAD";
+            OPTIONS: "OPTIONS";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>>;
+        safeMethods: z.ZodArray<z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            HEAD: "HEAD";
+            OPTIONS: "OPTIONS";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>>;
+        maxRedirects: z.ZodInt;
+        maxElapsedMs: z.ZodInt;
+        maxRequestBytes: z.ZodInt;
+        maxResponseBytes: z.ZodInt;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ProbeTargetAuthorization = z.infer<typeof ProbeTargetAuthorization>;
+export type ProbeTargetPolicy = z.infer<typeof ProbeTargetPolicy>;

package/dist/core/schemas/probe-policy.js

@@ -0,0 +1,33 @@
+/** AD-35's default-deny target authorization, as a declared mapping. */
+import { z } from 'zod';
+import { HttpMethod } from './interface.js';
+import { Identifier } from './primitives.js';
+/**
+ * One authorized target. AD-35: "An adapter denies by default and permits only
+ * what that mapping names." Every field is required and none has a default:
+ * an omitted cap is an unbounded cap, which is the failure this declaration
+ * exists to prevent.
+ */
+export const ProbeTargetAuthorization = z.strictObject({
+    interfaceId: Identifier.describe('The logical identifier the contract names. This mapping is where it becomes a target, outside the contract.'),
+    scheme: z.enum(['http', 'https']),
+    host: z.string().min(1),
+    port: z.int().min(1).max(65535),
+    addresses: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('The exact resolved addresses this authorization permits, compared after parsing rather than as strings. AD-35 requires every resolved address and every redirect to be revalidated, and requires a loopback, private, link-local, or metadata address to be authorized explicitly rather than by class, so the authorization names addresses rather than a range.'),
+    methods: z.array(HttpMethod).min(1),
+    safeMethods: z
+        .array(HttpMethod)
+        .describe('AD-35: "Differential body-sensitivity probes use only methods the mapping marks safe for that target." Empty is legal and means no method is safe for a differential here; it is not a synonym for "all of them".'),
+    maxRedirects: z.int().min(0),
+    maxElapsedMs: z.int().min(1),
+    maxRequestBytes: z.int().min(1),
+    maxResponseBytes: z.int().min(1),
+});
+export const ProbeTargetPolicy = z.strictObject({
+    authorizations: z
+        .array(ProbeTargetAuthorization)
+        .describe('An empty array is legal and authorizes nothing, which is the default-deny base case and must stay representable.'),
+});

package/dist/core/schemas/probe.d.ts

@@ -0,0 +1,189 @@
+/** a corpus probe: its class, its control status, and the defects it seeds. */
+import { z } from 'zod';
+/**
+ * AD-9's closed four, one per probe, in scope because AD-7's strength vector
+ * is keyed by probe class and needs this vocabulary. AD-7's exclusion rule
+ * reads directly off this field and `expectedClean`: canary probes and clean
+ * controls never enter the vector.
+ */
+export declare const PROBE_CLASSES: readonly ['defect', 'gameability', 'zero-action', 'canary'];
+export declare const ProbeClass: z.ZodEnum<{
+    canary: "canary";
+    defect: "defect";
+    gameability: "gameability";
+    "zero-action": "zero-action";
+}>;
+/** the prior art's six-field seeded defect, carried unchanged. */
+export declare const Defect: z.ZodObject<{
+    defectId: z.ZodString;
+    behaviorId: z.ZodString;
+    summary: z.ZodString;
+    severity: z.ZodEnum<{
+        critical: "critical";
+        low: "low";
+        material: "material";
+    }>;
+    oracleEvidence: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        storage: z.ZodLiteral<"public">;
+        path: z.ZodString;
+        privateRef: z.ZodNull;
+        digest: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        storage: z.ZodLiteral<"private">;
+        path: z.ZodNull;
+        privateRef: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>], "storage">>;
+    source: z.ZodEnum<{
+        "controlled-mutation": "controlled-mutation";
+        natural: "natural";
+    }>;
+    manifestationWitness: z.ZodNullable<z.ZodObject<{
+        legId: z.ZodString;
+        interfaceId: z.ZodString;
+        operationId: z.ZodString;
+        inputs: z.ZodObject<{
+            path: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
+            query: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
+            header: z.ZodRecord<z.ZodString, z.ZodString>;
+            body: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"json">;
+                value: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"absent">;
+            }, z.core.$strict>], "kind">;
+        }, z.core.$strict>;
+        relation: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * The prior art's `expectedClean` conditional, re-expressed as a discriminated
+ * union per AD-13 (a boolean literal discriminator parses on this pin,
+ * verified).
+ *
+ * `expectedClean: true` marks a clean control: AD-9's reason for the boolean
+ * is "ratifying the prior art's record-level field rather than adding a fifth
+ * class".
+ */
+export declare const Probe: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    schemaVersion: z.ZodInt;
+    parentDigest: z.ZodNullable<z.ZodString>;
+    revisionCount: z.ZodInt;
+    probeId: z.ZodString;
+    probeClass: z.ZodEnum<{
+        canary: "canary";
+        defect: "defect";
+        gameability: "gameability";
+        "zero-action": "zero-action";
+    }>;
+    behaviorId: z.ZodString;
+    systemId: z.ZodString;
+    implementationDigest: z.ZodString;
+    artifactDigest: z.ZodString;
+    commitDigest: z.ZodString;
+    rationale: z.ZodString;
+    expectedClean: z.ZodLiteral<true>;
+    defects: z.ZodArray<z.ZodObject<{
+        defectId: z.ZodString;
+        behaviorId: z.ZodString;
+        summary: z.ZodString;
+        severity: z.ZodEnum<{
+            critical: "critical";
+            low: "low";
+            material: "material";
+        }>;
+        oracleEvidence: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            storage: z.ZodLiteral<"public">;
+            path: z.ZodString;
+            privateRef: z.ZodNull;
+            digest: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            storage: z.ZodLiteral<"private">;
+            path: z.ZodNull;
+            privateRef: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>], "storage">>;
+        source: z.ZodEnum<{
+            "controlled-mutation": "controlled-mutation";
+            natural: "natural";
+        }>;
+        manifestationWitness: z.ZodNullable<z.ZodObject<{
+            legId: z.ZodString;
+            interfaceId: z.ZodString;
+            operationId: z.ZodString;
+            inputs: z.ZodObject<{
+                path: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
+                query: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
+                header: z.ZodRecord<z.ZodString, z.ZodString>;
+                body: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"json">;
+                    value: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"absent">;
+                }, z.core.$strict>], "kind">;
+            }, z.core.$strict>;
+            relation: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    schemaVersion: z.ZodInt;
+    parentDigest: z.ZodNullable<z.ZodString>;
+    revisionCount: z.ZodInt;
+    probeId: z.ZodString;
+    probeClass: z.ZodEnum<{
+        canary: "canary";
+        defect: "defect";
+        gameability: "gameability";
+        "zero-action": "zero-action";
+    }>;
+    behaviorId: z.ZodString;
+    systemId: z.ZodString;
+    implementationDigest: z.ZodString;
+    artifactDigest: z.ZodString;
+    commitDigest: z.ZodString;
+    rationale: z.ZodString;
+    expectedClean: z.ZodLiteral<false>;
+    defects: z.ZodArray<z.ZodObject<{
+        defectId: z.ZodString;
+        behaviorId: z.ZodString;
+        summary: z.ZodString;
+        severity: z.ZodEnum<{
+            critical: "critical";
+            low: "low";
+            material: "material";
+        }>;
+        oracleEvidence: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            storage: z.ZodLiteral<"public">;
+            path: z.ZodString;
+            privateRef: z.ZodNull;
+            digest: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            storage: z.ZodLiteral<"private">;
+            path: z.ZodNull;
+            privateRef: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>], "storage">>;
+        source: z.ZodEnum<{
+            "controlled-mutation": "controlled-mutation";
+            natural: "natural";
+        }>;
+        manifestationWitness: z.ZodNullable<z.ZodObject<{
+            legId: z.ZodString;
+            interfaceId: z.ZodString;
+            operationId: z.ZodString;
+            inputs: z.ZodObject<{
+                path: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
+                query: z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>;
+                header: z.ZodRecord<z.ZodString, z.ZodString>;
+                body: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"json">;
+                    value: z.ZodType<import("./primitives.ts").JsonValue, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonValue, unknown>>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"absent">;
+                }, z.core.$strict>], "kind">;
+            }, z.core.$strict>;
+            relation: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "expectedClean">;
+export type Probe = z.infer<typeof Probe>;

package/dist/core/schemas/probe.js

@@ -0,0 +1,82 @@
+/** a corpus probe: its class, its control status, and the defects it seeds. */
+import { z } from 'zod';
+import { ArtifactReference } from './artifact-reference.js';
+import { Severity } from './eval-contract.js';
+import { lineageFields } from './lineage.js';
+import { BehaviorId, DefectId, Digest, ProbeId } from './primitives.js';
+import { ManifestationWitness } from './sensitivity-witness.js';
+/**
+ * AD-9's closed four, one per probe, in scope because AD-7's strength vector
+ * is keyed by probe class and needs this vocabulary. AD-7's exclusion rule
+ * reads directly off this field and `expectedClean`: canary probes and clean
+ * controls never enter the vector.
+ */
+export const PROBE_CLASSES = [
+    'defect',
+    'gameability',
+    'zero-action',
+    'canary',
+];
+export const ProbeClass = z.enum(PROBE_CLASSES);
+/** the prior art's six-field seeded defect, carried unchanged. */
+export const Defect = z.strictObject({
+    defectId: DefectId,
+    behaviorId: BehaviorId.describe('The behaviour this defect breaks. AD-9 also puts a behaviour on the probe itself and this schema carries both; that the two may disagree is a cross-field rule with no AD-5 code and is left unenforced in v0 rather than silently refined here.'),
+    summary: z.string().min(1),
+    severity: Severity,
+    oracleEvidence: z.array(ArtifactReference),
+    source: z.enum(['natural', 'controlled-mutation']),
+    manifestationWitness: ManifestationWitness.nullable().describe("AD-10: what pre-flight probes to observe this defect fire. `null` parses, so the prior art's six-field defect still round-trips, and pre-flight records a null witness as a **failed** `seeded-fault-fired` check rather than as an exemption. A seeded fault that cannot be observed to fire is the vacuous probe AD-40 resolves to `infrastructure-error`, and pre-flight is the one place where invalidating is the cheap outcome."),
+});
+// Shared by both branches of the `expectedClean` union. AD-9's per-probe
+// `artifactDigest` and `commitDigest` sit at the root here, matching the prior
+// art's record-level `implementationSha`: one spelling instead of five.
+const probeCommonFields = {
+    ...lineageFields,
+    probeId: ProbeId,
+    probeClass: ProbeClass,
+    behaviorId: BehaviorId.describe('AD-9 puts the behaviour on the probe. The prior art put one on each seeded defect only, and this schema carries both.'),
+    systemId: z
+        .string()
+        .min(1)
+        .describe('An opaque caller label for the system under test.'),
+    implementationDigest: Digest.describe("The prior art's `implementationSha`, renamed against the shared AD-27 primitive. An AD-24 divergence."),
+    artifactDigest: Digest,
+    commitDigest: Digest,
+    rationale: z.string().min(1),
+};
+/**
+ * The prior art's `expectedClean` conditional, re-expressed as a discriminated
+ * union per AD-13 (a boolean literal discriminator parses on this pin,
+ * verified).
+ *
+ * `expectedClean: true` marks a clean control: AD-9's reason for the boolean
+ * is "ratifying the prior art's record-level field rather than adding a fifth
+ * class".
+ */
+export const Probe = z
+    .discriminatedUnion('expectedClean', [
+    z
+        .strictObject({
+        ...probeCommonFields,
+        expectedClean: z.literal(true),
+        defects: z
+            .array(Defect)
+            .max(0)
+            .describe("A known-clean control seeds nothing, which is the prior art's own `if`/`then` expressed structurally."),
+    })
+        .describe("A known-clean control. Never enters AD-7's dominance vector."),
+    z
+        .strictObject({
+        ...probeCommonFields,
+        expectedClean: z.literal(false),
+        defects: z
+            .array(Defect)
+            .describe('No minimum. AD-9 states none, and a minimum would make a canary unrepresentable, since a canary indicts the fixture rather than seeding a defect.'),
+    })
+        .describe('A probe that is not a known-clean control.'),
+])
+    .meta({
+    id: 'Probe',
+    description: "One corpus probe. Succeeds the prior-art `h0-ground-truth` schema per AD-24, carrying its system identifier, implementation digest, `expectedClean` flag, seeded defects, and rationale, and adding AD-9's probe class and AD-9's per-probe artifact and commit digests. Divergences: `implementationSha` becomes `implementationDigest`, `taskId` does not survive because the probe pins what it describes by digest, and `expectedGate` does not survive because AD-40 makes detection a signature match rather than a verdict comparison and AD-7 keeps comparisons inside the dominance vector, so carrying an expected gate would invite a comparison the architecture forbids. Two constructions are deliberately absent: AD-9's per-class QUALIFICATION record, whose five prose routes name no fields and whose acceptance criteria of record do not command it, and AD-40's machine-readable DEFECT SIGNATURE, which Owed item 7 records as having no fixture to land in because this repository contains no probe at all. Both arrive as additive `schemaVersion` bumps under AD-11 once a corpus exists to carry them. The cost is named rather than hidden: AD-9's \"an unqualified probe cannot enter a sealed set\" is enforced by nothing in v0: not this schema, not an AD-5 code, and not an AD-21 rung.",
+});

package/dist/core/schemas/publish.d.ts

@@ -0,0 +1,30 @@
+import { type InterchangeArtifactKey } from './artifact.ts';
+import { type ConstraintLedgerEntry } from './constraint-ledger.ts';
+/**
+ * A URN rather than an `https://` locator: every document is self-contained
+ * with local `#/$defs/...` references only, so the base never needs to
+ * resolve. The version is deliberately absent: `schemaVersion` is the in-band
+ * field, and AD-11's additive-bump discipline keeps this identifier stable
+ * across bumps.
+ */
+export declare const publishedSchemaId: (key: InterchangeArtifactKey) => string;
+export declare const injectConstraint: (document: Record<string, unknown>, entry: ConstraintLedgerEntry) => void;
+/**
+ * The one pure builder (AD-13): output mode, because published schemas
+ * describe artifacts as consumers receive them, though
+ * `tests/schemas/artifact-registry.test.ts` asserts all twelve export
+ * byte-identically in both modes either way. Zod emits no `$id` at any level,
+ * so it is synthesised here, second after `$schema`, with Zod's own key order
+ * unchanged after it.
+ */
+export declare const publishedDocument: (key: InterchangeArtifactKey) => Record<string, unknown>;
+/** all twelve, keyed by registry key; the registry is the only list walked. */
+export declare const publishedDocuments: () => Record<InterchangeArtifactKey, Record<string, unknown>>;
+/**
+ * The exact byte form of a published document, shared by the generator and the
+ * drift check so the two cannot disagree: 2-space indent, one trailing newline,
+ * and every code unit above U+007F escaped as `\uXXXX` so the committed files
+ * are pure ASCII. The test fixtures follow the same rule, which removes one
+ * byte-level encoding variable from a byte-exact comparison.
+ */
+export declare const serializePublishedDocument: (document: Record<string, unknown>) => string;

package/dist/core/schemas/publish.js

@@ -0,0 +1,135 @@
+/** the published JSON Schema export: twelve self-contained documents. */
+import { z } from 'zod';
+import { INTERCHANGE_ARTIFACT_KEYS, INTERCHANGE_ARTIFACTS, } from './artifact.js';
+import { CONSTRAINT_LEDGER, } from './constraint-ledger.js';
+// Downstream of every schema module and the constraint ledger; no module
+// under `src/core/schemas/` may import it back, or the cycle fails at load
+// with a temporal-dead-zone ReferenceError. Pure (AD-1): no filesystem,
+// network, clock, randomness, or validator import, so the runtime dependency
+// stays Zod alone.
+/**
+ * A URN rather than an `https://` locator: every document is self-contained
+ * with local `#/$defs/...` references only, so the base never needs to
+ * resolve. The version is deliberately absent: `schemaVersion` is the in-band
+ * field, and AD-11's additive-bump discipline keeps this identifier stable
+ * across bumps.
+ */
+export const publishedSchemaId = (key) => `urn:eval-quality:schema:${key}`;
+const unresolved = (entry, segment) => new Error(`constraint "${entry.id}" does not resolve: ${segment}. ` +
+    'A silently skipped injection is the failure AD-13 exists to prevent, so this is a throw rather than a warning.');
+const isNode = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** the branch's discriminator const, or undefined where the shape has none. */
+const opConstOf = (candidate) => {
+    if (!isNode(candidate) || !isNode(candidate.properties))
+        return undefined;
+    const op = candidate.properties.op;
+    return isNode(op) ? op.const : undefined;
+};
+const propertyOf = (candidate, field) => isNode(candidate) && isNode(candidate.properties)
+    ? candidate.properties[field]
+    : undefined;
+export const injectConstraint = (document, entry) => {
+    if (entry.disposition.kind !== 'inject')
+        throw unresolved(entry, 'its disposition is not "inject"');
+    // `items: false` bounds a tuple only beside 2020-12's `prefixItems`; under
+    // draft-7 the same injection overwrites the exported tuple and every operand
+    // list rejects everything. Read the field, never assume it.
+    if (entry.disposition.dialect !== 'draft-2020-12')
+        throw unresolved(entry, `dialect "${entry.disposition.dialect}" is not the export target "draft-2020-12"`);
+    const definitions = document.$defs;
+    const definition = entry.location.kind === 'root'
+        ? document
+        : isNode(definitions)
+            ? definitions[entry.location.name]
+            : undefined;
+    if (!isNode(definition))
+        throw unresolved(entry, entry.location.kind === 'root'
+            ? 'the document root is not an object'
+            : `no definition named "${entry.location.name}"`);
+    const branches = Array.isArray(definition.oneOf)
+        ? definition.oneOf
+        : undefined;
+    // Matched rather than found: two branches carrying the same discriminator
+    // would make `find` inject into the first and skip the rest, which is the
+    // silent skip every other throw in this function exists to prevent.
+    const matched = entry.branch === null
+        ? undefined
+        : (branches?.filter((candidate) => opConstOf(candidate) === entry.branch) ?? []);
+    if (matched !== undefined && matched.length > 1)
+        throw unresolved(entry, `${matched.length} oneOf branches carry op const "${entry.branch}", so the address names more than one shape`);
+    const target = entry.branch === null ? definition : matched?.[0];
+    if (!isNode(target))
+        throw unresolved(entry, `no oneOf branch whose op const is "${entry.branch}"`);
+    // The union fallback, kept for parity with the resolver of record: a
+    // union-rooted shape exports `{ $schema, oneOf, description }` with no
+    // `properties` object, and the field is spread into every branch. The copies
+    // are equal by construction, but aliasing is neither guaranteed nor
+    // excluded, so assigning to just one would inject into a single branch and
+    // silently skip the rest.
+    const field = entry.field;
+    const targetBranches = Array.isArray(target.oneOf)
+        ? target.oneOf
+        : undefined;
+    const sites = field === null
+        ? [target]
+        : isNode(target.properties)
+            ? [target.properties[field]]
+            : targetBranches !== undefined && targetBranches.length > 0
+                ? targetBranches.map((branch) => propertyOf(branch, field))
+                : [undefined];
+    if (!sites.every(isNode))
+        throw unresolved(entry, `no property named "${entry.field}" at the located shape`);
+    // Deduped by object identity: where two branches DO alias one copy, writing
+    // through the first alias would make the second trip the no-overwrite guard
+    // below on a keyword this very call just planted.
+    for (const site of new Set(sites)) {
+        for (const [keyword, value] of Object.entries(entry.disposition.keywords)) {
+            // An injection never overwrites: a keyword already present means the
+            // export changed under the ledger, and clobbering it would hide that.
+            if (keyword in site)
+                throw unresolved(entry, `keyword "${keyword}" is already present at the site`);
+            site[keyword] = value;
+        }
+    }
+};
+/**
+ * The one pure builder (AD-13): output mode, because published schemas
+ * describe artifacts as consumers receive them, though
+ * `tests/schemas/artifact-registry.test.ts` asserts all twelve export
+ * byte-identically in both modes either way. Zod emits no `$id` at any level,
+ * so it is synthesised here, second after `$schema`, with Zod's own key order
+ * unchanged after it.
+ */
+export const publishedDocument = (key) => {
+    const exported = z.toJSONSchema(INTERCHANGE_ARTIFACTS[key].schema, {
+        io: 'output',
+    });
+    // Cloned before injection so mutation never reaches objects Zod may retain
+    // or share across toJSONSchema calls. structuredClone preserves aliasing
+    // within the cloned graph, which `injectConstraint`'s identity-based dedup
+    // (above) depends on.
+    const { $schema, ...rest } = structuredClone(exported);
+    const document = {
+        $schema,
+        $id: publishedSchemaId(key),
+        ...rest,
+    };
+    for (const entry of CONSTRAINT_LEDGER) {
+        if (entry.disposition.kind !== 'inject')
+            continue;
+        if (entry.location.artifact !== key)
+            continue;
+        injectConstraint(document, entry);
+    }
+    return document;
+};
+/** all twelve, keyed by registry key; the registry is the only list walked. */
+export const publishedDocuments = () => Object.fromEntries(INTERCHANGE_ARTIFACT_KEYS.map((key) => [key, publishedDocument(key)]));
+/**
+ * The exact byte form of a published document, shared by the generator and the
+ * drift check so the two cannot disagree: 2-space indent, one trailing newline,
+ * and every code unit above U+007F escaped as `\uXXXX` so the committed files
+ * are pure ASCII. The test fixtures follow the same rule, which removes one
+ * byte-level encoding variable from a byte-exact comparison.
+ */
+export const serializePublishedDocument = (document) => `${JSON.stringify(document, null, 2).replace(/[\u0080-\uffff]/g, (unit) => `\\u${unit.charCodeAt(0).toString(16).padStart(4, '0')}`)}\n`;

package/dist/core/schemas/reference-set.d.ts

@@ -0,0 +1,18 @@
+/** a declared reference set: what a collection is reconciled against. */
+import { z } from 'zod';
+/**
+ * AD-19 fixes members as objects rather than scalars: `covers-by-key`
+ * compares on named keys, and a `set-membership` operand against the same set
+ * reads the single named key, so one declared form serves both operators and
+ * needs no second field for AD-20's rule 6 injection form.
+ *
+ * Members are `JsonValue` objects per the Consistency Conventions' placement
+ * of them under "expression literals, declared reference-set members, and
+ * every ingested response body", which is why they are not a seventh
+ * caller-keyed control map.
+ */
+export declare const ReferenceSetDeclaration: z.ZodObject<{
+    keys: z.ZodArray<z.ZodString>;
+    members: z.ZodArray<z.ZodType<import("./primitives.ts").JsonObject, unknown, z.core.$ZodTypeInternals<import("./primitives.ts").JsonObject, unknown>>>;
+    commentary: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;

package/dist/core/schemas/reference-set.js

@@ -0,0 +1,27 @@
+/** a declared reference set: what a collection is reconciled against. */
+import { z } from 'zod';
+import { JsonObjectValue, KeyName } from './primitives.js';
+/**
+ * AD-19 fixes members as objects rather than scalars: `covers-by-key`
+ * compares on named keys, and a `set-membership` operand against the same set
+ * reads the single named key, so one declared form serves both operators and
+ * needs no second field for AD-20's rule 6 injection form.
+ *
+ * Members are `JsonValue` objects per the Consistency Conventions' placement
+ * of them under "expression literals, declared reference-set members, and
+ * every ingested response body", which is why they are not a seventh
+ * caller-keyed control map.
+ */
+export const ReferenceSetDeclaration = z.strictObject({
+    keys: z
+        .array(KeyName)
+        .min(1)
+        .describe('The key names members are compared on. A reference set with no keys names nothing to compare, and no AD-5 code fires on it, so the schema is the enforcement point.'),
+    members: z
+        .array(JsonObjectValue)
+        .describe('Objects carrying at least the declared keys. That they do is deliberately not refined: no AD-5 code names it, and a refinement would be invisible to a non-TypeScript consumer and become a disagreement in the published-schema differential check.'),
+    commentary: z
+        .string()
+        .nullable()
+        .describe("Author documentation. Named `commentary` rather than the Gate C fixture's `note` so the sealed brief has one word to exclude, matching the oracle field of the same name. No predicate reads it."),
+});

package/dist/core/schemas/rubric.d.ts

@@ -0,0 +1,62 @@
+/** the rubric body a contract embeds, and the published Rubric artifact. */
+import { z } from 'zod';
+export declare const ScaleLevel: z.ZodObject<{
+    level: z.ZodInt;
+    anchor: z.ZodString;
+}, z.core.$strict>;
+export declare const FailureModePenalty: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strict>;
+export declare const RubricCriterion: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+    evidence: z.ZodString;
+}, z.core.$strict>;
+/**
+ * The embeddable rubric body: the published `Rubric` artifact below adds
+ * `schemaVersion`, lineage, and a prior-art declaration on top of this.
+ */
+export declare const RubricBody: z.ZodObject<{
+    id: z.ZodString;
+    scaleLevels: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        level: z.ZodInt;
+        anchor: z.ZodString;
+    }, z.core.$strict>>>;
+    failureModePenalties: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>>;
+    maxLength: z.ZodNullable<z.ZodInt>;
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        evidence: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RubricBody = z.infer<typeof RubricBody>;
+/**
+ * The published Rubric artifact: `RubricBody` above, spread flat, plus
+ * AD-11's version and AD-29's lineage.
+ */
+export declare const Rubric: z.ZodObject<{
+    schemaVersion: z.ZodInt;
+    parentDigest: z.ZodNullable<z.ZodString>;
+    revisionCount: z.ZodInt;
+    id: z.ZodString;
+    scaleLevels: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        level: z.ZodInt;
+        anchor: z.ZodString;
+    }, z.core.$strict>>>;
+    failureModePenalties: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>>;
+    maxLength: z.ZodNullable<z.ZodInt>;
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        evidence: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Rubric = z.infer<typeof Rubric>;