niceeval 0.12.1 → 0.12.2-canary.31

package/dist/assertions/match.d.mts

@@ -0,0 +1,276 @@
+import type { StandardSchemaV1 as StandardSchema } from "@standard-schema/spec";
+import type { CommandProjection, LogicalToolOccurrence } from "../o11y/types.mjs";
+import type { JsonMatch, JsonValue } from "../shared/types.mjs";
+export type MatchDomain = "value" | "tool" | "event";
+type MatchPathSegment = string | number;
+/** 可序列化的候选诊断；组合 matcher 用 children 保留声明顺序与嵌套位置。 */
+export interface MatchDiagnostic {
+    readonly code: string;
+    readonly message: string;
+    /** 相对当前 matcher 的路径；组合节点的 child index 也由 children 明确给出。 */
+    readonly path: readonly MatchPathSegment[];
+    readonly expected?: string;
+    readonly received?: string;
+    readonly reason?: string;
+    readonly locator?: {
+        readonly kind: "json-pointer";
+        readonly pointer: string;
+    } | {
+        readonly kind: "tool-occurrence";
+        readonly id: string;
+    };
+    readonly children?: readonly MatchDiagnosticChild[];
+}
+export interface MatchDiagnosticChild {
+    readonly index: number;
+    readonly label?: string;
+    readonly state: MatchEvaluationState;
+    readonly diagnostic?: MatchDiagnostic;
+}
+export type MatchEvaluationState = "matched" | "mismatched" | "unavailable";
+/** 一个单候选 matcher 的内部三态结果。 */
+export type BooleanMatchEvaluation<R> = {
+    readonly state: "matched";
+    /** 永远是传入 candidate 本身，只是在类型层收窄。 */
+    readonly value: R;
+    readonly diagnostic?: MatchDiagnostic;
+} | {
+    readonly state: "mismatched";
+    readonly diagnostic: MatchDiagnostic;
+} | {
+    readonly state: "unavailable";
+    readonly reason: string;
+    readonly diagnostic: MatchDiagnostic;
+};
+declare const matchInputBrand: unique symbol;
+declare const matchRefinementBrand: unique symbol;
+declare const matchEvaluatorBrand: unique symbol;
+declare const thresholdedScoreMatchBrand: unique symbol;
+declare const assertionEventIdentityBrand: unique symbol;
+declare const assertionEventPositionBrand: unique symbol;
+declare const toolOccurrenceIdentityBrand: unique symbol;
+export interface Match<in T, D extends MatchDomain> {
+    readonly domain: D;
+    readonly name: string;
+    readonly [matchInputBrand]: (candidate: T) => void;
+    readonly [matchEvaluatorBrand]: (candidate: T) => Promise<unknown>;
+}
+export interface BooleanMatch<in T, out R extends T, D extends MatchDomain = "value"> extends Match<T, D> {
+    readonly kind: "boolean";
+    readonly [matchRefinementBrand]: () => R;
+}
+export interface ScoreMatch<in T> extends Match<T, "value"> {
+    readonly kind: "score";
+    atLeast(threshold: number): ThresholdedScoreMatch<T>;
+}
+export interface ThresholdedScoreMatch<in T> {
+    readonly kind: "thresholded-score-match";
+    readonly [thresholdedScoreMatchBrand]: (candidate: T) => void;
+}
+export type ValueMatch<T, R extends T = T> = BooleanMatch<T, R, "value"> | ScoreMatch<T>;
+export type LogicalCommandOccurrence = LogicalToolOccurrence & {
+    readonly command: Extract<CommandProjection, {
+        readonly kind: "command";
+    }>;
+};
+export type ToolMatch<R extends LogicalToolOccurrence = LogicalToolOccurrence> = BooleanMatch<LogicalToolOccurrence, R, "tool">;
+export type AssertionEventIdentity = string & {
+    readonly [assertionEventIdentityBrand]: true;
+};
+export type ToolOccurrenceIdentity = string & {
+    readonly [toolOccurrenceIdentityBrand]: true;
+};
+export interface AssertionEventPosition {
+    readonly turnOrdinal: number;
+    readonly eventOrdinal: number;
+    readonly [assertionEventPositionBrand]: true;
+}
+export interface AssertionToolReference {
+    readonly id: ToolOccurrenceIdentity;
+    readonly name: string;
+}
+export type AssertionEvent = {
+    readonly id: AssertionEventIdentity;
+    readonly position: AssertionEventPosition;
+    readonly type: "message";
+    readonly role: "assistant" | "user";
+    readonly text: string;
+} | {
+    readonly id: AssertionEventIdentity;
+    readonly position: AssertionEventPosition;
+    readonly type: "operation.started";
+    readonly tool: AssertionToolReference;
+} | {
+    readonly id: AssertionEventIdentity;
+    readonly position: AssertionEventPosition;
+    readonly type: "operation.finished";
+    readonly tool: AssertionToolReference;
+    readonly status: "completed" | "failed" | "rejected";
+};
+export type MatchableEvent = AssertionEvent;
+export type EventMatch<R extends AssertionEvent = AssertionEvent> = BooleanMatch<AssertionEvent, R, "event">;
+export type RefinementOf<M> = M extends BooleanMatch<infer _T, infer R, infer _D> ? R : never;
+export type RefinementIntersection<M extends readonly unknown[]> = M extends readonly [infer Head, ...infer Tail] ? RefinementOf<Head> & RefinementIntersection<Tail> : unknown;
+/** @internal Runtime brand guard used by the context overload dispatcher. */
+export declare function isManagedMatch(value: unknown): boolean;
+/** @internal Reject Match-shaped raw subjects instead of silently treating them as ordinary values. */
+export declare function looksLikeMatch(value: unknown): boolean;
+/** @internal Runtime brand guard for ScoreMatch.atLeast(). */
+export declare function isManagedThresholdedScoreMatch(value: unknown): value is ThresholdedScoreMatch<unknown>;
+/** @internal Reserve threshold-view-shaped raw inputs at the authoring boundary. */
+export declare function looksLikeThresholdedScoreMatch(value: unknown): boolean;
+/** @internal Resolve a threshold view without evaluating its underlying Match. */
+export declare function thresholdedScoreMatchValue(value: unknown): {
+    readonly match: ScoreMatch<unknown>;
+    readonly threshold: number;
+};
+/** @internal The value-side consumer accepts only a real, value-domain Match. */
+export declare function assertManagedValueMatch(value: unknown, label?: string): BooleanMatch<unknown, unknown, "value"> | ScoreMatch<unknown>;
+/** @internal Project a raw message into the closed assertion-event surface. */
+export declare function makeAssertionMessageEvent(input: {
+    readonly session: string;
+    readonly turn: string;
+    readonly turnOrdinal: number;
+    readonly eventOrdinal: number;
+    readonly role: "assistant" | "user";
+    readonly text: string;
+}): Extract<AssertionEvent, {
+    readonly type: "message";
+}>;
+/** @internal Project a correlated tool lifecycle row without exposing raw adapter fields. */
+export declare function makeAssertionToolEvent(input: {
+    readonly session: string;
+    readonly turn: string;
+    readonly turnOrdinal: number;
+    readonly eventOrdinal: number;
+    readonly type: "operation.started" | "operation.finished";
+    readonly occurrence: LogicalToolOccurrence;
+    readonly status?: "completed" | "failed" | "rejected";
+}): Extract<AssertionEvent, {
+    readonly type: "operation.started" | "operation.finished";
+}>;
+/** @internal Retrieve the correlated occurrence for eventMatch(tool). */
+export declare function assertionEventOccurrence(event: AssertionEvent): LogicalToolOccurrence | undefined;
+/** 供 Assertion runtime / scope owner 消费 BooleanMatch；普通作者面不会导出此 evaluator。 */
+export declare function evaluateBooleanMatch<T, R extends T, D extends MatchDomain>(match: BooleanMatch<T, R, D>, candidate: T): Promise<BooleanMatchEvaluation<R>>;
+/** 供 Assertion runtime 消费 ScoreMatch。范围非法是 evaluator defect，绝不 clamp。 */
+export declare function evaluateScoreMatch<T>(match: ScoreMatch<T>, candidate: T): Promise<number>;
+export declare function and<T, R extends T, D extends MatchDomain, const Rest extends readonly [
+    BooleanMatch<NoInfer<T>, T, NoInfer<D>>,
+    ...BooleanMatch<NoInfer<T>, T, NoInfer<D>>[]
+]>(first: BooleanMatch<T, R, D>, ...rest: Rest): BooleanMatch<T, T & R & RefinementIntersection<Rest>, D>;
+export declare function or<T, R extends T, D extends MatchDomain, const Rest extends readonly [
+    BooleanMatch<NoInfer<T>, T, NoInfer<D>>,
+    ...BooleanMatch<NoInfer<T>, T, NoInfer<D>>[]
+]>(first: BooleanMatch<T, R, D>, ...rest: Rest): BooleanMatch<T, T & (R | RefinementOf<Rest[number]>), D>;
+export declare function not<T>(match: BooleanMatch<T, T, "value">): BooleanMatch<T, T, "value">;
+export interface TextMatchOptions {
+    readonly stripComments?: boolean;
+}
+export declare function includes(text: string, options?: TextMatchOptions): BooleanMatch<string, string>;
+export declare function excludes(text: string, options?: TextMatchOptions): BooleanMatch<string, string>;
+export declare function pattern(expression: RegExp, options?: TextMatchOptions): BooleanMatch<string, string>;
+/** 归一化 Levenshtein similarity；它是连续分数，不携带默认阈值或 verdict 策略。 */
+export declare function similarity(expected: string): ScoreMatch<string>;
+/** 至少含 min 个去重 http(s) URL 的纯文本 matcher。 */
+export declare function includesUrl(min?: number): BooleanMatch<string, string>;
+/** 至少含 min 个 Markdown heading 的纯文本 matcher。 */
+export declare function hasSections(min?: number): BooleanMatch<string, string>;
+/** 非 null / undefined 的 value matcher；泛型调用可保留原 candidate 的非空收窄。 */
+export declare function isDefined(label?: string): BooleanMatch<unknown, {}>;
+export declare function isDefined<T>(label?: string): BooleanMatch<T, Exclude<T, null | undefined>>;
+/** value === true 的 refinement matcher。 */
+export declare function isTrue<T = unknown>(label?: string): BooleanMatch<T, T & true>;
+/** value === false 的 refinement matcher。 */
+export declare function isFalse<T = unknown>(label?: string): BooleanMatch<T, T & false>;
+/** CommandResult-like candidate 的 exitCode === 0 matcher；不读取 stdout / stderr。 */
+export declare function commandSucceeded<T = unknown>(): BooleanMatch<T, T & {
+    readonly exitCode: 0;
+}>;
+/** 小而稳定的深相等：基本值、NaN、Array、Date 与 enumerable object properties。 */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+export declare function equals<const T>(expected: T): BooleanMatch<unknown, T>;
+export declare function matches<S extends StandardSchema>(schema: S): BooleanMatch<unknown, StandardSchema.InferInput<S>, "value">;
+/**
+ * 旧 context 接线还会调用这一个内部 helper。它不再接受 Zod-style fallback；新的公共 matches()
+ * 使用上面的严格 Standard Schema 入口，异常则由 evaluator 作为 defect 处理。
+ */
+export declare function validateSchema(value: unknown, schema: unknown): Promise<boolean>;
+export declare function satisfies<T, R extends T>(label: string, predicate: (value: T) => value is R): BooleanMatch<T, R>;
+export declare function satisfies<T>(label: string, predicate: (value: T) => boolean | Promise<boolean>): BooleanMatch<T, T>;
+export declare function defineValueMatch<T, R extends T>(spec: {
+    readonly name: string;
+    readonly evaluate: (value: T) => value is R;
+}): BooleanMatch<T, R>;
+export declare function defineValueMatch<T>(spec: {
+    readonly name: string;
+    readonly evaluate: (value: T) => boolean | Promise<boolean>;
+}): BooleanMatch<T, T>;
+export declare function defineScoreMatch<T>(spec: {
+    readonly name: string;
+    readonly score: (value: T) => number | Promise<number>;
+}): ScoreMatch<T>;
+export declare function referencesAnyPath(paths: readonly [string, ...string[]]): BooleanMatch<JsonValue, JsonValue, "value">;
+export type ToolStatus = Extract<LogicalToolOccurrence["lifecycle"], {
+    readonly state: "available";
+}>["status"];
+export interface CommandMatchOptions {
+    readonly argsStart?: readonly string[];
+    readonly excludes?: readonly string[];
+    readonly status?: ToolStatus;
+}
+export interface ToolMatchOptions {
+    readonly input?: BooleanMatch<JsonValue, JsonValue, "value">;
+    readonly output?: BooleanMatch<JsonValue, JsonValue, "value">;
+    readonly status?: ToolStatus;
+}
+/**
+ * Turns the recursive JsonMatch language into a managed value Match.  Raw
+ * JsonMatch stays at this explicit bridge; tool assertions consume only the
+ * branded Match so every tool field follows the same evaluator path.
+ */
+export declare function jsonMatch(expected: JsonMatch): BooleanMatch<JsonValue, JsonValue, "value">;
+export declare function toolMatch(name: string, options?: ToolMatchOptions): ToolMatch;
+export declare function toolMatch(options: ToolMatchOptions): ToolMatch;
+/** @internal Assert-first accepts only branded tool-domain matches. */
+export declare function assertManagedToolMatch(value: unknown, label?: string): ToolMatch;
+/** @internal Assert-first accepts only branded event-domain matches. */
+export declare function assertManagedEventMatch(value: unknown, label?: string): EventMatch;
+export type ToolMatchQuantifier = {
+    readonly kind: "at-least";
+    readonly count: number;
+} | {
+    readonly kind: "exact";
+    readonly count: number;
+} | {
+    readonly kind: "absent";
+};
+export interface ToolMatchCollectionOptions {
+    readonly quantifier: ToolMatchQuantifier;
+    /** Scope-level action coverage that can hide additional candidates. */
+    readonly coverageReason?: string;
+}
+/**
+ * The sole collection evaluator for scoped tool Assertions. It evaluates each
+ * occurrence through ToolMatch, then folds exact / at-least / absent with the
+ * same three-valued rule: a definite counterexample wins; incomplete evidence
+ * cannot manufacture a positive count or an absence proof.
+ */
+export declare function evaluateToolMatchCollection(match: ToolMatch, occurrences: readonly LogicalToolOccurrence[], options: ToolMatchCollectionOptions): Promise<BooleanMatchEvaluation<LogicalToolOccurrence | undefined>>;
+export declare function commandMatch(executable: string, options?: CommandMatchOptions): ToolMatch<LogicalCommandOccurrence>;
+export interface EventOptionsByType {
+    readonly message: {
+        readonly role?: "assistant" | "user";
+        readonly text?: BooleanMatch<string, string, "value">;
+    };
+    readonly "operation.started": {
+        readonly tool?: ToolMatch;
+    };
+    readonly "operation.finished": {
+        readonly tool?: ToolMatch;
+    };
+}
+export declare function eventMatch<K extends keyof EventOptionsByType>(type: K, options?: EventOptionsByType[K]): EventMatch<Extract<AssertionEvent, {
+    readonly type: K;
+}>>;
+export {};

package/dist/assertions/match.d.ts

@@ -0,0 +1,276 @@
+import type { StandardSchemaV1 as StandardSchema } from "@standard-schema/spec";
+import type { CommandProjection, LogicalToolOccurrence } from "../o11y/types.js";
+import type { JsonMatch, JsonValue } from "../shared/types.js";
+export type MatchDomain = "value" | "tool" | "event";
+type MatchPathSegment = string | number;
+/** 可序列化的候选诊断；组合 matcher 用 children 保留声明顺序与嵌套位置。 */
+export interface MatchDiagnostic {
+    readonly code: string;
+    readonly message: string;
+    /** 相对当前 matcher 的路径；组合节点的 child index 也由 children 明确给出。 */
+    readonly path: readonly MatchPathSegment[];
+    readonly expected?: string;
+    readonly received?: string;
+    readonly reason?: string;
+    readonly locator?: {
+        readonly kind: "json-pointer";
+        readonly pointer: string;
+    } | {
+        readonly kind: "tool-occurrence";
+        readonly id: string;
+    };
+    readonly children?: readonly MatchDiagnosticChild[];
+}
+export interface MatchDiagnosticChild {
+    readonly index: number;
+    readonly label?: string;
+    readonly state: MatchEvaluationState;
+    readonly diagnostic?: MatchDiagnostic;
+}
+export type MatchEvaluationState = "matched" | "mismatched" | "unavailable";
+/** 一个单候选 matcher 的内部三态结果。 */
+export type BooleanMatchEvaluation<R> = {
+    readonly state: "matched";
+    /** 永远是传入 candidate 本身，只是在类型层收窄。 */
+    readonly value: R;
+    readonly diagnostic?: MatchDiagnostic;
+} | {
+    readonly state: "mismatched";
+    readonly diagnostic: MatchDiagnostic;
+} | {
+    readonly state: "unavailable";
+    readonly reason: string;
+    readonly diagnostic: MatchDiagnostic;
+};
+declare const matchInputBrand: unique symbol;
+declare const matchRefinementBrand: unique symbol;
+declare const matchEvaluatorBrand: unique symbol;
+declare const thresholdedScoreMatchBrand: unique symbol;
+declare const assertionEventIdentityBrand: unique symbol;
+declare const assertionEventPositionBrand: unique symbol;
+declare const toolOccurrenceIdentityBrand: unique symbol;
+export interface Match<in T, D extends MatchDomain> {
+    readonly domain: D;
+    readonly name: string;
+    readonly [matchInputBrand]: (candidate: T) => void;
+    readonly [matchEvaluatorBrand]: (candidate: T) => Promise<unknown>;
+}
+export interface BooleanMatch<in T, out R extends T, D extends MatchDomain = "value"> extends Match<T, D> {
+    readonly kind: "boolean";
+    readonly [matchRefinementBrand]: () => R;
+}
+export interface ScoreMatch<in T> extends Match<T, "value"> {
+    readonly kind: "score";
+    atLeast(threshold: number): ThresholdedScoreMatch<T>;
+}
+export interface ThresholdedScoreMatch<in T> {
+    readonly kind: "thresholded-score-match";
+    readonly [thresholdedScoreMatchBrand]: (candidate: T) => void;
+}
+export type ValueMatch<T, R extends T = T> = BooleanMatch<T, R, "value"> | ScoreMatch<T>;
+export type LogicalCommandOccurrence = LogicalToolOccurrence & {
+    readonly command: Extract<CommandProjection, {
+        readonly kind: "command";
+    }>;
+};
+export type ToolMatch<R extends LogicalToolOccurrence = LogicalToolOccurrence> = BooleanMatch<LogicalToolOccurrence, R, "tool">;
+export type AssertionEventIdentity = string & {
+    readonly [assertionEventIdentityBrand]: true;
+};
+export type ToolOccurrenceIdentity = string & {
+    readonly [toolOccurrenceIdentityBrand]: true;
+};
+export interface AssertionEventPosition {
+    readonly turnOrdinal: number;
+    readonly eventOrdinal: number;
+    readonly [assertionEventPositionBrand]: true;
+}
+export interface AssertionToolReference {
+    readonly id: ToolOccurrenceIdentity;
+    readonly name: string;
+}
+export type AssertionEvent = {
+    readonly id: AssertionEventIdentity;
+    readonly position: AssertionEventPosition;
+    readonly type: "message";
+    readonly role: "assistant" | "user";
+    readonly text: string;
+} | {
+    readonly id: AssertionEventIdentity;
+    readonly position: AssertionEventPosition;
+    readonly type: "operation.started";
+    readonly tool: AssertionToolReference;
+} | {
+    readonly id: AssertionEventIdentity;
+    readonly position: AssertionEventPosition;
+    readonly type: "operation.finished";
+    readonly tool: AssertionToolReference;
+    readonly status: "completed" | "failed" | "rejected";
+};
+export type MatchableEvent = AssertionEvent;
+export type EventMatch<R extends AssertionEvent = AssertionEvent> = BooleanMatch<AssertionEvent, R, "event">;
+export type RefinementOf<M> = M extends BooleanMatch<infer _T, infer R, infer _D> ? R : never;
+export type RefinementIntersection<M extends readonly unknown[]> = M extends readonly [infer Head, ...infer Tail] ? RefinementOf<Head> & RefinementIntersection<Tail> : unknown;
+/** @internal Runtime brand guard used by the context overload dispatcher. */
+export declare function isManagedMatch(value: unknown): boolean;
+/** @internal Reject Match-shaped raw subjects instead of silently treating them as ordinary values. */
+export declare function looksLikeMatch(value: unknown): boolean;
+/** @internal Runtime brand guard for ScoreMatch.atLeast(). */
+export declare function isManagedThresholdedScoreMatch(value: unknown): value is ThresholdedScoreMatch<unknown>;
+/** @internal Reserve threshold-view-shaped raw inputs at the authoring boundary. */
+export declare function looksLikeThresholdedScoreMatch(value: unknown): boolean;
+/** @internal Resolve a threshold view without evaluating its underlying Match. */
+export declare function thresholdedScoreMatchValue(value: unknown): {
+    readonly match: ScoreMatch<unknown>;
+    readonly threshold: number;
+};
+/** @internal The value-side consumer accepts only a real, value-domain Match. */
+export declare function assertManagedValueMatch(value: unknown, label?: string): BooleanMatch<unknown, unknown, "value"> | ScoreMatch<unknown>;
+/** @internal Project a raw message into the closed assertion-event surface. */
+export declare function makeAssertionMessageEvent(input: {
+    readonly session: string;
+    readonly turn: string;
+    readonly turnOrdinal: number;
+    readonly eventOrdinal: number;
+    readonly role: "assistant" | "user";
+    readonly text: string;
+}): Extract<AssertionEvent, {
+    readonly type: "message";
+}>;
+/** @internal Project a correlated tool lifecycle row without exposing raw adapter fields. */
+export declare function makeAssertionToolEvent(input: {
+    readonly session: string;
+    readonly turn: string;
+    readonly turnOrdinal: number;
+    readonly eventOrdinal: number;
+    readonly type: "operation.started" | "operation.finished";
+    readonly occurrence: LogicalToolOccurrence;
+    readonly status?: "completed" | "failed" | "rejected";
+}): Extract<AssertionEvent, {
+    readonly type: "operation.started" | "operation.finished";
+}>;
+/** @internal Retrieve the correlated occurrence for eventMatch(tool). */
+export declare function assertionEventOccurrence(event: AssertionEvent): LogicalToolOccurrence | undefined;
+/** 供 Assertion runtime / scope owner 消费 BooleanMatch；普通作者面不会导出此 evaluator。 */
+export declare function evaluateBooleanMatch<T, R extends T, D extends MatchDomain>(match: BooleanMatch<T, R, D>, candidate: T): Promise<BooleanMatchEvaluation<R>>;
+/** 供 Assertion runtime 消费 ScoreMatch。范围非法是 evaluator defect，绝不 clamp。 */
+export declare function evaluateScoreMatch<T>(match: ScoreMatch<T>, candidate: T): Promise<number>;
+export declare function and<T, R extends T, D extends MatchDomain, const Rest extends readonly [
+    BooleanMatch<NoInfer<T>, T, NoInfer<D>>,
+    ...BooleanMatch<NoInfer<T>, T, NoInfer<D>>[]
+]>(first: BooleanMatch<T, R, D>, ...rest: Rest): BooleanMatch<T, T & R & RefinementIntersection<Rest>, D>;
+export declare function or<T, R extends T, D extends MatchDomain, const Rest extends readonly [
+    BooleanMatch<NoInfer<T>, T, NoInfer<D>>,
+    ...BooleanMatch<NoInfer<T>, T, NoInfer<D>>[]
+]>(first: BooleanMatch<T, R, D>, ...rest: Rest): BooleanMatch<T, T & (R | RefinementOf<Rest[number]>), D>;
+export declare function not<T>(match: BooleanMatch<T, T, "value">): BooleanMatch<T, T, "value">;
+export interface TextMatchOptions {
+    readonly stripComments?: boolean;
+}
+export declare function includes(text: string, options?: TextMatchOptions): BooleanMatch<string, string>;
+export declare function excludes(text: string, options?: TextMatchOptions): BooleanMatch<string, string>;
+export declare function pattern(expression: RegExp, options?: TextMatchOptions): BooleanMatch<string, string>;
+/** 归一化 Levenshtein similarity；它是连续分数，不携带默认阈值或 verdict 策略。 */
+export declare function similarity(expected: string): ScoreMatch<string>;
+/** 至少含 min 个去重 http(s) URL 的纯文本 matcher。 */
+export declare function includesUrl(min?: number): BooleanMatch<string, string>;
+/** 至少含 min 个 Markdown heading 的纯文本 matcher。 */
+export declare function hasSections(min?: number): BooleanMatch<string, string>;
+/** 非 null / undefined 的 value matcher；泛型调用可保留原 candidate 的非空收窄。 */
+export declare function isDefined(label?: string): BooleanMatch<unknown, {}>;
+export declare function isDefined<T>(label?: string): BooleanMatch<T, Exclude<T, null | undefined>>;
+/** value === true 的 refinement matcher。 */
+export declare function isTrue<T = unknown>(label?: string): BooleanMatch<T, T & true>;
+/** value === false 的 refinement matcher。 */
+export declare function isFalse<T = unknown>(label?: string): BooleanMatch<T, T & false>;
+/** CommandResult-like candidate 的 exitCode === 0 matcher；不读取 stdout / stderr。 */
+export declare function commandSucceeded<T = unknown>(): BooleanMatch<T, T & {
+    readonly exitCode: 0;
+}>;
+/** 小而稳定的深相等：基本值、NaN、Array、Date 与 enumerable object properties。 */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+export declare function equals<const T>(expected: T): BooleanMatch<unknown, T>;
+export declare function matches<S extends StandardSchema>(schema: S): BooleanMatch<unknown, StandardSchema.InferInput<S>, "value">;
+/**
+ * 旧 context 接线还会调用这一个内部 helper。它不再接受 Zod-style fallback；新的公共 matches()
+ * 使用上面的严格 Standard Schema 入口，异常则由 evaluator 作为 defect 处理。
+ */
+export declare function validateSchema(value: unknown, schema: unknown): Promise<boolean>;
+export declare function satisfies<T, R extends T>(label: string, predicate: (value: T) => value is R): BooleanMatch<T, R>;
+export declare function satisfies<T>(label: string, predicate: (value: T) => boolean | Promise<boolean>): BooleanMatch<T, T>;
+export declare function defineValueMatch<T, R extends T>(spec: {
+    readonly name: string;
+    readonly evaluate: (value: T) => value is R;
+}): BooleanMatch<T, R>;
+export declare function defineValueMatch<T>(spec: {
+    readonly name: string;
+    readonly evaluate: (value: T) => boolean | Promise<boolean>;
+}): BooleanMatch<T, T>;
+export declare function defineScoreMatch<T>(spec: {
+    readonly name: string;
+    readonly score: (value: T) => number | Promise<number>;
+}): ScoreMatch<T>;
+export declare function referencesAnyPath(paths: readonly [string, ...string[]]): BooleanMatch<JsonValue, JsonValue, "value">;
+export type ToolStatus = Extract<LogicalToolOccurrence["lifecycle"], {
+    readonly state: "available";
+}>["status"];
+export interface CommandMatchOptions {
+    readonly argsStart?: readonly string[];
+    readonly excludes?: readonly string[];
+    readonly status?: ToolStatus;
+}
+export interface ToolMatchOptions {
+    readonly input?: BooleanMatch<JsonValue, JsonValue, "value">;
+    readonly output?: BooleanMatch<JsonValue, JsonValue, "value">;
+    readonly status?: ToolStatus;
+}
+/**
+ * Turns the recursive JsonMatch language into a managed value Match.  Raw
+ * JsonMatch stays at this explicit bridge; tool assertions consume only the
+ * branded Match so every tool field follows the same evaluator path.
+ */
+export declare function jsonMatch(expected: JsonMatch): BooleanMatch<JsonValue, JsonValue, "value">;
+export declare function toolMatch(name: string, options?: ToolMatchOptions): ToolMatch;
+export declare function toolMatch(options: ToolMatchOptions): ToolMatch;
+/** @internal Assert-first accepts only branded tool-domain matches. */
+export declare function assertManagedToolMatch(value: unknown, label?: string): ToolMatch;
+/** @internal Assert-first accepts only branded event-domain matches. */
+export declare function assertManagedEventMatch(value: unknown, label?: string): EventMatch;
+export type ToolMatchQuantifier = {
+    readonly kind: "at-least";
+    readonly count: number;
+} | {
+    readonly kind: "exact";
+    readonly count: number;
+} | {
+    readonly kind: "absent";
+};
+export interface ToolMatchCollectionOptions {
+    readonly quantifier: ToolMatchQuantifier;
+    /** Scope-level action coverage that can hide additional candidates. */
+    readonly coverageReason?: string;
+}
+/**
+ * The sole collection evaluator for scoped tool Assertions. It evaluates each
+ * occurrence through ToolMatch, then folds exact / at-least / absent with the
+ * same three-valued rule: a definite counterexample wins; incomplete evidence
+ * cannot manufacture a positive count or an absence proof.
+ */
+export declare function evaluateToolMatchCollection(match: ToolMatch, occurrences: readonly LogicalToolOccurrence[], options: ToolMatchCollectionOptions): Promise<BooleanMatchEvaluation<LogicalToolOccurrence | undefined>>;
+export declare function commandMatch(executable: string, options?: CommandMatchOptions): ToolMatch<LogicalCommandOccurrence>;
+export interface EventOptionsByType {
+    readonly message: {
+        readonly role?: "assistant" | "user";
+        readonly text?: BooleanMatch<string, string, "value">;
+    };
+    readonly "operation.started": {
+        readonly tool?: ToolMatch;
+    };
+    readonly "operation.finished": {
+        readonly tool?: ToolMatch;
+    };
+}
+export declare function eventMatch<K extends keyof EventOptionsByType>(type: K, options?: EventOptionsByType[K]): EventMatch<Extract<AssertionEvent, {
+    readonly type: K;
+}>>;
+export {};

package/dist/assertions/match.js

@@ -0,0 +1,82 @@
+import { createRequire as __niceevalCreateRequire } from "node:module";
+const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
+const __niceevalCanonical = __niceevalRequire("./match.cjs");
+const __niceevalExport0 = __niceevalCanonical["and"];
+export { __niceevalExport0 as and };
+const __niceevalExport1 = __niceevalCanonical["assertManagedEventMatch"];
+export { __niceevalExport1 as assertManagedEventMatch };
+const __niceevalExport2 = __niceevalCanonical["assertManagedToolMatch"];
+export { __niceevalExport2 as assertManagedToolMatch };
+const __niceevalExport3 = __niceevalCanonical["assertManagedValueMatch"];
+export { __niceevalExport3 as assertManagedValueMatch };
+const __niceevalExport4 = __niceevalCanonical["assertionEventOccurrence"];
+export { __niceevalExport4 as assertionEventOccurrence };
+const __niceevalExport5 = __niceevalCanonical["commandMatch"];
+export { __niceevalExport5 as commandMatch };
+const __niceevalExport6 = __niceevalCanonical["commandSucceeded"];
+export { __niceevalExport6 as commandSucceeded };
+const __niceevalExport7 = __niceevalCanonical["deepEqual"];
+export { __niceevalExport7 as deepEqual };
+const __niceevalExport8 = __niceevalCanonical["defineScoreMatch"];
+export { __niceevalExport8 as defineScoreMatch };
+const __niceevalExport9 = __niceevalCanonical["defineValueMatch"];
+export { __niceevalExport9 as defineValueMatch };
+const __niceevalExport10 = __niceevalCanonical["equals"];
+export { __niceevalExport10 as equals };
+const __niceevalExport11 = __niceevalCanonical["evaluateBooleanMatch"];
+export { __niceevalExport11 as evaluateBooleanMatch };
+const __niceevalExport12 = __niceevalCanonical["evaluateScoreMatch"];
+export { __niceevalExport12 as evaluateScoreMatch };
+const __niceevalExport13 = __niceevalCanonical["evaluateToolMatchCollection"];
+export { __niceevalExport13 as evaluateToolMatchCollection };
+const __niceevalExport14 = __niceevalCanonical["eventMatch"];
+export { __niceevalExport14 as eventMatch };
+const __niceevalExport15 = __niceevalCanonical["excludes"];
+export { __niceevalExport15 as excludes };
+const __niceevalExport16 = __niceevalCanonical["hasSections"];
+export { __niceevalExport16 as hasSections };
+const __niceevalExport17 = __niceevalCanonical["includes"];
+export { __niceevalExport17 as includes };
+const __niceevalExport18 = __niceevalCanonical["includesUrl"];
+export { __niceevalExport18 as includesUrl };
+const __niceevalExport19 = __niceevalCanonical["isDefined"];
+export { __niceevalExport19 as isDefined };
+const __niceevalExport20 = __niceevalCanonical["isFalse"];
+export { __niceevalExport20 as isFalse };
+const __niceevalExport21 = __niceevalCanonical["isManagedMatch"];
+export { __niceevalExport21 as isManagedMatch };
+const __niceevalExport22 = __niceevalCanonical["isManagedThresholdedScoreMatch"];
+export { __niceevalExport22 as isManagedThresholdedScoreMatch };
+const __niceevalExport23 = __niceevalCanonical["isTrue"];
+export { __niceevalExport23 as isTrue };
+const __niceevalExport24 = __niceevalCanonical["jsonMatch"];
+export { __niceevalExport24 as jsonMatch };
+const __niceevalExport25 = __niceevalCanonical["looksLikeMatch"];
+export { __niceevalExport25 as looksLikeMatch };
+const __niceevalExport26 = __niceevalCanonical["looksLikeThresholdedScoreMatch"];
+export { __niceevalExport26 as looksLikeThresholdedScoreMatch };
+const __niceevalExport27 = __niceevalCanonical["makeAssertionMessageEvent"];
+export { __niceevalExport27 as makeAssertionMessageEvent };
+const __niceevalExport28 = __niceevalCanonical["makeAssertionToolEvent"];
+export { __niceevalExport28 as makeAssertionToolEvent };
+const __niceevalExport29 = __niceevalCanonical["matches"];
+export { __niceevalExport29 as matches };
+const __niceevalExport30 = __niceevalCanonical["not"];
+export { __niceevalExport30 as not };
+const __niceevalExport31 = __niceevalCanonical["or"];
+export { __niceevalExport31 as or };
+const __niceevalExport32 = __niceevalCanonical["pattern"];
+export { __niceevalExport32 as pattern };
+const __niceevalExport33 = __niceevalCanonical["referencesAnyPath"];
+export { __niceevalExport33 as referencesAnyPath };
+const __niceevalExport34 = __niceevalCanonical["satisfies"];
+export { __niceevalExport34 as satisfies };
+const __niceevalExport35 = __niceevalCanonical["similarity"];
+export { __niceevalExport35 as similarity };
+const __niceevalExport36 = __niceevalCanonical["thresholdedScoreMatchValue"];
+export { __niceevalExport36 as thresholdedScoreMatchValue };
+const __niceevalExport37 = __niceevalCanonical["toolMatch"];
+export { __niceevalExport37 as toolMatch };
+const __niceevalExport38 = __niceevalCanonical["validateSchema"];
+export { __niceevalExport38 as validateSchema };
+//# sourceMappingURL=match.js.map

package/dist/assertions/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sources":[],"names":[],"mappings":""}