eval-quality 0.1.0 → 0.2.0

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

@@ -43,19 +43,22 @@ export type CheckResolutionValue = {
  */
 export declare const CheckResolution: z.ZodType<CheckResolutionValue>;
 /**
- * AD-11's five named inputs, transcribed so a reader can recompute the
- * digest and see what was compared (AD-8's "by digest and opaque reference,
- * never by content or path"). Named object rather than a concatenated tuple:
+ * AD-11's identity inputs, transcribed so a reader can recompute the digest
+ * and see what was compared (AD-8's "by digest and opaque reference, never
+ * by content or path"). Named object rather than a concatenated tuple:
  * revision 1 let two conforming scorers compute different versions from
  * identical inputs if they hashed a different ordering. The scorer computes
- * the scoring version over this shape.
+ * the scoring version over this shape. Six now, not five: `mode` is owed
+ * item 4's identity clause, superseding AD-11's original five-field
+ * sentence.
  */
-export declare const SCORING_VERSION_INPUT_NAMES: readonly ['contractSchemaVersion', 'corpusDigest', 'fixtureDigest', 'evaluatorConfigurationDigest', 'scoringPolicyDigest'];
+export declare const SCORING_VERSION_INPUT_NAMES: readonly ['contractSchemaVersion', 'corpusDigest', 'fixtureDigest', 'evaluatorConfigurationDigest', 'scoringPolicyDigest', 'mode'];
 export declare const ScoringVersionInputName: z.ZodEnum<{
     contractSchemaVersion: "contractSchemaVersion";
     corpusDigest: "corpusDigest";
     evaluatorConfigurationDigest: "evaluatorConfigurationDigest";
     fixtureDigest: "fixtureDigest";
+    mode: "mode";
     scoringPolicyDigest: "scoringPolicyDigest";
 }>;
 export declare const ScoringVersionInputs: z.ZodObject<{
@@ -64,11 +67,17 @@ export declare const ScoringVersionInputs: z.ZodObject<{
     fixtureDigest: z.ZodString;
     evaluatorConfigurationDigest: z.ZodString;
     scoringPolicyDigest: z.ZodString;
+    mode: z.ZodEnum<{
+        "contract-scoring": "contract-scoring";
+        production: "production";
+    }>;
 }, z.core.$strict>;
 export declare const InvalidatedAttempt: z.ZodObject<{
     attempt: z.ZodInt;
     reason: z.ZodString;
 }, z.core.$strict>;
+/** exported so the trial-set reducer names this shape without importing Zod. */
+export type InvalidatedAttempt = z.infer<typeof InvalidatedAttempt>;
 /**
  * AD-6: "Every artifact records its trial count, its invalidated attempts, and
  * each attempt's reason, including on a PASS." None of the three is nullable,
@@ -83,6 +92,8 @@ export declare const Trials: z.ZodObject<{
         reason: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/** exported so the ladder names this shape without importing Zod. */
+export type Trials = z.infer<typeof Trials>;
 export declare const Outcome: z.ZodObject<{
     oracleId: z.ZodString;
     probeId: z.ZodNullable<z.ZodString>;
@@ -119,6 +130,8 @@ export declare const Outcome: z.ZodObject<{
     selectedObservationIds: z.ZodArray<z.ZodString>;
     checkResolution: z.ZodNullable<z.ZodType<CheckResolutionValue, unknown, z.core.$ZodTypeInternals<CheckResolutionValue, unknown>>>;
 }, z.core.$strict>;
+/** exported so the dominance comparator names this shape without importing Zod. */
+export type Outcome = z.infer<typeof Outcome>;
 export declare const CoverageGap: z.ZodObject<{
     rule: z.ZodString;
     relevancePredicate: z.ZodString;
@@ -132,11 +145,49 @@ export declare const CoverageGap: z.ZodObject<{
 }, z.core.$strict>;
 /** the record as a type, so `core/coverage/` names it without importing Zod. */
 export type CoverageGap = z.infer<typeof CoverageGap>;
+/**
+ * Owed item 5's record for an ingested `defect` finding citing no oracle:
+ * AD-23 already retains the finding rather than discarding it, but nothing
+ * downstream consumed it until this `schemaVersion`. Mirrors `CoverageGap`'s
+ * shape and the `defect`-branch fields on `Finding` it is read from, but
+ * carries no relevance or satisfaction predicate: AD-31's coverage gap is a
+ * declaration AD-31 could not confirm was satisfied, while an uncited defect
+ * finding is a runtime observation an evaluator made outside every declared
+ * oracle, with no relevance predicate to name and no satisfaction predicate
+ * that failed. This is the version-3 bump: required, not optional, per owed
+ * item 5, so a producer that never emits it stops parsing rather than
+ * silently under-reporting the gap.
+ */
+export declare const UncitedFindingGap: z.ZodObject<{
+    findingId: z.ZodString;
+    observationIds: z.ZodArray<z.ZodString>;
+    quotedEvidence: z.ZodArray<z.ZodObject<{
+        quote: z.ZodString;
+        channel: z.ZodEnum<{
+            "call-inputs": "call-inputs";
+            "exit-code": "exit-code";
+            "response-body": "response-body";
+            "response-headers": "response-headers";
+            "response-status": "response-status";
+            stderr: "stderr";
+            stdout: "stdout";
+        }>;
+    }, z.core.$strict>>;
+    severity: z.ZodEnum<{
+        critical: "critical";
+        low: "low";
+        material: "material";
+    }>;
+}, z.core.$strict>;
+/** exported so `core/score/ladder.ts` names this shape without importing Zod. */
+export type UncitedFindingGap = z.infer<typeof UncitedFindingGap>;
 export declare const ClassStrength: z.ZodObject<{
     caught: z.ZodInt;
     exercised: z.ZodInt;
     rate: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strict>;
+/** exported so the rate-vector builder names this shape without importing Zod. */
+export type ClassStrength = z.infer<typeof ClassStrength>;
 /**
  * A fixed three-key object instead of a map keyed by probe class. AD-7 is
  * explicit that "canary probes and clean controls never enter the vector", so
@@ -159,6 +210,8 @@ export declare const StrengthVector: z.ZodObject<{
         rate: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/** exported so the rate-vector builder names this shape without importing Zod. */
+export type StrengthVector = z.infer<typeof StrengthVector>;
 export declare const Strength: z.ZodObject<{
     denominator: z.ZodString;
     basis: z.ZodEnum<{
@@ -185,6 +238,8 @@ export declare const Strength: z.ZodObject<{
     comparable: z.ZodBoolean;
     note: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
+/** exported so the dominance comparator names this shape without importing Zod. */
+export type Strength = z.infer<typeof Strength>;
 /**
  * AD-12's three named checks, transcribed from the same sentence the field
  * comes from: the package "validates a caller-presented lineage chain (length
@@ -221,13 +276,6 @@ export declare const EvidenceArtifact: z.ZodDiscriminatedUnion<[z.ZodObject<{
     revisionCount: z.ZodInt;
     runId: z.ZodString;
     scoringVersion: z.ZodString;
-    scoringVersionInputs: z.ZodObject<{
-        contractSchemaVersion: z.ZodInt;
-        corpusDigest: z.ZodString;
-        fixtureDigest: z.ZodString;
-        evaluatorConfigurationDigest: z.ZodString;
-        scoringPolicyDigest: z.ZodString;
-    }, z.core.$strict>;
     comparabilityKey: z.ZodString;
     excludedProbeIds: z.ZodArray<z.ZodString>;
     exitCode: z.ZodInt;
@@ -237,6 +285,7 @@ export declare const EvidenceArtifact: z.ZodDiscriminatedUnion<[z.ZodObject<{
         corpusDigest: "corpusDigest";
         evaluatorConfigurationDigest: "evaluatorConfigurationDigest";
         fixtureDigest: "fixtureDigest";
+        mode: "mode";
         scoringPolicyDigest: "scoringPolicyDigest";
     }>>;
     trials: z.ZodObject<{
@@ -331,6 +380,14 @@ export declare const EvidenceArtifact: z.ZodDiscriminatedUnion<[z.ZodObject<{
             noGap: z.ZodBoolean;
         }, z.core.$strict>;
     }, z.core.$strict>;
+    scoringVersionInputs: z.ZodObject<{
+        contractSchemaVersion: z.ZodInt;
+        corpusDigest: z.ZodString;
+        fixtureDigest: z.ZodString;
+        evaluatorConfigurationDigest: z.ZodString;
+        scoringPolicyDigest: z.ZodString;
+        mode: z.ZodLiteral<"production">;
+    }, z.core.$strict>;
     mode: z.ZodLiteral<"production">;
     productionVerdict: z.ZodEnum<{
         CONCERNS: "CONCERNS";
@@ -344,13 +401,6 @@ export declare const EvidenceArtifact: z.ZodDiscriminatedUnion<[z.ZodObject<{
     revisionCount: z.ZodInt;
     runId: z.ZodString;
     scoringVersion: z.ZodString;
-    scoringVersionInputs: z.ZodObject<{
-        contractSchemaVersion: z.ZodInt;
-        corpusDigest: z.ZodString;
-        fixtureDigest: z.ZodString;
-        evaluatorConfigurationDigest: z.ZodString;
-        scoringPolicyDigest: z.ZodString;
-    }, z.core.$strict>;
     comparabilityKey: z.ZodString;
     excludedProbeIds: z.ZodArray<z.ZodString>;
     exitCode: z.ZodInt;
@@ -360,6 +410,7 @@ export declare const EvidenceArtifact: z.ZodDiscriminatedUnion<[z.ZodObject<{
         corpusDigest: "corpusDigest";
         evaluatorConfigurationDigest: "evaluatorConfigurationDigest";
         fixtureDigest: "fixtureDigest";
+        mode: "mode";
         scoringPolicyDigest: "scoringPolicyDigest";
     }>>;
     trials: z.ZodObject<{
@@ -454,6 +505,14 @@ export declare const EvidenceArtifact: z.ZodDiscriminatedUnion<[z.ZodObject<{
             noGap: z.ZodBoolean;
         }, z.core.$strict>;
     }, z.core.$strict>;
+    scoringVersionInputs: z.ZodObject<{
+        contractSchemaVersion: z.ZodInt;
+        corpusDigest: z.ZodString;
+        fixtureDigest: z.ZodString;
+        evaluatorConfigurationDigest: z.ZodString;
+        scoringPolicyDigest: z.ZodString;
+        mode: z.ZodLiteral<"contract-scoring">;
+    }, z.core.$strict>;
     mode: z.ZodLiteral<"contract-scoring">;
     contractVerdict: z.ZodEnum<{
         CONCERNS: "CONCERNS";
@@ -461,6 +520,27 @@ export declare const EvidenceArtifact: z.ZodDiscriminatedUnion<[z.ZodObject<{
         PASS: "PASS";
         WAIVED: "WAIVED";
     }>;
+    uncitedFindingGaps: z.ZodArray<z.ZodObject<{
+        findingId: z.ZodString;
+        observationIds: z.ZodArray<z.ZodString>;
+        quotedEvidence: z.ZodArray<z.ZodObject<{
+            quote: z.ZodString;
+            channel: z.ZodEnum<{
+                "call-inputs": "call-inputs";
+                "exit-code": "exit-code";
+                "response-body": "response-body";
+                "response-headers": "response-headers";
+                "response-status": "response-status";
+                stderr: "stderr";
+                stdout: "stdout";
+            }>;
+        }, z.core.$strict>>;
+        severity: z.ZodEnum<{
+            critical: "critical";
+            low: "low";
+            material: "material";
+        }>;
+    }, z.core.$strict>>;
     systemRecommendationRecorded: z.ZodEnum<{
         CONCERNS: "CONCERNS";
         FAIL: "FAIL";

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

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { Severity } from './eval-contract.js';
 import { lineageFields } from './lineage.js';
 import { Digest, FindingId, Identifier, OracleId, ProbeId, } from './primitives.js';
-import { OracleDispositionValue } from './sealed-run-record.js';
+import { OracleDispositionValue, QuotedEvidence, RunMode, } from './sealed-run-record.js';
 import { EvaluatorRecommendation, Verdict } from './verdict.js';
 /**
  * AD-6's closed twelve. Exported so a later reader can walk the list
@@ -52,12 +52,14 @@ export const CheckResolution = z
     description: "One node of an oracle's `check` tree as it resolved. AD-4's resolution is three-valued rather than two, and the introduction vocabulary has exactly one member because AD-4 closes the introduction set at one: an empty collection. `null` where the resolution is not `insufficient-evidence`. A leaf carries an empty `children` array.",
 });
 /**
- * AD-11's five named inputs, transcribed so a reader can recompute the
- * digest and see what was compared (AD-8's "by digest and opaque reference,
- * never by content or path"). Named object rather than a concatenated tuple:
+ * AD-11's identity inputs, transcribed so a reader can recompute the digest
+ * and see what was compared (AD-8's "by digest and opaque reference, never
+ * by content or path"). Named object rather than a concatenated tuple:
  * revision 1 let two conforming scorers compute different versions from
  * identical inputs if they hashed a different ordering. The scorer computes
- * the scoring version over this shape.
+ * the scoring version over this shape. Six now, not five: `mode` is owed
+ * item 4's identity clause, superseding AD-11's original five-field
+ * sentence.
  */
 export const SCORING_VERSION_INPUT_NAMES = [
     'contractSchemaVersion',
@@ -65,14 +67,44 @@ export const SCORING_VERSION_INPUT_NAMES = [
     'fixtureDigest',
     'evaluatorConfigurationDigest',
     'scoringPolicyDigest',
+    'mode',
 ];
 export const ScoringVersionInputName = z.enum(SCORING_VERSION_INPUT_NAMES);
+const SCORING_VERSION_MODE_DESCRIPTION = "Owed item 4's identity clause: mode enters AD-11's scoring version, superseding AD-11's five-field sentence. Read from the sealed run record, never re-derived, so two runs scored under one mode never collide with a version computed for the other. Required, not optional, which makes this the evidence artifact'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\". A version-1 artifact carries five scoring-version inputs where this one carries six, so it does not parse, and no version computed before the bump compares with one computed after it.";
 export const ScoringVersionInputs = z.strictObject({
     contractSchemaVersion: z.int().min(1),
     corpusDigest: Digest,
     fixtureDigest: Digest,
     evaluatorConfigurationDigest: Digest,
     scoringPolicyDigest: Digest,
+    mode: RunMode.describe(SCORING_VERSION_MODE_DESCRIPTION),
+});
+/**
+ * `scoringVersionInputs.mode` narrowed to the one value that agrees with
+ * `EvidenceArtifact`'s own branch discriminant (AD-11, AD-32), rather than a
+ * `.refine()` comparing the two fields. A refinement never exports, so the
+ * published document would keep admitting the disagreement, and the
+ * corpus-mutation generator synthesises witnesses for an untaken `oneOf`
+ * branch straight from that branch's own JSON Schema with no knowledge of a
+ * Zod-only cross-field rule -- verified: it produced two dozen genuine
+ * `zod=false published=true` disagreements this way. Narrowing the schema
+ * itself removes the gap at its source: a synthesised example for a
+ * `const`-typed field can only be that one value.
+ *
+ * Two named consts rather than one generic builder: a `<M extends
+ * RunModeValue>(mode: M)` helper builds each schema correctly, but TypeScript
+ * fails to preserve the per-call-site literal through `EvidenceArtifact`'s
+ * `z.discriminatedUnion` inference, so a fixture assigning the wrong branch's
+ * `mode` here compiles instead of erroring. Two concrete literals close that
+ * gap by construction; there is nothing generic left for the checker to lose.
+ */
+const productionScoringVersionInputs = ScoringVersionInputs.extend({
+    mode: z.literal('production').describe(SCORING_VERSION_MODE_DESCRIPTION),
+});
+const contractScoringVersionInputs = ScoringVersionInputs.extend({
+    mode: z
+        .literal('contract-scoring')
+        .describe(SCORING_VERSION_MODE_DESCRIPTION),
 });
 export const InvalidatedAttempt = z.strictObject({
     attempt: z.int().min(1),
@@ -115,6 +147,25 @@ export const CoverageGap = z.strictObject({
     satisfied: z.boolean(),
     severity: Severity,
 });
+/**
+ * Owed item 5's record for an ingested `defect` finding citing no oracle:
+ * AD-23 already retains the finding rather than discarding it, but nothing
+ * downstream consumed it until this `schemaVersion`. Mirrors `CoverageGap`'s
+ * shape and the `defect`-branch fields on `Finding` it is read from, but
+ * carries no relevance or satisfaction predicate: AD-31's coverage gap is a
+ * declaration AD-31 could not confirm was satisfied, while an uncited defect
+ * finding is a runtime observation an evaluator made outside every declared
+ * oracle, with no relevance predicate to name and no satisfaction predicate
+ * that failed. This is the version-3 bump: required, not optional, per owed
+ * item 5, so a producer that never emits it stops parsing rather than
+ * silently under-reporting the gap.
+ */
+export const UncitedFindingGap = z.strictObject({
+    findingId: FindingId,
+    observationIds: z.array(Identifier).min(1),
+    quotedEvidence: z.array(QuotedEvidence).min(1),
+    severity: Severity,
+});
 export const ClassStrength = z.strictObject({
     caught: z.int().min(0),
     exercised: z.int().min(0),
@@ -178,7 +229,7 @@ export const Remediation = z.strictObject({
 const evidenceCommonFields = {
     ...lineageFields,
     runId: z.string().min(1),
-    scoringVersion: Digest.describe('AD-11: computed by the scorer over the five named inputs below and never caller-supplied.'),
+    scoringVersion: Digest.describe('AD-11: computed by the scorer over the six named inputs below and never caller-supplied.'),
     scoringVersionInputs: ScoringVersionInputs,
     comparabilityKey: Digest.describe("AD-7's declared key: the scoring policy digest plus the corpus digest restricted to the probes both results cover. Deliberately weaker than the scoring version, so adding a probe narrows a comparison rather than voiding every prior result."),
     excludedProbeIds: z
@@ -192,7 +243,7 @@ const evidenceCommonFields = {
         .describe('Every condition that fired, in AD-21 terms. Free text by design: the rungs are prose in AD-21 and assigning them identifiers would be minting a vocabulary that AD has not. Each member is non-empty, on the same reasoning that `InvalidatedAttempt.reason` is: a condition that names itself with nothing has not been recorded. An empty array is legal and is what a PASS with no firing condition carries.'),
     callerAttestedInputs: z
         .array(ScoringVersionInputName)
-        .describe('Which of the five scoring-version inputs were caller-attested rather than computed by this package. An enum over the five key names rather than free strings, because AD-32 requires the artifact to state *which* inputs were attested and an unconstrained string cannot be checked against anything. AD-11 names three of the five as caller-attested; the enum admits any subset so a stricter or looser integration stays representable.'),
+        .describe('Which of the six scoring-version inputs were caller-attested rather than computed by this package. An enum over the six key names rather than free strings, because AD-32 requires the artifact to state *which* inputs were attested and an unconstrained string cannot be checked against anything. AD-11 names three of the six as caller-attested; the enum admits any subset so a stricter or looser integration stays representable.'),
     trials: Trials,
     outcomes: z.array(Outcome),
     uncitedFindings: z
@@ -212,6 +263,7 @@ export const EvidenceArtifact = z
     z
         .strictObject({
         ...evidenceCommonFields,
+        scoringVersionInputs: productionScoringVersionInputs,
         mode: z.literal('production'),
         productionVerdict: Verdict,
     })
@@ -219,8 +271,12 @@ export const EvidenceArtifact = z
     z
         .strictObject({
         ...evidenceCommonFields,
+        scoringVersionInputs: contractScoringVersionInputs,
         mode: z.literal('contract-scoring'),
         contractVerdict: Verdict,
+        uncitedFindingGaps: z
+            .array(UncitedFindingGap)
+            .describe("Owed item 5's rung record, contract-scoring only: one entry per uncited `defect` finding, per `core/score/outcome.ts`'s `uncitedDefectFindingGaps`. Required, not optional, which makes this the `schemaVersion` 2 -> 3 BREAKING bump under AD-11: an empty array is legal and is what a run with no uncited defect finding carries, but the key itself must be present. Never on the production branch, where the ladder signal alone is enough and this key would fail `strictObject`'s `unrecognized_keys` rule."),
         systemRecommendationRecorded: EvaluatorRecommendation.describe("The evaluator's recommendation about the SYSTEM, recorded and never promoted. On a knowingly defective probe a system-directed FAIL is an input rather than a signal about the contract."),
         systemRecommendationNote: z.string().nullable(),
     })
@@ -228,5 +284,5 @@ export const EvidenceArtifact = z
 ])
     .meta({
     id: 'EvidenceArtifact',
-    description: "The scored output, owned by `emit` per AD-24, with no prior art; `score` produces the outcome and verdict values it serializes. The two modes are separate branches because AD-21 requires that the production verdict and the contract verdict never share a field. This expresses that settled sentence and no more: Owed item 4's remaining half stays open, namely mode being fixed before ingest and entering AD-11's identity inputs rather than appearing first here; and the Sealed Run Record still carries no mode.",
+    description: 'The scored output, owned by `emit` per AD-24, with no prior art; `score` produces the outcome and verdict values it serializes. The two modes are separate branches because AD-21 requires that the production verdict and the contract verdict never share a field. Mode is no longer first stated here: the Sealed Run Record now carries a required `mode`, where AD-21\'s "fixed before ingest" puts it, so this artifact restates a mode the sealed record already fixed and is never the source. Owed item 4 is closed as of this schemaVersion: `mode` is `ScoringVersionInputs`\'s sixth field, `core/score/ladder.ts` carries `ProductionAssessment`/`ContractAssessment` and their own total ladders, and `core/score/mode-agreement.ts` rejects a `production` record paired with a `contract-scoring` artifact in both directions as an AD-32 cross-artifact disagreement. That check is a hand-written function at the assembly boundary rather than a schema refinement, since no single schema sees both artifacts; `emit` is its one caller, immediately before returning the artifact it just built. Owed item 5 is closed as of this schemaVersion too: the contract-scoring branch carries a required `uncitedFindingGaps`, and both ladders in `core/score/ladder.ts` gain a shared `uncited-defect-finding` CONCERNS row over `AssessmentCommon.uncitedDefectFindings`, so an ingested defect finding citing no oracle now resolves at least CONCERNS instead of routing nowhere.',
 });

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

@@ -7,7 +7,52 @@ import { JsonValue } from './primitives.ts';
  * one implementation and the literal string to another, and flipped a witness
  * match between `caught` and `missed` on one record; that form is
  * unrepresentable here.
+ *
+ * Four members, one tag each. `{ literal }` writes the sent value down;
+ * `{ matcher: 'any' }` binds whatever was sent and `{ matcher: 'type-violating' }`
+ * binds a value whose JSON type differs from the operation's declared type for
+ * the key, which is how AD-31 rule 3's malformed-input behaviour is addressed.
+ *
+ * `{ captured }` addresses an earlier step's declared scalar output. Owed item
+ * 3: a `POST` returning a server-generated identifier followed by a `GET`
+ * proving persistence is unwritable with the first two, since a literal
+ * hard-codes a resource the evaluator never created and `any` matches
+ * unrelated reads. "Earlier" is earlier in the capture graph's own topological
+ * order, which `binding-cycle` makes exist. It is deliberately not AD-39's
+ * `after` clause: `nested-temporal-clause` already rejects every `after` cycle,
+ * so a capture forced to follow an `after` edge would leave `binding-cycle`
+ * unfireable. At score time the ordering is the record's `sequence`.
+ *
+ * `{ principal }` names a principal `testData.principals` declares. The two
+ * critical-severity cross-user behaviours (act as A, read as B, must be denied
+ * or absent) bind a step to an account that is neither a literal, since AD-19
+ * forbids credential values in declarations, nor an earlier step's output,
+ * since accounts are provisioned outside the observation stream. The name is
+ * an opaque label carrying no account identifier, credential, or subject data
+ * (AD-18). An undeclared name fires `undeclared-mandatory-input` in strict
+ * mode; a Zod refinement here would be a cross-subtree constraint the export
+ * cannot carry, and the published-schema differential sweep synthesises a
+ * union-branch witness that would expose the disagreement.
+ *
+ * A captured pointer resolves to a declared scalar with no transform applied,
+ * which keeps AD-4's ban on arithmetic, projection, and user-defined functions
+ * holding by construction: the grammar has no place to write one.
  */
+/**
+ * The first two members, named individually so the probe-side selector under
+ * AD-40 admits exactly these two and nothing else. Bare `export const` with no
+ * `.meta({ id })`: an id would collapse the branches to `$ref`s and mint new
+ * `$defs`, so the export stays byte-identical.
+ */
+export declare const LiteralBindingValue: z.ZodObject<{
+    literal: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
+}, z.core.$strict>;
+export declare const MatcherBindingValue: z.ZodObject<{
+    matcher: z.ZodEnum<{
+        any: "any";
+        "type-violating": "type-violating";
+    }>;
+}, z.core.$strict>;
 export declare const BindingValue: z.ZodUnion<readonly [z.ZodObject<{
     literal: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
 }, z.core.$strict>, z.ZodObject<{
@@ -15,6 +60,10 @@ export declare const BindingValue: z.ZodUnion<readonly [z.ZodObject<{
         any: "any";
         "type-violating": "type-violating";
     }>;
+}, z.core.$strict>, z.ZodObject<{
+    captured: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    principal: z.ZodString;
 }, z.core.$strict>]>;
 /** the constraint identifier the ledger carries for the check below. */
 export declare const BINDING_CHANNEL_NON_EMPTY = "binding-channel-non-empty";
@@ -25,6 +74,10 @@ export declare const BindingChannel: z.ZodNullable<z.ZodRecord<z.ZodString, z.Zo
         any: "any";
         "type-violating": "type-violating";
     }>;
+}, z.core.$strict>, z.ZodObject<{
+    captured: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    principal: z.ZodString;
 }, z.core.$strict>]>>>;
 /**
  * A four-key strict object with each channel nullable, not a record over the
@@ -40,6 +93,10 @@ export declare const InputBinding: z.ZodObject<{
             any: "any";
             "type-violating": "type-violating";
         }>;
+    }, z.core.$strict>, z.ZodObject<{
+        captured: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        principal: z.ZodString;
     }, z.core.$strict>]>>>;
     query: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         literal: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
@@ -48,6 +105,10 @@ export declare const InputBinding: z.ZodObject<{
             any: "any";
             "type-violating": "type-violating";
         }>;
+    }, z.core.$strict>, z.ZodObject<{
+        captured: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        principal: z.ZodString;
     }, z.core.$strict>]>>>;
     header: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         literal: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
@@ -56,6 +117,10 @@ export declare const InputBinding: z.ZodObject<{
             any: "any";
             "type-violating": "type-violating";
         }>;
+    }, z.core.$strict>, z.ZodObject<{
+        captured: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        principal: z.ZodString;
     }, z.core.$strict>]>>>;
     body: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         literal: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
@@ -64,8 +129,34 @@ export declare const InputBinding: z.ZodObject<{
             any: "any";
             "type-violating": "type-violating";
         }>;
+    }, z.core.$strict>, z.ZodObject<{
+        captured: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        principal: z.ZodString;
     }, z.core.$strict>]>>>;
 }, z.core.$strict>;
+/**
+ * AD-39's declared selector cardinality (owed item 2): what a step means when
+ * its selector matches more than one observation was not decided at the
+ * architecture layer, so a first-match scorer and a last-match scorer could
+ * bind different evidence. The contract now declares the rule per step.
+ * `several` under `exactly-one`/`at-most-one` is a named ambiguity condition;
+ * a reference function returns it as data. Routing that ambiguity to a
+ * verdict rung is later work. `any` is unrelated to
+ * `BindingValue`'s `{ matcher: 'any' }` above: same string, different field,
+ * no type-level collision. `ExpectedCardinality` (`interface.ts`) is a
+ * second, unrelated reuse of the word for AD-20's response-collection
+ * cardinality, and its `at-most` mode is a near-miss for `at-most-one` here;
+ * different type, different field, no collision, but easy to misread as the
+ * same declaration.
+ */
+export declare const SELECTOR_CARDINALITIES: readonly ['exactly-one', 'at-most-one', 'any'];
+export type SelectorCardinalityValue = (typeof SELECTOR_CARDINALITIES)[number];
+export declare const SelectorCardinality: z.ZodEnum<{
+    any: "any";
+    "at-most-one": "at-most-one";
+    "exactly-one": "exactly-one";
+}>;
 /**
  * AD-39: a step is a selector over observations the evaluator produced, never
  * an instruction. Its selection predicate is spelled as its two members, the
@@ -84,6 +175,10 @@ export declare const InteractionStep: z.ZodObject<{
                 any: "any";
                 "type-violating": "type-violating";
             }>;
+        }, z.core.$strict>, z.ZodObject<{
+            captured: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            principal: z.ZodString;
         }, z.core.$strict>]>>>;
         query: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
             literal: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
@@ -92,6 +187,10 @@ export declare const InteractionStep: z.ZodObject<{
                 any: "any";
                 "type-violating": "type-violating";
             }>;
+        }, z.core.$strict>, z.ZodObject<{
+            captured: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            principal: z.ZodString;
         }, z.core.$strict>]>>>;
         header: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
             literal: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
@@ -100,6 +199,10 @@ export declare const InteractionStep: z.ZodObject<{
                 any: "any";
                 "type-violating": "type-violating";
             }>;
+        }, z.core.$strict>, z.ZodObject<{
+            captured: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            principal: z.ZodString;
         }, z.core.$strict>]>>>;
         body: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
             literal: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
@@ -108,8 +211,17 @@ export declare const InteractionStep: z.ZodObject<{
                 any: "any";
                 "type-violating": "type-violating";
             }>;
+        }, z.core.$strict>, z.ZodObject<{
+            captured: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            principal: z.ZodString;
         }, z.core.$strict>]>>>;
     }, z.core.$strict>;
     after: z.ZodNullable<z.ZodString>;
+    cardinality: z.ZodEnum<{
+        any: "any";
+        "at-most-one": "at-most-one";
+        "exactly-one": "exactly-one";
+    }>;
 }, z.core.$strict>;
 export type InteractionStep = z.infer<typeof InteractionStep>;

package/dist/core/schemas/plan.js

@@ -1,5 +1,6 @@
 /** the interaction plan: steps as selectors over observations. */
 import { z } from 'zod';
+import { InteractionPointer } from './pointer.js';
 import { Identifier, JsonValue, KeyName } from './primitives.js';
 /**
  * AD-39: input-binding values are tagged and never share a value space. The
@@ -7,10 +8,52 @@ import { Identifier, JsonValue, KeyName } from './primitives.js';
  * one implementation and the literal string to another, and flipped a witness
  * match between `caught` and `missed` on one record; that form is
  * unrepresentable here.
+ *
+ * Four members, one tag each. `{ literal }` writes the sent value down;
+ * `{ matcher: 'any' }` binds whatever was sent and `{ matcher: 'type-violating' }`
+ * binds a value whose JSON type differs from the operation's declared type for
+ * the key, which is how AD-31 rule 3's malformed-input behaviour is addressed.
+ *
+ * `{ captured }` addresses an earlier step's declared scalar output. Owed item
+ * 3: a `POST` returning a server-generated identifier followed by a `GET`
+ * proving persistence is unwritable with the first two, since a literal
+ * hard-codes a resource the evaluator never created and `any` matches
+ * unrelated reads. "Earlier" is earlier in the capture graph's own topological
+ * order, which `binding-cycle` makes exist. It is deliberately not AD-39's
+ * `after` clause: `nested-temporal-clause` already rejects every `after` cycle,
+ * so a capture forced to follow an `after` edge would leave `binding-cycle`
+ * unfireable. At score time the ordering is the record's `sequence`.
+ *
+ * `{ principal }` names a principal `testData.principals` declares. The two
+ * critical-severity cross-user behaviours (act as A, read as B, must be denied
+ * or absent) bind a step to an account that is neither a literal, since AD-19
+ * forbids credential values in declarations, nor an earlier step's output,
+ * since accounts are provisioned outside the observation stream. The name is
+ * an opaque label carrying no account identifier, credential, or subject data
+ * (AD-18). An undeclared name fires `undeclared-mandatory-input` in strict
+ * mode; a Zod refinement here would be a cross-subtree constraint the export
+ * cannot carry, and the published-schema differential sweep synthesises a
+ * union-branch witness that would expose the disagreement.
+ *
+ * A captured pointer resolves to a declared scalar with no transform applied,
+ * which keeps AD-4's ban on arithmetic, projection, and user-defined functions
+ * holding by construction: the grammar has no place to write one.
  */
+/**
+ * The first two members, named individually so the probe-side selector under
+ * AD-40 admits exactly these two and nothing else. Bare `export const` with no
+ * `.meta({ id })`: an id would collapse the branches to `$ref`s and mint new
+ * `$defs`, so the export stays byte-identical.
+ */
+export const LiteralBindingValue = z.strictObject({ literal: JsonValue });
+export const MatcherBindingValue = z.strictObject({
+    matcher: z.enum(['any', 'type-violating']),
+});
 export const BindingValue = z.union([
-    z.strictObject({ literal: JsonValue }),
-    z.strictObject({ matcher: z.enum(['any', 'type-violating']) }),
+    LiteralBindingValue,
+    MatcherBindingValue,
+    z.strictObject({ captured: InteractionPointer }),
+    z.strictObject({ principal: Identifier }),
 ]);
 /** the constraint identifier the ledger carries for the check below. */
 export const BINDING_CHANNEL_NON_EMPTY = 'binding-channel-non-empty';
@@ -43,6 +86,27 @@ export const InputBinding = z.strictObject({
     header: BindingChannel,
     body: BindingChannel,
 });
+/**
+ * AD-39's declared selector cardinality (owed item 2): what a step means when
+ * its selector matches more than one observation was not decided at the
+ * architecture layer, so a first-match scorer and a last-match scorer could
+ * bind different evidence. The contract now declares the rule per step.
+ * `several` under `exactly-one`/`at-most-one` is a named ambiguity condition;
+ * a reference function returns it as data. Routing that ambiguity to a
+ * verdict rung is later work. `any` is unrelated to
+ * `BindingValue`'s `{ matcher: 'any' }` above: same string, different field,
+ * no type-level collision. `ExpectedCardinality` (`interface.ts`) is a
+ * second, unrelated reuse of the word for AD-20's response-collection
+ * cardinality, and its `at-most` mode is a near-miss for `at-most-one` here;
+ * different type, different field, no collision, but easy to misread as the
+ * same declaration.
+ */
+export const SELECTOR_CARDINALITIES = [
+    'exactly-one',
+    'at-most-one',
+    'any',
+];
+export const SelectorCardinality = z.enum(SELECTOR_CARDINALITIES);
 /**
  * AD-39: a step is a selector over observations the evaluator produced, never
  * an instruction. Its selection predicate is spelled as its two members, the
@@ -55,4 +119,5 @@ export const InteractionStep = z.strictObject({
     operationId: Identifier,
     inputBinding: InputBinding,
     after: Identifier.nullable().describe("The temporal clause: the identifier of an earlier step, or `null`. That the named step carries no clause of its own is AD-39's one-level bound, which fires `nested-temporal-clause` at compile time and is deliberately not enforced here, so the code keeps a shape to fire on."),
+    cardinality: SelectorCardinality.describe("AD-39's declared selector cardinality (owed item 2): `exactly-one` or `at-most-one` when the step expects a single matching observation, `any` when several are legitimate. Several matches under `exactly-one`/`at-most-one` is the named ambiguity condition; a reference selection function returns it as data. Required rather than optional, which makes this a BREAKING `schemaVersion` bump under AD-11: adding an optional field is additive, and this field is not optional."),
 });