niceeval 0.13.2 → 0.13.3

package/dist/assertions/api.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["api.ts"],"names":[],"mappings":";;;AA4KA;;;;GAIG;AACU,QAAA,oBAAoB,GAAkB,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAevF;;;;;GAKG;AACH,MAAa,6BAA8B,SAAQ,KAAK;IAE/B;IADZ,IAAI,GAAG,+BAA+B,CAAC;IAChD,YAAqB,MAA4G;QAC7H,KAAK,CAAC,kDAAkD,MAAM,EAAE,CAAC,CAAC;QADjD,WAAM,GAAN,MAAM,CAAsG;QAE7H,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAChD,CAAC;CACJ;AAND,sEAMC","sourcesContent":["import type { Effect } from \"effect\";\nimport type { BooleanMatch, MatchDiagnostic, ScoreMatch, ThresholdedScoreMatch, } from \"./match.ts\";\nimport type { AgentWorkspaceDiff } from \"./workspace-diff.ts\";\n/** The two Evaluation kinds deliberately share one Assertion entry model. */\nexport type AssertionEvaluationKind = \"pass\" | \"score\";\n/**\n * A bounded JSON-shaped value owned by the authoring runtime.  It is a\n * domain value, not the durable Assertions attachment material type.\n */\nexport type AssertionSnapshotValue = null | boolean | number | string | readonly AssertionSnapshotValue[] | AssertionSnapshotObject;\nexport interface AssertionSnapshotObject {\n    readonly [key: string]: AssertionSnapshotValue;\n}\nexport interface AssertionDisplay {\n    readonly key?: string;\n    readonly label?: string;\n    readonly groupPath: readonly string[];\n}\nexport type AssertionCoverage = {\n    readonly state: \"complete\";\n} | {\n    readonly state: \"partial\";\n    readonly reason: \"sampled\" | \"truncated\" | \"redacted\" | \"provider-limited\";\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"not-collected\" | \"source-unavailable\" | \"producer-failed\";\n} | {\n    readonly state: \"not-applicable\";\n    readonly reason: \"optional-material\" | \"unsupported-subject\";\n};\nexport type AssertionLimitation = {\n    readonly kind: \"redacted\";\n    readonly fieldCount: number;\n} | {\n    readonly kind: \"sampled\";\n    readonly captured: number;\n    readonly knownTotal?: number;\n} | {\n    readonly kind: \"truncated\";\n    readonly omittedBytes: number;\n} | {\n    readonly kind: \"provider-limited\";\n};\n/**\n * Authoring material intentionally has no blob ref, attachment entry ID, or\n * durable schema identity. The private producer adapter selects the exact\n * same-owner Attachment schema when it serializes this domain reference.\n */\nexport type AssertionMaterial = {\n    readonly kind: \"snapshot\";\n    readonly value: AssertionSnapshotValue;\n} | {\n    readonly kind: \"record-attachment\";\n    readonly preview: string;\n};\nexport type AssertionCriterion = {\n    readonly kind: \"value-match\";\n    readonly subject: \"explicit-value\";\n} | {\n    readonly kind: \"scope-status\";\n    readonly scope: \"turn\" | \"session\" | \"attempt\";\n    readonly assertion: \"succeeded\" | \"no-failed-actions\";\n} | {\n    readonly kind: \"occurrence\";\n    readonly scope: \"turn\" | \"session\" | \"attempt\";\n    readonly occurrence: \"tool\" | \"skill\" | \"event\";\n    readonly assertion: \"present\" | \"absent\" | \"count\";\n    readonly matcher?: string;\n    readonly quantifier?: {\n        readonly kind: \"absent\";\n    } | {\n        readonly kind: \"at-least\" | \"exact\";\n        readonly count: number;\n    };\n} | {\n    readonly kind: \"judge-measurement\";\n    readonly recipe: \"closed-qa\" | \"factuality\" | \"summarizes\";\n    readonly scale: \"unit-interval\";\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"changed-paths\";\n    readonly paths: readonly string[];\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"no-changes\";\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"file-changed\";\n    readonly path: string;\n    readonly status?: \"added\" | \"modified\" | \"deleted\";\n    readonly before?: string;\n    readonly after?: string;\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"file-deleted\";\n    readonly path: string;\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"not-in-diff\";\n    readonly pattern: string;\n    readonly flags: string;\n    readonly content: \"added\" | \"removed\" | \"both\";\n} | {\n    readonly kind: \"direct-score\";\n    readonly source: \"author\";\n} | {\n    readonly kind: \"third-party\";\n    readonly name: string;\n    readonly schemaId: string;\n    readonly data: AssertionSnapshotValue;\n};\nexport type AssertionScoreContribution = {\n    readonly state: \"not-scored\";\n} | {\n    readonly state: \"earned\";\n    readonly points: number;\n    readonly earned: number;\n} | {\n    readonly state: \"unavailable\";\n    readonly points: number;\n    readonly reason: \"source-unavailable\" | \"evaluation-errored\" | \"not-applicable\";\n};\nexport type AssertionResult = {\n    readonly state: \"matched\";\n    readonly gate: \"not-gate\" | \"satisfied\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"earned\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n} | {\n    readonly state: \"mismatched\";\n    readonly reason: \"condition-not-met\";\n    readonly gate: \"not-gate\" | \"failed\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"earned\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"evidence-unavailable\" | \"source-unavailable\" | \"redacted\";\n    readonly gate: \"not-gate\" | \"unavailable\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"unavailable\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n} | {\n    readonly state: \"errored\";\n    readonly reason: \"evaluator-failed\" | \"producer-interrupted\" | \"invalid-subject\";\n    readonly gate: \"not-gate\" | \"unavailable\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"unavailable\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n} | {\n    readonly state: \"not-applicable\";\n    readonly reason: \"coverage-not-applicable\";\n    readonly gate: \"not-gate\" | \"not-applicable\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"unavailable\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n};\n/** One fully formed author/runtime result, before durable attachment encoding. */\nexport interface SealedAssertionEntry {\n    readonly display: AssertionDisplay;\n    readonly criterion: AssertionCriterion;\n    readonly subject: AssertionMaterial;\n    readonly evidence: readonly AssertionMaterial[];\n    readonly coverage: AssertionCoverage;\n    readonly limitations: readonly AssertionLimitation[];\n    readonly result: AssertionResult;\n}\n/**\n * Assertion handles are runtime-owned capabilities, not subjects for another\n * `t.check`. The symbol is public only for TypeScript's nominal boundary; the\n * runtime also keeps an unforgeable ownership registry.\n */\nexport const assertionHandleBrand: unique symbol = Symbol(\"niceeval.assertion-handle\");\nexport interface AssertionHandleBase {\n    readonly [assertionHandleBrand]: true;\n    key(value: string): this;\n    label(value: string): this;\n    /** Adds one display-only group segment to this already registered entry. */\n    group(title: string): this;\n}\n/** A value that is not an AssertionHandle. */\nexport type AssertionSubject<Value> = Value extends AssertionHandleBase ? never : Value;\nexport interface AssertionStopError {\n    readonly _tag: \"AssertionStopError\";\n    readonly entryIndex: number;\n    readonly reason: \"condition-not-met\" | \"source-unavailable\" | \"evaluator-failed\" | \"not-applicable\";\n}\n/**\n * A public authoring call reached an Attempt boundary which is no longer able\n * to accept it. Keeping this distinct from an evaluator failure lets a\n * detached Promise diagnose its own lifecycle error instead of looking like a\n * failed assertion.\n */\nexport class AssertionAuthoringClosedError extends Error {\n    readonly _tag = \"AssertionAuthoringClosedError\";\n    constructor(readonly reason: \"stop-latched\" | \"attempt-sealing\" | \"attempt-sealed\" | \"attempt-interrupted\" | \"runtime-unattached\") {\n        super(`Cannot use an Assertion authoring handle after ${reason}`);\n        this.name = \"AssertionAuthoringClosedError\";\n    }\n}\n/**\n * The owning Attempt executes a requested stop barrier in its existing Effect\n * scope. Handles only enqueue this request; they never create a runtime.\n */\nexport type AssertionStopExecutor = <Value>(effect: Effect.Effect<Value, AssertionStopError, never>) => Promise<Value>;\n/** A Boolean entry is evaluated once and may retain a refinement witness. */\nexport type BooleanAssertionEvaluation<Refined> = {\n    readonly state: \"matched\";\n    readonly value: Refined;\n    readonly diagnostic?: MatchDiagnostic;\n} | {\n    readonly state: \"mismatched\";\n    readonly diagnostic?: MatchDiagnostic;\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"evidence-unavailable\" | \"source-unavailable\" | \"redacted\";\n    readonly diagnostic?: MatchDiagnostic;\n} | {\n    readonly state: \"not-applicable\";\n    readonly diagnostic?: MatchDiagnostic;\n};\n/** A measurement is always a finite unit-interval value when it is available. */\nexport type MeasurementAssertionEvaluation = {\n    readonly state: \"measured\";\n    readonly value: number;\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"evidence-unavailable\" | \"source-unavailable\" | \"redacted\";\n} | {\n    readonly state: \"not-applicable\";\n} | {\n    readonly state: \"errored\";\n};\nexport interface CapturedAssertionSnapshot {\n    readonly material: Extract<AssertionMaterial, {\n        readonly kind: \"snapshot\";\n    }>;\n    readonly coverage: AssertionCoverage;\n    readonly limitations: readonly AssertionLimitation[];\n}\nexport interface AssertionRegistrationBase {\n    readonly criterion: AssertionCriterion;\n    readonly subject: AssertionMaterial;\n    readonly evidence?: readonly AssertionMaterial[];\n    readonly coverage?: AssertionCoverage;\n    readonly limitations?: readonly AssertionLimitation[];\n}\n/**\n * Scope, Judge, and Sandbox adapters use this internal registration shape.\n * They still register exactly one Assertion entry; they do not manufacture a\n * separate intermediate value for a later consumer.\n */\nexport interface BooleanAssertionRegistration<Refined> extends AssertionRegistrationBase {\n    readonly evaluate: () => Effect.Effect<BooleanAssertionEvaluation<Refined>, unknown, never>;\n}\nexport interface MeasurementAssertionRegistration extends AssertionRegistrationBase {\n    readonly evaluate: () => Effect.Effect<MeasurementAssertionEvaluation, unknown, never>;\n}\nexport interface PassBooleanAssertionHandle<out Refined> extends AssertionHandleBase {\n    readonly kind: \"boolean\";\n    /** An unavailable/errored optional entry does not independently error Verdict. */\n    optional(): this;\n    gate(): this;\n    orStop(): Promise<Refined>;\n}\nexport interface ScoreBooleanAssertionHandle<out Refined> extends AssertionHandleBase {\n    readonly kind: \"boolean\";\n    score(points: number): this;\n    orStop(): Promise<Refined>;\n}\nexport interface PassMeasurementAssertionHandle<Thresholded extends boolean = false> extends AssertionHandleBase {\n    readonly kind: \"measurement\";\n    /** An unavailable/errored optional entry does not independently error Verdict. */\n    optional(): this;\n    atLeast(value: number): PassMeasurementAssertionHandle<true>;\n    gate(value: number): PassMeasurementAssertionHandle<true>;\n    orStop(this: PassMeasurementAssertionHandle<true>): Promise<number>;\n}\nexport interface ScoreMeasurementAssertionHandle<Thresholded extends boolean = false> extends AssertionHandleBase {\n    readonly kind: \"measurement\";\n    atLeast(value: number): ScoreMeasurementAssertionHandle<true>;\n    score(points: number): this;\n    orStop(this: ScoreMeasurementAssertionHandle<true>): Promise<number>;\n}\n/** A Boolean Assertion that intentionally has no author control-flow operation. */\ninterface PostRunPassBooleanAssertionHandle<Refined> extends AssertionHandleBase {\n    readonly kind: \"boolean\";\n    optional(): this;\n    gate(): this;\n}\ninterface PostRunScoreBooleanAssertionHandle<Refined> extends AssertionHandleBase {\n    readonly kind: \"boolean\";\n    score(points: number): this;\n}\nexport type PostRunBooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined> = Kind extends \"pass\" ? PostRunPassBooleanAssertionHandle<Refined> : PostRunScoreBooleanAssertionHandle<Refined>;\n/** Direct score is an Assertion entry, but has no condition or stop barrier. */\nexport interface DirectScoreAssertionHandle extends AssertionHandleBase {\n    readonly kind: \"direct-score\";\n}\nexport interface AssertionGroupContext {\n    /**\n     * Runs an ordinary author callback with one display-only group segment. The\n     * callback remains inside the Attempt's outer Promise boundary; this facade\n     * does not evaluate an Effect or create an independent runtime.\n     */\n    group<Value>(title: string, body: () => Value | PromiseLike<Value>): Promise<Awaited<Value>>;\n}\nexport interface PassAssertionsContext extends AssertionGroupContext {\n    readonly evaluationKind: \"pass\";\n    check<Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, \"value\">): PassBooleanAssertionHandle<Refined>;\n    check<Value>(value: AssertionSubject<Value>, match: ScoreMatch<NoInfer<Value>>): PassMeasurementAssertionHandle;\n    check<Value>(value: AssertionSubject<Value>, match: ThresholdedScoreMatch<NoInfer<Value>>): PassMeasurementAssertionHandle<true>;\n}\nexport interface ScoreAssertionsContext extends AssertionGroupContext {\n    readonly evaluationKind: \"score\";\n    check<Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, \"value\">): ScoreBooleanAssertionHandle<Refined>;\n    check<Value>(value: AssertionSubject<Value>, match: ScoreMatch<NoInfer<Value>>): ScoreMeasurementAssertionHandle;\n    check<Value>(value: AssertionSubject<Value>, match: ThresholdedScoreMatch<NoInfer<Value>>): ScoreMeasurementAssertionHandle<true>;\n    score(points: number): DirectScoreAssertionHandle;\n}\nexport type AssertionsContext<Kind extends AssertionEvaluationKind> = Kind extends \"pass\" ? PassAssertionsContext : ScoreAssertionsContext;\nexport type BooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined> = Kind extends \"pass\" ? PassBooleanAssertionHandle<Refined> : ScoreBooleanAssertionHandle<Refined>;\nexport type MeasurementAssertionHandle<Kind extends AssertionEvaluationKind> = Kind extends \"pass\" ? PassMeasurementAssertionHandle : ScoreMeasurementAssertionHandle;\nexport interface AssertionSealOptions {\n    readonly execution?: \"completed\" | \"errored\";\n    readonly explicitlySkipped?: boolean;\n    /**\n     * The owning Attempt was interrupted before ordinary evaluation could\n     * finish. Unsettled entries are sealed as producer-interrupted instead of\n     * being silently omitted or evaluated on a detached runtime.\n     */\n    readonly interrupted?: boolean;\n}\nexport interface AssertionSealError {\n    readonly _tag: \"AssertionSealError\";\n    readonly code: \"pass-measurement-threshold-missing\";\n    readonly entryIndex: number;\n}\n/** The sealed evaluation is a domain result, not a durable Record payload. */\nexport interface SealedAssertionEvaluationEntry {\n    readonly required: boolean;\n    readonly result: AssertionResult;\n}\nexport interface SealedAssertionEvaluation {\n    readonly execution: \"completed\" | \"errored\";\n    readonly explicitlySkipped: boolean;\n    readonly assertions: readonly SealedAssertionEvaluationEntry[];\n}\n/**\n * One immutable result feeds the Verdict/Score fold and the private durable\n * producer adapter. No RecordAttachment writer type crosses this boundary.\n */\nexport interface SealedAssertionsRuntime {\n    readonly entries: readonly SealedAssertionEntry[];\n    readonly evaluation: SealedAssertionEvaluation;\n}\n/** The runtime Verdict is independent of the durable Verdict attachment codec. */\nexport interface AssertionVerdict {\n    readonly state: \"passed\" | \"failed\" | \"errored\" | \"skipped\";\n}\nexport type AssertionScoreIncompleteReason = \"execution-errored\" | \"source-unavailable\" | \"evaluation-errored\" | \"not-applicable\";\n/** The runtime Score is independent of the durable Score attachment codec. */\nexport type AssertionScore = {\n    readonly state: \"complete\";\n    readonly earned: number;\n} | {\n    readonly state: \"partial\";\n    readonly earned: number;\n    readonly reasons: readonly AssertionScoreIncompleteReason[];\n} | {\n    readonly state: \"unavailable\";\n    readonly reasons: readonly AssertionScoreIncompleteReason[];\n};\n/**\n * The attempt-owned frozen result is handed from Runner to the Evaluation\n * Record adapter. The adapter alone adds attachment schemas and writes.\n */\nexport interface SealedAttemptAssertions {\n    readonly entries: readonly SealedAssertionEntry[];\n    readonly evaluation: SealedAssertionEvaluation;\n    readonly workspaceDiff?: AgentWorkspaceDiff;\n    readonly verdict: AssertionVerdict;\n    readonly score?: AssertionScore;\n}\nexport interface AssertionsRuntime<Kind extends AssertionEvaluationKind> {\n    readonly evaluationKind: Kind;\n    readonly t: AssertionsContext<Kind>;\n    registerBoolean<Refined>(definition: BooleanAssertionRegistration<Refined>): BooleanAssertionHandle<Kind, Refined>;\n    registerMeasurement(definition: MeasurementAssertionRegistration): MeasurementAssertionHandle<Kind>;\n    seal(options?: AssertionSealOptions): Effect.Effect<SealedAssertionsRuntime, AssertionSealError, never>;\n}\n"]}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["api.ts"],"names":[],"mappings":";;;AAmOA;;;;GAIG;AACU,QAAA,oBAAoB,GAAkB,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAevF;;;;;GAKG;AACH,MAAa,6BAA8B,SAAQ,KAAK;IAE/B;IADZ,IAAI,GAAG,+BAA+B,CAAC;IAChD,YAAqB,MAA4G;QAC7H,KAAK,CAAC,kDAAkD,MAAM,EAAE,CAAC,CAAC;QADjD,WAAM,GAAN,MAAM,CAAsG;QAE7H,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAChD,CAAC;CACJ;AAND,sEAMC","sourcesContent":["import type { Effect } from \"effect\";\nimport type { BooleanMatch, MatchDiagnostic, ScoreMatch, ThresholdedScoreMatch, } from \"./match.ts\";\nimport type { AgentWorkspaceDiff } from \"./workspace-diff.ts\";\n/** The two Evaluation kinds deliberately share one Assertion entry model. */\nexport type AssertionEvaluationKind = \"pass\" | \"score\";\n/**\n * A bounded JSON-shaped value owned by the authoring runtime.  It is a\n * domain value, not the durable Assertions attachment material type.\n */\nexport type AssertionSnapshotValue = null | boolean | number | string | readonly AssertionSnapshotValue[] | AssertionSnapshotObject;\nexport interface AssertionSnapshotObject {\n    readonly [key: string]: AssertionSnapshotValue;\n}\nexport interface AssertionDisplay {\n    readonly key?: string;\n    readonly label?: string;\n    readonly groupPath: readonly string[];\n}\nexport type AssertionCoverage = {\n    readonly state: \"complete\";\n} | {\n    readonly state: \"partial\";\n    readonly reason: \"sampled\" | \"truncated\" | \"redacted\" | \"provider-limited\";\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"not-collected\" | \"source-unavailable\" | \"producer-failed\";\n} | {\n    readonly state: \"not-applicable\";\n    readonly reason: \"optional-material\" | \"unsupported-subject\";\n};\nexport type AssertionLimitation = {\n    readonly kind: \"redacted\";\n    readonly fieldCount: number;\n} | {\n    readonly kind: \"sampled\";\n    readonly captured: number;\n    readonly knownTotal?: number;\n} | {\n    readonly kind: \"truncated\";\n    readonly omittedBytes: number;\n} | {\n    readonly kind: \"provider-limited\";\n};\n/**\n * Authoring material intentionally has no blob ref, attachment entry ID, or\n * durable schema identity. The private producer adapter selects the exact\n * same-owner Attachment schema when it serializes this domain reference.\n */\nexport type AssertionMaterial = {\n    readonly kind: \"snapshot\";\n    readonly value: AssertionSnapshotValue;\n} | {\n    readonly kind: \"record-attachment\";\n    readonly preview: string;\n};\nexport type AssertionCriterion = {\n    readonly kind: \"value-match\";\n    readonly subject: \"explicit-value\";\n    readonly matcher: {\n        readonly state: \"declared\";\n        readonly name: string;\n    } | {\n        readonly state: \"unavailable\";\n    };\n} | {\n    readonly kind: \"scope-status\";\n    readonly scope: \"turn\" | \"session\" | \"attempt\";\n    readonly assertion: \"succeeded\" | \"no-failed-actions\";\n} | {\n    readonly kind: \"occurrence\";\n    readonly scope: \"turn\" | \"session\" | \"attempt\";\n    readonly occurrence: \"tool\" | \"skill\" | \"event\";\n    readonly assertion: \"present\" | \"absent\" | \"count\";\n    readonly matcher?: string;\n    readonly quantifier?: {\n        readonly kind: \"absent\";\n    } | {\n        readonly kind: \"at-least\" | \"exact\";\n        readonly count: number;\n    };\n} | {\n    readonly kind: \"judge-measurement\";\n    readonly recipe: \"closed-qa\" | \"factuality\" | \"summarizes\";\n    readonly scale: \"unit-interval\";\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"changed-paths\";\n    readonly paths: readonly string[];\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"no-changes\";\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"file-changed\";\n    readonly path: string;\n    readonly status?: \"added\" | \"modified\" | \"deleted\";\n    readonly before?: string;\n    readonly after?: string;\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"file-deleted\";\n    readonly path: string;\n} | {\n    readonly kind: \"sandbox-result\";\n    readonly operation: \"not-in-diff\";\n    readonly pattern: string;\n    readonly flags: string;\n    readonly content: \"added\" | \"removed\" | \"both\";\n} | {\n    readonly kind: \"direct-score\";\n    readonly source: \"author\";\n} | {\n    readonly kind: \"third-party\";\n    readonly name: string;\n    readonly schemaId: string;\n    readonly data: AssertionSnapshotValue;\n};\nexport type AssertionScoreContribution = {\n    readonly state: \"not-scored\";\n} | {\n    readonly state: \"earned\";\n    readonly points: number;\n    readonly earned: number;\n} | {\n    readonly state: \"unavailable\";\n    readonly points: number;\n    readonly reason: \"source-unavailable\" | \"evaluation-errored\" | \"not-applicable\";\n};\n/** Constant-size semantic receipt for one collection evaluation. */\nexport interface AssertionCollectionReceipt {\n    readonly examined: number;\n    readonly matched: number;\n    readonly mismatched: number;\n    readonly unavailable: number;\n    readonly knownTotal: number | null;\n    readonly complete: boolean;\n    readonly exhaustive: boolean;\n    readonly decisive: boolean;\n}\nexport type AssertionConditionPolicy = {\n    readonly kind: \"boolean\";\n    readonly expected: true;\n} | {\n    readonly kind: \"at-least\";\n    readonly threshold: number;\n} | {\n    readonly kind: \"record-only\";\n};\nexport interface AssertionPolicy {\n    readonly requirement: \"required\" | \"optional\";\n    readonly condition: AssertionConditionPolicy;\n}\nexport type AssertionObserved = {\n    readonly kind: \"boolean\";\n    readonly outcome: \"matched\" | \"mismatched\" | \"unavailable\" | \"errored\" | \"not-applicable\";\n} | {\n    readonly kind: \"measurement\";\n    readonly state: \"available\";\n    readonly value: number;\n} | {\n    readonly kind: \"measurement\";\n    readonly state: \"unavailable\";\n} | {\n    readonly kind: \"direct-score\";\n    readonly state: \"available\";\n    readonly value: number;\n} | {\n    readonly kind: \"direct-score\";\n    readonly state: \"unavailable\";\n};\nexport type AssertionResult = {\n    readonly state: \"matched\";\n    readonly gate: \"not-gate\" | \"satisfied\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"earned\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n    readonly receipt?: AssertionCollectionReceipt;\n} | {\n    readonly state: \"mismatched\";\n    readonly reason: \"condition-not-met\";\n    readonly gate: \"not-gate\" | \"failed\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"earned\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n    readonly receipt?: AssertionCollectionReceipt;\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"evidence-unavailable\" | \"source-unavailable\" | \"redacted\";\n    readonly gate: \"not-gate\" | \"unavailable\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"unavailable\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n    readonly receipt?: AssertionCollectionReceipt;\n} | {\n    readonly state: \"errored\";\n    readonly reason: \"evaluator-failed\" | \"producer-interrupted\" | \"invalid-subject\";\n    readonly gate: \"not-gate\" | \"unavailable\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"unavailable\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n    readonly receipt?: AssertionCollectionReceipt;\n} | {\n    readonly state: \"not-applicable\";\n    readonly reason: \"coverage-not-applicable\";\n    readonly gate: \"not-gate\" | \"not-applicable\";\n    readonly score: Extract<AssertionScoreContribution, {\n        readonly state: \"not-scored\" | \"unavailable\";\n    }>;\n    readonly diagnostic?: AssertionSnapshotObject;\n    readonly receipt?: AssertionCollectionReceipt;\n};\n/** One fully formed author/runtime result, before durable attachment encoding. */\nexport interface SealedAssertionEntry {\n    readonly display: AssertionDisplay;\n    readonly criterion: AssertionCriterion;\n    readonly subject: AssertionMaterial;\n    readonly evidence: readonly AssertionMaterial[];\n    readonly coverage: AssertionCoverage;\n    readonly limitations: readonly AssertionLimitation[];\n    readonly result: AssertionResult;\n    readonly policy: AssertionPolicy;\n    readonly observed: AssertionObserved;\n}\n/**\n * Assertion handles are runtime-owned capabilities, not subjects for another\n * `t.check`. The symbol is public only for TypeScript's nominal boundary; the\n * runtime also keeps an unforgeable ownership registry.\n */\nexport const assertionHandleBrand: unique symbol = Symbol(\"niceeval.assertion-handle\");\nexport interface AssertionHandleBase {\n    readonly [assertionHandleBrand]: true;\n    key(value: string): this;\n    label(value: string): this;\n    /** Adds one display-only group segment to this already registered entry. */\n    group(title: string): this;\n}\n/** A value that is not an AssertionHandle. */\nexport type AssertionSubject<Value> = Value extends AssertionHandleBase ? never : Value;\nexport interface AssertionStopError {\n    readonly _tag: \"AssertionStopError\";\n    readonly entryIndex: number;\n    readonly reason: \"condition-not-met\" | \"source-unavailable\" | \"evaluator-failed\" | \"not-applicable\";\n}\n/**\n * A public authoring call reached an Attempt boundary which is no longer able\n * to accept it. Keeping this distinct from an evaluator failure lets a\n * detached Promise diagnose its own lifecycle error instead of looking like a\n * failed assertion.\n */\nexport class AssertionAuthoringClosedError extends Error {\n    readonly _tag = \"AssertionAuthoringClosedError\";\n    constructor(readonly reason: \"stop-latched\" | \"attempt-sealing\" | \"attempt-sealed\" | \"attempt-interrupted\" | \"runtime-unattached\") {\n        super(`Cannot use an Assertion authoring handle after ${reason}`);\n        this.name = \"AssertionAuthoringClosedError\";\n    }\n}\n/**\n * The owning Attempt executes a requested stop barrier in its existing Effect\n * scope. Handles only enqueue this request; they never create a runtime.\n */\nexport type AssertionStopExecutor = <Value>(effect: Effect.Effect<Value, AssertionStopError, never>) => Promise<Value>;\n/** A Boolean entry is evaluated once and may retain a refinement witness. */\nexport type BooleanAssertionEvaluation<Refined> = {\n    readonly state: \"matched\";\n    readonly value: Refined;\n    readonly diagnostic?: MatchDiagnostic;\n    readonly receipt?: AssertionCollectionReceipt;\n} | {\n    readonly state: \"mismatched\";\n    readonly diagnostic?: MatchDiagnostic;\n    readonly receipt?: AssertionCollectionReceipt;\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"evidence-unavailable\" | \"source-unavailable\" | \"redacted\";\n    readonly diagnostic?: MatchDiagnostic;\n    readonly receipt?: AssertionCollectionReceipt;\n} | {\n    readonly state: \"not-applicable\";\n    readonly diagnostic?: MatchDiagnostic;\n};\n/** A measurement is always a finite unit-interval value when it is available. */\nexport type MeasurementAssertionEvaluation = {\n    readonly state: \"measured\";\n    readonly value: number;\n    readonly detail?: AssertionSnapshotObject;\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"evidence-unavailable\" | \"source-unavailable\" | \"redacted\";\n    readonly detail?: AssertionSnapshotObject;\n} | {\n    readonly state: \"not-applicable\";\n    readonly detail?: AssertionSnapshotObject;\n} | {\n    readonly state: \"errored\";\n    readonly detail?: AssertionSnapshotObject;\n};\nexport interface CapturedAssertionSnapshot {\n    readonly material: Extract<AssertionMaterial, {\n        readonly kind: \"snapshot\";\n    }>;\n    readonly coverage: AssertionCoverage;\n    readonly limitations: readonly AssertionLimitation[];\n}\nexport interface AssertionRegistrationBase {\n    readonly criterion: AssertionCriterion;\n    readonly subject: AssertionMaterial;\n    readonly evidence?: readonly AssertionMaterial[];\n    readonly coverage?: AssertionCoverage;\n    readonly limitations?: readonly AssertionLimitation[];\n}\n/**\n * Scope, Judge, and Sandbox adapters use this internal registration shape.\n * They still register exactly one Assertion entry; they do not manufacture a\n * separate intermediate value for a later consumer.\n */\nexport interface BooleanAssertionRegistration<Refined> extends AssertionRegistrationBase {\n    readonly evaluate: () => Effect.Effect<BooleanAssertionEvaluation<Refined>, unknown, never>;\n}\nexport interface MeasurementAssertionRegistration extends AssertionRegistrationBase {\n    readonly evaluate: () => Effect.Effect<MeasurementAssertionEvaluation, unknown, never>;\n}\nexport interface PassBooleanAssertionHandle<out Refined> extends AssertionHandleBase {\n    readonly kind: \"boolean\";\n    /** An unavailable/errored optional entry does not independently error Verdict. */\n    optional(): this;\n    gate(): this;\n    orStop(): Promise<Refined>;\n}\nexport interface ScoreBooleanAssertionHandle<out Refined> extends AssertionHandleBase {\n    readonly kind: \"boolean\";\n    score(points: number): this;\n    orStop(): Promise<Refined>;\n}\nexport interface PassMeasurementAssertionHandle<Thresholded extends boolean = false> extends AssertionHandleBase {\n    readonly kind: \"measurement\";\n    /** An unavailable/errored optional entry does not independently error Verdict. */\n    optional(): this;\n    atLeast(value: number): PassMeasurementAssertionHandle<true>;\n    gate(value: number): PassMeasurementAssertionHandle<true>;\n    orStop(this: PassMeasurementAssertionHandle<true>): Promise<number>;\n}\nexport interface ScoreMeasurementAssertionHandle<Thresholded extends boolean = false> extends AssertionHandleBase {\n    readonly kind: \"measurement\";\n    atLeast(value: number): ScoreMeasurementAssertionHandle<true>;\n    score(points: number): this;\n    orStop(this: ScoreMeasurementAssertionHandle<true>): Promise<number>;\n}\n/** A Boolean Assertion that intentionally has no author control-flow operation. */\ninterface PostRunPassBooleanAssertionHandle<Refined> extends AssertionHandleBase {\n    readonly kind: \"boolean\";\n    optional(): this;\n    gate(): this;\n}\ninterface PostRunScoreBooleanAssertionHandle<Refined> extends AssertionHandleBase {\n    readonly kind: \"boolean\";\n    score(points: number): this;\n}\nexport type PostRunBooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined> = Kind extends \"pass\" ? PostRunPassBooleanAssertionHandle<Refined> : PostRunScoreBooleanAssertionHandle<Refined>;\n/** Direct score is an Assertion entry, but has no condition or stop barrier. */\nexport interface DirectScoreAssertionHandle extends AssertionHandleBase {\n    readonly kind: \"direct-score\";\n}\nexport interface AssertionGroupContext {\n    /**\n     * Runs an ordinary author callback with one display-only group segment. The\n     * callback remains inside the Attempt's outer Promise boundary; this facade\n     * does not evaluate an Effect or create an independent runtime.\n     */\n    group<Value>(title: string, body: () => Value | PromiseLike<Value>): Promise<Awaited<Value>>;\n}\nexport interface PassAssertionsContext extends AssertionGroupContext {\n    readonly evaluationKind: \"pass\";\n    check<Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, \"value\">): PassBooleanAssertionHandle<Refined>;\n    check<Value>(value: AssertionSubject<Value>, match: ScoreMatch<NoInfer<Value>>): PassMeasurementAssertionHandle;\n    check<Value>(value: AssertionSubject<Value>, match: ThresholdedScoreMatch<NoInfer<Value>>): PassMeasurementAssertionHandle<true>;\n}\nexport interface ScoreAssertionsContext extends AssertionGroupContext {\n    readonly evaluationKind: \"score\";\n    check<Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, \"value\">): ScoreBooleanAssertionHandle<Refined>;\n    check<Value>(value: AssertionSubject<Value>, match: ScoreMatch<NoInfer<Value>>): ScoreMeasurementAssertionHandle;\n    check<Value>(value: AssertionSubject<Value>, match: ThresholdedScoreMatch<NoInfer<Value>>): ScoreMeasurementAssertionHandle<true>;\n    score(points: number): DirectScoreAssertionHandle;\n}\nexport type AssertionsContext<Kind extends AssertionEvaluationKind> = Kind extends \"pass\" ? PassAssertionsContext : ScoreAssertionsContext;\nexport type BooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined> = Kind extends \"pass\" ? PassBooleanAssertionHandle<Refined> : ScoreBooleanAssertionHandle<Refined>;\nexport type MeasurementAssertionHandle<Kind extends AssertionEvaluationKind> = Kind extends \"pass\" ? PassMeasurementAssertionHandle : ScoreMeasurementAssertionHandle;\nexport interface AssertionSealOptions {\n    readonly execution?: \"completed\" | \"errored\";\n    readonly explicitlySkipped?: boolean;\n    /**\n     * The owning Attempt was interrupted before ordinary evaluation could\n     * finish. Unsettled entries are sealed as producer-interrupted instead of\n     * being silently omitted or evaluated on a detached runtime.\n     */\n    readonly interrupted?: boolean;\n}\nexport interface AssertionSealError {\n    readonly _tag: \"AssertionSealError\";\n    readonly code: \"pass-measurement-threshold-missing\";\n    readonly entryIndex: number;\n}\n/** The sealed evaluation is a domain result, not a durable Record payload. */\nexport interface SealedAssertionEvaluationEntry {\n    readonly required: boolean;\n    readonly result: AssertionResult;\n}\nexport interface SealedAssertionEvaluation {\n    readonly execution: \"completed\" | \"errored\";\n    readonly explicitlySkipped: boolean;\n    readonly assertions: readonly SealedAssertionEvaluationEntry[];\n}\n/**\n * One immutable result feeds the Verdict/Score fold and the private durable\n * producer adapter. No RecordAttachment writer type crosses this boundary.\n */\nexport interface SealedAssertionsRuntime {\n    readonly entries: readonly SealedAssertionEntry[];\n    readonly evaluation: SealedAssertionEvaluation;\n}\n/** The runtime Verdict is independent of the durable Verdict attachment codec. */\nexport interface AssertionVerdict {\n    readonly state: \"passed\" | \"failed\" | \"errored\" | \"skipped\";\n}\nexport type AssertionScoreIncompleteReason = \"execution-errored\" | \"source-unavailable\" | \"evaluation-errored\" | \"not-applicable\";\n/** The runtime Score is independent of the durable Score attachment codec. */\nexport type AssertionScore = {\n    readonly state: \"complete\";\n    readonly earned: number;\n} | {\n    readonly state: \"partial\";\n    readonly earned: number;\n    readonly reasons: readonly AssertionScoreIncompleteReason[];\n} | {\n    readonly state: \"unavailable\";\n    readonly reasons: readonly AssertionScoreIncompleteReason[];\n};\n/**\n * The attempt-owned frozen result is handed from Runner to the Evaluation\n * Record adapter. The adapter alone adds attachment schemas and writes.\n */\nexport interface SealedAttemptAssertions {\n    readonly entries: readonly SealedAssertionEntry[];\n    readonly evaluation: SealedAssertionEvaluation;\n    readonly workspaceDiff?: AgentWorkspaceDiff;\n    readonly verdict: AssertionVerdict;\n    readonly score?: AssertionScore;\n}\nexport interface AssertionsRuntime<Kind extends AssertionEvaluationKind> {\n    readonly evaluationKind: Kind;\n    readonly t: AssertionsContext<Kind>;\n    registerBoolean<Refined>(definition: BooleanAssertionRegistration<Refined>): BooleanAssertionHandle<Kind, Refined>;\n    registerMeasurement(definition: MeasurementAssertionRegistration): MeasurementAssertionHandle<Kind>;\n    seal(options?: AssertionSealOptions): Effect.Effect<SealedAssertionsRuntime, AssertionSealError, never>;\n}\n"]}

package/dist/assertions/api.d.cts

@@ -56,6 +56,12 @@ export type AssertionMaterial = {
 export type AssertionCriterion = {
     readonly kind: "value-match";
     readonly subject: "explicit-value";
+    readonly matcher: {
+        readonly state: "declared";
+        readonly name: string;
+    } | {
+        readonly state: "unavailable";
+    };
 } | {
     readonly kind: "scope-status";
     readonly scope: "turn" | "session" | "attempt";
@@ -120,6 +126,48 @@ export type AssertionScoreContribution = {
     readonly points: number;
     readonly reason: "source-unavailable" | "evaluation-errored" | "not-applicable";
 };
+/** Constant-size semantic receipt for one collection evaluation. */
+export interface AssertionCollectionReceipt {
+    readonly examined: number;
+    readonly matched: number;
+    readonly mismatched: number;
+    readonly unavailable: number;
+    readonly knownTotal: number | null;
+    readonly complete: boolean;
+    readonly exhaustive: boolean;
+    readonly decisive: boolean;
+}
+export type AssertionConditionPolicy = {
+    readonly kind: "boolean";
+    readonly expected: true;
+} | {
+    readonly kind: "at-least";
+    readonly threshold: number;
+} | {
+    readonly kind: "record-only";
+};
+export interface AssertionPolicy {
+    readonly requirement: "required" | "optional";
+    readonly condition: AssertionConditionPolicy;
+}
+export type AssertionObserved = {
+    readonly kind: "boolean";
+    readonly outcome: "matched" | "mismatched" | "unavailable" | "errored" | "not-applicable";
+} | {
+    readonly kind: "measurement";
+    readonly state: "available";
+    readonly value: number;
+} | {
+    readonly kind: "measurement";
+    readonly state: "unavailable";
+} | {
+    readonly kind: "direct-score";
+    readonly state: "available";
+    readonly value: number;
+} | {
+    readonly kind: "direct-score";
+    readonly state: "unavailable";
+};
 export type AssertionResult = {
     readonly state: "matched";
     readonly gate: "not-gate" | "satisfied";
@@ -127,6 +175,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "earned";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "mismatched";
     readonly reason: "condition-not-met";
@@ -135,6 +184,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "earned";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
@@ -143,6 +193,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "errored";
     readonly reason: "evaluator-failed" | "producer-interrupted" | "invalid-subject";
@@ -151,6 +202,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "not-applicable";
     readonly reason: "coverage-not-applicable";
@@ -159,6 +211,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 };
 /** One fully formed author/runtime result, before durable attachment encoding. */
 export interface SealedAssertionEntry {
@@ -169,6 +222,8 @@ export interface SealedAssertionEntry {
     readonly coverage: AssertionCoverage;
     readonly limitations: readonly AssertionLimitation[];
     readonly result: AssertionResult;
+    readonly policy: AssertionPolicy;
+    readonly observed: AssertionObserved;
 }
 /**
  * Assertion handles are runtime-owned capabilities, not subjects for another
@@ -211,13 +266,16 @@ export type BooleanAssertionEvaluation<Refined> = {
     readonly state: "matched";
     readonly value: Refined;
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "mismatched";
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "not-applicable";
     readonly diagnostic?: MatchDiagnostic;
@@ -226,13 +284,17 @@ export type BooleanAssertionEvaluation<Refined> = {
 export type MeasurementAssertionEvaluation = {
     readonly state: "measured";
     readonly value: number;
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "not-applicable";
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "errored";
+    readonly detail?: AssertionSnapshotObject;
 };
 export interface CapturedAssertionSnapshot {
     readonly material: Extract<AssertionMaterial, {

package/dist/assertions/api.d.mts

@@ -56,6 +56,12 @@ export type AssertionMaterial = {
 export type AssertionCriterion = {
     readonly kind: "value-match";
     readonly subject: "explicit-value";
+    readonly matcher: {
+        readonly state: "declared";
+        readonly name: string;
+    } | {
+        readonly state: "unavailable";
+    };
 } | {
     readonly kind: "scope-status";
     readonly scope: "turn" | "session" | "attempt";
@@ -120,6 +126,48 @@ export type AssertionScoreContribution = {
     readonly points: number;
     readonly reason: "source-unavailable" | "evaluation-errored" | "not-applicable";
 };
+/** Constant-size semantic receipt for one collection evaluation. */
+export interface AssertionCollectionReceipt {
+    readonly examined: number;
+    readonly matched: number;
+    readonly mismatched: number;
+    readonly unavailable: number;
+    readonly knownTotal: number | null;
+    readonly complete: boolean;
+    readonly exhaustive: boolean;
+    readonly decisive: boolean;
+}
+export type AssertionConditionPolicy = {
+    readonly kind: "boolean";
+    readonly expected: true;
+} | {
+    readonly kind: "at-least";
+    readonly threshold: number;
+} | {
+    readonly kind: "record-only";
+};
+export interface AssertionPolicy {
+    readonly requirement: "required" | "optional";
+    readonly condition: AssertionConditionPolicy;
+}
+export type AssertionObserved = {
+    readonly kind: "boolean";
+    readonly outcome: "matched" | "mismatched" | "unavailable" | "errored" | "not-applicable";
+} | {
+    readonly kind: "measurement";
+    readonly state: "available";
+    readonly value: number;
+} | {
+    readonly kind: "measurement";
+    readonly state: "unavailable";
+} | {
+    readonly kind: "direct-score";
+    readonly state: "available";
+    readonly value: number;
+} | {
+    readonly kind: "direct-score";
+    readonly state: "unavailable";
+};
 export type AssertionResult = {
     readonly state: "matched";
     readonly gate: "not-gate" | "satisfied";
@@ -127,6 +175,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "earned";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "mismatched";
     readonly reason: "condition-not-met";
@@ -135,6 +184,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "earned";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
@@ -143,6 +193,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "errored";
     readonly reason: "evaluator-failed" | "producer-interrupted" | "invalid-subject";
@@ -151,6 +202,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "not-applicable";
     readonly reason: "coverage-not-applicable";
@@ -159,6 +211,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 };
 /** One fully formed author/runtime result, before durable attachment encoding. */
 export interface SealedAssertionEntry {
@@ -169,6 +222,8 @@ export interface SealedAssertionEntry {
     readonly coverage: AssertionCoverage;
     readonly limitations: readonly AssertionLimitation[];
     readonly result: AssertionResult;
+    readonly policy: AssertionPolicy;
+    readonly observed: AssertionObserved;
 }
 /**
  * Assertion handles are runtime-owned capabilities, not subjects for another
@@ -211,13 +266,16 @@ export type BooleanAssertionEvaluation<Refined> = {
     readonly state: "matched";
     readonly value: Refined;
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "mismatched";
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "not-applicable";
     readonly diagnostic?: MatchDiagnostic;
@@ -226,13 +284,17 @@ export type BooleanAssertionEvaluation<Refined> = {
 export type MeasurementAssertionEvaluation = {
     readonly state: "measured";
     readonly value: number;
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "not-applicable";
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "errored";
+    readonly detail?: AssertionSnapshotObject;
 };
 export interface CapturedAssertionSnapshot {
     readonly material: Extract<AssertionMaterial, {

package/dist/assertions/api.d.ts

@@ -56,6 +56,12 @@ export type AssertionMaterial = {
 export type AssertionCriterion = {
     readonly kind: "value-match";
     readonly subject: "explicit-value";
+    readonly matcher: {
+        readonly state: "declared";
+        readonly name: string;
+    } | {
+        readonly state: "unavailable";
+    };
 } | {
     readonly kind: "scope-status";
     readonly scope: "turn" | "session" | "attempt";
@@ -120,6 +126,48 @@ export type AssertionScoreContribution = {
     readonly points: number;
     readonly reason: "source-unavailable" | "evaluation-errored" | "not-applicable";
 };
+/** Constant-size semantic receipt for one collection evaluation. */
+export interface AssertionCollectionReceipt {
+    readonly examined: number;
+    readonly matched: number;
+    readonly mismatched: number;
+    readonly unavailable: number;
+    readonly knownTotal: number | null;
+    readonly complete: boolean;
+    readonly exhaustive: boolean;
+    readonly decisive: boolean;
+}
+export type AssertionConditionPolicy = {
+    readonly kind: "boolean";
+    readonly expected: true;
+} | {
+    readonly kind: "at-least";
+    readonly threshold: number;
+} | {
+    readonly kind: "record-only";
+};
+export interface AssertionPolicy {
+    readonly requirement: "required" | "optional";
+    readonly condition: AssertionConditionPolicy;
+}
+export type AssertionObserved = {
+    readonly kind: "boolean";
+    readonly outcome: "matched" | "mismatched" | "unavailable" | "errored" | "not-applicable";
+} | {
+    readonly kind: "measurement";
+    readonly state: "available";
+    readonly value: number;
+} | {
+    readonly kind: "measurement";
+    readonly state: "unavailable";
+} | {
+    readonly kind: "direct-score";
+    readonly state: "available";
+    readonly value: number;
+} | {
+    readonly kind: "direct-score";
+    readonly state: "unavailable";
+};
 export type AssertionResult = {
     readonly state: "matched";
     readonly gate: "not-gate" | "satisfied";
@@ -127,6 +175,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "earned";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "mismatched";
     readonly reason: "condition-not-met";
@@ -135,6 +184,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "earned";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
@@ -143,6 +193,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "errored";
     readonly reason: "evaluator-failed" | "producer-interrupted" | "invalid-subject";
@@ -151,6 +202,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "not-applicable";
     readonly reason: "coverage-not-applicable";
@@ -159,6 +211,7 @@ export type AssertionResult = {
         readonly state: "not-scored" | "unavailable";
     }>;
     readonly diagnostic?: AssertionSnapshotObject;
+    readonly receipt?: AssertionCollectionReceipt;
 };
 /** One fully formed author/runtime result, before durable attachment encoding. */
 export interface SealedAssertionEntry {
@@ -169,6 +222,8 @@ export interface SealedAssertionEntry {
     readonly coverage: AssertionCoverage;
     readonly limitations: readonly AssertionLimitation[];
     readonly result: AssertionResult;
+    readonly policy: AssertionPolicy;
+    readonly observed: AssertionObserved;
 }
 /**
  * Assertion handles are runtime-owned capabilities, not subjects for another
@@ -211,13 +266,16 @@ export type BooleanAssertionEvaluation<Refined> = {
     readonly state: "matched";
     readonly value: Refined;
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "mismatched";
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
     readonly diagnostic?: MatchDiagnostic;
+    readonly receipt?: AssertionCollectionReceipt;
 } | {
     readonly state: "not-applicable";
     readonly diagnostic?: MatchDiagnostic;
@@ -226,13 +284,17 @@ export type BooleanAssertionEvaluation<Refined> = {
 export type MeasurementAssertionEvaluation = {
     readonly state: "measured";
     readonly value: number;
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "unavailable";
     readonly reason: "evidence-unavailable" | "source-unavailable" | "redacted";
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "not-applicable";
+    readonly detail?: AssertionSnapshotObject;
 } | {
     readonly state: "errored";
+    readonly detail?: AssertionSnapshotObject;
 };
 export interface CapturedAssertionSnapshot {
     readonly material: Extract<AssertionMaterial, {

package/dist/assertions/judge.cjs

@@ -181,9 +181,6 @@ function freezeJudgeMaterial(material) {
     }
     return Object.freeze({ input: material.input, output: material.output });
 }
-function evidenceFor(material) {
-    return JSON.stringify({ input: (0, display_ts_1.summaryText)(material.input), output: (0, display_ts_1.summaryText)(material.output) });
-}
 function missingConfiguration(resolved) {
     if (!resolved.model)
         return unavailable("judge-model-unresolved");
@@ -309,11 +306,25 @@ function evaluateJudgeRecipe(input) {
                 return effect_1.Effect.succeed(evaluatorError("judge-invalid-response", "Judge returned no finite score in [0, 1]"));
             }
             const rationale = result.metadata?.rationale;
+            const returnedEvidence = result.metadata?.evidence;
+            const returnedDetail = result.metadata?.detail;
+            const returnedCitations = result.metadata?.citations;
             return effect_1.Effect.succeed({
                 state: "measured",
                 value: result.score,
-                evidence: evidenceFor(frozenMaterial),
+                ...(typeof returnedEvidence === "string" && returnedEvidence.trim() !== ""
+                    ? { evidence: (0, display_ts_1.summaryText)(returnedEvidence) }
+                    : {}),
                 ...(typeof rationale === "string" && rationale.trim() !== "" ? { explanation: (0, display_ts_1.summaryText)(rationale) } : {}),
+                ...(typeof returnedDetail === "string" && returnedDetail.trim() !== "" ? { detail: (0, display_ts_1.summaryText)(returnedDetail) } : {}),
+                ...(Array.isArray(returnedCitations)
+                    ? {
+                        citations: Object.freeze(returnedCitations
+                            .slice(0, 16)
+                            .filter((citation) => typeof citation === "string" && citation.trim() !== "")
+                            .map(display_ts_1.summaryText)),
+                    }
+                    : {}),
             });
         }), effect_1.Effect.catchAll((failure) => effect_1.Effect.gen(function* () {
             const error = failure.error;
@@ -338,6 +349,46 @@ function evaluateJudgeRecipe(input) {
 }
 /** Assert-first bridge: one provider Promise adaptation in the Attempt Effect. */
 function evaluateJudgeMeasurement(input) {
-    return evaluateJudgeRecipe(input);
+    return evaluateJudgeRecipe(input).pipe(effect_1.Effect.map((result) => {
+        switch (result.state) {
+            case "measured":
+                return Object.freeze({
+                    state: "measured",
+                    value: result.value,
+                    detail: Object.freeze({
+                        evidence: result.evidence === undefined
+                            ? Object.freeze({ state: "unavailable", reason: "not-recorded" })
+                            : Object.freeze({ state: "available", value: result.evidence }),
+                        rationale: result.explanation === undefined
+                            ? Object.freeze({ state: "unavailable", reason: "not-recorded" })
+                            : Object.freeze({ state: "available", value: result.explanation }),
+                        detail: result.detail === undefined
+                            ? Object.freeze({ state: "unavailable", reason: "not-recorded" })
+                            : Object.freeze({ state: "available", value: result.detail }),
+                        citations: result.citations === undefined
+                            ? Object.freeze({ state: "unavailable", reason: "not-recorded" })
+                            : Object.freeze({ state: "available", value: result.citations }),
+                    }),
+                });
+            case "unavailable":
+                return Object.freeze({
+                    state: "unavailable",
+                    reason: result.reason,
+                    detail: Object.freeze({
+                        failureDetail: result.detail,
+                        failureEvidence: result.evidence ?? Object.freeze({ state: "unavailable", reason: "not-recorded" }),
+                        rationale: Object.freeze({ state: "unavailable", reason: "not-recorded" }),
+                        evidence: Object.freeze({ state: "unavailable", reason: "not-recorded" }),
+                        detail: Object.freeze({ state: "unavailable", reason: "not-recorded" }),
+                        citations: Object.freeze({ state: "unavailable", reason: "not-recorded" }),
+                    }),
+                });
+            case "errored":
+                return Object.freeze({
+                    state: "errored",
+                    detail: Object.freeze({ code: result.code, message: result.message }),
+                });
+        }
+    }));
 }
 //# sourceMappingURL=judge.cjs.map