niceeval 0.12.2-canary.31 → 0.13.0

package/dist/o11y/record/validation.d.mts

@@ -1,4 +1,4 @@
-import { type AttemptObservabilityFamilySchemaIdV1, type AttemptReferenceTargetV1, type AttemptReferencesForFamilyV1, type ObservabilityEntityIdV1, type ObservabilityOwnerV1, type ObservabilityReferenceTargetV1, type RunObservabilityFamilySchemaIdV1, type RunReferenceTargetV1, type RunReferencesForFamilyV1 } from "./model.mjs";
+import { type AttemptObservabilityFamilySchemaId, type AttemptReferenceTarget, type AttemptReferencesForFamily, type ObservabilityEntityId, type ObservabilityOwner, type ObservabilityReferenceTarget, type RunObservabilityFamilySchemaId, type RunReferenceTarget, type RunReferencesForFamily } from "./model.mjs";
 import { type ObservabilityRecordContractError } from "./errors.mjs";
 declare const observabilityFamilyValidationTypeId: unique symbol;
 /**
@@ -6,57 +6,57 @@ declare const observabilityFamilyValidationTypeId: unique symbol;
  * Payloads remain in their owning family; this proof carries only entity and
  * direct-reference facts needed by the whole-Run contract.
  */
-export interface ObservabilityFamilyValidationV1<Owner extends ObservabilityOwnerV1> {
+export interface ObservabilityFamilyValidation<Owner extends ObservabilityOwner> {
     readonly [observabilityFamilyValidationTypeId]: () => Owner;
 }
-export interface AttemptReferenceSourceV1<Family extends AttemptObservabilityFamilySchemaIdV1> {
-    readonly sourceId: ObservabilityEntityIdV1;
-    readonly refs: readonly AttemptReferencesForFamilyV1<Family>[];
+export interface AttemptReferenceSource<Family extends AttemptObservabilityFamilySchemaId> {
+    readonly sourceId: ObservabilityEntityId;
+    readonly refs: readonly AttemptReferencesForFamily<Family>[];
 }
-export interface RunReferenceSourceV1<Family extends RunObservabilityFamilySchemaIdV1> {
-    readonly sourceId: ObservabilityEntityIdV1;
-    readonly refs: readonly RunReferencesForFamilyV1<Family>[];
+export interface RunReferenceSource<Family extends RunObservabilityFamilySchemaId> {
+    readonly sourceId: ObservabilityEntityId;
+    readonly refs: readonly RunReferencesForFamily<Family>[];
 }
-export interface AttemptObservabilityFamilyValidationInputV1<Family extends AttemptObservabilityFamilySchemaIdV1> {
+export interface AttemptObservabilityFamilyValidationInput<Family extends AttemptObservabilityFamilySchemaId> {
     readonly schemaId: Family;
-    readonly entities: readonly AttemptReferenceTargetV1[];
-    readonly references: readonly AttemptReferenceSourceV1<Family>[];
+    readonly entities: readonly AttemptReferenceTarget[];
+    readonly references: readonly AttemptReferenceSource<Family>[];
     /** Family-local timing/source-frame errors use the stable aggregate union. */
     readonly localErrors?: readonly ObservabilityRecordContractError[];
 }
-export interface RunObservabilityFamilyValidationInputV1<Family extends RunObservabilityFamilySchemaIdV1> {
+export interface RunObservabilityFamilyValidationInput<Family extends RunObservabilityFamilySchemaId> {
     readonly schemaId: Family;
-    readonly entities: readonly RunReferenceTargetV1[];
-    readonly references: readonly RunReferenceSourceV1<Family>[];
+    readonly entities: readonly RunReferenceTarget[];
+    readonly references: readonly RunReferenceSource<Family>[];
     /** Family-local timing/source-frame errors use the stable aggregate union. */
     readonly localErrors?: readonly ObservabilityRecordContractError[];
 }
-export declare const REQUIRED_ATTEMPT_OBSERVABILITY_FAMILIES_V1: readonly ["niceeval.conversation/v1", "niceeval.commands/v1", "niceeval.usage/v1", "niceeval.timing/v1", "niceeval.diagnostics/v1"];
-export declare const REQUIRED_RUN_OBSERVABILITY_FAMILIES_V1: readonly ["niceeval.timing/v1", "niceeval.diagnostics/v1"];
-export declare function compareObservabilityFamilySchemaIdV1(left: string, right: string): number;
-export declare function compareObservabilityEntityTargetV1(left: ObservabilityReferenceTargetV1, right: ObservabilityReferenceTargetV1): number;
+export declare const REQUIRED_ATTEMPT_OBSERVABILITY_FAMILIES: readonly ["niceeval.observability", "niceeval.observability", "niceeval.observability", "niceeval.observability", "niceeval.observability"];
+export declare const REQUIRED_RUN_OBSERVABILITY_FAMILIES: readonly ["niceeval.observability", "niceeval.observability"];
+export declare function compareObservabilityFamilySchemaId(left: string, right: string): number;
+export declare function compareObservabilityEntityTarget(left: ObservabilityReferenceTarget, right: ObservabilityReferenceTarget): number;
 /** A pure convenience for family encoders that need a canonical entity order. */
-export declare function sortObservabilityEntityTargetsV1(targets: readonly ObservabilityReferenceTargetV1[]): readonly ObservabilityReferenceTargetV1[];
-export declare function compareObservabilityRecordContractErrorV1(left: ObservabilityRecordContractError, right: ObservabilityRecordContractError): number;
-export declare function sortObservabilityRecordContractErrorsV1(errors: readonly ObservabilityRecordContractError[]): readonly ObservabilityRecordContractError[];
-export declare function validateAttemptObservabilityFamilyV1<Family extends AttemptObservabilityFamilySchemaIdV1>(input: AttemptObservabilityFamilyValidationInputV1<Family>): readonly ObservabilityRecordContractError[];
-export declare function validateRunObservabilityFamilyV1<Family extends RunObservabilityFamilySchemaIdV1>(input: RunObservabilityFamilyValidationInputV1<Family>): readonly ObservabilityRecordContractError[];
-export declare function makeAttemptObservabilityFamilyValidationV1<Family extends AttemptObservabilityFamilySchemaIdV1>(input: AttemptObservabilityFamilyValidationInputV1<Family>): ObservabilityFamilyValidationV1<"attempt">;
-export declare function makeRunObservabilityFamilyValidationV1<Family extends RunObservabilityFamilySchemaIdV1>(input: RunObservabilityFamilyValidationInputV1<Family>): ObservabilityFamilyValidationV1<"run">;
-export interface AttemptObservabilityContractInputV1 {
-    readonly families: readonly ObservabilityFamilyValidationV1<"attempt">[];
-}
-export interface RunObservabilityContractInputV1 {
-    readonly families: readonly ObservabilityFamilyValidationV1<"run">[];
-}
-export interface ObservabilityRecordContractValidationInputV1 {
-    readonly run: RunObservabilityContractInputV1;
-    readonly attempts: readonly AttemptObservabilityContractInputV1[];
+export declare function sortObservabilityEntityTargets(targets: readonly ObservabilityReferenceTarget[]): readonly ObservabilityReferenceTarget[];
+export declare function compareObservabilityRecordContractError(left: ObservabilityRecordContractError, right: ObservabilityRecordContractError): number;
+export declare function sortObservabilityRecordContractErrors(errors: readonly ObservabilityRecordContractError[]): readonly ObservabilityRecordContractError[];
+export declare function validateAttemptObservabilityFamily<Family extends AttemptObservabilityFamilySchemaId>(input: AttemptObservabilityFamilyValidationInput<Family>): readonly ObservabilityRecordContractError[];
+export declare function validateRunObservabilityFamily<Family extends RunObservabilityFamilySchemaId>(input: RunObservabilityFamilyValidationInput<Family>): readonly ObservabilityRecordContractError[];
+export declare function makeAttemptObservabilityFamilyValidation<Family extends AttemptObservabilityFamilySchemaId>(input: AttemptObservabilityFamilyValidationInput<Family>): ObservabilityFamilyValidation<"attempt">;
+export declare function makeRunObservabilityFamilyValidation<Family extends RunObservabilityFamilySchemaId>(input: RunObservabilityFamilyValidationInput<Family>): ObservabilityFamilyValidation<"run">;
+export interface AttemptObservabilityContractInput {
+    readonly families: readonly ObservabilityFamilyValidation<"attempt">[];
+}
+export interface RunObservabilityContractInput {
+    readonly families: readonly ObservabilityFamilyValidation<"run">[];
+}
+export interface ObservabilityRecordContractValidationInput {
+    readonly run: RunObservabilityContractInput;
+    readonly attempts: readonly AttemptObservabilityContractInput[];
 }
 /**
  * Pure aggregate preflight for the official five Attempt and two Run families.
  * It validates only durable official facts; opening a writer, emitting blobs,
  * and publishing the complete marker remain Record's separate responsibilities.
  */
-export declare function validateObservabilityRecordContractV1(input: ObservabilityRecordContractValidationInputV1): readonly ObservabilityRecordContractError[];
+export declare function validateObservabilityRecordContract(input: ObservabilityRecordContractValidationInput): readonly ObservabilityRecordContractError[];
 export {};

package/dist/o11y/record/validation.d.ts

@@ -1,4 +1,4 @@
-import { type AttemptObservabilityFamilySchemaIdV1, type AttemptReferenceTargetV1, type AttemptReferencesForFamilyV1, type ObservabilityEntityIdV1, type ObservabilityOwnerV1, type ObservabilityReferenceTargetV1, type RunObservabilityFamilySchemaIdV1, type RunReferenceTargetV1, type RunReferencesForFamilyV1 } from "./model.js";
+import { type AttemptObservabilityFamilySchemaId, type AttemptReferenceTarget, type AttemptReferencesForFamily, type ObservabilityEntityId, type ObservabilityOwner, type ObservabilityReferenceTarget, type RunObservabilityFamilySchemaId, type RunReferenceTarget, type RunReferencesForFamily } from "./model.js";
 import { type ObservabilityRecordContractError } from "./errors.js";
 declare const observabilityFamilyValidationTypeId: unique symbol;
 /**
@@ -6,57 +6,57 @@ declare const observabilityFamilyValidationTypeId: unique symbol;
  * Payloads remain in their owning family; this proof carries only entity and
  * direct-reference facts needed by the whole-Run contract.
  */
-export interface ObservabilityFamilyValidationV1<Owner extends ObservabilityOwnerV1> {
+export interface ObservabilityFamilyValidation<Owner extends ObservabilityOwner> {
     readonly [observabilityFamilyValidationTypeId]: () => Owner;
 }
-export interface AttemptReferenceSourceV1<Family extends AttemptObservabilityFamilySchemaIdV1> {
-    readonly sourceId: ObservabilityEntityIdV1;
-    readonly refs: readonly AttemptReferencesForFamilyV1<Family>[];
+export interface AttemptReferenceSource<Family extends AttemptObservabilityFamilySchemaId> {
+    readonly sourceId: ObservabilityEntityId;
+    readonly refs: readonly AttemptReferencesForFamily<Family>[];
 }
-export interface RunReferenceSourceV1<Family extends RunObservabilityFamilySchemaIdV1> {
-    readonly sourceId: ObservabilityEntityIdV1;
-    readonly refs: readonly RunReferencesForFamilyV1<Family>[];
+export interface RunReferenceSource<Family extends RunObservabilityFamilySchemaId> {
+    readonly sourceId: ObservabilityEntityId;
+    readonly refs: readonly RunReferencesForFamily<Family>[];
 }
-export interface AttemptObservabilityFamilyValidationInputV1<Family extends AttemptObservabilityFamilySchemaIdV1> {
+export interface AttemptObservabilityFamilyValidationInput<Family extends AttemptObservabilityFamilySchemaId> {
     readonly schemaId: Family;
-    readonly entities: readonly AttemptReferenceTargetV1[];
-    readonly references: readonly AttemptReferenceSourceV1<Family>[];
+    readonly entities: readonly AttemptReferenceTarget[];
+    readonly references: readonly AttemptReferenceSource<Family>[];
     /** Family-local timing/source-frame errors use the stable aggregate union. */
     readonly localErrors?: readonly ObservabilityRecordContractError[];
 }
-export interface RunObservabilityFamilyValidationInputV1<Family extends RunObservabilityFamilySchemaIdV1> {
+export interface RunObservabilityFamilyValidationInput<Family extends RunObservabilityFamilySchemaId> {
     readonly schemaId: Family;
-    readonly entities: readonly RunReferenceTargetV1[];
-    readonly references: readonly RunReferenceSourceV1<Family>[];
+    readonly entities: readonly RunReferenceTarget[];
+    readonly references: readonly RunReferenceSource<Family>[];
     /** Family-local timing/source-frame errors use the stable aggregate union. */
     readonly localErrors?: readonly ObservabilityRecordContractError[];
 }
-export declare const REQUIRED_ATTEMPT_OBSERVABILITY_FAMILIES_V1: readonly ["niceeval.conversation/v1", "niceeval.commands/v1", "niceeval.usage/v1", "niceeval.timing/v1", "niceeval.diagnostics/v1"];
-export declare const REQUIRED_RUN_OBSERVABILITY_FAMILIES_V1: readonly ["niceeval.timing/v1", "niceeval.diagnostics/v1"];
-export declare function compareObservabilityFamilySchemaIdV1(left: string, right: string): number;
-export declare function compareObservabilityEntityTargetV1(left: ObservabilityReferenceTargetV1, right: ObservabilityReferenceTargetV1): number;
+export declare const REQUIRED_ATTEMPT_OBSERVABILITY_FAMILIES: readonly ["niceeval.observability", "niceeval.observability", "niceeval.observability", "niceeval.observability", "niceeval.observability"];
+export declare const REQUIRED_RUN_OBSERVABILITY_FAMILIES: readonly ["niceeval.observability", "niceeval.observability"];
+export declare function compareObservabilityFamilySchemaId(left: string, right: string): number;
+export declare function compareObservabilityEntityTarget(left: ObservabilityReferenceTarget, right: ObservabilityReferenceTarget): number;
 /** A pure convenience for family encoders that need a canonical entity order. */
-export declare function sortObservabilityEntityTargetsV1(targets: readonly ObservabilityReferenceTargetV1[]): readonly ObservabilityReferenceTargetV1[];
-export declare function compareObservabilityRecordContractErrorV1(left: ObservabilityRecordContractError, right: ObservabilityRecordContractError): number;
-export declare function sortObservabilityRecordContractErrorsV1(errors: readonly ObservabilityRecordContractError[]): readonly ObservabilityRecordContractError[];
-export declare function validateAttemptObservabilityFamilyV1<Family extends AttemptObservabilityFamilySchemaIdV1>(input: AttemptObservabilityFamilyValidationInputV1<Family>): readonly ObservabilityRecordContractError[];
-export declare function validateRunObservabilityFamilyV1<Family extends RunObservabilityFamilySchemaIdV1>(input: RunObservabilityFamilyValidationInputV1<Family>): readonly ObservabilityRecordContractError[];
-export declare function makeAttemptObservabilityFamilyValidationV1<Family extends AttemptObservabilityFamilySchemaIdV1>(input: AttemptObservabilityFamilyValidationInputV1<Family>): ObservabilityFamilyValidationV1<"attempt">;
-export declare function makeRunObservabilityFamilyValidationV1<Family extends RunObservabilityFamilySchemaIdV1>(input: RunObservabilityFamilyValidationInputV1<Family>): ObservabilityFamilyValidationV1<"run">;
-export interface AttemptObservabilityContractInputV1 {
-    readonly families: readonly ObservabilityFamilyValidationV1<"attempt">[];
-}
-export interface RunObservabilityContractInputV1 {
-    readonly families: readonly ObservabilityFamilyValidationV1<"run">[];
-}
-export interface ObservabilityRecordContractValidationInputV1 {
-    readonly run: RunObservabilityContractInputV1;
-    readonly attempts: readonly AttemptObservabilityContractInputV1[];
+export declare function sortObservabilityEntityTargets(targets: readonly ObservabilityReferenceTarget[]): readonly ObservabilityReferenceTarget[];
+export declare function compareObservabilityRecordContractError(left: ObservabilityRecordContractError, right: ObservabilityRecordContractError): number;
+export declare function sortObservabilityRecordContractErrors(errors: readonly ObservabilityRecordContractError[]): readonly ObservabilityRecordContractError[];
+export declare function validateAttemptObservabilityFamily<Family extends AttemptObservabilityFamilySchemaId>(input: AttemptObservabilityFamilyValidationInput<Family>): readonly ObservabilityRecordContractError[];
+export declare function validateRunObservabilityFamily<Family extends RunObservabilityFamilySchemaId>(input: RunObservabilityFamilyValidationInput<Family>): readonly ObservabilityRecordContractError[];
+export declare function makeAttemptObservabilityFamilyValidation<Family extends AttemptObservabilityFamilySchemaId>(input: AttemptObservabilityFamilyValidationInput<Family>): ObservabilityFamilyValidation<"attempt">;
+export declare function makeRunObservabilityFamilyValidation<Family extends RunObservabilityFamilySchemaId>(input: RunObservabilityFamilyValidationInput<Family>): ObservabilityFamilyValidation<"run">;
+export interface AttemptObservabilityContractInput {
+    readonly families: readonly ObservabilityFamilyValidation<"attempt">[];
+}
+export interface RunObservabilityContractInput {
+    readonly families: readonly ObservabilityFamilyValidation<"run">[];
+}
+export interface ObservabilityRecordContractValidationInput {
+    readonly run: RunObservabilityContractInput;
+    readonly attempts: readonly AttemptObservabilityContractInput[];
 }
 /**
  * Pure aggregate preflight for the official five Attempt and two Run families.
  * It validates only durable official facts; opening a writer, emitting blobs,
  * and publishing the complete marker remain Record's separate responsibilities.
  */
-export declare function validateObservabilityRecordContractV1(input: ObservabilityRecordContractValidationInputV1): readonly ObservabilityRecordContractError[];
+export declare function validateObservabilityRecordContract(input: ObservabilityRecordContractValidationInput): readonly ObservabilityRecordContractError[];
 export {};

package/dist/o11y/record/validation.js

@@ -1,28 +1,28 @@
 import { createRequire as __niceevalCreateRequire } from "node:module";
 const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
 const __niceevalCanonical = __niceevalRequire("./validation.cjs");
-const __niceevalExport0 = __niceevalCanonical["REQUIRED_ATTEMPT_OBSERVABILITY_FAMILIES_V1"];
-export { __niceevalExport0 as REQUIRED_ATTEMPT_OBSERVABILITY_FAMILIES_V1 };
-const __niceevalExport1 = __niceevalCanonical["REQUIRED_RUN_OBSERVABILITY_FAMILIES_V1"];
-export { __niceevalExport1 as REQUIRED_RUN_OBSERVABILITY_FAMILIES_V1 };
-const __niceevalExport2 = __niceevalCanonical["compareObservabilityEntityTargetV1"];
-export { __niceevalExport2 as compareObservabilityEntityTargetV1 };
-const __niceevalExport3 = __niceevalCanonical["compareObservabilityFamilySchemaIdV1"];
-export { __niceevalExport3 as compareObservabilityFamilySchemaIdV1 };
-const __niceevalExport4 = __niceevalCanonical["compareObservabilityRecordContractErrorV1"];
-export { __niceevalExport4 as compareObservabilityRecordContractErrorV1 };
-const __niceevalExport5 = __niceevalCanonical["makeAttemptObservabilityFamilyValidationV1"];
-export { __niceevalExport5 as makeAttemptObservabilityFamilyValidationV1 };
-const __niceevalExport6 = __niceevalCanonical["makeRunObservabilityFamilyValidationV1"];
-export { __niceevalExport6 as makeRunObservabilityFamilyValidationV1 };
-const __niceevalExport7 = __niceevalCanonical["sortObservabilityEntityTargetsV1"];
-export { __niceevalExport7 as sortObservabilityEntityTargetsV1 };
-const __niceevalExport8 = __niceevalCanonical["sortObservabilityRecordContractErrorsV1"];
-export { __niceevalExport8 as sortObservabilityRecordContractErrorsV1 };
-const __niceevalExport9 = __niceevalCanonical["validateAttemptObservabilityFamilyV1"];
-export { __niceevalExport9 as validateAttemptObservabilityFamilyV1 };
-const __niceevalExport10 = __niceevalCanonical["validateObservabilityRecordContractV1"];
-export { __niceevalExport10 as validateObservabilityRecordContractV1 };
-const __niceevalExport11 = __niceevalCanonical["validateRunObservabilityFamilyV1"];
-export { __niceevalExport11 as validateRunObservabilityFamilyV1 };
+const __niceevalExport0 = __niceevalCanonical["REQUIRED_ATTEMPT_OBSERVABILITY_FAMILIES"];
+export { __niceevalExport0 as REQUIRED_ATTEMPT_OBSERVABILITY_FAMILIES };
+const __niceevalExport1 = __niceevalCanonical["REQUIRED_RUN_OBSERVABILITY_FAMILIES"];
+export { __niceevalExport1 as REQUIRED_RUN_OBSERVABILITY_FAMILIES };
+const __niceevalExport2 = __niceevalCanonical["compareObservabilityEntityTarget"];
+export { __niceevalExport2 as compareObservabilityEntityTarget };
+const __niceevalExport3 = __niceevalCanonical["compareObservabilityFamilySchemaId"];
+export { __niceevalExport3 as compareObservabilityFamilySchemaId };
+const __niceevalExport4 = __niceevalCanonical["compareObservabilityRecordContractError"];
+export { __niceevalExport4 as compareObservabilityRecordContractError };
+const __niceevalExport5 = __niceevalCanonical["makeAttemptObservabilityFamilyValidation"];
+export { __niceevalExport5 as makeAttemptObservabilityFamilyValidation };
+const __niceevalExport6 = __niceevalCanonical["makeRunObservabilityFamilyValidation"];
+export { __niceevalExport6 as makeRunObservabilityFamilyValidation };
+const __niceevalExport7 = __niceevalCanonical["sortObservabilityEntityTargets"];
+export { __niceevalExport7 as sortObservabilityEntityTargets };
+const __niceevalExport8 = __niceevalCanonical["sortObservabilityRecordContractErrors"];
+export { __niceevalExport8 as sortObservabilityRecordContractErrors };
+const __niceevalExport9 = __niceevalCanonical["validateAttemptObservabilityFamily"];
+export { __niceevalExport9 as validateAttemptObservabilityFamily };
+const __niceevalExport10 = __niceevalCanonical["validateObservabilityRecordContract"];
+export { __niceevalExport10 as validateObservabilityRecordContract };
+const __niceevalExport11 = __niceevalCanonical["validateRunObservabilityFamily"];
+export { __niceevalExport11 as validateRunObservabilityFamily };
 //# sourceMappingURL=validation.js.map

package/dist/o11y/types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"","sourcesContent":["// o11y 域类型:标准事件流(StreamEvent)、折叠事实(DerivedFacts)、\n// OTLP trace(TraceSpan / SpanKind)与用量 / 摘要。\nimport type { JsonValue, SourceLoc } from \"../shared/types.ts\";\n/**\n * 一次运行的 token 用量(沙箱型从 transcript/OTel span 的 `gen_ai.usage.*` 属性抠,remote 由\n * send 的 `Turn.usage` 直接返回)。每个字段只在协议真实提供该值时存在——原始协议没有 usage 时\n * 省略,不编造数值;不存在「默认 0」或「默认 1」的字段。三个输入侧桶恒互斥:相加才是送进模型的\n * 完整上下文量;把协议原生口径归一到互斥是 adapter 的落值义务——OpenAI 系报「含缓存的输入总量 +\n * 缓存命中子集」,落 inputTokens 前先扣掉子集(docs/feature/record/architecture.md#usage,\n * 各协议明细见 docs/feature/adapters/sdk/<name>/cost.md)。\n */\nexport interface Usage {\n    /** 未命中缓存、按全价计费的输入 token;与两个 cache 桶互斥。 */\n    inputTokens?: number;\n    /** 输出(completion)token 数。 */\n    outputTokens?: number;\n    /** 从提示缓存命中的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。 */\n    cacheReadTokens?: number;\n    /** 写入提示缓存的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。 */\n    cacheCreationTokens?: number;\n    /** 推理(thinking)token 数,outputTokens 的已含明细,单列展示用;只在协议真实提供时存在。 */\n    reasoningTokens?: number;\n    /** 真实发生的模型请求数。协议不提供请求计数就省略,绝不写 1 凑数。 */\n    requests?: number;\n    /**\n     * 网关/adapter 实测的真实美元成本(只能由 `Turn.usage.costUSD` 显式带回,从不从\n     * token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个事实:\n     * 存在时优先于按价格表(`defineConfig({ pricing })`)估算的成本——见 `estimateCost` 的\n     * `usage.costUSD ?? estimateCost(...)` 兜底顺序。\n     */\n    costUSD?: number;\n}\n/** 跨 agent 归一化后的规范工具名。 */\nexport type ToolName = \"file_read\" | \"file_write\" | \"file_edit\" | \"shell\" | \"web_fetch\" | \"web_search\" | \"glob\" | \"grep\" | \"list_dir\" | \"agent_task\" | \"unknown\";\n/** Adapter 确认原始 command 不能安全还原为 argv 的原因。 */\nexport type OriginalCommandOpaqueReason = \"redacted\" | \"truncated\" | \"compound-shell\" | \"dynamic-shell\" | \"unsupported-protocol\";\n/** Adapter 已确认的原始 command invocation；token 保留原生执行边界的形状。 */\nexport type OriginalCommandInvocation = {\n    readonly state: \"available\";\n    readonly executable: string;\n    readonly args: readonly string[];\n} | {\n    readonly state: \"opaque\";\n    readonly reason: OriginalCommandOpaqueReason;\n};\n/** Observation Protocol 唯一的 logical-command normalizer profile。 */\nexport type LogicalCommandNormalizer = \"logical-command/v1\";\n/** 可供 command matcher 消费的、已经归一的逻辑 invocation。 */\nexport type LogicalCommandInvocation = {\n    readonly state: \"available\";\n    readonly executable: string;\n    readonly args: readonly string[];\n    readonly normalizer: LogicalCommandNormalizer;\n    readonly normalization: \"identity\" | \"pnpm-exec\" | \"npx\";\n} | {\n    readonly state: \"opaque\";\n    readonly normalizer: LogicalCommandNormalizer;\n    readonly reason: \"original-opaque\";\n    readonly originalReason: OriginalCommandOpaqueReason;\n} | {\n    readonly state: \"opaque\";\n    readonly normalizer: LogicalCommandNormalizer;\n    readonly reason: \"unsupported-wrapper-form\" | \"ambiguous-wrapper-target\" | \"multiple-executions\";\n};\n/** 一笔 tool operation 的穷尽 command 分类；不从 tool name 或 input 推导。 */\nexport type CommandProjection = {\n    readonly kind: \"not-command\";\n} | {\n    readonly kind: \"command\";\n    readonly original: OriginalCommandInvocation;\n    readonly logical: LogicalCommandInvocation;\n};\n/** 一条 Agent session 内的稳定事件位置。 */\nexport interface EventPosition {\n    readonly turnOrdinal: number;\n    readonly eventOrdinal: number;\n}\n/** 单笔 tool occurrence 的可用 lifecycle 证据。 */\nexport type LogicalToolLifecycle = {\n    readonly state: \"available\";\n    readonly status: \"pending\";\n} | {\n    readonly state: \"available\";\n    readonly status: \"completed\" | \"failed\" | \"rejected\";\n    readonly finish: EventPosition;\n} | {\n    readonly state: \"opaque\";\n    readonly reason: \"partial-stream\" | \"missing-lifecycle-evidence\";\n};\n/**\n * A tool field is independently observable.  Input and output deliberately\n * use the same envelope so a matcher only becomes uncertain when it actually\n * asks for the field whose material is incomplete.\n */\nexport type LogicalToolEvidence = {\n    readonly state: \"complete\";\n    readonly value: JsonValue;\n} | {\n    readonly state: \"partial\";\n    readonly value: JsonValue;\n    readonly opaquePointers: readonly string[];\n    readonly reason: \"truncated\" | \"redacted\";\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: string;\n};\n/** Fact matcher 消费的一笔、按 started/finished 关联后的 tool operation。 */\nexport interface LogicalToolOccurrence {\n    /** 由 session、turn 与 started event position 组成的 occurrence identity；不是 operationId。 */\n    readonly id: string;\n    readonly session: string;\n    readonly turn: string;\n    readonly name: {\n        readonly original: string;\n        readonly canonical?: ToolName;\n    };\n    readonly input: LogicalToolEvidence;\n    /**\n     * A completed lifecycle alone does not prove that output was collected.\n     * Missing, pending, and orphan output are explicit unavailable evidence.\n     */\n    readonly output: LogicalToolEvidence;\n    /**\n     * 旧 Adapter 尚未升级时允许缺失，调用方必须把它视作 command evidence unavailable，\n     * 不能回退为 not-command。新 Adapter 对每笔 tool operation 都必须提供分类。\n     */\n    readonly command?: CommandProjection;\n    readonly start: EventPosition;\n    readonly lifecycle: LogicalToolLifecycle;\n}\n/** `operation.finished` 找不到可信 started 时留下的协议诊断输入，不构造 occurrence。 */\nexport interface OrphanToolOperationFinish {\n    readonly session: string;\n    readonly turn: string;\n    readonly operationId: string;\n    readonly status: \"completed\" | \"failed\" | \"rejected\";\n    readonly position: EventPosition;\n}\n/** `deriveLogicalToolOccurrences` 的 scope 与可信 Turn outcome。 */\nexport interface LogicalToolOccurrenceDeriveOptions {\n    readonly session: string;\n    readonly turn: string;\n    readonly turnOrdinal: number;\n    /** events[0] 对应的 event ordinal；完整 Turn.events 默认从 core user message 的 0 开始。 */\n    readonly firstEventOrdinal?: number;\n    /** 没有可信 Outcome 时保持省略，未关闭 operation 因而只能是 partial-stream。 */\n    readonly outcome?: \"completed\" | \"failed\" | \"waiting\";\n}\n/** One immutable Turn segment in a scope projection. */\nexport interface LogicalToolOccurrenceScopeTurn {\n    readonly session: string;\n    readonly turn: string;\n    readonly turnOrdinal: number;\n    readonly events: readonly StreamEvent[];\n    /** The scope's latest Turn controls whether an unclosed call is pending. */\n    readonly outcome?: \"completed\" | \"failed\" | \"waiting\";\n    readonly firstEventOrdinal?: number;\n}\n/** occurrence 投影与其不能成为匹配候选的 orphan finished。 */\nexport interface LogicalToolOccurrenceDerivation {\n    readonly occurrences: readonly LogicalToolOccurrence[];\n    readonly orphanFinishes: readonly OrphanToolOperationFinish[];\n}\n/** HITL 停轮请求的结构化描述,供 `t.requireInputRequest(filter)` / `t.respondAll` 按条件匹配。 */\nexport interface InputRequest {\n    /** 请求的唯一标识;多个请求并停时,`InputResponse.requestId` 靠它对位。 */\n    readonly id?: string;\n    /** 模型提出的原始问题/文本(用于 `stringMatches` 过滤)。 */\n    readonly prompt?: string;\n    /** adapter 自定义的人类可读展示文案,与 `prompt` 二选一或并存,用于 UI/日志展示及过滤匹配。 */\n    readonly display?: string;\n    /** 请求关联的动作类型(如某个待批准的工具调用名),供过滤用。 */\n    readonly action?: string;\n    /** 请求携带的结构化输入(如待批准命令的参数)。 */\n    readonly input?: JsonValue;\n    /** 若请求提供了预设选项(如批准/拒绝),逐项列出;`id` 对应 `InputResponse.optionId`。 */\n    readonly options?: readonly {\n        id: string;\n        label?: string;\n    }[];\n}\n/**\n * 落盘截断的结构化标记(见 docs/feature/record/architecture.md「大值截断」):\n * `path` 是被截断的位置(事件里是字段名,如 \"output\";span 里是 attribute key,如 \"output.value\"),\n * `originalBytes` 是截断前的 UTF-8 字节数。view 显示「输出过大,已截断」靠它,不正则匹配 marker。\n */\nexport interface Truncation {\n    path: string;\n    originalBytes: number;\n}\n/**\n * 标准事件流的词汇(对标 docs/feature/adapters/architecture/events.md)。adapter 唯一的硬活就是把\n * 各 agent 五花八门的原始 transcript 映射成 StreamEvent[];映射完,整套断言免费。\n * `truncated` 只由 results writer 在落盘时刻写入(运行时全量,落盘截断);adapter 不产出它。\n */\nexport type StreamEvent = {\n    truncated?: Truncation[];\n    /**\n     * Field paths intentionally withheld by the producing boundary.  Runtime\n     * matching sees the original event shape plus this evidence limitation;\n     * persistence can retain the same signal without replacing values with a\n     * magic string.\n     */\n    redacted?: readonly string[];\n} & (\n/** assistant 回复；它不是 eval 源码上的作者事实，不参与 sourceOrder 序列。 */\n{\n    type: \"message\";\n    role: \"assistant\";\n    text: string;\n    loc?: SourceLoc;\n}\n/**\n * eval 作者发出的用户输入；`loc` 把消息叠回源码，`sourceOrder` 与断言、直接给分共用同一条\n * attempt 级序列。历史事件可省略，当前 SessionManager 产出的 user message 必写。\n */\n | {\n    type: \"message\";\n    role: \"user\";\n    text: string;\n    loc?: SourceLoc;\n    sourceOrder?: number;\n}\n/** 发起一次工具或子 agent 操作；嵌套 `kind` 让两种 started 形状保持闭合。 */\n | {\n    type: \"operation.started\";\n    operationId: string;\n    operation: {\n        kind: \"tool\";\n        name: string;\n        input: JsonValue;\n        tool?: ToolName;\n        /**\n         * Adapter 对 command / not-command 的协议级分类。暂时可选以兼容尚未迁移的\n         * 第三方 Adapter；缺失不得在 core 侧由 name、input 或 shell text 补造。\n         */\n        command?: CommandProjection;\n    } | {\n        kind: \"subagent\";\n        name: string;\n        remoteUrl?: string;\n    };\n}\n/** 工具操作完成；人工拒绝只属于工具操作。 */\n | {\n    type: \"operation.finished\";\n    operationId: string;\n    kind: \"tool\";\n    output?: JsonValue;\n    status: \"completed\" | \"failed\" | \"rejected\";\n}\n/** 子 agent 操作完成；子 agent 没有人工拒绝状态。 */\n | {\n    type: \"operation.finished\";\n    operationId: string;\n    kind: \"subagent\";\n    output?: JsonValue;\n    status: \"completed\" | \"failed\";\n}\n/**\n * 一次 Skill 加载:一等事件,由 adapter 从原生协议里识别出「这是加载 Skill」并直接产出,\n * 不靠 renderer 按工具名/文本猜。`operationId` 仅当原生协议把 Skill 加载表达成可关联的工具调用时才有。\n */\n | {\n    type: \"skill.loaded\";\n    skill: string;\n    operationId?: string;\n}\n/** 模型停下来向人请求输入(HITL);具体请求内容见 InputRequest。 */\n | {\n    type: \"input.requested\";\n    request: InputRequest;\n}\n/** 模型的思考/推理文本(非最终回复)。 */\n | {\n    type: \"thinking\";\n    text: string;\n}\n/**\n * 被测系统内部注入的、不披着 `message` 外衣的上下文文本(如 Claude Code 的 SessionStart /\n * UserPromptSubmit hook 在下一轮开始前前置进模型上下文的文本)。只承载带实际文本内容的注入;\n * `source` 是可选的原始来源标记(如 hook 名),adapter 按各自协议原样透传,不强行归一到封闭枚举。\n */\n | {\n    type: \"context.injected\";\n    text: string;\n    source?: string;\n}\n/** 上下文被压缩/摘要(如超长会话截断历史);`reason` 是可选的压缩原因说明。 */\n | {\n    type: \"compaction\";\n    reason?: string;\n}\n/** 运行中出现的错误。 */\n | {\n    type: \"error\";\n    message: string;\n});\n/**\n * core 从事件流折叠出的结构化事实(deriveRunFacts)。折叠按 operationId 把 started 与 finished 对成一条\n * 调用:配上 finished 的取其状态;只有 started、尚未等到 finished 的调用状态是 `pending`——\n * HITL 停在审批上的调用就以这个状态被断言,不是容错分支(见 docs/feature/adapters/architecture/events.md)。\n */\nexport interface ToolCall {\n    operationId: string;\n    name: ToolName;\n    originalName?: string;\n    input: JsonValue;\n    output?: JsonValue;\n    status: \"pending\" | \"completed\" | \"failed\" | \"rejected\";\n}\nexport interface SubagentCall {\n    operationId: string;\n    name: string;\n    remoteUrl?: string;\n    output?: JsonValue;\n    /** 子 agent 委派没有 rejected 状态(operation.finished 只报 completed / failed)。 */\n    status: \"pending\" | \"completed\" | \"failed\";\n}\nexport interface DerivedFacts {\n    readonly toolCalls: readonly ToolCall[];\n    readonly subagentCalls: readonly SubagentCall[];\n    readonly inputRequests: readonly InputRequest[];\n    readonly parked: boolean;\n    readonly messageCount: number;\n    readonly compactions: number;\n    /** 事件流里 `context.injected` 事件的次数;只回答存在性问题,不替代逐条读取原文。 */\n    readonly contextInjections: number;\n}\n/**\n * span 的【语义角色】,从 OTel GenAI 语义约定的 gen_ai.operation.name 归一而来\n * (见 o11y/otlp/canonical.ts)。view 据此着色 / 分组 / 跨 agent 对比,**只认这个,\n * 不读原生 span 名**。未识别的 span 落 \"other\",view 折叠。\n */\nexport type SpanKind = \"turn\" | \"model\" | \"tool\" | \"agent\" | \"other\";\n/**\n * 一条分布式追踪的 span(从 agent 经 OpenTelemetry 导出的 OTLP traces 归一而来)。\n * 与 StreamEvent 不同:它带【时间】(起止 epoch 毫秒)与【父子】(parentSpanId),\n * 所以 view 能画成瀑布图。事件流回答「做了什么」,trace 回答「各花了多久、谁套谁」。\n *\n * 两层归一:线格式层(OTLP/JSON|protobuf → 本结构,见 otlp/parse.ts,通用);\n * 语义层(原生 span 名/属性 → canonical GenAI semconv,见 otlp/mappers/<agent>.ts,每 agent 一个薄 mapper)。\n */\nexport interface TraceSpan {\n    traceId: string;\n    spanId: string;\n    parentSpanId?: string;\n    name: string;\n    /** span 起点 / 终点(epoch 毫秒)。 */\n    startMs: number;\n    endMs: number;\n    status?: \"ok\" | \"error\" | \"unset\";\n    /**\n     * 归一后的语义角色(每-agent mapper 据 canonical GenAI semconv 定;view/select 只认它)。\n     * 未经 mapper 或未识别时为 undefined / \"other\"。\n     */\n    kind?: SpanKind;\n    /** OTLP span 属性(gen_ai.* / tool 名 / token 等),按 key 摊平。raw 属性始终保留供下钻。 */\n    attributes?: globalThis.Record<string, JsonValue>;\n    /** 落盘截断标记(只由 results writer 在序列化时写入,运行时全量;见 Truncation)。 */\n    truncated?: Truncation[];\n}\n/**\n * 给人与宿主侧行为断言(`t.o11y`)看的 o11y 摘要。从 `events.json` 派生的\n * 行为计数缓存,不是权威——同一 niceeval 版本写读,删除后可从 `events.json` 重算。token 用量、\n * 成本与耗时不在这里:权威唯一在 `result.json` 的 `Usage` / `estimatedCostUSD` 与 `durationMs`\n * / `phases`(见 docs/feature/record/architecture.md「o11y.json」)。\n */\nexport interface O11ySummary {\n    totalTurns: number;\n    /** 只有跑之前调用过的 canonical 工具名才有 key,不是全量出现;省略的 ToolName 视为 0。 */\n    toolCalls: Partial<globalThis.Record<ToolName, number>>;\n    totalToolCalls: number;\n    filesRead: string[];\n    filesModified: string[];\n    shellCommands: {\n        command: string;\n        exitCode?: number;\n        success?: boolean;\n    }[];\n    webFetches: {\n        url: string;\n        status?: number;\n        success?: boolean;\n    }[];\n    errors: string[];\n    thinkingBlocks: number;\n    compactions: number;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"","sourcesContent":["// o11y 域类型:标准事件流(StreamEvent)、折叠事实(DerivedFacts)、\n// OTLP trace(TraceSpan / SpanKind)与用量 / 摘要。\nimport type { JsonValue, SourceLoc } from \"../shared/types.ts\";\n/**\n * 一次运行的 token 用量(沙箱型从 transcript/OTel span 的 `gen_ai.usage.*` 属性抠,remote 由\n * send 的 `Turn.usage` 直接返回)。每个字段只在协议真实提供该值时存在——原始协议没有 usage 时\n * 省略,不编造数值;不存在「默认 0」或「默认 1」的字段。三个输入侧桶恒互斥:相加才是送进模型的\n * 完整上下文量;把协议原生口径归一到互斥是 adapter 的落值义务——OpenAI 系报「含缓存的输入总量 +\n * 缓存命中子集」,落 inputTokens 前先扣掉子集(docs/feature/record/architecture.md#usage,\n * 各协议明细见 docs/feature/adapters/sdk/<name>/cost.md)。\n */\nexport interface Usage {\n    /** 未命中缓存、按全价计费的输入 token;与两个 cache 桶互斥。 */\n    inputTokens?: number;\n    /** 输出(completion)token 数。 */\n    outputTokens?: number;\n    /** 从提示缓存命中的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。 */\n    cacheReadTokens?: number;\n    /** 写入提示缓存的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。 */\n    cacheCreationTokens?: number;\n    /** 推理(thinking)token 数,outputTokens 的已含明细,单列展示用;只在协议真实提供时存在。 */\n    reasoningTokens?: number;\n    /** 真实发生的模型请求数。协议不提供请求计数就省略,绝不写 1 凑数。 */\n    requests?: number;\n    /**\n     * 网关/adapter 实测的真实美元成本(只能由 `Turn.usage.costUSD` 显式带回,从不从\n     * token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个\n     * 相互独立的事实,单向字段契约:本字段只存 observed 值;`estimatedCostUSD` 恒等于\n     * `estimateCost(model, usage, pricing)` 的估算,即使 observed 存在也照常独立计算——\n     * 两者互不覆盖、互不兜底；observed 值从不替代或触发 estimate。\n     */\n    costUSD?: number;\n}\n/** 跨 agent 归一化后的规范工具名。 */\nexport type ToolName = \"file_read\" | \"file_write\" | \"file_edit\" | \"shell\" | \"web_fetch\" | \"web_search\" | \"glob\" | \"grep\" | \"list_dir\" | \"agent_task\" | \"unknown\";\n/** Adapter 确认原始 command 不能安全还原为 argv 的原因。 */\nexport type OriginalCommandOpaqueReason = \"redacted\" | \"truncated\" | \"compound-shell\" | \"dynamic-shell\" | \"unsupported-protocol\";\n/** Adapter 已确认的原始 command invocation；token 保留原生执行边界的形状。 */\nexport type OriginalCommandInvocation = {\n    readonly state: \"available\";\n    readonly executable: string;\n    readonly args: readonly string[];\n} | {\n    readonly state: \"opaque\";\n    readonly reason: OriginalCommandOpaqueReason;\n};\n/** Observation Protocol 唯一的 logical-command normalizer profile。 */\nexport type LogicalCommandNormalizer = \"logical-command/v1\";\n/** 可供 command matcher 消费的、已经归一的逻辑 invocation。 */\nexport type LogicalCommandInvocation = {\n    readonly state: \"available\";\n    readonly executable: string;\n    readonly args: readonly string[];\n    readonly normalizer: LogicalCommandNormalizer;\n    readonly normalization: \"identity\" | \"pnpm-exec\" | \"npx\";\n} | {\n    readonly state: \"opaque\";\n    readonly normalizer: LogicalCommandNormalizer;\n    readonly reason: \"original-opaque\";\n    readonly originalReason: OriginalCommandOpaqueReason;\n} | {\n    readonly state: \"opaque\";\n    readonly normalizer: LogicalCommandNormalizer;\n    readonly reason: \"unsupported-wrapper-form\" | \"ambiguous-wrapper-target\" | \"multiple-executions\";\n};\n/** 一笔 tool operation 的穷尽 command 分类；不从 tool name 或 input 推导。 */\nexport type CommandProjection = {\n    readonly kind: \"not-command\";\n} | {\n    readonly kind: \"command\";\n    readonly original: OriginalCommandInvocation;\n    readonly logical: LogicalCommandInvocation;\n};\n/** 一条 Agent session 内的稳定事件位置。 */\nexport interface EventPosition {\n    readonly turnOrdinal: number;\n    readonly eventOrdinal: number;\n}\n/** 单笔 tool occurrence 的可用 lifecycle 证据。 */\nexport type LogicalToolLifecycle = {\n    readonly state: \"available\";\n    readonly status: \"pending\";\n} | {\n    readonly state: \"available\";\n    readonly status: \"completed\" | \"failed\" | \"rejected\";\n    readonly finish: EventPosition;\n} | {\n    readonly state: \"opaque\";\n    readonly reason: \"partial-stream\" | \"missing-lifecycle-evidence\";\n};\n/**\n * A tool field is independently observable.  Input and output deliberately\n * use the same envelope so a matcher only becomes uncertain when it actually\n * asks for the field whose material is incomplete.\n */\nexport type LogicalToolEvidence = {\n    readonly state: \"complete\";\n    readonly value: JsonValue;\n} | {\n    readonly state: \"partial\";\n    readonly value: JsonValue;\n    readonly opaquePointers: readonly string[];\n    readonly reason: \"truncated\" | \"redacted\";\n} | {\n    readonly state: \"unavailable\";\n    readonly reason: string;\n};\n/** Fact matcher 消费的一笔、按 started/finished 关联后的 tool operation。 */\nexport interface LogicalToolOccurrence {\n    /** 由 session、turn 与 started event position 组成的 occurrence identity；不是 operationId。 */\n    readonly id: string;\n    readonly session: string;\n    readonly turn: string;\n    readonly name: {\n        readonly original: string;\n        readonly canonical?: ToolName;\n    };\n    readonly input: LogicalToolEvidence;\n    /**\n     * A completed lifecycle alone does not prove that output was collected.\n     * Missing, pending, and orphan output are explicit unavailable evidence.\n     */\n    readonly output: LogicalToolEvidence;\n    /**\n     * 旧 Adapter 尚未升级时允许缺失，调用方必须把它视作 command evidence unavailable，\n     * 不能回退为 not-command。新 Adapter 对每笔 tool operation 都必须提供分类。\n     */\n    readonly command?: CommandProjection;\n    readonly start: EventPosition;\n    readonly lifecycle: LogicalToolLifecycle;\n}\n/** `operation.finished` 找不到可信 started 时留下的协议诊断输入，不构造 occurrence。 */\nexport interface OrphanToolOperationFinish {\n    readonly session: string;\n    readonly turn: string;\n    readonly operationId: string;\n    readonly status: \"completed\" | \"failed\" | \"rejected\";\n    readonly position: EventPosition;\n}\n/** `deriveLogicalToolOccurrences` 的 scope 与可信 Turn outcome。 */\nexport interface LogicalToolOccurrenceDeriveOptions {\n    readonly session: string;\n    readonly turn: string;\n    readonly turnOrdinal: number;\n    /** events[0] 对应的 event ordinal；完整 Turn.events 默认从 core user message 的 0 开始。 */\n    readonly firstEventOrdinal?: number;\n    /** 没有可信 Outcome 时保持省略，未关闭 operation 因而只能是 partial-stream。 */\n    readonly outcome?: \"completed\" | \"failed\" | \"waiting\";\n}\n/** One immutable Turn segment in a scope projection. */\nexport interface LogicalToolOccurrenceScopeTurn {\n    readonly session: string;\n    readonly turn: string;\n    readonly turnOrdinal: number;\n    readonly events: readonly StreamEvent[];\n    /** The scope's latest Turn controls whether an unclosed call is pending. */\n    readonly outcome?: \"completed\" | \"failed\" | \"waiting\";\n    readonly firstEventOrdinal?: number;\n}\n/** occurrence 投影与其不能成为匹配候选的 orphan finished。 */\nexport interface LogicalToolOccurrenceDerivation {\n    readonly occurrences: readonly LogicalToolOccurrence[];\n    readonly orphanFinishes: readonly OrphanToolOperationFinish[];\n}\n/** HITL 停轮请求的结构化描述,供 `t.requireInputRequest(filter)` / `t.respondAll` 按条件匹配。 */\nexport interface InputRequest {\n    /** 请求的唯一标识;多个请求并停时,`InputResponse.requestId` 靠它对位。 */\n    readonly id?: string;\n    /** 模型提出的原始问题/文本(用于 `stringMatches` 过滤)。 */\n    readonly prompt?: string;\n    /** adapter 自定义的人类可读展示文案,与 `prompt` 二选一或并存,用于 UI/日志展示及过滤匹配。 */\n    readonly display?: string;\n    /** 请求关联的动作类型(如某个待批准的工具调用名),供过滤用。 */\n    readonly action?: string;\n    /** 请求携带的结构化输入(如待批准命令的参数)。 */\n    readonly input?: JsonValue;\n    /** 若请求提供了预设选项(如批准/拒绝),逐项列出;`id` 对应 `InputResponse.optionId`。 */\n    readonly options?: readonly {\n        id: string;\n        label?: string;\n    }[];\n}\n/**\n * 落盘截断的结构化标记(见 docs/feature/record/architecture.md「大值截断」):\n * `path` 是被截断的位置(事件里是字段名,如 \"output\";span 里是 attribute key,如 \"output.value\"),\n * `originalBytes` 是截断前的 UTF-8 字节数。view 显示「输出过大,已截断」靠它,不正则匹配 marker。\n */\nexport interface Truncation {\n    path: string;\n    originalBytes: number;\n}\n/**\n * 标准事件流的词汇(对标 docs/feature/adapters/architecture/events.md)。adapter 唯一的硬活就是把\n * 各 agent 五花八门的原始 transcript 映射成 StreamEvent[];映射完,整套断言免费。\n * `truncated` 只由 results writer 在落盘时刻写入(运行时全量,落盘截断);adapter 不产出它。\n */\nexport type StreamEvent = {\n    truncated?: Truncation[];\n    /**\n     * Field paths intentionally withheld by the producing boundary.  Runtime\n     * matching sees the original event shape plus this evidence limitation;\n     * persistence can retain the same signal without replacing values with a\n     * magic string.\n     */\n    redacted?: readonly string[];\n} & (\n/** assistant 回复；它不是 eval 源码上的作者事实，不参与 sourceOrder 序列。 */\n{\n    type: \"message\";\n    role: \"assistant\";\n    text: string;\n    loc?: SourceLoc;\n}\n/**\n * eval 作者发出的用户输入；`loc` 把消息叠回源码，`sourceOrder` 与断言、直接给分共用同一条\n * attempt 级序列。历史事件可省略，当前 SessionManager 产出的 user message 必写。\n */\n | {\n    type: \"message\";\n    role: \"user\";\n    text: string;\n    loc?: SourceLoc;\n    sourceOrder?: number;\n}\n/** 发起一次工具或子 agent 操作；嵌套 `kind` 让两种 started 形状保持闭合。 */\n | {\n    type: \"operation.started\";\n    operationId: string;\n    operation: {\n        kind: \"tool\";\n        name: string;\n        input: JsonValue;\n        tool?: ToolName;\n        /**\n         * Adapter 对 command / not-command 的协议级分类。暂时可选以兼容尚未迁移的\n         * 第三方 Adapter；缺失不得在 core 侧由 name、input 或 shell text 补造。\n         */\n        command?: CommandProjection;\n    } | {\n        kind: \"subagent\";\n        name: string;\n        remoteUrl?: string;\n    };\n}\n/** 工具操作完成；人工拒绝只属于工具操作。 */\n | {\n    type: \"operation.finished\";\n    operationId: string;\n    kind: \"tool\";\n    output?: JsonValue;\n    status: \"completed\" | \"failed\" | \"rejected\";\n}\n/** 子 agent 操作完成；子 agent 没有人工拒绝状态。 */\n | {\n    type: \"operation.finished\";\n    operationId: string;\n    kind: \"subagent\";\n    output?: JsonValue;\n    status: \"completed\" | \"failed\";\n}\n/**\n * 一次 Skill 加载:一等事件,由 adapter 从原生协议里识别出「这是加载 Skill」并直接产出,\n * 不靠 renderer 按工具名/文本猜。`operationId` 仅当原生协议把 Skill 加载表达成可关联的工具调用时才有。\n */\n | {\n    type: \"skill.loaded\";\n    skill: string;\n    operationId?: string;\n}\n/** 模型停下来向人请求输入(HITL);具体请求内容见 InputRequest。 */\n | {\n    type: \"input.requested\";\n    request: InputRequest;\n}\n/** 模型的思考/推理文本(非最终回复)。 */\n | {\n    type: \"thinking\";\n    text: string;\n}\n/**\n * 被测系统内部注入的、不披着 `message` 外衣的上下文文本(如 Claude Code 的 SessionStart /\n * UserPromptSubmit hook 在下一轮开始前前置进模型上下文的文本)。只承载带实际文本内容的注入;\n * `source` 是可选的原始来源标记(如 hook 名),adapter 按各自协议原样透传,不强行归一到封闭枚举。\n */\n | {\n    type: \"context.injected\";\n    text: string;\n    source?: string;\n}\n/** 上下文被压缩/摘要(如超长会话截断历史);`reason` 是可选的压缩原因说明。 */\n | {\n    type: \"compaction\";\n    reason?: string;\n}\n/** 运行中出现的错误。 */\n | {\n    type: \"error\";\n    message: string;\n});\n/**\n * core 从事件流折叠出的结构化事实(deriveRunFacts)。折叠按 operationId 把 started 与 finished 对成一条\n * 调用:配上 finished 的取其状态;只有 started、尚未等到 finished 的调用状态是 `pending`——\n * HITL 停在审批上的调用就以这个状态被断言,不是容错分支(见 docs/feature/adapters/architecture/events.md)。\n */\nexport interface ToolCall {\n    operationId: string;\n    name: ToolName;\n    originalName?: string;\n    input: JsonValue;\n    output?: JsonValue;\n    status: \"pending\" | \"completed\" | \"failed\" | \"rejected\";\n}\nexport interface SubagentCall {\n    operationId: string;\n    name: string;\n    remoteUrl?: string;\n    output?: JsonValue;\n    /** 子 agent 委派没有 rejected 状态(operation.finished 只报 completed / failed)。 */\n    status: \"pending\" | \"completed\" | \"failed\";\n}\nexport interface DerivedFacts {\n    readonly toolCalls: readonly ToolCall[];\n    readonly subagentCalls: readonly SubagentCall[];\n    readonly inputRequests: readonly InputRequest[];\n    readonly parked: boolean;\n    readonly messageCount: number;\n    readonly compactions: number;\n    /** 事件流里 `context.injected` 事件的次数;只回答存在性问题,不替代逐条读取原文。 */\n    readonly contextInjections: number;\n}\n/**\n * span 的【语义角色】,从 OTel GenAI 语义约定的 gen_ai.operation.name 归一而来\n * (见 o11y/otlp/canonical.ts)。view 据此着色 / 分组 / 跨 agent 对比,**只认这个,\n * 不读原生 span 名**。未识别的 span 落 \"other\",view 折叠。\n */\nexport type SpanKind = \"turn\" | \"model\" | \"tool\" | \"agent\" | \"other\";\n/**\n * 一条分布式追踪的 span(从 agent 经 OpenTelemetry 导出的 OTLP traces 归一而来)。\n * 与 StreamEvent 不同:它带【时间】(起止 epoch 毫秒)与【父子】(parentSpanId),\n * 所以 view 能画成瀑布图。事件流回答「做了什么」,trace 回答「各花了多久、谁套谁」。\n *\n * 两层归一:线格式层(OTLP/JSON|protobuf → 本结构,见 otlp/parse.ts,通用);\n * 语义层(原生 span 名/属性 → canonical GenAI semconv,见 otlp/mappers/<agent>.ts,每 agent 一个薄 mapper)。\n */\nexport interface TraceSpan {\n    traceId: string;\n    spanId: string;\n    parentSpanId?: string;\n    name: string;\n    /** span 起点 / 终点(epoch 毫秒)。 */\n    startMs: number;\n    endMs: number;\n    status?: \"ok\" | \"error\" | \"unset\";\n    /**\n     * 归一后的语义角色(每-agent mapper 据 canonical GenAI semconv 定;view/select 只认它)。\n     * 未经 mapper 或未识别时为 undefined / \"other\"。\n     */\n    kind?: SpanKind;\n    /** OTLP span 属性(gen_ai.* / tool 名 / token 等),按 key 摊平。raw 属性始终保留供下钻。 */\n    attributes?: globalThis.Record<string, JsonValue>;\n    /** 落盘截断标记(只由 results writer 在序列化时写入,运行时全量;见 Truncation)。 */\n    truncated?: Truncation[];\n}\n/**\n * 给人与宿主侧行为断言(`t.o11y`)看的 o11y 摘要。从 `events.json` 派生的\n * 行为计数缓存,不是权威——同一 niceeval 版本写读,删除后可从 `events.json` 重算。token 用量、\n * 成本与耗时不在这里:observed cost 权威唯一在 `result.json` 的 `Usage.costUSD`,\n * 估算成本与耗时在 `estimatedCostUSD` 与 `durationMs`/`phases`\n * (见 docs/feature/record/architecture.md「o11y.json」)。\n */\nexport interface O11ySummary {\n    totalTurns: number;\n    /** 只有跑之前调用过的 canonical 工具名才有 key,不是全量出现;省略的 ToolName 视为 0。 */\n    toolCalls: Partial<globalThis.Record<ToolName, number>>;\n    totalToolCalls: number;\n    filesRead: string[];\n    filesModified: string[];\n    shellCommands: {\n        command: string;\n        exitCode?: number;\n        success?: boolean;\n    }[];\n    webFetches: {\n        url: string;\n        status?: number;\n        success?: boolean;\n    }[];\n    errors: string[];\n    thinkingBlocks: number;\n    compactions: number;\n}\n"]}

package/dist/o11y/types.d.cts

@@ -22,9 +22,10 @@ export interface Usage {
     requests?: number;
     /**
      * 网关/adapter 实测的真实美元成本(只能由 `Turn.usage.costUSD` 显式带回,从不从
-     * token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个事实:
-     * 存在时优先于按价格表(`defineConfig({ pricing })`)估算的成本——见 `estimateCost` 的
-     * `usage.costUSD ?? estimateCost(...)` 兜底顺序。
+     * token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个
+     * 相互独立的事实,单向字段契约:本字段只存 observed 值;`estimatedCostUSD` 恒等于
+     * `estimateCost(model, usage, pricing)` 的估算,即使 observed 存在也照常独立计算——
+     * 两者互不覆盖、互不兜底；observed 值从不替代或触发 estimate。
      */
     costUSD?: number;
 }
@@ -361,8 +362,9 @@ export interface TraceSpan {
 /**
  * 给人与宿主侧行为断言(`t.o11y`)看的 o11y 摘要。从 `events.json` 派生的
  * 行为计数缓存,不是权威——同一 niceeval 版本写读,删除后可从 `events.json` 重算。token 用量、
- * 成本与耗时不在这里:权威唯一在 `result.json` 的 `Usage` / `estimatedCostUSD` 与 `durationMs`
- * / `phases`(见 docs/feature/record/architecture.md「o11y.json」)。
+ * 成本与耗时不在这里:observed cost 权威唯一在 `result.json` 的 `Usage.costUSD`,
+ * 估算成本与耗时在 `estimatedCostUSD` 与 `durationMs`/`phases`
+ * (见 docs/feature/record/architecture.md「o11y.json」)。
  */
 export interface O11ySummary {
     totalTurns: number;

package/dist/o11y/types.d.mts

@@ -22,9 +22,10 @@ export interface Usage {
     requests?: number;
     /**
      * 网关/adapter 实测的真实美元成本(只能由 `Turn.usage.costUSD` 显式带回,从不从
-     * token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个事实:
-     * 存在时优先于按价格表(`defineConfig({ pricing })`)估算的成本——见 `estimateCost` 的
-     * `usage.costUSD ?? estimateCost(...)` 兜底顺序。
+     * token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个
+     * 相互独立的事实,单向字段契约:本字段只存 observed 值;`estimatedCostUSD` 恒等于
+     * `estimateCost(model, usage, pricing)` 的估算,即使 observed 存在也照常独立计算——
+     * 两者互不覆盖、互不兜底；observed 值从不替代或触发 estimate。
      */
     costUSD?: number;
 }
@@ -361,8 +362,9 @@ export interface TraceSpan {
 /**
  * 给人与宿主侧行为断言(`t.o11y`)看的 o11y 摘要。从 `events.json` 派生的
  * 行为计数缓存,不是权威——同一 niceeval 版本写读,删除后可从 `events.json` 重算。token 用量、
- * 成本与耗时不在这里:权威唯一在 `result.json` 的 `Usage` / `estimatedCostUSD` 与 `durationMs`
- * / `phases`(见 docs/feature/record/architecture.md「o11y.json」)。
+ * 成本与耗时不在这里:observed cost 权威唯一在 `result.json` 的 `Usage.costUSD`,
+ * 估算成本与耗时在 `estimatedCostUSD` 与 `durationMs`/`phases`
+ * (见 docs/feature/record/architecture.md「o11y.json」)。
  */
 export interface O11ySummary {
     totalTurns: number;

package/dist/o11y/types.d.ts

@@ -22,9 +22,10 @@ export interface Usage {
     requests?: number;
     /**
      * 网关/adapter 实测的真实美元成本(只能由 `Turn.usage.costUSD` 显式带回,从不从
-     * token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个事实:
-     * 存在时优先于按价格表(`defineConfig({ pricing })`)估算的成本——见 `estimateCost` 的
-     * `usage.costUSD ?? estimateCost(...)` 兜底顺序。
+     * token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表估算)是两个
+     * 相互独立的事实,单向字段契约:本字段只存 observed 值;`estimatedCostUSD` 恒等于
+     * `estimateCost(model, usage, pricing)` 的估算,即使 observed 存在也照常独立计算——
+     * 两者互不覆盖、互不兜底；observed 值从不替代或触发 estimate。
      */
     costUSD?: number;
 }
@@ -361,8 +362,9 @@ export interface TraceSpan {
 /**
  * 给人与宿主侧行为断言(`t.o11y`)看的 o11y 摘要。从 `events.json` 派生的
  * 行为计数缓存,不是权威——同一 niceeval 版本写读,删除后可从 `events.json` 重算。token 用量、
- * 成本与耗时不在这里:权威唯一在 `result.json` 的 `Usage` / `estimatedCostUSD` 与 `durationMs`
- * / `phases`(见 docs/feature/record/architecture.md「o11y.json」)。
+ * 成本与耗时不在这里:observed cost 权威唯一在 `result.json` 的 `Usage.costUSD`,
+ * 估算成本与耗时在 `estimatedCostUSD` 与 `durationMs`/`phases`
+ * (见 docs/feature/record/architecture.md「o11y.json」)。
  */
 export interface O11ySummary {
     totalTurns: number;

package/dist/plugin/contracts.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.js","sourceRoot":"","sources":["contracts.ts"],"names":[],"mappings":"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","sourcesContent":["// Plugin is deliberately a small lifecycle composition surface. It owns\n// stable identity and scoped setup/teardown only; configuration, commands and\n// resource handles stay with their existing owners.\nimport type { ExperimentHookContext } from \"../runner/types.ts\";\nimport type { FactValue } from \"../shared/facts.ts\";\nimport type { JsonValue, ScopedFeedback } from \"../shared/types.ts\";\nimport type { Sandbox, SandboxHookContext } from \"../sandbox/types.ts\";\nexport type PluginScope = \"experiment\" | \"group\" | \"sandbox\" | \"eval\";\n/** @deprecated Internal compatibility alias while the runner migrates to scope terminology. */\nexport type PluginOwner = Exclude<PluginScope, \"sandbox\">;\nexport type PluginOnUnavailable = \"stop-group\" | \"replace-sandbox\";\ndeclare const PLUGIN_INSTANCE: unique symbol;\nexport interface PluginInstance<Scopes extends PluginScope = PluginScope> {\n    readonly [PLUGIN_INSTANCE]: (scope: Scopes) => void;\n}\nexport type PluginHook<Context> = (context: Context) => void | Promise<void>;\nexport type SandboxPluginHook = (sandbox: Sandbox, context: SandboxHookContext) => void | Promise<void>;\nexport interface GroupPluginContext extends ScopedFeedback {\n    readonly experimentId: string;\n    readonly evalGroupId: string;\n    readonly signal: AbortSignal;\n    fact(key: string, value: FactValue): void;\n}\nexport interface EvalPluginContext extends ScopedFeedback {\n    readonly experimentId: string;\n    readonly evalId: string;\n    readonly attempt: number;\n    readonly evalGroupId?: string;\n    readonly signal: AbortSignal;\n    fact(key: string, value: FactValue): void;\n}\nexport type ExperimentPluginContext = ExperimentHookContext;\nexport type SandboxPluginContext = SandboxHookContext;\nexport type PluginLifecycleFragment<Hook> = Readonly<{\n    readonly identity?: Readonly<globalThis.Record<string, JsonValue>>;\n} & ({\n    readonly setup: Hook;\n    readonly teardown?: Hook;\n} | {\n    readonly setup?: Hook;\n    readonly teardown: Hook;\n})>;\nexport type ExperimentPluginFragment = PluginLifecycleFragment<PluginHook<ExperimentHookContext>>;\nexport type GroupPluginFragment = PluginLifecycleFragment<PluginHook<GroupPluginContext>>;\nexport type SandboxPluginFragment = PluginLifecycleFragment<SandboxPluginHook>;\nexport type EvalPluginFragment = PluginLifecycleFragment<PluginHook<EvalPluginContext>>;\nexport interface PluginDefinition<Options> {\n    readonly name: string;\n    readonly behaviorRevision: string;\n    readonly instanceKey?: (options: Options) => string;\n    readonly experiment?: (options: Options) => ExperimentPluginFragment;\n    readonly group?: (options: Options) => GroupPluginFragment;\n    readonly sandbox?: (options: Options) => SandboxPluginFragment;\n    readonly eval?: (options: Options) => EvalPluginFragment;\n}\ntype AtLeastOneScope<Options> = {\n    readonly experiment: (options: Options) => ExperimentPluginFragment;\n} | {\n    readonly group: (options: Options) => GroupPluginFragment;\n} | {\n    readonly sandbox: (options: Options) => SandboxPluginFragment;\n} | {\n    readonly eval: (options: Options) => EvalPluginFragment;\n};\ntype ScopesOf<Definition> = (Definition extends {\n    readonly experiment: (...args: any[]) => unknown;\n} ? \"experiment\" : never) | (Definition extends {\n    readonly group: (...args: any[]) => unknown;\n} ? \"group\" : never) | (Definition extends {\n    readonly sandbox: (...args: any[]) => unknown;\n} ? \"sandbox\" : never) | (Definition extends {\n    readonly eval: (...args: any[]) => unknown;\n} ? \"eval\" : never);\nexport interface PluginInstanceData {\n    readonly name: string;\n    readonly behaviorRevision: string;\n    readonly instanceKey: string;\n    readonly experiment?: ExperimentPluginFragment;\n    readonly group?: GroupPluginFragment;\n    readonly sandbox?: SandboxPluginFragment;\n    readonly eval?: EvalPluginFragment;\n}\nexport interface LinkedPluginLifecycle {\n    readonly scope: PluginScope;\n    readonly name: string;\n    readonly behaviorRevision: string;\n    readonly instanceKey: string;\n    readonly identity: Readonly<globalThis.Record<string, JsonValue>>;\n    readonly arrayPosition: number;\n    readonly hasSetup: boolean;\n    readonly hasTeardown: boolean;\n    readonly setup?: PluginHook<any> | SandboxPluginHook;\n    readonly teardown?: PluginHook<any> | SandboxPluginHook;\n}\nconst pluginInstances = new WeakMap<object, PluginInstanceData>();\nfunction assertNonEmptyString(value: unknown, label: string): string {\n    if (typeof value !== \"string\" || value.trim() === \"\")\n        throw new TypeError(`${label} must be a non-empty string.`);\n    return value;\n}\nfunction isPlainRecord(value: unknown): value is globalThis.Record<string, unknown> {\n    if (value === null || typeof value !== \"object\" || Array.isArray(value))\n        return false;\n    const prototype = Object.getPrototypeOf(value);\n    return prototype === Object.prototype || prototype === null;\n}\nfunction normalizeJson(value: unknown, path: string, ancestors = new WeakSet<object>()): JsonValue {\n    if (value === null || typeof value === \"string\" || typeof value === \"boolean\")\n        return value;\n    if (typeof value === \"number\") {\n        if (!Number.isFinite(value))\n            throw new TypeError(`${path} must not contain a non-finite number.`);\n        return value;\n    }\n    if (typeof value !== \"object\")\n        throw new TypeError(`${path} must be JSON-compatible.`);\n    if (ancestors.has(value))\n        throw new TypeError(`${path} must not contain a cycle.`);\n    ancestors.add(value);\n    try {\n        if (Array.isArray(value)) {\n            const normalized: JsonValue[] = value.map((item, index) => normalizeJson(item, `${path}[${index}]`, ancestors));\n            Object.freeze(normalized);\n            return normalized;\n        }\n        if (!isPlainRecord(value))\n            throw new TypeError(`${path} must contain only plain JSON objects.`);\n        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, normalizeJson(item, `${path}.${key}`, ancestors)])));\n    }\n    finally {\n        ancestors.delete(value);\n    }\n}\nfunction normalizeFragment<Hook>(value: unknown, path: string): PluginLifecycleFragment<Hook> {\n    if (!isPlainRecord(value))\n        throw new TypeError(`${path} must return an object.`);\n    for (const key of Object.keys(value)) {\n        if (![\"identity\", \"setup\", \"teardown\"].includes(key)) {\n            throw new TypeError(`${path}.${key} is not supported by lifecycle plugins.`);\n        }\n    }\n    if (value.setup === undefined && value.teardown === undefined) {\n        throw new TypeError(`${path} must declare setup or teardown.`);\n    }\n    if (value.setup !== undefined && typeof value.setup !== \"function\")\n        throw new TypeError(`${path}.setup must be a function.`);\n    if (value.teardown !== undefined && typeof value.teardown !== \"function\")\n        throw new TypeError(`${path}.teardown must be a function.`);\n    const identity = value.identity === undefined ? Object.freeze({}) : normalizeJson(value.identity, `${path}.identity`);\n    if (!isPlainRecord(identity))\n        throw new TypeError(`${path}.identity must be a JSON object.`);\n    return Object.freeze({\n        identity: identity as Readonly<globalThis.Record<string, JsonValue>>,\n        ...(value.setup === undefined ? {} : { setup: value.setup as Hook }),\n        ...(value.teardown === undefined ? {} : { teardown: value.teardown as Hook }),\n    }) as PluginLifecycleFragment<Hook>;\n}\nexport function definePlugin<const Definition extends PluginDefinition<void> & AtLeastOneScope<void>>(definition: Definition & {\n    readonly instanceKey?: never;\n}): () => PluginInstance<ScopesOf<Definition>>;\nexport function definePlugin<Options, const Definition extends PluginDefinition<Options> & AtLeastOneScope<Options>>(definition: Definition & {\n    readonly instanceKey: (options: Options) => string;\n}): (options: Options) => PluginInstance<ScopesOf<Definition>>;\n/** Explicit `definePlugin<Options>(...)` form; runtime link still validates the exact attachment scope. */\nexport function definePlugin<Options>(definition: PluginDefinition<Options> & AtLeastOneScope<Options> & {\n    readonly instanceKey: (options: Options) => string;\n}): (options: Options) => PluginInstance<PluginScope>;\nexport function definePlugin(definition: PluginDefinition<any> & AtLeastOneScope<any>): (...args: readonly unknown[]) => PluginInstance<PluginScope> {\n    if (!isPlainRecord(definition))\n        throw new TypeError(\"definePlugin requires an object.\");\n    const name = assertNonEmptyString(definition.name, \"definePlugin name\");\n    const behaviorRevision = assertNonEmptyString(definition.behaviorRevision, \"definePlugin behaviorRevision\");\n    if (definition.instanceKey !== undefined && typeof definition.instanceKey !== \"function\") {\n        throw new TypeError(\"definePlugin instanceKey must be a function when provided.\");\n    }\n    const scopes = [\"experiment\", \"group\", \"sandbox\", \"eval\"] as const;\n    if (!scopes.some((scope) => definition[scope] !== undefined)) {\n        throw new TypeError(\"definePlugin must declare at least one scope callback.\");\n    }\n    for (const scope of scopes) {\n        if (definition[scope] !== undefined && typeof definition[scope] !== \"function\") {\n            throw new TypeError(`definePlugin ${scope} must be a function.`);\n        }\n    }\n    return (...args: readonly unknown[]): PluginInstance<PluginScope> => {\n        if (definition.instanceKey === undefined && args.length !== 0)\n            throw new TypeError(`Plugin ${name} takes no options.`);\n        if (definition.instanceKey !== undefined && args.length !== 1)\n            throw new TypeError(`Plugin ${name} requires exactly one options value.`);\n        const options = args[0];\n        const instanceKey = definition.instanceKey === undefined\n            ? \"default\"\n            : assertNonEmptyString(definition.instanceKey(options), `Plugin ${name} instanceKey`);\n        const data: PluginInstanceData = Object.freeze({\n            name,\n            behaviorRevision,\n            instanceKey,\n            ...Object.fromEntries(scopes.flatMap((scope) => {\n                const factory = definition[scope];\n                return factory === undefined ? [] : [[scope, normalizeFragment(factory(options), `Plugin ${name}.${scope}`)]];\n            })),\n        });\n        const instance = Object.freeze({}) as PluginInstance<PluginScope>;\n        pluginInstances.set(instance, data);\n        return instance;\n    };\n}\nexport function isPluginInstance(value: unknown): value is PluginInstance {\n    return typeof value === \"object\" && value !== null && pluginInstances.has(value);\n}\nexport function pluginInstanceDataOf(value: PluginInstance<any>): PluginInstanceData {\n    const data = pluginInstances.get(value);\n    if (data === undefined)\n        throw new TypeError(\"Plugin instance must be created by definePlugin().\");\n    return data;\n}\nexport function linkPluginLifecycles<Scope extends PluginScope>(plugins: readonly PluginInstance<Scope>[], scope: Scope): readonly LinkedPluginLifecycle[] {\n    const seen = new Set<string>();\n    return Object.freeze(plugins.map((plugin, arrayPosition) => {\n        const data = pluginInstanceDataOf(plugin);\n        const fragment = data[scope];\n        if (fragment === undefined)\n            throw new TypeError(`Plugin ${JSON.stringify(data.name)} does not support ${scope} attachment.`);\n        const duplicateKey = JSON.stringify([data.name, data.instanceKey]);\n        if (seen.has(duplicateKey)) {\n            throw new TypeError(`Duplicate ${scope} plugin occurrence (${JSON.stringify(data.name)}, ${JSON.stringify(data.instanceKey)}).`);\n        }\n        seen.add(duplicateKey);\n        return Object.freeze({\n            scope,\n            name: data.name,\n            behaviorRevision: data.behaviorRevision,\n            instanceKey: data.instanceKey,\n            identity: fragment.identity ?? Object.freeze({}),\n            arrayPosition,\n            hasSetup: fragment.setup !== undefined,\n            hasTeardown: fragment.teardown !== undefined,\n            ...(fragment.setup === undefined ? {} : { setup: fragment.setup }),\n            ...(fragment.teardown === undefined ? {} : { teardown: fragment.teardown }),\n        });\n    }));\n}\n/** @internal Project an optional secondary fragment (currently sandbox) from an existing attachment. */\nexport function projectPluginLifecycles<Scope extends PluginScope>(plugins: readonly PluginInstance<any>[], scope: Scope): readonly LinkedPluginLifecycle[] {\n    let projectedPosition = 0;\n    return Object.freeze(plugins.flatMap((plugin) => {\n        const data = pluginInstanceDataOf(plugin);\n        const fragment = data[scope];\n        if (fragment === undefined)\n            return [];\n        return [Object.freeze({\n                scope,\n                name: data.name,\n                behaviorRevision: data.behaviorRevision,\n                instanceKey: data.instanceKey,\n                identity: fragment.identity ?? Object.freeze({}),\n                arrayPosition: projectedPosition++,\n                hasSetup: fragment.setup !== undefined,\n                hasTeardown: fragment.teardown !== undefined,\n                ...(fragment.setup === undefined ? {} : { setup: fragment.setup }),\n                ...(fragment.teardown === undefined ? {} : { teardown: fragment.teardown }),\n            })];\n    }));\n}\nexport function pluginLifecycleIdentity({ scope, name, behaviorRevision, instanceKey, identity, arrayPosition, hasSetup, hasTeardown }: LinkedPluginLifecycle): JsonValue {\n    return Object.freeze({\n        scope,\n        name,\n        behaviorRevision,\n        instanceKey,\n        identity,\n        arrayPosition,\n        hasSetup,\n        hasTeardown,\n    });\n}\nexport function pluginLifecycleProjection(lifecycles: readonly LinkedPluginLifecycle[]): JsonValue {\n    const projection: JsonValue[] = lifecycles.map(pluginLifecycleIdentity);\n    Object.freeze(projection);\n    return projection;\n}\n"]}
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["contracts.ts"],"names":[],"mappings":"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","sourcesContent":["// Plugin is deliberately a small lifecycle composition surface. It owns\n// stable identity and scoped setup/teardown only; configuration, commands and\n// resource handles stay with their existing owners.\nimport type { ExperimentHookContext } from \"../runner/types.ts\";\nimport type { JsonValue, ScopedFeedback } from \"../shared/types.ts\";\nimport type { Sandbox, SandboxHookContext } from \"../sandbox/types.ts\";\nexport type PluginScope = \"experiment\" | \"group\" | \"sandbox\" | \"eval\";\n/** @deprecated Internal compatibility alias while the runner migrates to scope terminology. */\nexport type PluginOwner = Exclude<PluginScope, \"sandbox\">;\nexport type PluginOnUnavailable = \"stop-group\" | \"replace-sandbox\";\ndeclare const PLUGIN_INSTANCE: unique symbol;\nexport interface PluginInstance<Scopes extends PluginScope = PluginScope> {\n    readonly [PLUGIN_INSTANCE]: (scope: Scopes) => void;\n}\nexport type PluginHook<Context> = (context: Context) => void | Promise<void>;\nexport type SandboxPluginHook = (sandbox: Sandbox, context: SandboxHookContext) => void | Promise<void>;\nexport interface GroupPluginContext extends ScopedFeedback {\n    readonly experimentId: string;\n    readonly evalGroupId: string;\n    readonly signal: AbortSignal;\n}\nexport interface EvalPluginContext extends ScopedFeedback {\n    readonly experimentId: string;\n    readonly evalId: string;\n    readonly attempt: number;\n    readonly evalGroupId?: string;\n    readonly signal: AbortSignal;\n}\nexport type ExperimentPluginContext = ExperimentHookContext;\nexport type SandboxPluginContext = SandboxHookContext;\nexport type PluginLifecycleFragment<Hook> = Readonly<{\n    readonly identity?: Readonly<globalThis.Record<string, JsonValue>>;\n} & ({\n    readonly setup: Hook;\n    readonly teardown?: Hook;\n} | {\n    readonly setup?: Hook;\n    readonly teardown: Hook;\n})>;\nexport type ExperimentPluginFragment = PluginLifecycleFragment<PluginHook<ExperimentHookContext>>;\nexport type GroupPluginFragment = PluginLifecycleFragment<PluginHook<GroupPluginContext>>;\nexport type SandboxPluginFragment = PluginLifecycleFragment<SandboxPluginHook>;\nexport type EvalPluginFragment = PluginLifecycleFragment<PluginHook<EvalPluginContext>>;\nexport interface PluginDefinition<Options> {\n    readonly name: string;\n    readonly behaviorRevision: string;\n    readonly instanceKey?: (options: Options) => string;\n    readonly experiment?: (options: Options) => ExperimentPluginFragment;\n    readonly group?: (options: Options) => GroupPluginFragment;\n    readonly sandbox?: (options: Options) => SandboxPluginFragment;\n    readonly eval?: (options: Options) => EvalPluginFragment;\n}\ntype AtLeastOneScope<Options> = {\n    readonly experiment: (options: Options) => ExperimentPluginFragment;\n} | {\n    readonly group: (options: Options) => GroupPluginFragment;\n} | {\n    readonly sandbox: (options: Options) => SandboxPluginFragment;\n} | {\n    readonly eval: (options: Options) => EvalPluginFragment;\n};\ntype ScopesOf<Definition> = (Definition extends {\n    readonly experiment: (...args: any[]) => unknown;\n} ? \"experiment\" : never) | (Definition extends {\n    readonly group: (...args: any[]) => unknown;\n} ? \"group\" : never) | (Definition extends {\n    readonly sandbox: (...args: any[]) => unknown;\n} ? \"sandbox\" : never) | (Definition extends {\n    readonly eval: (...args: any[]) => unknown;\n} ? \"eval\" : never);\nexport interface PluginInstanceData {\n    readonly name: string;\n    readonly behaviorRevision: string;\n    readonly instanceKey: string;\n    readonly experiment?: ExperimentPluginFragment;\n    readonly group?: GroupPluginFragment;\n    readonly sandbox?: SandboxPluginFragment;\n    readonly eval?: EvalPluginFragment;\n}\nexport interface LinkedPluginLifecycle {\n    readonly scope: PluginScope;\n    readonly name: string;\n    readonly behaviorRevision: string;\n    readonly instanceKey: string;\n    readonly identity: Readonly<globalThis.Record<string, JsonValue>>;\n    readonly arrayPosition: number;\n    readonly hasSetup: boolean;\n    readonly hasTeardown: boolean;\n    readonly setup?: PluginHook<any> | SandboxPluginHook;\n    readonly teardown?: PluginHook<any> | SandboxPluginHook;\n}\nconst pluginInstances = new WeakMap<object, PluginInstanceData>();\nfunction assertNonEmptyString(value: unknown, label: string): string {\n    if (typeof value !== \"string\" || value.trim() === \"\")\n        throw new TypeError(`${label} must be a non-empty string.`);\n    return value;\n}\nfunction isPlainRecord(value: unknown): value is globalThis.Record<string, unknown> {\n    if (value === null || typeof value !== \"object\" || Array.isArray(value))\n        return false;\n    const prototype = Object.getPrototypeOf(value);\n    return prototype === Object.prototype || prototype === null;\n}\nfunction normalizeJson(value: unknown, path: string, ancestors = new WeakSet<object>()): JsonValue {\n    if (value === null || typeof value === \"string\" || typeof value === \"boolean\")\n        return value;\n    if (typeof value === \"number\") {\n        if (!Number.isFinite(value))\n            throw new TypeError(`${path} must not contain a non-finite number.`);\n        return value;\n    }\n    if (typeof value !== \"object\")\n        throw new TypeError(`${path} must be JSON-compatible.`);\n    if (ancestors.has(value))\n        throw new TypeError(`${path} must not contain a cycle.`);\n    ancestors.add(value);\n    try {\n        if (Array.isArray(value)) {\n            const normalized: JsonValue[] = value.map((item, index) => normalizeJson(item, `${path}[${index}]`, ancestors));\n            Object.freeze(normalized);\n            return normalized;\n        }\n        if (!isPlainRecord(value))\n            throw new TypeError(`${path} must contain only plain JSON objects.`);\n        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, normalizeJson(item, `${path}.${key}`, ancestors)])));\n    }\n    finally {\n        ancestors.delete(value);\n    }\n}\nfunction normalizeFragment<Hook>(value: unknown, path: string): PluginLifecycleFragment<Hook> {\n    if (!isPlainRecord(value))\n        throw new TypeError(`${path} must return an object.`);\n    for (const key of Object.keys(value)) {\n        if (![\"identity\", \"setup\", \"teardown\"].includes(key)) {\n            throw new TypeError(`${path}.${key} is not supported by lifecycle plugins.`);\n        }\n    }\n    if (value.setup === undefined && value.teardown === undefined) {\n        throw new TypeError(`${path} must declare setup or teardown.`);\n    }\n    if (value.setup !== undefined && typeof value.setup !== \"function\")\n        throw new TypeError(`${path}.setup must be a function.`);\n    if (value.teardown !== undefined && typeof value.teardown !== \"function\")\n        throw new TypeError(`${path}.teardown must be a function.`);\n    const identity = value.identity === undefined ? Object.freeze({}) : normalizeJson(value.identity, `${path}.identity`);\n    if (!isPlainRecord(identity))\n        throw new TypeError(`${path}.identity must be a JSON object.`);\n    return Object.freeze({\n        identity: identity as Readonly<globalThis.Record<string, JsonValue>>,\n        ...(value.setup === undefined ? {} : { setup: value.setup as Hook }),\n        ...(value.teardown === undefined ? {} : { teardown: value.teardown as Hook }),\n    }) as PluginLifecycleFragment<Hook>;\n}\nexport function definePlugin<const Definition extends PluginDefinition<void> & AtLeastOneScope<void>>(definition: Definition & {\n    readonly instanceKey?: never;\n}): () => PluginInstance<ScopesOf<Definition>>;\nexport function definePlugin<Options, const Definition extends PluginDefinition<Options> & AtLeastOneScope<Options>>(definition: Definition & {\n    readonly instanceKey: (options: Options) => string;\n}): (options: Options) => PluginInstance<ScopesOf<Definition>>;\n/** Explicit `definePlugin<Options>(...)` form; runtime link still validates the exact attachment scope. */\nexport function definePlugin<Options>(definition: PluginDefinition<Options> & AtLeastOneScope<Options> & {\n    readonly instanceKey: (options: Options) => string;\n}): (options: Options) => PluginInstance<PluginScope>;\nexport function definePlugin(definition: PluginDefinition<any> & AtLeastOneScope<any>): (...args: readonly unknown[]) => PluginInstance<PluginScope> {\n    if (!isPlainRecord(definition))\n        throw new TypeError(\"definePlugin requires an object.\");\n    const name = assertNonEmptyString(definition.name, \"definePlugin name\");\n    const behaviorRevision = assertNonEmptyString(definition.behaviorRevision, \"definePlugin behaviorRevision\");\n    if (definition.instanceKey !== undefined && typeof definition.instanceKey !== \"function\") {\n        throw new TypeError(\"definePlugin instanceKey must be a function when provided.\");\n    }\n    const scopes = [\"experiment\", \"group\", \"sandbox\", \"eval\"] as const;\n    if (!scopes.some((scope) => definition[scope] !== undefined)) {\n        throw new TypeError(\"definePlugin must declare at least one scope callback.\");\n    }\n    for (const scope of scopes) {\n        if (definition[scope] !== undefined && typeof definition[scope] !== \"function\") {\n            throw new TypeError(`definePlugin ${scope} must be a function.`);\n        }\n    }\n    return (...args: readonly unknown[]): PluginInstance<PluginScope> => {\n        if (definition.instanceKey === undefined && args.length !== 0)\n            throw new TypeError(`Plugin ${name} takes no options.`);\n        if (definition.instanceKey !== undefined && args.length !== 1)\n            throw new TypeError(`Plugin ${name} requires exactly one options value.`);\n        const options = args[0];\n        const instanceKey = definition.instanceKey === undefined\n            ? \"default\"\n            : assertNonEmptyString(definition.instanceKey(options), `Plugin ${name} instanceKey`);\n        const data: PluginInstanceData = Object.freeze({\n            name,\n            behaviorRevision,\n            instanceKey,\n            ...Object.fromEntries(scopes.flatMap((scope) => {\n                const factory = definition[scope];\n                return factory === undefined ? [] : [[scope, normalizeFragment(factory(options), `Plugin ${name}.${scope}`)]];\n            })),\n        });\n        const instance = Object.freeze({}) as PluginInstance<PluginScope>;\n        pluginInstances.set(instance, data);\n        return instance;\n    };\n}\nexport function isPluginInstance(value: unknown): value is PluginInstance {\n    return typeof value === \"object\" && value !== null && pluginInstances.has(value);\n}\nexport function pluginInstanceDataOf(value: PluginInstance<any>): PluginInstanceData {\n    const data = pluginInstances.get(value);\n    if (data === undefined)\n        throw new TypeError(\"Plugin instance must be created by definePlugin().\");\n    return data;\n}\nexport function linkPluginLifecycles<Scope extends PluginScope>(plugins: readonly PluginInstance<Scope>[], scope: Scope): readonly LinkedPluginLifecycle[] {\n    const seen = new Set<string>();\n    return Object.freeze(plugins.map((plugin, arrayPosition) => {\n        const data = pluginInstanceDataOf(plugin);\n        const fragment = data[scope];\n        if (fragment === undefined)\n            throw new TypeError(`Plugin ${JSON.stringify(data.name)} does not support ${scope} attachment.`);\n        const duplicateKey = JSON.stringify([data.name, data.instanceKey]);\n        if (seen.has(duplicateKey)) {\n            throw new TypeError(`Duplicate ${scope} plugin occurrence (${JSON.stringify(data.name)}, ${JSON.stringify(data.instanceKey)}).`);\n        }\n        seen.add(duplicateKey);\n        return Object.freeze({\n            scope,\n            name: data.name,\n            behaviorRevision: data.behaviorRevision,\n            instanceKey: data.instanceKey,\n            identity: fragment.identity ?? Object.freeze({}),\n            arrayPosition,\n            hasSetup: fragment.setup !== undefined,\n            hasTeardown: fragment.teardown !== undefined,\n            ...(fragment.setup === undefined ? {} : { setup: fragment.setup }),\n            ...(fragment.teardown === undefined ? {} : { teardown: fragment.teardown }),\n        });\n    }));\n}\n/** @internal Project an optional secondary fragment (currently sandbox) from an existing attachment. */\nexport function projectPluginLifecycles<Scope extends PluginScope>(plugins: readonly PluginInstance<any>[], scope: Scope): readonly LinkedPluginLifecycle[] {\n    let projectedPosition = 0;\n    return Object.freeze(plugins.flatMap((plugin) => {\n        const data = pluginInstanceDataOf(plugin);\n        const fragment = data[scope];\n        if (fragment === undefined)\n            return [];\n        return [Object.freeze({\n                scope,\n                name: data.name,\n                behaviorRevision: data.behaviorRevision,\n                instanceKey: data.instanceKey,\n                identity: fragment.identity ?? Object.freeze({}),\n                arrayPosition: projectedPosition++,\n                hasSetup: fragment.setup !== undefined,\n                hasTeardown: fragment.teardown !== undefined,\n                ...(fragment.setup === undefined ? {} : { setup: fragment.setup }),\n                ...(fragment.teardown === undefined ? {} : { teardown: fragment.teardown }),\n            })];\n    }));\n}\nexport function pluginLifecycleIdentity({ scope, name, behaviorRevision, instanceKey, identity, arrayPosition, hasSetup, hasTeardown }: LinkedPluginLifecycle): JsonValue {\n    return Object.freeze({\n        scope,\n        name,\n        behaviorRevision,\n        instanceKey,\n        identity,\n        arrayPosition,\n        hasSetup,\n        hasTeardown,\n    });\n}\nexport function pluginLifecycleProjection(lifecycles: readonly LinkedPluginLifecycle[]): JsonValue {\n    const projection: JsonValue[] = lifecycles.map(pluginLifecycleIdentity);\n    Object.freeze(projection);\n    return projection;\n}\n"]}

package/dist/plugin/contracts.d.cts

@@ -1,5 +1,4 @@
 import type { ExperimentHookContext } from "../runner/types.cjs";
-import type { FactValue } from "../shared/facts.cjs";
 import type { JsonValue, ScopedFeedback } from "../shared/types.cjs";
 import type { Sandbox, SandboxHookContext } from "../sandbox/types.cjs";
 export type PluginScope = "experiment" | "group" | "sandbox" | "eval";
@@ -16,7 +15,6 @@ export interface GroupPluginContext extends ScopedFeedback {
     readonly experimentId: string;
     readonly evalGroupId: string;
     readonly signal: AbortSignal;
-    fact(key: string, value: FactValue): void;
 }
 export interface EvalPluginContext extends ScopedFeedback {
     readonly experimentId: string;
@@ -24,7 +22,6 @@ export interface EvalPluginContext extends ScopedFeedback {
     readonly attempt: number;
     readonly evalGroupId?: string;
     readonly signal: AbortSignal;
-    fact(key: string, value: FactValue): void;
 }
 export type ExperimentPluginContext = ExperimentHookContext;
 export type SandboxPluginContext = SandboxHookContext;

package/dist/plugin/contracts.d.mts

@@ -1,5 +1,4 @@
 import type { ExperimentHookContext } from "../runner/types.mjs";
-import type { FactValue } from "../shared/facts.mjs";
 import type { JsonValue, ScopedFeedback } from "../shared/types.mjs";
 import type { Sandbox, SandboxHookContext } from "../sandbox/types.mjs";
 export type PluginScope = "experiment" | "group" | "sandbox" | "eval";
@@ -16,7 +15,6 @@ export interface GroupPluginContext extends ScopedFeedback {
     readonly experimentId: string;
     readonly evalGroupId: string;
     readonly signal: AbortSignal;
-    fact(key: string, value: FactValue): void;
 }
 export interface EvalPluginContext extends ScopedFeedback {
     readonly experimentId: string;
@@ -24,7 +22,6 @@ export interface EvalPluginContext extends ScopedFeedback {
     readonly attempt: number;
     readonly evalGroupId?: string;
     readonly signal: AbortSignal;
-    fact(key: string, value: FactValue): void;
 }
 export type ExperimentPluginContext = ExperimentHookContext;
 export type SandboxPluginContext = SandboxHookContext;