eval-quality 2.0.0 → 3.1.0

package/README.md

@@ -179,7 +179,9 @@ import spec from 'eval-quality/schemas/eval-contract.schema.json' with { type: '
 
 The import attribute is required: ESM on Node 22 and 24 both throw `ERR_IMPORT_ATTRIBUTE_MISSING` without it. The development corpus ships the same way, at `eval-quality/corpus/dev/`, so you can read twenty-four real contracts and one compiled-and-sealed pair without cloning this repository.
 
-Version 1.0 is out and the published surface is stable: a breaking change to a command, an export, or a schema is a major version bump. `compile` refuses a contract whose `schemaVersion` differs from the one this build reads, so check the stamp on anything you did not author against this version. `CHANGELOG.md` records what each release breaks.
+**The repository gates** are a second binary, `eval-quality-gates`, which holds your own trees to rules you declare in one JSON file at your repository root. `lockfile-age` audits every entry of every lockfile you name against its real publication timestamp on the npm registry. `licences` holds every locked entry's licence expression against an allowlist of identifiers you declare. The file carries only the gates you have adopted, and a gate you invoke with no section for it refuses by name with no fallback to this package's own values. [Run the gates on your repository](https://bmad-code-org.github.io/bmad-eval-quality/how-to/run-the-gates-on-your-repository/) is the page for it.
+
+The published surface is stable: a breaking change to a command, an export, or a schema is a major version bump. `compile` refuses a contract whose `schemaVersion` differs from the one this build reads, and `preflight` and `score` refuse a probe the same way, so check the stamp on anything you did not author against this version. The library exports both numbers, `EVAL_CONTRACT_SCHEMA_VERSION` and `PROBE_SCHEMA_VERSION`, so the version to check against comes from the package. `CHANGELOG.md` records what each release breaks.
 
 ## Relationship with BMad and TEA
 
@@ -238,6 +240,7 @@ Several files are generated from the code and guarded byte for byte, so a hand e
 | `docs/ad31-coverage-predicates.generated.md`, the coverage predicates | `npm run generate:ad31-table` | `npm run check:ad31-table` |
 | `docs/ad33-outcome-decision.generated.md`, the outcome decision procedure | `npm run generate:ad33-table` | `npm run check:ad33-table` |
 | the three committed worked chains | `npm run generate:worked-example` | `npm run check:worked-example` |
+| `VERSION` in `src/index.ts`, from `package.json` | `npm run generate:version` | `npm run check:version` |
 | `_bmad-output/shareable/`, this README, CONTRIBUTING, and the planning artifacts as standalone HTML | `npm run build:shareable` | `npm run check:shareable` |
 
 Every artifact the library hands back is deep-frozen. A revision is a new artifact carrying its parent's digest and a revision count one greater, and `npm run check:lineage` fails the build when a lineage field is written outside the modules that own it. `npm run check:boundary` fails it when anything the tarball carries references the planning system that produced it.

package/dist/application/index.d.ts

@@ -11,12 +11,16 @@ export { FAILURE_CODES, StructuralFailure } from '../core/failure-codes.ts';
 export type { LineageChainReport, LineageFinding, } from '../core/lineage/chain.ts';
 export { validateLineageChain } from '../core/lineage/chain.ts';
 export { INTERCHANGE_ARTIFACT_KEYS } from '../core/schemas/artifact.ts';
+export type { Severity } from '../core/schemas/eval-contract.ts';
+export { SEVERITY_LEVELS } from '../core/schemas/eval-contract.ts';
 export type { RuntimeFaultCode } from '../core/schemas/faults.ts';
 export { RUNTIME_FAULT_CODES, RuntimeFault } from '../core/schemas/faults.ts';
 export type { EvaluatorRecommendation, Verdict, } from '../core/schemas/verdict.ts';
 export { EVALUATOR_RECOMMENDATIONS, VERDICTS, } from '../core/schemas/verdict.ts';
 export type { QualificationFailure, QualificationFailureCode, QualificationResult, } from '../core/score/qualification.ts';
 export { QUALIFICATION_FAILURES } from '../core/score/qualification.ts';
+export type { ComparableResult, DominanceRelationValue, } from '../core/score/strength.ts';
+export { compareDominance, DOMINANCE_RELATIONS, } from '../core/score/strength.ts';
 export { compile } from './compile.ts';
 export type { Diagnostic, DiagnosticSink } from './diagnostics.ts';
 export type { PreflightFromObservationsOptions, RunPreflightOptions, } from './preflight.ts';

package/dist/application/index.js

@@ -9,9 +9,11 @@ export { digestArtifact, digestBytes, digestComposite, } from '../core/canonical
 export { FAILURE_CODES, StructuralFailure } from '../core/failure-codes.js';
 export { validateLineageChain } from '../core/lineage/chain.js';
 export { INTERCHANGE_ARTIFACT_KEYS } from '../core/schemas/artifact.js';
+export { SEVERITY_LEVELS } from '../core/schemas/eval-contract.js';
 export { RUNTIME_FAULT_CODES, RuntimeFault } from '../core/schemas/faults.js';
 export { EVALUATOR_RECOMMENDATIONS, VERDICTS, } from '../core/schemas/verdict.js';
 export { QUALIFICATION_FAILURES } from '../core/score/qualification.js';
+export { compareDominance, DOMINANCE_RELATIONS, } from '../core/score/strength.js';
 export { compile } from './compile.js';
 export { preflightFromObservations, runPreflight } from './preflight.js';
 export { runScore } from './score.js';

package/dist/core/compile/compile.js

@@ -55,7 +55,12 @@ export function compile(contract, options) {
     // First, and before any check reads a declaration. AD-11 makes an unequal
     // stamp a rejection rather than a degraded read, and every check below is
     // written against this version's field shapes.
-    checkSchemaVersion(contract.schemaVersion, EVAL_CONTRACT_SCHEMA_VERSION, 'EvalContract.schemaVersion');
+    checkSchemaVersion({
+        stamped: contract.schemaVersion,
+        accepted: EVAL_CONTRACT_SCHEMA_VERSION,
+        artifactPath: 'EvalContract.schemaVersion',
+        consequence: 'since its stale version would travel into the scoring version',
+    });
     checkRequirementLinkage(contract);
     checkObservableSuccessCriterion(contract);
     // Ahead of reachability, because a pointer naming an artifact nothing

package/dist/core/compile/schema-version.d.ts

@@ -1,2 +1,15 @@
-/** `schema-version-mismatch`: the stamp is not the version this build reads. */
-export declare function checkSchemaVersion(stamped: number, accepted: number, artifactPath: string): void;
+/**
+ * `schema-version-mismatch`: the stamp is not the version this build reads.
+ *
+ * An options object rather than four positional arguments. `artifactPath` and
+ * `consequence` are both free-form strings, and transposed they typecheck: the
+ * fault's `artifactPath`, which callers read programmatically, would then hold
+ * a sentence.
+ */
+export declare function checkSchemaVersion(options: {
+    readonly stamped: number;
+    readonly accepted: number;
+    readonly artifactPath: string;
+    /** Why an unequal stamp is a rejection for this artifact, as a clause. */
+    readonly consequence: string;
+}): void;

package/dist/core/compile/schema-version.js

@@ -17,9 +17,17 @@
  * happened to notice first.
  */
 import { RuntimeFault } from '../schemas/faults.js';
-/** `schema-version-mismatch`: the stamp is not the version this build reads. */
-export function checkSchemaVersion(stamped, accepted, artifactPath) {
+/**
+ * `schema-version-mismatch`: the stamp is not the version this build reads.
+ *
+ * An options object rather than four positional arguments. `artifactPath` and
+ * `consequence` are both free-form strings, and transposed they typecheck: the
+ * fault's `artifactPath`, which callers read programmatically, would then hold
+ * a sentence.
+ */
+export function checkSchemaVersion(options) {
+    const { stamped, accepted, artifactPath, consequence } = options;
     if (stamped === accepted)
         return;
-    throw new RuntimeFault('schema-version-mismatch', artifactPath, `carries "schemaVersion" ${stamped} where this build reads ${accepted}; a contract written for another version is not read leniently, since its stale version would travel into the scoring version (AD-11)`);
+    throw new RuntimeFault('schema-version-mismatch', artifactPath, `carries "schemaVersion" ${stamped} where this build reads ${accepted}; an artifact written for another version is not read leniently, ${consequence} (AD-11)`);
 }

package/dist/core/emit/emit.js

@@ -11,7 +11,7 @@
  */
 import { digestArtifact } from '../canonical/digest.js';
 import { freezeArtifact } from '../lineage/freeze.js';
-import { EvidenceArtifact, } from '../schemas/evidence-artifact.js';
+import { EVIDENCE_ARTIFACT_SCHEMA_VERSION, EvidenceArtifact, } from '../schemas/evidence-artifact.js';
 import { checkModeAgreement } from '../score/mode-agreement.js';
 import { buildStrengthVector } from '../score/strength.js';
 const SCORING_POLICY_ARTIFACT_PATH = 'ScoringPolicy';
@@ -74,7 +74,9 @@ export const emit = (scored, corpusDigest, fixtureDigest, evaluatorConfiguration
     // re-checked a second time.
     const verdict = scored.ladder.verdict;
     const commonFields = {
-        schemaVersion: 3,
+        // Read from the evidence schema's own constant, so a bump is one edit
+        // beside the shape that moved.
+        schemaVersion: EVIDENCE_ARTIFACT_SCHEMA_VERSION,
         parentDigest: null,
         // v0 mints no revision path for an evidence artifact: every `emit`
         // call is a lineage root, matching `seal.ts`'s own root-artifact

package/dist/core/preflight/plan.js

@@ -9,11 +9,13 @@
  * identifier up in at reduce time.
  */
 import { isSupportedInterfaceKind, SUPPORTED_KINDS_CLAUSE, } from '../compile/interface-inventory.js';
+import { checkSchemaVersion } from '../compile/schema-version.js';
 import { checkInputsAgainstShape, isApiWitnessInputs, isMcpWitnessInputs, } from '../compile/sensitivity-witness.js';
 import { declaresNoRequiredKeys, isCommandOperation, isMcpOperation, } from '../declared-inputs.js';
 import { referenceSetKeysOf } from '../evaluate/evidence-resolution.js';
 import { StructuralFailure } from '../failure-codes.js';
 import { operationsOf } from '../schemas/interface.js';
+import { PROBE_SCHEMA_VERSION, PROBE_SCHEMA_VERSION_CONSEQUENCE, } from '../schemas/probe.js';
 import { referenceSetMembers } from './witness-evidence.js';
 const requestOf = (legId, interfaceId, operation, inputs) => {
     // NFR9's correlation by identifier: the port echoes these back, and they
@@ -202,6 +204,19 @@ const selectControl = (contract, permittedInterfaces) => {
  */
 export const planPreflight = (input) => {
     const { contract, probes, runId } = input;
+    // First, and before any check reads a probe. AD-11 makes an unequal stamp a
+    // rejection rather than a degraded read, and every rule below is written
+    // against this version's field shapes. `compile` performs the same check for
+    // the contract; this is the probe's reader, since a probe reaches no other
+    // core stage on the pre-flight path.
+    for (const probe of probes) {
+        checkSchemaVersion({
+            stamped: probe.schemaVersion,
+            accepted: PROBE_SCHEMA_VERSION,
+            artifactPath: `Probe[probeId=${probe.probeId}].schemaVersion`,
+            consequence: PROBE_SCHEMA_VERSION_CONSEQUENCE,
+        });
+    }
     for (const iface of contract.permittedInterfaces) {
         // Already thrown at compile; asserted again because the plan is
         // reachable from a caller who assembled a contract by hand. Reads the

package/dist/core/preflight/reduce.d.ts

@@ -1,5 +1,5 @@
 import type { ProbeObservation } from '../schemas/port-messages.ts';
-import type { PreflightVerdict } from '../schemas/preflight-verdict.ts';
+import { type PreflightVerdict } from '../schemas/preflight-verdict.ts';
 import type { ReduceStage } from '../stage-contracts.ts';
 import type { PreflightPlan } from './plan.ts';
 export type PreflightObservations = {

package/dist/core/preflight/reduce.js

@@ -11,6 +11,7 @@ import { digestArtifact } from '../canonical/digest.js';
 import { declaresNoRequestKeys } from '../declared-inputs.js';
 import { freezeArtifact } from '../lineage/freeze.js';
 import { RuntimeFault } from '../schemas/faults.js';
+import { PREFLIGHT_VERDICT_SCHEMA_VERSION, } from '../schemas/preflight-verdict.js';
 import { fixtureDigest, PREFLIGHT_ARTIFACT_PATH, projectObservation, } from './projection.js';
 import { evidenceOf, resolveWitnessRelation } from './witness-evidence.js';
 /**
@@ -297,8 +298,10 @@ export const reducePreflight = (plan, { observations }) => {
     const projections = [...states.values()].map((state) => state.projected);
     return freezeArtifact({
         // A pre-flight verdict is an origin artifact, so AD-29's lineage fields
-        // carry their origin values.
-        schemaVersion: 1,
+        // carry their origin values. The version is read from the verdict
+        // schema's own constant, so a bump is one edit beside the shape that
+        // moved.
+        schemaVersion: PREFLIGHT_VERDICT_SCHEMA_VERSION,
         parentDigest: null,
         revisionCount: 0,
         runId: plan.runId,

package/dist/core/schemas/evaluator-configuration.d.ts

@@ -12,6 +12,15 @@ export declare const JudgeConfiguration: z.ZodObject<{
     modelSnapshot: z.ZodString;
     systemPromptDigest: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * The configuration version this build accepts. No stage writes one, so a
+ * caller assembling a configuration had no value to read and transcribed the
+ * number.
+ *
+ * `1`: this artifact has never moved, so it has no predecessor shape and a
+ * parse-behaviour case over one would be vacuous.
+ */
+export declare const EVALUATOR_CONFIGURATION_SCHEMA_VERSION = 1;
 export declare const EvaluatorConfiguration: z.ZodObject<{
     schemaVersion: z.ZodInt;
     parentDigest: z.ZodNullable<z.ZodString>;

package/dist/core/schemas/evaluator-configuration.js

@@ -15,6 +15,15 @@ export const JudgeConfiguration = z.strictObject({
     modelSnapshot: z.string().min(1),
     systemPromptDigest: Digest.nullable().describe('`null` for a judge configured with no system prompt of its own. This is the only nullable member: the absent-judge state belongs to the field above, not to this shape.'),
 });
+/**
+ * The configuration version this build accepts. No stage writes one, so a
+ * caller assembling a configuration had no value to read and transcribed the
+ * number.
+ *
+ * `1`: this artifact has never moved, so it has no predecessor shape and a
+ * parse-behaviour case over one would be vacuous.
+ */
+export const EVALUATOR_CONFIGURATION_SCHEMA_VERSION = 1;
 export const EvaluatorConfiguration = z
     .strictObject({
     ...lineageFields,

package/dist/core/schemas/evidence-artifact.d.ts

@@ -270,6 +270,15 @@ export declare const Remediation: z.ZodObject<{
         noGap: z.ZodBoolean;
     }, z.core.$strict>;
 }, z.core.$strict>;
+/**
+ * The evidence version `emit` stamps, and the single place that number is
+ * written. It was a literal inside `emit`'s own assembly, so the value a
+ * consumer needed sat in a stage rather than beside the shape it names.
+ *
+ * `3` on two recorded bumps: `mode` made it 2 and `uncitedFindingGaps` made
+ * it 3, each in the field's own description above.
+ */
+export declare const EVIDENCE_ARTIFACT_SCHEMA_VERSION = 3;
 /**
  * A discriminated union, because AD-21 requires that no shape hold a
  * production verdict and a contract verdict at once, with neither mode able

package/dist/core/schemas/evidence-artifact.js

@@ -253,6 +253,15 @@ const evidenceCommonFields = {
     strength: Strength,
     remediation: Remediation,
 };
+/**
+ * The evidence version `emit` stamps, and the single place that number is
+ * written. It was a literal inside `emit`'s own assembly, so the value a
+ * consumer needed sat in a stage rather than beside the shape it names.
+ *
+ * `3` on two recorded bumps: `mode` made it 2 and `uncitedFindingGaps` made
+ * it 3, each in the field's own description above.
+ */
+export const EVIDENCE_ARTIFACT_SCHEMA_VERSION = 3;
 /**
  * A discriminated union, because AD-21 requires that no shape hold a
  * production verdict and a contract verdict at once, with neither mode able

package/dist/core/schemas/isolation-manifest.d.ts

@@ -69,6 +69,24 @@ export declare const ForbiddenInputAccountingMap: z.ZodObject<{
         note: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+/**
+ * The manifest version this build accepts. No stage writes one, so a caller
+ * assembling a manifest had no value to read and transcribed the number.
+ *
+ * `1`, on one shape move the number never marked. `cb1cae8` retyped the six
+ * label arrays below from `z.array(z.string())` to `z.array(NonEmptyLabel)`
+ * and gave `violation` a `.min(1)`, which AD-11 counts as breaking, and the
+ * same commit took the eval contract to 4, the sealed run record to 4 and the
+ * probe to 3 while leaving this at 1. A manifest carrying
+ * `allowedMounts: ['']` parsed before that commit and fails after it, under
+ * the same version, in every release since.
+ *
+ * So the parse-behaviour method has nothing to compare here. It builds one
+ * fixture at the constant and one at the constant minus one, and 1 has no
+ * predecessor to build: the one break this shape has taken is inside the
+ * version it is still stamped with.
+ */
+export declare const ISOLATION_MANIFEST_SCHEMA_VERSION = 1;
 export declare const IsolationManifest: z.ZodObject<{
     schemaVersion: z.ZodInt;
     parentDigest: z.ZodNullable<z.ZodString>;

package/dist/core/schemas/isolation-manifest.js

@@ -62,6 +62,24 @@ export const ForbiddenInputAccountingMap = z.strictObject(accountingShape);
  * nothing after its colon.
  */
 const NonEmptyLabel = z.string().min(1);
+/**
+ * The manifest version this build accepts. No stage writes one, so a caller
+ * assembling a manifest had no value to read and transcribed the number.
+ *
+ * `1`, on one shape move the number never marked. `cb1cae8` retyped the six
+ * label arrays below from `z.array(z.string())` to `z.array(NonEmptyLabel)`
+ * and gave `violation` a `.min(1)`, which AD-11 counts as breaking, and the
+ * same commit took the eval contract to 4, the sealed run record to 4 and the
+ * probe to 3 while leaving this at 1. A manifest carrying
+ * `allowedMounts: ['']` parsed before that commit and fails after it, under
+ * the same version, in every release since.
+ *
+ * So the parse-behaviour method has nothing to compare here. It builds one
+ * fixture at the constant and one at the constant minus one, and 1 has no
+ * predecessor to build: the one break this shape has taken is inside the
+ * version it is still stamped with.
+ */
+export const ISOLATION_MANIFEST_SCHEMA_VERSION = 1;
 export const IsolationManifest = z
     .strictObject({
     ...lineageFields,

package/dist/core/schemas/preflight-verdict.d.ts

@@ -32,6 +32,15 @@ export declare const PreflightCheck: z.ZodObject<{
     note: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type PreflightCheck = z.infer<typeof PreflightCheck>;
+/**
+ * The verdict version `preflight`'s reducer stamps, and the single place that
+ * number is written. It was a literal inside `reduce.ts`, so the value a
+ * consumer needed sat in a stage rather than beside the shape it names.
+ *
+ * `1`: this artifact has never moved, so it has no predecessor shape and a
+ * parse-behaviour case over one would be vacuous.
+ */
+export declare const PREFLIGHT_VERDICT_SCHEMA_VERSION = 1;
 export declare const PreflightVerdict: z.ZodObject<{
     schemaVersion: z.ZodInt;
     parentDigest: z.ZodNullable<z.ZodString>;

package/dist/core/schemas/preflight-verdict.js

@@ -24,6 +24,15 @@ export const PreflightCheck = z.strictObject({
         .describe('`exempt` exists because AD-10 says "an operation declaring no inputs in any channel is exempt and records the exemption", and an exemption with no spelling is an exemption nobody records. That a failed pre-flight invalidates the run, and that a sensitivity witness resolving `insufficient-evidence` fails rather than passes, are AD-10 semantics for `core/preflight`; the schema carries the outcome and refines nothing.'),
     note: z.string().nullable(),
 });
+/**
+ * The verdict version `preflight`'s reducer stamps, and the single place that
+ * number is written. It was a literal inside `reduce.ts`, so the value a
+ * consumer needed sat in a stage rather than beside the shape it names.
+ *
+ * `1`: this artifact has never moved, so it has no predecessor shape and a
+ * parse-behaviour case over one would be vacuous.
+ */
+export const PREFLIGHT_VERDICT_SCHEMA_VERSION = 1;
 export const PreflightVerdict = z
     .strictObject({
     ...lineageFields,

package/dist/core/schemas/private-artifact-manifest.d.ts

@@ -32,6 +32,16 @@ export declare const PrivateArtifactEntry: z.ZodObject<{
     publicSafeRunId: z.ZodNullable<z.ZodString>;
     sanitizationPolicy: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * The manifest version this build accepts. No stage writes one, so a caller
+ * publishing a manifest had no value to read and transcribed the number.
+ *
+ * `1`: this artifact has never moved, so it has no predecessor shape and a
+ * parse-behaviour case over one would be vacuous. The prior art's
+ * `manifestVersion: const 1` became AD-11's plain integer, so the number is
+ * not readable off the published document either.
+ */
+export declare const PRIVATE_ARTIFACT_MANIFEST_SCHEMA_VERSION = 1;
 export declare const PrivateArtifactManifest: z.ZodObject<{
     schemaVersion: z.ZodInt;
     parentDigest: z.ZodNullable<z.ZodString>;

package/dist/core/schemas/private-artifact-manifest.js

@@ -35,6 +35,16 @@ export const PrivateArtifactEntry = z.strictObject({
         .nullable()
         .describe('AD-8 carries "the sanitization policy applied to it", and the nearest antecedent is the entry rather than the manifest: a manifest holding a raw trace beside a human label gives the two different treatment, so per-entry is the only reading that survives. Opaque rather than an enum for the reason `ScopedResource.kind` is opaque: no AD supplies a value space, and inventing one is the unshaped-declaration defect in reverse. `null` spells "none applied", which must stay representable.'),
 });
+/**
+ * The manifest version this build accepts. No stage writes one, so a caller
+ * publishing a manifest had no value to read and transcribed the number.
+ *
+ * `1`: this artifact has never moved, so it has no predecessor shape and a
+ * parse-behaviour case over one would be vacuous. The prior art's
+ * `manifestVersion: const 1` became AD-11's plain integer, so the number is
+ * not readable off the published document either.
+ */
+export const PRIVATE_ARTIFACT_MANIFEST_SCHEMA_VERSION = 1;
 export const PrivateArtifactManifest = z
     .strictObject({
     ...lineageFields,

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

@@ -71,6 +71,47 @@ export declare const Defect: z.ZodObject<{
         relation: z.ZodType<import("./expression.ts").Expression, unknown, z.core.$ZodTypeInternals<import("./expression.ts").Expression, unknown>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/**
+ * The probe's current schema version. `EVAL_CONTRACT_SCHEMA_VERSION` is the
+ * same thing for the eval contract.
+ *
+ * It exists for the reason that one does: `lineage.ts` keeps the field a plain
+ * integer so a stale artifact fails as AD-28's `schema-version-mismatch` rather
+ * than as an anonymous parse error, which puts the comparison on the reader.
+ * `compile` is that reader for a contract. A probe has two in this pipeline and
+ * both compare against this constant: `planPreflight` before it plans a leg,
+ * and `score` before it seals the probe. An unequal stamp leaves by the fault
+ * path rather than being read leniently.
+ *
+ * A third reader exists for a caller outside this package.
+ * `validateLineageChain` takes an `acceptedSchemaVersion` and raises the same
+ * code over a presented chain, and `Probe` carries lineage, so a caller who
+ * presents one gets the comparison there. It words the fault its own way, which
+ * is why the two spellings of `schema-version-mismatch` in this tree are not a
+ * drift.
+ *
+ * It is also the single place the number is written. The committed
+ * worked-example chains build their probes from it and `check:doc-claims` reads
+ * it to hold the published sentence that names it, where the number was a
+ * literal in three places that could disagree in silence.
+ */
+export declare const PROBE_SCHEMA_VERSION = 5;
+/**
+ * Why a stale probe stamp is a rejection, in the words the fault carries.
+ *
+ * One string for both readers. Two copies of a sentence this long disagree in
+ * silence exactly as the number did before `PROBE_SCHEMA_VERSION` existed, and
+ * it lives here because this is where a version bump is one edit.
+ *
+ * It splits the shapes by branch, because a clean control carries neither a
+ * `defectSignature` nor a manifestation witness: the signature is declared on
+ * the seeded branch below and a witness hangs off a `Defect`, which that branch
+ * bounds at zero. What every probe carries is the qualification record, whose
+ * arrival on both branches is what made the 1 to 2 bump breaking. A clean
+ * control is the probe a reader is most likely to meet this message with, so
+ * naming a field it does not have would be the wrong half to lead with.
+ */
+export declare const PROBE_SCHEMA_VERSION_CONSEQUENCE: string;
 /**
  * The prior art's `expectedClean` conditional, re-expressed as a discriminated
  * union per AD-13 (a boolean literal discriminator parses on this pin,

package/dist/core/schemas/probe.js

@@ -48,6 +48,49 @@ const probeCommonFields = {
     rationale: z.string().min(1),
     qualification: ProbeQualification.describe('AD-9\'s qualification record: which of the five routes earned this probe its ground truth, and the evidence that route demands. Required on every branch and on every class, canaries included, because AD-9 closes with "an unqualified probe cannot enter a sealed set" and spells a route for all five kinds. That the route is compatible with this probe\'s class and `expectedClean` flag is a cross-field rule the export cannot carry; the corpus qualification gate enforces it and returns a reason code. Required, not optional, which with `defectSignature` below makes the probe\'s `schemaVersion` 1 -> 2 BREAKING bump under AD-11, whose rule is that "adding an optional field is a `schemaVersion` bump recorded in the field\'s own description; removing or retyping is breaking". This field is on both branches, so it alone is what stops every version-1 probe from parsing.'),
 };
+/**
+ * The probe's current schema version. `EVAL_CONTRACT_SCHEMA_VERSION` is the
+ * same thing for the eval contract.
+ *
+ * It exists for the reason that one does: `lineage.ts` keeps the field a plain
+ * integer so a stale artifact fails as AD-28's `schema-version-mismatch` rather
+ * than as an anonymous parse error, which puts the comparison on the reader.
+ * `compile` is that reader for a contract. A probe has two in this pipeline and
+ * both compare against this constant: `planPreflight` before it plans a leg,
+ * and `score` before it seals the probe. An unequal stamp leaves by the fault
+ * path rather than being read leniently.
+ *
+ * A third reader exists for a caller outside this package.
+ * `validateLineageChain` takes an `acceptedSchemaVersion` and raises the same
+ * code over a presented chain, and `Probe` carries lineage, so a caller who
+ * presents one gets the comparison there. It words the fault its own way, which
+ * is why the two spellings of `schema-version-mismatch` in this tree are not a
+ * drift.
+ *
+ * It is also the single place the number is written. The committed
+ * worked-example chains build their probes from it and `check:doc-claims` reads
+ * it to hold the published sentence that names it, where the number was a
+ * literal in three places that could disagree in silence.
+ */
+export const PROBE_SCHEMA_VERSION = 5;
+/**
+ * Why a stale probe stamp is a rejection, in the words the fault carries.
+ *
+ * One string for both readers. Two copies of a sentence this long disagree in
+ * silence exactly as the number did before `PROBE_SCHEMA_VERSION` existed, and
+ * it lives here because this is where a version bump is one edit.
+ *
+ * It splits the shapes by branch, because a clean control carries neither a
+ * `defectSignature` nor a manifestation witness: the signature is declared on
+ * the seeded branch below and a witness hangs off a `Defect`, which that branch
+ * bounds at zero. What every probe carries is the qualification record, whose
+ * arrival on both branches is what made the 1 to 2 bump breaking. A clean
+ * control is the probe a reader is most likely to meet this message with, so
+ * naming a field it does not have would be the wrong half to lead with.
+ */
+export const PROBE_SCHEMA_VERSION_CONSEQUENCE = 'since the stamp says which shapes the probe was authored against: the ' +
+    'qualification record on every probe, and the witness legs and the defect ' +
+    'signature grammar on a seeded one';
 /**
  * The prior art's `expectedClean` conditional, re-expressed as a discriminated
  * union per AD-13 (a boolean literal discriminator parses on this pin,

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

@@ -1,5 +1,16 @@
 /** the published policy artifact the scorer reads its thresholds from. */
 import { z } from 'zod';
+/**
+ * The policy version this build accepts. No stage writes one, so a caller
+ * publishing a policy document had no value to read and transcribed the
+ * number.
+ *
+ * `2` because `catchThreshold` became required with no default, which the
+ * field's own description below records; a version-1 document omits it and
+ * fails to parse, which is the predecessor shape the parse-behaviour case is
+ * built on.
+ */
+export declare const SCORING_POLICY_SCHEMA_VERSION = 2;
 /**
  * A published artifact rather than constants, per the Consistency
  * Conventions, so "the default" has an identity a no-op edit cannot move.

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

@@ -3,6 +3,17 @@ import { z } from 'zod';
 import { Severity } from './eval-contract.js';
 import { lineageFields } from './lineage.js';
 import { Identifier } from './primitives.js';
+/**
+ * The policy version this build accepts. No stage writes one, so a caller
+ * publishing a policy document had no value to read and transcribed the
+ * number.
+ *
+ * `2` because `catchThreshold` became required with no default, which the
+ * field's own description below records; a version-1 document omits it and
+ * fails to parse, which is the predecessor shape the parse-behaviour case is
+ * built on.
+ */
+export const SCORING_POLICY_SCHEMA_VERSION = 2;
 /**
  * A published artifact rather than constants, per the Consistency
  * Conventions, so "the default" has an identity a no-op edit cannot move.

package/dist/core/schemas/sealed-evaluator-brief.d.ts

@@ -28,6 +28,18 @@ export declare const BriefInterface: z.ZodObject<{
         web: "web";
     }>;
 }, z.core.$strict>;
+/**
+ * The brief version `seal` stamps, and the single place that number is
+ * written. `seal` read it as a literal in its own module, so a bump meant
+ * editing a number in a file that declares no schema, and the value a
+ * consumer needed lived in a stage rather than beside the shape it names.
+ *
+ * `2` because `principals` is required, which AD-11 counts as breaking; the
+ * field's own description below records the bump. No `z.literal` on
+ * `schemaVersion` itself: `lineage.ts` states why, and this constant is the
+ * reader-side half of that decision seen from the caller.
+ */
+export declare const SEALED_EVALUATOR_BRIEF_SCHEMA_VERSION = 2;
 export declare const SealedEvaluatorBrief: z.ZodObject<{
     schemaVersion: z.ZodInt;
     parentDigest: z.ZodNullable<z.ZodString>;

package/dist/core/schemas/sealed-evaluator-brief.js

@@ -29,6 +29,18 @@ export const BriefInterface = z.strictObject({
     logicalId: Identifier.describe('AD-35 binds the brief as it binds the contract: a logical interface identifier only, never a URL, host, or port. The brief is the artifact that actually reaches the executing caller, so a URL leaking onto it defeats the mapping AD-35 keeps outside the package.'),
     kind: InterfaceKind,
 });
+/**
+ * The brief version `seal` stamps, and the single place that number is
+ * written. `seal` read it as a literal in its own module, so a bump meant
+ * editing a number in a file that declares no schema, and the value a
+ * consumer needed lived in a stage rather than beside the shape it names.
+ *
+ * `2` because `principals` is required, which AD-11 counts as breaking; the
+ * field's own description below records the bump. No `z.literal` on
+ * `schemaVersion` itself: `lineage.ts` states why, and this constant is the
+ * reader-side half of that decision seen from the caller.
+ */
+export const SEALED_EVALUATOR_BRIEF_SCHEMA_VERSION = 2;
 export const SealedEvaluatorBrief = z
     .strictObject({
     ...lineageFields,

package/dist/core/schemas/sealed-run-record.d.ts

@@ -320,6 +320,17 @@ export declare const RunMode: z.ZodEnum<{
     "contract-scoring": "contract-scoring";
     production: "production";
 }>;
+/**
+ * The record version this build accepts. No stage writes a sealed run record,
+ * so before this constant the number existed in `src/` only as prose in the
+ * description below, and a caller assembling a record transcribed it. One
+ * consumer transcribed it as 3 and emitted records no stage could read.
+ *
+ * `6` on five recorded bumps, the last of which drops `invalidReason`: a
+ * version-5 record carrying that key fails `strictObject`, which is the
+ * predecessor shape the parse-behaviour case is built on.
+ */
+export declare const SEALED_RUN_RECORD_SCHEMA_VERSION = 6;
 export declare const SealedRunRecord: z.ZodObject<{
     schemaVersion: z.ZodInt;
     parentDigest: z.ZodNullable<z.ZodString>;

package/dist/core/schemas/sealed-run-record.js

@@ -246,6 +246,17 @@ export const EvidenceDisclosure = z.strictObject({
  */
 export const RUN_MODES = ['production', 'contract-scoring'];
 export const RunMode = z.enum(RUN_MODES);
+/**
+ * The record version this build accepts. No stage writes a sealed run record,
+ * so before this constant the number existed in `src/` only as prose in the
+ * description below, and a caller assembling a record transcribed it. One
+ * consumer transcribed it as 3 and emitted records no stage could read.
+ *
+ * `6` on five recorded bumps, the last of which drops `invalidReason`: a
+ * version-5 record carrying that key fails `strictObject`, which is the
+ * predecessor shape the parse-behaviour case is built on.
+ */
+export const SEALED_RUN_RECORD_SCHEMA_VERSION = 6;
 export const SealedRunRecord = z
     .strictObject({
     // A record carries lineage fields and nothing here ever puts one in a

package/dist/core/score/score.d.ts

@@ -31,7 +31,7 @@
 import type { ValidatedObservations } from '../ingest/ingest.ts';
 import { type EvalContract } from '../schemas/eval-contract.ts';
 import type { Outcome } from '../schemas/evidence-artifact.ts';
-import type { Probe } from '../schemas/probe.ts';
+import { type Probe } from '../schemas/probe.ts';
 import type { ScoringPolicy } from '../schemas/scoring-policy.ts';
 import type { ScoreStage } from '../stage-contracts.ts';
 import type { ContractAssessment, LadderResolution, ProductionAssessment } from './ladder.ts';