niceeval 0.15.1-canary.76 → 0.16.1

package/dist/assertions/api.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["api.ts"],"names":[],"mappings":";;;AAyXA;;;;GAIG;AACU,QAAA,oBAAoB,GAAkB,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAsBvF;;;;;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, CollectionMatch, ManagedToolCalls, MatchDiagnostic, NumericComparator, NumericComparisonMatch, ScoreMatch, EventMatch, ManagedEventOccurrences, ToolMatch, } from \"./match.ts\";\nimport type { AgentWorkspaceDiff } from \"./workspace-diff.ts\";\nimport type { EvaluationKind } from \"../shared/evaluation.ts\";\nimport type { JudgeImage } from \"../judge/image.ts\";\n/** The two Evaluation kinds deliberately share one Assertion entry model. */\nexport type AssertionEvaluationKind = EvaluationKind;\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: \"judge-image\";\n    readonly image: JudgeImage;\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    /** Package-private runtime variant encoded as numeric-comparison/v1. */\n    readonly kind: \"value-match\";\n    readonly numeric: {\n        readonly comparator: NumericComparator;\n        readonly threshold: number;\n        readonly subject: {\n            readonly kind: \"explicit-value\";\n        } | {\n            readonly kind: \"scope-metric\";\n            readonly metric: \"tokens\";\n            readonly scope: \"turn\" | \"session\" | \"attempt\";\n            readonly unit: \"tokens\";\n        } | {\n            readonly kind: \"scope-metric\";\n            readonly metric: \"cost\";\n            readonly scope: \"turn\" | \"session\" | \"attempt\";\n            readonly unit: \"usd\";\n        } | {\n            readonly kind: \"collection-cardinality\";\n            readonly collection: \"tool-calls\";\n            readonly scope: \"turn\" | \"session\" | \"attempt\";\n        };\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\" | \"order\";\n    readonly matcher?: string;\n    readonly quantifier?: {\n        readonly kind: \"absent\";\n    } | {\n        readonly kind: \"at-least\" | \"less-than\" | \"at-most\" | \"greater-than\" | \"exact\";\n        readonly count: number;\n    };\n} | {\n    readonly kind: \"judge-measurement\";\n    readonly name: string;\n    readonly scale: \"unit-interval\";\n} | {\n    readonly kind: \"managed-score-measurement\";\n    readonly name: string;\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 MatcherRelationStatus = {\n    readonly state: \"exact\";\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"historical-not-recorded\" | \"source-unavailable\" | \"ambiguous\";\n};\nexport type MatcherSourceLocator = {\n    readonly kind: \"tool-occurrence\";\n    readonly toolOccurrenceId: string;\n    readonly relation: MatcherRelationStatus;\n} | {\n    readonly kind: \"event\";\n    readonly eventId: string;\n    readonly toolOccurrenceId?: string;\n    readonly relation: MatcherRelationStatus;\n};\nexport interface MatcherRetainedRow {\n    readonly locator: MatcherSourceLocator;\n    readonly result: \"matched\" | \"mismatched\" | \"unavailable\" | \"not-evaluated\";\n    readonly difference?: AssertionSnapshotValue;\n}\nexport interface MatcherQueryStep {\n    readonly step: number;\n    readonly summary: AssertionSnapshotValue;\n}\nexport type MatcherSourceSnapshot = {\n    readonly scope: \"turn\";\n    readonly sessionId: string;\n    readonly turnId: string;\n    readonly scopeId: string;\n    readonly throughSessionSequence: number;\n    readonly source: {\n        readonly family: \"niceeval.agent-turns\";\n        readonly schemaVersion: number;\n    };\n    readonly collectionAtCut: \"complete\" | \"partial\" | \"unavailable\";\n} | {\n    readonly scope: \"session\";\n    readonly sessionId: string;\n    readonly scopeId: string;\n    readonly throughSessionSequence: number;\n    readonly source: {\n        readonly family: \"niceeval.agent-turns\";\n        readonly schemaVersion: number;\n    };\n    readonly collectionAtCut: \"complete\" | \"partial\" | \"unavailable\";\n} | {\n    readonly scope: \"attempt\";\n    readonly scopeId: string;\n    readonly sessions: readonly {\n        readonly sessionId: string;\n        readonly throughSessionSequence: number;\n    }[];\n    readonly source: {\n        readonly family: \"niceeval.agent-turns\";\n        readonly schemaVersion: number;\n    };\n    readonly collectionAtCut: \"complete\" | \"partial\" | \"unavailable\";\n};\nexport interface OrderStepReceipt {\n    readonly step: number;\n    readonly comparisons: number;\n    readonly matched: number;\n    readonly mismatched: number;\n    readonly unavailable: number;\n}\nexport interface OrderEvaluationReceipt {\n    readonly sourceRows: number;\n    readonly comparisons: number;\n    readonly unavailableComparisons: number;\n    readonly definitePrefixLength: number;\n    readonly possiblePrefixLength: number;\n    readonly stepReceipts: readonly OrderStepReceipt[];\n    readonly complete: boolean;\n    readonly exhaustive: boolean;\n    readonly decisive: boolean;\n}\nexport interface MatcherOrderPathNode {\n    readonly step: number;\n    readonly locator: MatcherSourceLocator;\n    readonly sessionId: string;\n    readonly sessionSequence: number;\n    readonly result: \"matched\" | \"unavailable\";\n}\nexport interface MatcherFailureFrontier {\n    readonly longestDefinitePrefix: readonly MatcherOrderPathNode[];\n    readonly longestPossiblePrefix: readonly MatcherOrderPathNode[];\n    readonly firstBlockingStep: number;\n    readonly suffixChecked: AssertionCollectionReceipt;\n    readonly representatives: readonly MatcherRetainedRow[];\n}\nexport type MatcherQueryArtifact = {\n    readonly kind: \"collection-filter\";\n    readonly sourceSnapshot: MatcherSourceSnapshot;\n    readonly query: MatcherQueryStep;\n    readonly receipt: AssertionCollectionReceipt;\n    readonly retainedRows: readonly MatcherRetainedRow[];\n} | {\n    readonly kind: \"ordered-sequence\";\n    readonly sourceSnapshot: Extract<MatcherSourceSnapshot, {\n        readonly scope: \"turn\" | \"session\";\n    }>;\n    readonly querySteps: readonly MatcherQueryStep[];\n    readonly receipt: OrderEvaluationReceipt;\n    readonly result: {\n        readonly state: \"matched\";\n        readonly witnessPath: readonly MatcherOrderPathNode[];\n    } | {\n        readonly state: \"mismatched\";\n        readonly failureFrontier: MatcherFailureFrontier;\n    } | {\n        readonly state: \"unavailable\";\n        readonly reason: string;\n    };\n    readonly retainedRows: readonly MatcherRetainedRow[];\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    readonly matcherArtifact?: MatcherQueryArtifact;\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\");\ndeclare const assertionConditionStateBrand: unique symbol;\ndeclare const assertionGateStateBrand: unique symbol;\ndeclare const assertionScoreStateBrand: unique symbol;\nexport interface AssertionHandleBase<HasCondition extends boolean = boolean, HasScore extends boolean = boolean> {\n    readonly [assertionHandleBrand]: true;\n    readonly [assertionConditionStateBrand]: HasCondition;\n    readonly [assertionScoreStateBrand]: HasScore;\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;\n/** Numeric cardinality deliberately excludes the managed event occurrence subject. */\nexport type NumericAssertionSubject<Value> = Value extends ManagedEventOccurrences ? never : AssertionSubject<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    readonly matcherArtifact?: MatcherQueryArtifact;\n} | {\n    readonly state: \"mismatched\";\n    readonly diagnostic?: MatchDiagnostic;\n    readonly receipt?: AssertionCollectionReceipt;\n    readonly matcherArtifact?: MatcherQueryArtifact;\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"evidence-unavailable\" | \"source-unavailable\" | \"redacted\";\n    readonly diagnostic?: MatchDiagnostic;\n    readonly receipt?: AssertionCollectionReceipt;\n    readonly matcherArtifact?: MatcherQueryArtifact;\n} | {\n    readonly state: \"not-applicable\";\n    readonly diagnostic?: MatchDiagnostic;\n    readonly matcherArtifact?: MatcherQueryArtifact;\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    /** Sealed when Attempt interruption prevents the ordinary evaluator from running. */\n    readonly interruptedMatcherArtifact?: MatcherQueryArtifact;\n    readonly evaluate: () => Effect.Effect<BooleanAssertionEvaluation<Refined>, unknown, never>;\n}\nexport interface MeasurementAssertionRegistration extends AssertionRegistrationBase {\n    /** Bytes synchronously reserved from an Attempt-local producer budget. */\n    readonly retainedBytes?: number;\n    readonly retainedImageBytes?: number;\n    /** Complete terminal Content appended exactly once by the shared sealing path. */\n    readonly terminalEvidence?: () => readonly AssertionMaterial[];\n    /** Terminal producer facts frozen by the shared Assertion sealing path. */\n    readonly terminalDetail?: () => AssertionSnapshotObject;\n    readonly evaluate: () => Effect.Effect<MeasurementAssertionEvaluation, unknown, never>;\n}\nexport interface PassBooleanAssertionHandle<out Refined, HasGate extends boolean = false> extends AssertionHandleBase<true, false> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    /** An unavailable/errored optional entry does not independently error Verdict. */\n    optional(): this;\n    gate(this: PassBooleanAssertionHandle<Refined, false>): PassBooleanAssertionHandle<Refined, true>;\n    orStop(): Promise<Refined>;\n}\nexport interface ScoreBooleanAssertionHandle<out Refined, HasGate extends boolean = false, HasScore extends boolean = false> extends AssertionHandleBase<true, HasScore> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    gate(this: ScoreBooleanAssertionHandle<Refined, false, HasScore>): ScoreBooleanAssertionHandle<Refined, true, HasScore>;\n    score(this: ScoreBooleanAssertionHandle<Refined, HasGate, false>, points: number): ScoreBooleanAssertionHandle<Refined, HasGate, true>;\n    orStop(): Promise<Refined>;\n}\nexport interface PassMeasurementAssertionHandle<HasCondition extends boolean = false> extends AssertionHandleBase<HasCondition, false> {\n    readonly kind: \"measurement\";\n    gate(this: PassMeasurementAssertionHandle<false>, minimum: number): PassMeasurementAssertionHandle<true>;\n    orStop(this: PassMeasurementAssertionHandle<false>, minimum: number): Promise<number>;\n    orStop(this: PassMeasurementAssertionHandle<true>): Promise<number>;\n}\nexport interface ScoreMeasurementAssertionHandle<HasCondition extends boolean = false, HasScore extends boolean = false> extends AssertionHandleBase<HasCondition, HasScore> {\n    readonly kind: \"measurement\";\n    gate(this: ScoreMeasurementAssertionHandle<false, HasScore>, minimum: number): ScoreMeasurementAssertionHandle<true, HasScore>;\n    score(this: ScoreMeasurementAssertionHandle<HasCondition, false>, points: number): ScoreMeasurementAssertionHandle<HasCondition, true>;\n    orStop(this: ScoreMeasurementAssertionHandle<false, HasScore>, minimum: number): Promise<number>;\n    orStop(this: ScoreMeasurementAssertionHandle<true, HasScore>): Promise<number>;\n}\n/** A Boolean Assertion that intentionally has no author control-flow operation. */\ninterface PostRunPassBooleanAssertionHandle<Refined, HasGate extends boolean = false> extends AssertionHandleBase<true, false> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    optional(): this;\n    gate(this: PostRunPassBooleanAssertionHandle<Refined, false>): PostRunPassBooleanAssertionHandle<Refined, true>;\n}\ninterface PostRunScoreBooleanAssertionHandle<Refined, HasGate extends boolean = false, HasScore extends boolean = false> extends AssertionHandleBase<true, HasScore> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    gate(this: PostRunScoreBooleanAssertionHandle<Refined, false, HasScore>): PostRunScoreBooleanAssertionHandle<Refined, true, HasScore>;\n    score(this: PostRunScoreBooleanAssertionHandle<Refined, HasGate, false>, points: number): PostRunScoreBooleanAssertionHandle<Refined, HasGate, true>;\n}\nexport type PostRunBooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined, HasGate extends boolean = false, HasScore extends boolean = false> = Kind extends \"pass\" ? PostRunPassBooleanAssertionHandle<Refined, HasGate> : PostRunScoreBooleanAssertionHandle<Refined, HasGate, HasScore>;\n/** Direct score is an Assertion entry, but has no condition or stop barrier. */\nexport interface DirectScoreAssertionHandle extends AssertionHandleBase<false, true> {\n    readonly kind: \"direct-score\";\n}\n/**\n * Definition-time handle shared by Adapter Assertion factories. It exposes\n * only operations whose meaning is identical in Pass and Score Evals; the\n * bound Eval factory replaces it with the native handle for its Kind.\n */\nexport interface PolymorphicBooleanAssertionHandle<out Refined, HasGate extends boolean = false> extends AssertionHandleBase<true, false> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    gate(this: PolymorphicBooleanAssertionHandle<Refined, false>): PolymorphicBooleanAssertionHandle<Refined, true>;\n    orStop(): Promise<Refined>;\n}\n/** Definition-time measurement counterpart to PolymorphicBooleanAssertionHandle. */\nexport interface PolymorphicMeasurementAssertionHandle<HasCondition extends boolean = false> extends AssertionHandleBase<HasCondition, false> {\n    readonly kind: \"measurement\";\n    gate(this: PolymorphicMeasurementAssertionHandle<false>, minimum: number): PolymorphicMeasurementAssertionHandle<true>;\n    orStop(this: PolymorphicMeasurementAssertionHandle<false>, minimum: number): Promise<number>;\n    orStop(this: PolymorphicMeasurementAssertionHandle<true>): Promise<number>;\n}\nexport type AssertionCheckKind = AssertionEvaluationKind | \"polymorphic\";\ntype CheckedBooleanHandle<Kind extends AssertionCheckKind, Refined> = Kind extends AssertionEvaluationKind ? BooleanAssertionHandle<Kind, Refined> : PolymorphicBooleanAssertionHandle<Refined>;\ntype CheckedMeasurementHandle<Kind extends AssertionCheckKind> = Kind extends AssertionEvaluationKind ? MeasurementAssertionHandle<Kind> : PolymorphicMeasurementAssertionHandle;\n/** Single owner for the public check overload set, including Adapter-polymorphic factories. */\nexport interface AssertionCheck<Kind extends AssertionCheckKind> {\n    <Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, \"value\">): CheckedBooleanHandle<Kind, Refined>;\n    <Value extends readonly unknown[]>(value: NumericAssertionSubject<Value>, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, Value>;\n    <S extends \"turn\" | \"session\" | \"attempt\">(value: AssertionSubject<ManagedToolCalls<S>>, match: ToolMatch): CheckedBooleanHandle<Kind, ManagedToolCalls<S>>;\n    <S extends \"turn\" | \"session\" | \"attempt\">(value: AssertionSubject<ManagedEventOccurrences<S>>, match: EventMatch): CheckedBooleanHandle<Kind, ManagedEventOccurrences<S>>;\n    <Value>(value: AssertionSubject<Value>, match: CollectionMatch<NoInfer<Value>>): CheckedBooleanHandle<Kind, Value>;\n    <Value>(value: AssertionSubject<Value>, match: ScoreMatch<NoInfer<Value>>): CheckedMeasurementHandle<Kind>;\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    readonly check: AssertionCheck<\"pass\">;\n}\nexport interface ScoreAssertionsContext extends AssertionGroupContext {\n    readonly evaluationKind: \"score\";\n    readonly check: AssertionCheck<\"score\">;\n    score(points: number): DirectScoreAssertionHandle;\n}\nexport type AssertionsContext<Kind extends AssertionEvaluationKind> = Kind extends \"pass\" ? PassAssertionsContext : ScoreAssertionsContext;\nexport type BooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined, HasGate extends boolean = false, HasScore extends boolean = false> = Kind extends \"pass\" ? PassBooleanAssertionHandle<Refined, HasGate> : ScoreBooleanAssertionHandle<Refined, HasGate, HasScore>;\nexport type MeasurementAssertionHandle<Kind extends AssertionEvaluationKind, HasCondition extends boolean = false, HasScore extends boolean = false> = Kind extends \"pass\" ? PassMeasurementAssertionHandle<HasCondition> : ScoreMeasurementAssertionHandle<HasCondition, HasScore>;\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}\n/** Sealing has no expected authoring failure after registration-time validation. */\nexport type AssertionSealError = never;\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: import(\"../shared/types.ts\").Verdict;\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    /** @internal Reject before an adapter reads or snapshots author material. */\n    assertAuthoringOpen(): void;\n    /** Attempt-owned synchronous admission close; sealing still happens once through `seal`. */\n    closeAuthoring(reason: \"attempt-sealing\" | \"attempt-interrupted\"): void;\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":";;;AAmYA;;;;GAIG;AACU,QAAA,oBAAoB,GAAkB,MAAM,CAAC,2BAA2B,CAAC,CAAC;AAsBvF;;;;;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":["// @concord-file ne-eval-assertions-api\n// @concord-implements docs/feature/assertions/README.md\n// @concord-implements docs/feature/assertions/library.md\n// @concord-implements docs/feature/assertions/library/value-assertions.md\n// @concord-implements docs/feature/assertions/library/scoped-assertions.md\nimport type { Effect } from \"effect\";\nimport type { BooleanMatch, CollectionMatch, ManagedToolCalls, MatchDiagnostic, NumericComparator, NumericMaterial, NumericComparisonMatch, ScoreMatch, EventMatch, ManagedEventOccurrences, ToolMatch, } from \"./match.ts\";\nimport type { AgentWorkspaceDiff } from \"./workspace-diff.ts\";\nimport type { EvaluationKind } from \"../shared/evaluation.ts\";\nimport type { JudgeImage } from \"../judge/image.ts\";\n/** The two Evaluation kinds deliberately share one Assertion entry model. */\nexport type AssertionEvaluationKind = EvaluationKind;\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\" | \"capacity-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    readonly kind: \"capacity-limited\";\n    readonly capturedItems: number;\n    readonly knownTotalItems: number;\n    readonly omittedBytes: number | null;\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: \"judge-image\";\n    readonly image: JudgeImage;\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    /** Package-private runtime variant encoded as numeric-comparison/v1. */\n    readonly kind: \"value-match\";\n    readonly numeric: {\n        readonly comparator: NumericComparator;\n        readonly threshold: number;\n        readonly subject: {\n            readonly kind: \"explicit-value\";\n        } | {\n            readonly kind: \"scope-metric\";\n            readonly metric: \"tokens\";\n            readonly scope: \"turn\" | \"session\" | \"attempt\";\n            readonly unit: \"tokens\";\n        } | {\n            readonly kind: \"scope-metric\";\n            readonly metric: \"cost\";\n            readonly scope: \"turn\" | \"session\" | \"attempt\";\n            readonly unit: \"usd\";\n        } | {\n            readonly kind: \"collection-cardinality\";\n            readonly collection: \"tool-calls\";\n            readonly scope: \"turn\" | \"session\" | \"attempt\";\n        };\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\" | \"order\";\n    readonly matcher?: string;\n    readonly quantifier?: {\n        readonly kind: \"absent\";\n    } | {\n        readonly kind: \"at-least\" | \"less-than\" | \"at-most\" | \"greater-than\" | \"exact\";\n        readonly count: number;\n    };\n} | {\n    readonly kind: \"judge-measurement\";\n    readonly name: string;\n    readonly scale: \"unit-interval\";\n} | {\n    readonly kind: \"managed-score-measurement\";\n    readonly name: string;\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 MatcherRelationStatus = {\n    readonly state: \"exact\";\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"historical-not-recorded\" | \"source-unavailable\" | \"ambiguous\";\n};\nexport type MatcherSourceLocator = {\n    readonly kind: \"tool-occurrence\";\n    readonly toolOccurrenceId: string;\n    readonly relation: MatcherRelationStatus;\n} | {\n    readonly kind: \"event\";\n    readonly eventId: string;\n    readonly toolOccurrenceId?: string;\n    readonly relation: MatcherRelationStatus;\n};\nexport interface MatcherRetainedRow {\n    readonly locator: MatcherSourceLocator;\n    readonly result: \"matched\" | \"mismatched\" | \"unavailable\" | \"not-evaluated\";\n    readonly difference?: AssertionSnapshotValue;\n}\nexport interface MatcherQueryStep {\n    readonly step: number;\n    readonly summary: AssertionSnapshotValue;\n}\nexport type MatcherSourceSnapshot = {\n    readonly scope: \"turn\";\n    readonly sessionId: string;\n    readonly turnId: string;\n    readonly scopeId: string;\n    readonly throughSessionSequence: number;\n    readonly source: {\n        readonly family: \"niceeval.agent-turns\";\n        readonly schemaVersion: number;\n    };\n    readonly collectionAtCut: \"complete\" | \"partial\" | \"unavailable\";\n} | {\n    readonly scope: \"session\";\n    readonly sessionId: string;\n    readonly scopeId: string;\n    readonly throughSessionSequence: number;\n    readonly source: {\n        readonly family: \"niceeval.agent-turns\";\n        readonly schemaVersion: number;\n    };\n    readonly collectionAtCut: \"complete\" | \"partial\" | \"unavailable\";\n} | {\n    readonly scope: \"attempt\";\n    readonly scopeId: string;\n    readonly sessions: readonly {\n        readonly sessionId: string;\n        readonly throughSessionSequence: number;\n    }[];\n    readonly source: {\n        readonly family: \"niceeval.agent-turns\";\n        readonly schemaVersion: number;\n    };\n    readonly collectionAtCut: \"complete\" | \"partial\" | \"unavailable\";\n};\nexport interface OrderStepReceipt {\n    readonly step: number;\n    readonly comparisons: number;\n    readonly matched: number;\n    readonly mismatched: number;\n    readonly unavailable: number;\n}\nexport interface OrderEvaluationReceipt {\n    readonly sourceRows: number;\n    readonly comparisons: number;\n    readonly unavailableComparisons: number;\n    readonly definitePrefixLength: number;\n    readonly possiblePrefixLength: number;\n    readonly stepReceipts: readonly OrderStepReceipt[];\n    readonly complete: boolean;\n    readonly exhaustive: boolean;\n    readonly decisive: boolean;\n}\nexport interface MatcherOrderPathNode {\n    readonly step: number;\n    readonly locator: MatcherSourceLocator;\n    readonly sessionId: string;\n    readonly sessionSequence: number;\n    readonly result: \"matched\" | \"unavailable\";\n}\nexport interface MatcherFailureFrontier {\n    readonly longestDefinitePrefix: readonly MatcherOrderPathNode[];\n    readonly longestPossiblePrefix: readonly MatcherOrderPathNode[];\n    readonly firstBlockingStep: number;\n    readonly suffixChecked: AssertionCollectionReceipt;\n    readonly representatives: readonly MatcherRetainedRow[];\n}\nexport type MatcherQueryArtifact = {\n    readonly kind: \"collection-filter\";\n    readonly sourceSnapshot: MatcherSourceSnapshot;\n    readonly query: MatcherQueryStep;\n    readonly receipt: AssertionCollectionReceipt;\n    readonly retainedRows: readonly MatcherRetainedRow[];\n} | {\n    readonly kind: \"ordered-sequence\";\n    readonly sourceSnapshot: Extract<MatcherSourceSnapshot, {\n        readonly scope: \"turn\" | \"session\";\n    }>;\n    readonly querySteps: readonly MatcherQueryStep[];\n    readonly receipt: OrderEvaluationReceipt;\n    readonly result: {\n        readonly state: \"matched\";\n        readonly witnessPath: readonly MatcherOrderPathNode[];\n    } | {\n        readonly state: \"mismatched\";\n        readonly failureFrontier: MatcherFailureFrontier;\n    } | {\n        readonly state: \"unavailable\";\n        readonly reason: string;\n    };\n    readonly retainedRows: readonly MatcherRetainedRow[];\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    readonly matcherArtifact?: MatcherQueryArtifact;\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\");\ndeclare const assertionConditionStateBrand: unique symbol;\ndeclare const assertionGateStateBrand: unique symbol;\ndeclare const assertionScoreStateBrand: unique symbol;\nexport interface AssertionHandleBase<HasCondition extends boolean = boolean, HasScore extends boolean = boolean> {\n    readonly [assertionHandleBrand]: true;\n    readonly [assertionConditionStateBrand]: HasCondition;\n    readonly [assertionScoreStateBrand]: HasScore;\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;\n/** Numeric cardinality deliberately excludes the managed event occurrence subject. */\nexport type NumericAssertionSubject<Value> = Value extends ManagedEventOccurrences ? never : AssertionSubject<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    readonly matcherArtifact?: MatcherQueryArtifact;\n} | {\n    readonly state: \"mismatched\";\n    readonly diagnostic?: MatchDiagnostic;\n    readonly receipt?: AssertionCollectionReceipt;\n    readonly matcherArtifact?: MatcherQueryArtifact;\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: \"evidence-unavailable\" | \"source-unavailable\" | \"redacted\";\n    readonly diagnostic?: MatchDiagnostic;\n    readonly receipt?: AssertionCollectionReceipt;\n    readonly matcherArtifact?: MatcherQueryArtifact;\n} | {\n    readonly state: \"not-applicable\";\n    readonly diagnostic?: MatchDiagnostic;\n    readonly matcherArtifact?: MatcherQueryArtifact;\n};\n/** A measurement is always a finite unit-interval value when it is available. */\nexport type MeasurementAssertionEvaluation = {\n    readonly receipt?: AssertionCollectionReceipt;\n} & ({\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    /** @internal Seal the criterion for the actual local or managed evaluation path. */\n    readonly terminalCriterion?: () => AssertionCriterion;\n    readonly retainedBytes?: number;\n    readonly terminalReceipt?: () => AssertionCollectionReceipt;\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    /** Sealed when Attempt interruption prevents the ordinary evaluator from running. */\n    readonly interruptedMatcherArtifact?: MatcherQueryArtifact;\n    readonly evaluate: () => Effect.Effect<BooleanAssertionEvaluation<Refined>, unknown, never>;\n}\nexport interface MeasurementAssertionRegistration extends AssertionRegistrationBase {\n    /** Bytes synchronously reserved from an Attempt-local producer budget. */\n    readonly retainedBytes?: number;\n    readonly retainedImageBytes?: number;\n    /** Complete terminal Content appended exactly once by the shared sealing path. */\n    readonly terminalEvidence?: () => readonly AssertionMaterial[];\n    /** Terminal producer facts frozen by the shared Assertion sealing path. */\n    readonly terminalDetail?: () => AssertionSnapshotObject;\n    readonly evaluate: () => Effect.Effect<MeasurementAssertionEvaluation, unknown, never>;\n}\nexport interface PassBooleanAssertionHandle<out Refined, HasGate extends boolean = false> extends AssertionHandleBase<true, false> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    /** An unavailable/errored optional entry does not independently error Verdict. */\n    optional(): this;\n    gate(this: PassBooleanAssertionHandle<Refined, false>): PassBooleanAssertionHandle<Refined, true>;\n    orStop(): Promise<Refined>;\n}\nexport interface ScoreBooleanAssertionHandle<out Refined, HasGate extends boolean = false, HasScore extends boolean = false> extends AssertionHandleBase<true, HasScore> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    gate(this: ScoreBooleanAssertionHandle<Refined, false, HasScore>): ScoreBooleanAssertionHandle<Refined, true, HasScore>;\n    score(this: ScoreBooleanAssertionHandle<Refined, HasGate, false>, points: number): ScoreBooleanAssertionHandle<Refined, HasGate, true>;\n    orStop(): Promise<Refined>;\n}\nexport interface PassMeasurementAssertionHandle<HasCondition extends boolean = false> extends AssertionHandleBase<HasCondition, false> {\n    readonly kind: \"measurement\";\n    gate(this: PassMeasurementAssertionHandle<false>, minimum: number): PassMeasurementAssertionHandle<true>;\n    orStop(this: PassMeasurementAssertionHandle<false>, minimum: number): Promise<number>;\n    orStop(this: PassMeasurementAssertionHandle<true>): Promise<number>;\n}\nexport interface ScoreMeasurementAssertionHandle<HasCondition extends boolean = false, HasScore extends boolean = false> extends AssertionHandleBase<HasCondition, HasScore> {\n    readonly kind: \"measurement\";\n    gate(this: ScoreMeasurementAssertionHandle<false, HasScore>, minimum: number): ScoreMeasurementAssertionHandle<true, HasScore>;\n    score(this: ScoreMeasurementAssertionHandle<HasCondition, false>, points: number): ScoreMeasurementAssertionHandle<HasCondition, true>;\n    orStop(this: ScoreMeasurementAssertionHandle<false, HasScore>, minimum: number): Promise<number>;\n    orStop(this: ScoreMeasurementAssertionHandle<true, HasScore>): Promise<number>;\n}\n/** A Boolean Assertion that intentionally has no author control-flow operation. */\ninterface PostRunPassBooleanAssertionHandle<Refined, HasGate extends boolean = false> extends AssertionHandleBase<true, false> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    optional(): this;\n    gate(this: PostRunPassBooleanAssertionHandle<Refined, false>): PostRunPassBooleanAssertionHandle<Refined, true>;\n}\ninterface PostRunScoreBooleanAssertionHandle<Refined, HasGate extends boolean = false, HasScore extends boolean = false> extends AssertionHandleBase<true, HasScore> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    gate(this: PostRunScoreBooleanAssertionHandle<Refined, false, HasScore>): PostRunScoreBooleanAssertionHandle<Refined, true, HasScore>;\n    score(this: PostRunScoreBooleanAssertionHandle<Refined, HasGate, false>, points: number): PostRunScoreBooleanAssertionHandle<Refined, HasGate, true>;\n}\nexport type PostRunBooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined, HasGate extends boolean = false, HasScore extends boolean = false> = Kind extends \"pass\" ? PostRunPassBooleanAssertionHandle<Refined, HasGate> : PostRunScoreBooleanAssertionHandle<Refined, HasGate, HasScore>;\n/** Direct score is an Assertion entry, but has no condition or stop barrier. */\nexport interface DirectScoreAssertionHandle extends AssertionHandleBase<false, true> {\n    readonly kind: \"direct-score\";\n}\n/**\n * Definition-time handle shared by Adapter Assertion factories. It exposes\n * only operations whose meaning is identical in Pass and Score Evals; the\n * bound Eval factory replaces it with the native handle for its Kind.\n */\nexport interface PolymorphicBooleanAssertionHandle<out Refined, HasGate extends boolean = false> extends AssertionHandleBase<true, false> {\n    readonly kind: \"boolean\";\n    readonly [assertionGateStateBrand]: HasGate;\n    gate(this: PolymorphicBooleanAssertionHandle<Refined, false>): PolymorphicBooleanAssertionHandle<Refined, true>;\n    orStop(): Promise<Refined>;\n}\n/** Definition-time measurement counterpart to PolymorphicBooleanAssertionHandle. */\nexport interface PolymorphicMeasurementAssertionHandle<HasCondition extends boolean = false> extends AssertionHandleBase<HasCondition, false> {\n    readonly kind: \"measurement\";\n    gate(this: PolymorphicMeasurementAssertionHandle<false>, minimum: number): PolymorphicMeasurementAssertionHandle<true>;\n    orStop(this: PolymorphicMeasurementAssertionHandle<false>, minimum: number): Promise<number>;\n    orStop(this: PolymorphicMeasurementAssertionHandle<true>): Promise<number>;\n}\nexport type AssertionCheckKind = AssertionEvaluationKind | \"polymorphic\";\ntype CheckedBooleanHandle<Kind extends AssertionCheckKind, Refined> = Kind extends AssertionEvaluationKind ? BooleanAssertionHandle<Kind, Refined> : PolymorphicBooleanAssertionHandle<Refined>;\ntype CheckedMeasurementHandle<Kind extends AssertionCheckKind> = Kind extends AssertionEvaluationKind ? MeasurementAssertionHandle<Kind> : PolymorphicMeasurementAssertionHandle;\n/** Single owner for the public check overload set, including Adapter-polymorphic factories. */\nexport interface AssertionCheck<Kind extends AssertionCheckKind, Context = unknown> {\n    <T>(match: import(\"./context-match.ts\").MaterialMatch<Context, T>): CheckedBooleanHandle<Kind, void>;\n    <T>(match: import(\"./context-match.ts\").ContextBooleanMatch<Context, T>): CheckedBooleanHandle<Kind, void>;\n    <T>(match: import(\"./context-match.ts\").ContextScoreMatch<Context, T>): CheckedMeasurementHandle<Kind>;\n    (value: import(\"./match.ts\").NumericMaterial, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, number>;\n    <Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, \"value\">): CheckedBooleanHandle<Kind, Refined>;\n    <Value extends readonly unknown[]>(value: NumericAssertionSubject<Value>, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, Value>;\n    <S extends \"turn\" | \"session\" | \"attempt\">(value: AssertionSubject<ManagedToolCalls<S>>, match: ToolMatch): CheckedBooleanHandle<Kind, ManagedToolCalls<S>>;\n    <S extends \"turn\" | \"session\" | \"attempt\">(value: AssertionSubject<ManagedEventOccurrences<S>>, match: EventMatch): CheckedBooleanHandle<Kind, ManagedEventOccurrences<S>>;\n    <Value>(value: AssertionSubject<Value>, match: CollectionMatch<NoInfer<Value>>): CheckedBooleanHandle<Kind, Value>;\n    <Value>(value: AssertionSubject<Value>, match: ScoreMatch<NoInfer<Value>>): CheckedMeasurementHandle<Kind>;\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    readonly check: AssertionCheck<\"pass\">;\n}\n/** Adds direct points, or a unit-interval measurement with an explicit fixed weight. */\nexport interface ScoreFunction {\n    (points: number): DirectScoreAssertionHandle;\n    (ratio: number | NumericMaterial, options: {\n        readonly weight: number;\n    }): ScoreMeasurementAssertionHandle<false, true>;\n}\nexport interface ScoreAssertionsContext extends AssertionGroupContext {\n    readonly evaluationKind: \"score\";\n    readonly check: AssertionCheck<\"score\">;\n    readonly score: ScoreFunction;\n}\nexport type AssertionsContext<Kind extends AssertionEvaluationKind> = Kind extends \"pass\" ? PassAssertionsContext : ScoreAssertionsContext;\nexport type BooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined, HasGate extends boolean = false, HasScore extends boolean = false> = Kind extends \"pass\" ? PassBooleanAssertionHandle<Refined, HasGate> : ScoreBooleanAssertionHandle<Refined, HasGate, HasScore>;\nexport type MeasurementAssertionHandle<Kind extends AssertionEvaluationKind, HasCondition extends boolean = false, HasScore extends boolean = false> = Kind extends \"pass\" ? PassMeasurementAssertionHandle<HasCondition> : ScoreMeasurementAssertionHandle<HasCondition, HasScore>;\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}\n/** Sealing has no expected authoring failure after registration-time validation. */\nexport type AssertionSealError = never;\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: import(\"../shared/types.ts\").Verdict;\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    /** @internal Reject before an adapter reads or snapshots author material. */\n    assertAuthoringOpen(): void;\n    /** Attempt-owned synchronous admission close; sealing still happens once through `seal`. */\n    closeAuthoring(reason: \"attempt-sealing\" | \"attempt-interrupted\"): void;\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

@@ -1,5 +1,5 @@
 import type { Effect } from "effect";
-import type { BooleanMatch, CollectionMatch, ManagedToolCalls, MatchDiagnostic, NumericComparator, NumericComparisonMatch, ScoreMatch, EventMatch, ManagedEventOccurrences, ToolMatch } from "./match.cjs";
+import type { BooleanMatch, CollectionMatch, ManagedToolCalls, MatchDiagnostic, NumericComparator, NumericMaterial, NumericComparisonMatch, ScoreMatch, EventMatch, ManagedEventOccurrences, ToolMatch } from "./match.cjs";
 import type { AgentWorkspaceDiff } from "./workspace-diff.cjs";
 import type { EvaluationKind } from "../shared/evaluation.cjs";
 import type { JudgeImage } from "../judge/image.cjs";
@@ -22,7 +22,7 @@ export type AssertionCoverage = {
     readonly state: "complete";
 } | {
     readonly state: "partial";
-    readonly reason: "sampled" | "truncated" | "redacted" | "provider-limited";
+    readonly reason: "sampled" | "truncated" | "redacted" | "provider-limited" | "capacity-limited";
 } | {
     readonly state: "unavailable";
     readonly reason: "not-collected" | "source-unavailable" | "producer-failed";
@@ -42,6 +42,11 @@ export type AssertionLimitation = {
     readonly omittedBytes: number;
 } | {
     readonly kind: "provider-limited";
+} | {
+    readonly kind: "capacity-limited";
+    readonly capturedItems: number;
+    readonly knownTotalItems: number;
+    readonly omittedBytes: number | null;
 };
 /**
  * Authoring material intentionally has no blob ref, attachment entry ID, or
@@ -443,6 +448,8 @@ export type BooleanAssertionEvaluation<Refined> = {
 };
 /** A measurement is always a finite unit-interval value when it is available. */
 export type MeasurementAssertionEvaluation = {
+    readonly receipt?: AssertionCollectionReceipt;
+} & ({
     readonly state: "measured";
     readonly value: number;
     readonly detail?: AssertionSnapshotObject;
@@ -456,7 +463,7 @@ export type MeasurementAssertionEvaluation = {
 } | {
     readonly state: "errored";
     readonly detail?: AssertionSnapshotObject;
-};
+});
 export interface CapturedAssertionSnapshot {
     readonly material: Extract<AssertionMaterial, {
         readonly kind: "snapshot";
@@ -465,6 +472,10 @@ export interface CapturedAssertionSnapshot {
     readonly limitations: readonly AssertionLimitation[];
 }
 export interface AssertionRegistrationBase {
+    /** @internal Seal the criterion for the actual local or managed evaluation path. */
+    readonly terminalCriterion?: () => AssertionCriterion;
+    readonly retainedBytes?: number;
+    readonly terminalReceipt?: () => AssertionCollectionReceipt;
     readonly criterion: AssertionCriterion;
     readonly subject: AssertionMaterial;
     readonly evidence?: readonly AssertionMaterial[];
@@ -559,7 +570,11 @@ export type AssertionCheckKind = AssertionEvaluationKind | "polymorphic";
 type CheckedBooleanHandle<Kind extends AssertionCheckKind, Refined> = Kind extends AssertionEvaluationKind ? BooleanAssertionHandle<Kind, Refined> : PolymorphicBooleanAssertionHandle<Refined>;
 type CheckedMeasurementHandle<Kind extends AssertionCheckKind> = Kind extends AssertionEvaluationKind ? MeasurementAssertionHandle<Kind> : PolymorphicMeasurementAssertionHandle;
 /** Single owner for the public check overload set, including Adapter-polymorphic factories. */
-export interface AssertionCheck<Kind extends AssertionCheckKind> {
+export interface AssertionCheck<Kind extends AssertionCheckKind, Context = unknown> {
+    <T>(match: import("./context-match.cjs").MaterialMatch<Context, T>): CheckedBooleanHandle<Kind, void>;
+    <T>(match: import("./context-match.cjs").ContextBooleanMatch<Context, T>): CheckedBooleanHandle<Kind, void>;
+    <T>(match: import("./context-match.cjs").ContextScoreMatch<Context, T>): CheckedMeasurementHandle<Kind>;
+    (value: import("./match.cjs").NumericMaterial, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, number>;
     <Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, "value">): CheckedBooleanHandle<Kind, Refined>;
     <Value extends readonly unknown[]>(value: NumericAssertionSubject<Value>, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, Value>;
     <S extends "turn" | "session" | "attempt">(value: AssertionSubject<ManagedToolCalls<S>>, match: ToolMatch): CheckedBooleanHandle<Kind, ManagedToolCalls<S>>;
@@ -579,10 +594,17 @@ export interface PassAssertionsContext extends AssertionGroupContext {
     readonly evaluationKind: "pass";
     readonly check: AssertionCheck<"pass">;
 }
+/** Adds direct points, or a unit-interval measurement with an explicit fixed weight. */
+export interface ScoreFunction {
+    (points: number): DirectScoreAssertionHandle;
+    (ratio: number | NumericMaterial, options: {
+        readonly weight: number;
+    }): ScoreMeasurementAssertionHandle<false, true>;
+}
 export interface ScoreAssertionsContext extends AssertionGroupContext {
     readonly evaluationKind: "score";
     readonly check: AssertionCheck<"score">;
-    score(points: number): DirectScoreAssertionHandle;
+    readonly score: ScoreFunction;
 }
 export type AssertionsContext<Kind extends AssertionEvaluationKind> = Kind extends "pass" ? PassAssertionsContext : ScoreAssertionsContext;
 export type BooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined, HasGate extends boolean = false, HasScore extends boolean = false> = Kind extends "pass" ? PassBooleanAssertionHandle<Refined, HasGate> : ScoreBooleanAssertionHandle<Refined, HasGate, HasScore>;

package/dist/assertions/api.d.mts

@@ -1,5 +1,5 @@
 import type { Effect } from "effect";
-import type { BooleanMatch, CollectionMatch, ManagedToolCalls, MatchDiagnostic, NumericComparator, NumericComparisonMatch, ScoreMatch, EventMatch, ManagedEventOccurrences, ToolMatch } from "./match.mjs";
+import type { BooleanMatch, CollectionMatch, ManagedToolCalls, MatchDiagnostic, NumericComparator, NumericMaterial, NumericComparisonMatch, ScoreMatch, EventMatch, ManagedEventOccurrences, ToolMatch } from "./match.mjs";
 import type { AgentWorkspaceDiff } from "./workspace-diff.mjs";
 import type { EvaluationKind } from "../shared/evaluation.mjs";
 import type { JudgeImage } from "../judge/image.mjs";
@@ -22,7 +22,7 @@ export type AssertionCoverage = {
     readonly state: "complete";
 } | {
     readonly state: "partial";
-    readonly reason: "sampled" | "truncated" | "redacted" | "provider-limited";
+    readonly reason: "sampled" | "truncated" | "redacted" | "provider-limited" | "capacity-limited";
 } | {
     readonly state: "unavailable";
     readonly reason: "not-collected" | "source-unavailable" | "producer-failed";
@@ -42,6 +42,11 @@ export type AssertionLimitation = {
     readonly omittedBytes: number;
 } | {
     readonly kind: "provider-limited";
+} | {
+    readonly kind: "capacity-limited";
+    readonly capturedItems: number;
+    readonly knownTotalItems: number;
+    readonly omittedBytes: number | null;
 };
 /**
  * Authoring material intentionally has no blob ref, attachment entry ID, or
@@ -443,6 +448,8 @@ export type BooleanAssertionEvaluation<Refined> = {
 };
 /** A measurement is always a finite unit-interval value when it is available. */
 export type MeasurementAssertionEvaluation = {
+    readonly receipt?: AssertionCollectionReceipt;
+} & ({
     readonly state: "measured";
     readonly value: number;
     readonly detail?: AssertionSnapshotObject;
@@ -456,7 +463,7 @@ export type MeasurementAssertionEvaluation = {
 } | {
     readonly state: "errored";
     readonly detail?: AssertionSnapshotObject;
-};
+});
 export interface CapturedAssertionSnapshot {
     readonly material: Extract<AssertionMaterial, {
         readonly kind: "snapshot";
@@ -465,6 +472,10 @@ export interface CapturedAssertionSnapshot {
     readonly limitations: readonly AssertionLimitation[];
 }
 export interface AssertionRegistrationBase {
+    /** @internal Seal the criterion for the actual local or managed evaluation path. */
+    readonly terminalCriterion?: () => AssertionCriterion;
+    readonly retainedBytes?: number;
+    readonly terminalReceipt?: () => AssertionCollectionReceipt;
     readonly criterion: AssertionCriterion;
     readonly subject: AssertionMaterial;
     readonly evidence?: readonly AssertionMaterial[];
@@ -559,7 +570,11 @@ export type AssertionCheckKind = AssertionEvaluationKind | "polymorphic";
 type CheckedBooleanHandle<Kind extends AssertionCheckKind, Refined> = Kind extends AssertionEvaluationKind ? BooleanAssertionHandle<Kind, Refined> : PolymorphicBooleanAssertionHandle<Refined>;
 type CheckedMeasurementHandle<Kind extends AssertionCheckKind> = Kind extends AssertionEvaluationKind ? MeasurementAssertionHandle<Kind> : PolymorphicMeasurementAssertionHandle;
 /** Single owner for the public check overload set, including Adapter-polymorphic factories. */
-export interface AssertionCheck<Kind extends AssertionCheckKind> {
+export interface AssertionCheck<Kind extends AssertionCheckKind, Context = unknown> {
+    <T>(match: import("./context-match.mjs").MaterialMatch<Context, T>): CheckedBooleanHandle<Kind, void>;
+    <T>(match: import("./context-match.mjs").ContextBooleanMatch<Context, T>): CheckedBooleanHandle<Kind, void>;
+    <T>(match: import("./context-match.mjs").ContextScoreMatch<Context, T>): CheckedMeasurementHandle<Kind>;
+    (value: import("./match.mjs").NumericMaterial, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, number>;
     <Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, "value">): CheckedBooleanHandle<Kind, Refined>;
     <Value extends readonly unknown[]>(value: NumericAssertionSubject<Value>, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, Value>;
     <S extends "turn" | "session" | "attempt">(value: AssertionSubject<ManagedToolCalls<S>>, match: ToolMatch): CheckedBooleanHandle<Kind, ManagedToolCalls<S>>;
@@ -579,10 +594,17 @@ export interface PassAssertionsContext extends AssertionGroupContext {
     readonly evaluationKind: "pass";
     readonly check: AssertionCheck<"pass">;
 }
+/** Adds direct points, or a unit-interval measurement with an explicit fixed weight. */
+export interface ScoreFunction {
+    (points: number): DirectScoreAssertionHandle;
+    (ratio: number | NumericMaterial, options: {
+        readonly weight: number;
+    }): ScoreMeasurementAssertionHandle<false, true>;
+}
 export interface ScoreAssertionsContext extends AssertionGroupContext {
     readonly evaluationKind: "score";
     readonly check: AssertionCheck<"score">;
-    score(points: number): DirectScoreAssertionHandle;
+    readonly score: ScoreFunction;
 }
 export type AssertionsContext<Kind extends AssertionEvaluationKind> = Kind extends "pass" ? PassAssertionsContext : ScoreAssertionsContext;
 export type BooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined, HasGate extends boolean = false, HasScore extends boolean = false> = Kind extends "pass" ? PassBooleanAssertionHandle<Refined, HasGate> : ScoreBooleanAssertionHandle<Refined, HasGate, HasScore>;

package/dist/assertions/api.d.ts

@@ -1,5 +1,5 @@
 import type { Effect } from "effect";
-import type { BooleanMatch, CollectionMatch, ManagedToolCalls, MatchDiagnostic, NumericComparator, NumericComparisonMatch, ScoreMatch, EventMatch, ManagedEventOccurrences, ToolMatch } from "./match.js";
+import type { BooleanMatch, CollectionMatch, ManagedToolCalls, MatchDiagnostic, NumericComparator, NumericMaterial, NumericComparisonMatch, ScoreMatch, EventMatch, ManagedEventOccurrences, ToolMatch } from "./match.js";
 import type { AgentWorkspaceDiff } from "./workspace-diff.js";
 import type { EvaluationKind } from "../shared/evaluation.js";
 import type { JudgeImage } from "../judge/image.js";
@@ -22,7 +22,7 @@ export type AssertionCoverage = {
     readonly state: "complete";
 } | {
     readonly state: "partial";
-    readonly reason: "sampled" | "truncated" | "redacted" | "provider-limited";
+    readonly reason: "sampled" | "truncated" | "redacted" | "provider-limited" | "capacity-limited";
 } | {
     readonly state: "unavailable";
     readonly reason: "not-collected" | "source-unavailable" | "producer-failed";
@@ -42,6 +42,11 @@ export type AssertionLimitation = {
     readonly omittedBytes: number;
 } | {
     readonly kind: "provider-limited";
+} | {
+    readonly kind: "capacity-limited";
+    readonly capturedItems: number;
+    readonly knownTotalItems: number;
+    readonly omittedBytes: number | null;
 };
 /**
  * Authoring material intentionally has no blob ref, attachment entry ID, or
@@ -443,6 +448,8 @@ export type BooleanAssertionEvaluation<Refined> = {
 };
 /** A measurement is always a finite unit-interval value when it is available. */
 export type MeasurementAssertionEvaluation = {
+    readonly receipt?: AssertionCollectionReceipt;
+} & ({
     readonly state: "measured";
     readonly value: number;
     readonly detail?: AssertionSnapshotObject;
@@ -456,7 +463,7 @@ export type MeasurementAssertionEvaluation = {
 } | {
     readonly state: "errored";
     readonly detail?: AssertionSnapshotObject;
-};
+});
 export interface CapturedAssertionSnapshot {
     readonly material: Extract<AssertionMaterial, {
         readonly kind: "snapshot";
@@ -465,6 +472,10 @@ export interface CapturedAssertionSnapshot {
     readonly limitations: readonly AssertionLimitation[];
 }
 export interface AssertionRegistrationBase {
+    /** @internal Seal the criterion for the actual local or managed evaluation path. */
+    readonly terminalCriterion?: () => AssertionCriterion;
+    readonly retainedBytes?: number;
+    readonly terminalReceipt?: () => AssertionCollectionReceipt;
     readonly criterion: AssertionCriterion;
     readonly subject: AssertionMaterial;
     readonly evidence?: readonly AssertionMaterial[];
@@ -559,7 +570,11 @@ export type AssertionCheckKind = AssertionEvaluationKind | "polymorphic";
 type CheckedBooleanHandle<Kind extends AssertionCheckKind, Refined> = Kind extends AssertionEvaluationKind ? BooleanAssertionHandle<Kind, Refined> : PolymorphicBooleanAssertionHandle<Refined>;
 type CheckedMeasurementHandle<Kind extends AssertionCheckKind> = Kind extends AssertionEvaluationKind ? MeasurementAssertionHandle<Kind> : PolymorphicMeasurementAssertionHandle;
 /** Single owner for the public check overload set, including Adapter-polymorphic factories. */
-export interface AssertionCheck<Kind extends AssertionCheckKind> {
+export interface AssertionCheck<Kind extends AssertionCheckKind, Context = unknown> {
+    <T>(match: import("./context-match.js").MaterialMatch<Context, T>): CheckedBooleanHandle<Kind, void>;
+    <T>(match: import("./context-match.js").ContextBooleanMatch<Context, T>): CheckedBooleanHandle<Kind, void>;
+    <T>(match: import("./context-match.js").ContextScoreMatch<Context, T>): CheckedMeasurementHandle<Kind>;
+    (value: import("./match.js").NumericMaterial, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, number>;
     <Value, Refined extends Value>(value: AssertionSubject<Value>, match: BooleanMatch<NoInfer<Value>, Refined, "value">): CheckedBooleanHandle<Kind, Refined>;
     <Value extends readonly unknown[]>(value: NumericAssertionSubject<Value>, match: NumericComparisonMatch): CheckedBooleanHandle<Kind, Value>;
     <S extends "turn" | "session" | "attempt">(value: AssertionSubject<ManagedToolCalls<S>>, match: ToolMatch): CheckedBooleanHandle<Kind, ManagedToolCalls<S>>;
@@ -579,10 +594,17 @@ export interface PassAssertionsContext extends AssertionGroupContext {
     readonly evaluationKind: "pass";
     readonly check: AssertionCheck<"pass">;
 }
+/** Adds direct points, or a unit-interval measurement with an explicit fixed weight. */
+export interface ScoreFunction {
+    (points: number): DirectScoreAssertionHandle;
+    (ratio: number | NumericMaterial, options: {
+        readonly weight: number;
+    }): ScoreMeasurementAssertionHandle<false, true>;
+}
 export interface ScoreAssertionsContext extends AssertionGroupContext {
     readonly evaluationKind: "score";
     readonly check: AssertionCheck<"score">;
-    score(points: number): DirectScoreAssertionHandle;
+    readonly score: ScoreFunction;
 }
 export type AssertionsContext<Kind extends AssertionEvaluationKind> = Kind extends "pass" ? PassAssertionsContext : ScoreAssertionsContext;
 export type BooleanAssertionHandle<Kind extends AssertionEvaluationKind, Refined, HasGate extends boolean = false, HasScore extends boolean = false> = Kind extends "pass" ? PassBooleanAssertionHandle<Refined, HasGate> : ScoreBooleanAssertionHandle<Refined, HasGate, HasScore>;

package/dist/assertions/collection.cjs

@@ -4,7 +4,13 @@ exports.freezeManagedToolCalls = freezeManagedToolCalls;
 exports.managedToolCallsSidecarOf = managedToolCallsSidecarOf;
 exports.freezeManagedEventOccurrences = freezeManagedEventOccurrences;
 exports.managedEventOccurrencesSidecarOf = managedEventOccurrencesSidecarOf;
+exports.toolMatcherQuery = toolMatcherQuery;
+exports.eventMatcherQuery = eventMatcherQuery;
 exports.collectionMatchRegistration = collectionMatchRegistration;
+// @concord-file ne-eval-assertions-collection
+// @concord-implements docs/feature/assertions/library/scoped-assertions.md
+// @concord-implements docs/feature/assertions/architecture/evidence.md
+// @concord-implements docs/feature/eval/use-case/calledtool.md
 const effect_1 = require("effect");
 const matcher_artifact_ts_1 = require("./matcher-artifact.cjs");
 const match_ts_1 = require("./match.cjs");