niceeval 0.16.3-canary.99 → 0.17.0

package/dist/o11y/cache-read.cjs

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheReadReportSchema = void 0;
+exports.projectCacheRead = projectCacheRead;
+const effect_1 = require("effect");
+const common_ts_1 = require("../record/family/common.cjs");
+const Reason = effect_1.Schema.Literals([
+    "usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete",
+    "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total",
+]);
+const Rate = effect_1.Schema.Union([
+    effect_1.Schema.Struct({ state: effect_1.Schema.Literal("exact"), value: effect_1.Schema.Number.check(effect_1.Schema.makeFilter((value) => Number.isFinite(value) && value >= 0 && value <= 1)) }),
+    effect_1.Schema.Struct({ state: effect_1.Schema.Literal("unavailable"), reason: Reason }),
+]);
+const fields = {
+    rate: Rate,
+    recordedCalls: common_ts_1.NonNegativeSafeIntegerSchema,
+    coveredCalls: common_ts_1.NonNegativeSafeIntegerSchema,
+    missingCacheReadCalls: common_ts_1.NonNegativeSafeIntegerSchema,
+    missingInputTotalCalls: common_ts_1.NonNegativeSafeIntegerSchema,
+    unknownStatusCalls: common_ts_1.NonNegativeSafeIntegerSchema,
+    collectionComplete: effect_1.Schema.Boolean,
+    reasons: effect_1.Schema.Array(Reason),
+};
+const consistent = (value) => {
+    const count = value.recordedCalls;
+    return count <= 4000 && value.coveredCalls <= count && value.unknownStatusCalls <= count &&
+        value.missingCacheReadCalls <= count && value.missingInputTotalCalls <= count &&
+        value.coveredCalls <= count - Math.max(value.missingCacheReadCalls, value.missingInputTotalCalls) &&
+        value.coveredCalls >= count - value.missingCacheReadCalls - value.missingInputTotalCalls &&
+        new Set(value.reasons).size === value.reasons.length &&
+        (value.rate.state === "exact" ? value.reasons.length === 0 && value.collectionComplete && count > 0 &&
+            value.coveredCalls === count && value.unknownStatusCalls === 0 : value.rate.reason === value.reasons[0]);
+};
+const SummaryShape = effect_1.Schema.Struct(fields);
+const Summary = SummaryShape.check(effect_1.Schema.makeFilter(consistent));
+exports.CacheReadReportSchema = effect_1.Schema.Struct({
+    total: Summary,
+    modelSlots: effect_1.Schema.Array(effect_1.Schema.Struct({ modelSlot: effect_1.Schema.NullOr(effect_1.Schema.String), ...fields }).check(effect_1.Schema.makeFilter(consistent))),
+    models: effect_1.Schema.Array(effect_1.Schema.Struct({ modelSlot: effect_1.Schema.NullOr(effect_1.Schema.String), provider: effect_1.Schema.NullOr(effect_1.Schema.String), model: effect_1.Schema.NullOr(effect_1.Schema.String), ...fields }).check(effect_1.Schema.makeFilter(consistent))),
+}).check(effect_1.Schema.makeFilter((value) => value.modelSlots.length <= 65 && value.models.length <= 4000));
+function summary(calls, collectionComplete, absent) {
+    let numerator = 0;
+    let denominator = 0;
+    let coveredCalls = 0;
+    let missingCacheReadCalls = 0;
+    let missingInputTotalCalls = 0;
+    let unknownStatusCalls = 0;
+    let unsafe = false;
+    for (const call of calls) {
+        const total = call.inputTotalTokens ?? (call.inputTokens !== null && call.cacheReadTokens !== null && call.cacheWriteTokens !== null
+            ? call.inputTokens + call.cacheReadTokens + call.cacheWriteTokens : null);
+        if (call.status === "unknown")
+            unknownStatusCalls++;
+        if (call.cacheReadTokens === null)
+            missingCacheReadCalls++;
+        else
+            numerator += call.cacheReadTokens;
+        if (total === null)
+            missingInputTotalCalls++;
+        else
+            denominator += total;
+        if (total !== null && call.cacheReadTokens !== null)
+            coveredCalls++;
+        if ((total !== null && !Number.isSafeInteger(total)) || !Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator))
+            unsafe = true;
+    }
+    const reasons = absent === undefined ? [
+        ...(!collectionComplete ? ["collection-incomplete"] : []),
+        ...(unknownStatusCalls > 0 ? ["call-status-unknown"] : []),
+        ...(calls.length === 0 ? ["no-calls"] : []),
+        ...(missingCacheReadCalls > 0 ? ["cache-read-missing"] : []),
+        ...(missingInputTotalCalls > 0 ? ["input-total-missing"] : []),
+        ...(calls.length > 0 && missingInputTotalCalls === 0 && denominator === 0 ? ["zero-input-total"] : []),
+        ...(unsafe ? ["unsafe-token-total"] : []),
+    ] : [absent];
+    const rate = reasons.length === 0
+        ? Object.freeze({ state: "exact", value: numerator / denominator })
+        : Object.freeze({ state: "unavailable", reason: reasons[0] });
+    return Object.freeze({ rate, recordedCalls: calls.length, coveredCalls, missingCacheReadCalls, missingInputTotalCalls,
+        unknownStatusCalls, collectionComplete, reasons: Object.freeze(reasons) });
+}
+const compare = (a, b) => a === b ? 0 : a === null ? -1 : b === null ? 1 : a < b ? -1 : 1;
+/** A historical collection marked complete is not proof of an explicit producer seal. */
+function projectCacheRead(usage, slots, producerCompletenessKnown, absent = "usage-not-recorded") {
+    if (usage === null)
+        return Object.freeze({ total: summary([], false, absent), modelSlots: Object.freeze([]), models: Object.freeze([]) });
+    const complete = producerCompletenessKnown && usage.collection.state === "complete";
+    const bySlot = new Map(Object.keys(slots ?? {}).map((slot) => [slot, []]));
+    const byModel = new Map();
+    for (const call of usage.calls) {
+        const slot = bySlot.get(call.modelSlot);
+        if (slot === undefined)
+            bySlot.set(call.modelSlot, [call]);
+        else
+            slot.push(call);
+        const key = JSON.stringify([call.modelSlot, call.provider, call.model]);
+        const model = byModel.get(key);
+        if (model === undefined)
+            byModel.set(key, [call]);
+        else
+            model.push(call);
+    }
+    const models = [...byModel.values()].map((calls) => {
+        const { modelSlot, provider, model } = calls[0];
+        return Object.freeze({ modelSlot, provider, model, ...summary(calls, complete) });
+    }).sort((a, b) => compare(a.modelSlot, b.modelSlot) || compare(a.provider, b.provider) || compare(a.model, b.model));
+    return Object.freeze({ total: summary(usage.calls, complete),
+        modelSlots: Object.freeze([...bySlot].sort(([a], [b]) => compare(a, b)).map(([modelSlot, calls]) => Object.freeze({ modelSlot, ...summary(calls, complete) }))),
+        models: Object.freeze(models),
+    });
+}
+//# sourceMappingURL=cache-read.cjs.map

package/dist/o11y/cache-read.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-read.js","sourceRoot":"","sources":["cache-read.ts"],"names":[],"mappings":"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","sourcesContent":["import { Schema } from \"effect\";\nimport type { ResolvedModelSlots } from \"../model-slots.ts\";\nimport type { AdapterUsageCall, ReadableAdapterUsageAttachment } from \"../record/family/adapter-usage/schema.ts\";\nimport { NonNegativeSafeIntegerSchema } from \"../record/family/common.ts\";\nconst Reason = Schema.Literals([\n    \"usage-not-recorded\", \"source-invalid\", \"adapter-usage-required\", \"collection-incomplete\",\n    \"call-status-unknown\", \"no-calls\", \"cache-read-missing\", \"input-total-missing\", \"zero-input-total\", \"unsafe-token-total\",\n]);\ntype Reason = typeof Reason.Type;\nconst Rate = Schema.Union([\n    Schema.Struct({ state: Schema.Literal(\"exact\"), value: Schema.Number.check(Schema.makeFilter((value) => Number.isFinite(value) && value >= 0 && value <= 1)) }),\n    Schema.Struct({ state: Schema.Literal(\"unavailable\"), reason: Reason }),\n]);\nconst fields = {\n    rate: Rate,\n    recordedCalls: NonNegativeSafeIntegerSchema,\n    coveredCalls: NonNegativeSafeIntegerSchema,\n    missingCacheReadCalls: NonNegativeSafeIntegerSchema,\n    missingInputTotalCalls: NonNegativeSafeIntegerSchema,\n    unknownStatusCalls: NonNegativeSafeIntegerSchema,\n    collectionComplete: Schema.Boolean,\n    reasons: Schema.Array(Reason),\n};\nconst consistent = (value: typeof SummaryShape.Type): boolean => {\n    const count = value.recordedCalls;\n    return count <= 4000 && value.coveredCalls <= count && value.unknownStatusCalls <= count &&\n        value.missingCacheReadCalls <= count && value.missingInputTotalCalls <= count &&\n        value.coveredCalls <= count - Math.max(value.missingCacheReadCalls, value.missingInputTotalCalls) &&\n        value.coveredCalls >= count - value.missingCacheReadCalls - value.missingInputTotalCalls &&\n        new Set(value.reasons).size === value.reasons.length &&\n        (value.rate.state === \"exact\" ? value.reasons.length === 0 && value.collectionComplete && count > 0 &&\n            value.coveredCalls === count && value.unknownStatusCalls === 0 : value.rate.reason === value.reasons[0]);\n};\nconst SummaryShape = Schema.Struct(fields);\nconst Summary = SummaryShape.check(Schema.makeFilter(consistent));\n/** Token-weighted cache reading, with explicit input coverage and collection completeness. */\nexport type CacheReadSummary = typeof Summary.Type;\nexport const CacheReadReportSchema = Schema.Struct({\n    total: Summary,\n    modelSlots: Schema.Array(Schema.Struct({ modelSlot: Schema.NullOr(Schema.String), ...fields }).check(Schema.makeFilter(consistent))),\n    models: Schema.Array(Schema.Struct({ modelSlot: Schema.NullOr(Schema.String), provider: Schema.NullOr(Schema.String), model: Schema.NullOr(Schema.String), ...fields }).check(Schema.makeFilter(consistent))),\n}).check(Schema.makeFilter((value) => value.modelSlots.length <= 65 && value.models.length <= 4000));\n/** Complete per-Attempt report; unknown model identities remain null. */\nexport type CacheReadReport = typeof CacheReadReportSchema.Type;\nfunction summary(calls: readonly AdapterUsageCall[], collectionComplete: boolean, absent?: Reason): CacheReadSummary {\n    let numerator = 0;\n    let denominator = 0;\n    let coveredCalls = 0;\n    let missingCacheReadCalls = 0;\n    let missingInputTotalCalls = 0;\n    let unknownStatusCalls = 0;\n    let unsafe = false;\n    for (const call of calls) {\n        const total = call.inputTotalTokens ?? (call.inputTokens !== null && call.cacheReadTokens !== null && call.cacheWriteTokens !== null\n            ? call.inputTokens + call.cacheReadTokens + call.cacheWriteTokens : null);\n        if (call.status === \"unknown\")\n            unknownStatusCalls++;\n        if (call.cacheReadTokens === null)\n            missingCacheReadCalls++;\n        else\n            numerator += call.cacheReadTokens;\n        if (total === null)\n            missingInputTotalCalls++;\n        else\n            denominator += total;\n        if (total !== null && call.cacheReadTokens !== null)\n            coveredCalls++;\n        if ((total !== null && !Number.isSafeInteger(total)) || !Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator))\n            unsafe = true;\n    }\n    const reasons: Reason[] = absent === undefined ? [\n        ...(!collectionComplete ? [\"collection-incomplete\" as const] : []),\n        ...(unknownStatusCalls > 0 ? [\"call-status-unknown\" as const] : []),\n        ...(calls.length === 0 ? [\"no-calls\" as const] : []),\n        ...(missingCacheReadCalls > 0 ? [\"cache-read-missing\" as const] : []),\n        ...(missingInputTotalCalls > 0 ? [\"input-total-missing\" as const] : []),\n        ...(calls.length > 0 && missingInputTotalCalls === 0 && denominator === 0 ? [\"zero-input-total\" as const] : []),\n        ...(unsafe ? [\"unsafe-token-total\" as const] : []),\n    ] : [absent];\n    const rate: CacheReadSummary[\"rate\"] = reasons.length === 0\n        ? Object.freeze({ state: \"exact\", value: numerator / denominator })\n        : Object.freeze({ state: \"unavailable\", reason: reasons[0]! });\n    return Object.freeze({ rate, recordedCalls: calls.length, coveredCalls, missingCacheReadCalls, missingInputTotalCalls,\n        unknownStatusCalls, collectionComplete, reasons: Object.freeze(reasons) });\n}\nconst compare = (a: string | null, b: string | null): number => a === b ? 0 : a === null ? -1 : b === null ? 1 : a < b ? -1 : 1;\n/** A historical collection marked complete is not proof of an explicit producer seal. */\nexport function projectCacheRead(usage: ReadableAdapterUsageAttachment | null, slots: ResolvedModelSlots | undefined, producerCompletenessKnown: boolean, absent: \"usage-not-recorded\" | \"source-invalid\" | \"adapter-usage-required\" = \"usage-not-recorded\"): CacheReadReport {\n    if (usage === null)\n        return Object.freeze({ total: summary([], false, absent), modelSlots: Object.freeze([]), models: Object.freeze([]) });\n    const complete = producerCompletenessKnown && usage.collection.state === \"complete\";\n    const bySlot = new Map<string | null, AdapterUsageCall[]>(Object.keys(slots ?? {}).map((slot) => [slot, []]));\n    const byModel = new Map<string, AdapterUsageCall[]>();\n    for (const call of usage.calls) {\n        const slot = bySlot.get(call.modelSlot);\n        if (slot === undefined)\n            bySlot.set(call.modelSlot, [call]);\n        else\n            slot.push(call);\n        const key = JSON.stringify([call.modelSlot, call.provider, call.model]);\n        const model = byModel.get(key);\n        if (model === undefined)\n            byModel.set(key, [call]);\n        else\n            model.push(call);\n    }\n    const models = [...byModel.values()].map((calls) => {\n        const { modelSlot, provider, model } = calls[0]!;\n        return Object.freeze({ modelSlot, provider, model, ...summary(calls, complete) });\n    }).sort((a, b) => compare(a.modelSlot, b.modelSlot) || compare(a.provider, b.provider) || compare(a.model, b.model));\n    return Object.freeze({ total: summary(usage.calls, complete),\n        modelSlots: Object.freeze([...bySlot].sort(([a], [b]) => compare(a, b)).map(([modelSlot, calls]) => Object.freeze({ modelSlot, ...summary(calls, complete) }))),\n        models: Object.freeze(models),\n    });\n}\n"]}

package/dist/o11y/cache-read.d.cts

@@ -0,0 +1,80 @@
+import { Schema } from "effect";
+import type { ResolvedModelSlots } from "../model-slots.cjs";
+import type { ReadableAdapterUsageAttachment } from "../record/family/adapter-usage/schema.cjs";
+declare const Summary: Schema.Struct<{
+    rate: Schema.Union<readonly [Schema.Struct<{
+        readonly state: Schema.Literal<"exact">;
+        readonly value: Schema.Number;
+    }>, Schema.Struct<{
+        readonly state: Schema.Literal<"unavailable">;
+        readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+    }>]>;
+    recordedCalls: Schema.Number;
+    coveredCalls: Schema.Number;
+    missingCacheReadCalls: Schema.Number;
+    missingInputTotalCalls: Schema.Number;
+    unknownStatusCalls: Schema.Number;
+    collectionComplete: Schema.Boolean;
+    reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+}>;
+/** Token-weighted cache reading, with explicit input coverage and collection completeness. */
+export type CacheReadSummary = typeof Summary.Type;
+export declare const CacheReadReportSchema: Schema.Struct<{
+    readonly total: Schema.Struct<{
+        rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        recordedCalls: Schema.Number;
+        coveredCalls: Schema.Number;
+        missingCacheReadCalls: Schema.Number;
+        missingInputTotalCalls: Schema.Number;
+        unknownStatusCalls: Schema.Number;
+        collectionComplete: Schema.Boolean;
+        reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+    }>;
+    readonly modelSlots: Schema.$Array<Schema.Struct<{
+        readonly rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        readonly recordedCalls: Schema.Number;
+        readonly coveredCalls: Schema.Number;
+        readonly missingCacheReadCalls: Schema.Number;
+        readonly missingInputTotalCalls: Schema.Number;
+        readonly unknownStatusCalls: Schema.Number;
+        readonly collectionComplete: Schema.Boolean;
+        readonly reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+        readonly modelSlot: Schema.NullOr<Schema.String>;
+    }>>;
+    readonly models: Schema.$Array<Schema.Struct<{
+        readonly rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        readonly recordedCalls: Schema.Number;
+        readonly coveredCalls: Schema.Number;
+        readonly missingCacheReadCalls: Schema.Number;
+        readonly missingInputTotalCalls: Schema.Number;
+        readonly unknownStatusCalls: Schema.Number;
+        readonly collectionComplete: Schema.Boolean;
+        readonly reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+        readonly modelSlot: Schema.NullOr<Schema.String>;
+        readonly provider: Schema.NullOr<Schema.String>;
+        readonly model: Schema.NullOr<Schema.String>;
+    }>>;
+}>;
+/** Complete per-Attempt report; unknown model identities remain null. */
+export type CacheReadReport = typeof CacheReadReportSchema.Type;
+/** A historical collection marked complete is not proof of an explicit producer seal. */
+export declare function projectCacheRead(usage: ReadableAdapterUsageAttachment | null, slots: ResolvedModelSlots | undefined, producerCompletenessKnown: boolean, absent?: "usage-not-recorded" | "source-invalid" | "adapter-usage-required"): CacheReadReport;
+export {};

package/dist/o11y/cache-read.d.mts

@@ -0,0 +1,80 @@
+import { Schema } from "effect";
+import type { ResolvedModelSlots } from "../model-slots.mjs";
+import type { ReadableAdapterUsageAttachment } from "../record/family/adapter-usage/schema.mjs";
+declare const Summary: Schema.Struct<{
+    rate: Schema.Union<readonly [Schema.Struct<{
+        readonly state: Schema.Literal<"exact">;
+        readonly value: Schema.Number;
+    }>, Schema.Struct<{
+        readonly state: Schema.Literal<"unavailable">;
+        readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+    }>]>;
+    recordedCalls: Schema.Number;
+    coveredCalls: Schema.Number;
+    missingCacheReadCalls: Schema.Number;
+    missingInputTotalCalls: Schema.Number;
+    unknownStatusCalls: Schema.Number;
+    collectionComplete: Schema.Boolean;
+    reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+}>;
+/** Token-weighted cache reading, with explicit input coverage and collection completeness. */
+export type CacheReadSummary = typeof Summary.Type;
+export declare const CacheReadReportSchema: Schema.Struct<{
+    readonly total: Schema.Struct<{
+        rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        recordedCalls: Schema.Number;
+        coveredCalls: Schema.Number;
+        missingCacheReadCalls: Schema.Number;
+        missingInputTotalCalls: Schema.Number;
+        unknownStatusCalls: Schema.Number;
+        collectionComplete: Schema.Boolean;
+        reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+    }>;
+    readonly modelSlots: Schema.$Array<Schema.Struct<{
+        readonly rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        readonly recordedCalls: Schema.Number;
+        readonly coveredCalls: Schema.Number;
+        readonly missingCacheReadCalls: Schema.Number;
+        readonly missingInputTotalCalls: Schema.Number;
+        readonly unknownStatusCalls: Schema.Number;
+        readonly collectionComplete: Schema.Boolean;
+        readonly reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+        readonly modelSlot: Schema.NullOr<Schema.String>;
+    }>>;
+    readonly models: Schema.$Array<Schema.Struct<{
+        readonly rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        readonly recordedCalls: Schema.Number;
+        readonly coveredCalls: Schema.Number;
+        readonly missingCacheReadCalls: Schema.Number;
+        readonly missingInputTotalCalls: Schema.Number;
+        readonly unknownStatusCalls: Schema.Number;
+        readonly collectionComplete: Schema.Boolean;
+        readonly reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+        readonly modelSlot: Schema.NullOr<Schema.String>;
+        readonly provider: Schema.NullOr<Schema.String>;
+        readonly model: Schema.NullOr<Schema.String>;
+    }>>;
+}>;
+/** Complete per-Attempt report; unknown model identities remain null. */
+export type CacheReadReport = typeof CacheReadReportSchema.Type;
+/** A historical collection marked complete is not proof of an explicit producer seal. */
+export declare function projectCacheRead(usage: ReadableAdapterUsageAttachment | null, slots: ResolvedModelSlots | undefined, producerCompletenessKnown: boolean, absent?: "usage-not-recorded" | "source-invalid" | "adapter-usage-required"): CacheReadReport;
+export {};

package/dist/o11y/cache-read.d.ts

@@ -0,0 +1,80 @@
+import { Schema } from "effect";
+import type { ResolvedModelSlots } from "../model-slots.js";
+import type { ReadableAdapterUsageAttachment } from "../record/family/adapter-usage/schema.js";
+declare const Summary: Schema.Struct<{
+    rate: Schema.Union<readonly [Schema.Struct<{
+        readonly state: Schema.Literal<"exact">;
+        readonly value: Schema.Number;
+    }>, Schema.Struct<{
+        readonly state: Schema.Literal<"unavailable">;
+        readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+    }>]>;
+    recordedCalls: Schema.Number;
+    coveredCalls: Schema.Number;
+    missingCacheReadCalls: Schema.Number;
+    missingInputTotalCalls: Schema.Number;
+    unknownStatusCalls: Schema.Number;
+    collectionComplete: Schema.Boolean;
+    reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+}>;
+/** Token-weighted cache reading, with explicit input coverage and collection completeness. */
+export type CacheReadSummary = typeof Summary.Type;
+export declare const CacheReadReportSchema: Schema.Struct<{
+    readonly total: Schema.Struct<{
+        rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        recordedCalls: Schema.Number;
+        coveredCalls: Schema.Number;
+        missingCacheReadCalls: Schema.Number;
+        missingInputTotalCalls: Schema.Number;
+        unknownStatusCalls: Schema.Number;
+        collectionComplete: Schema.Boolean;
+        reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+    }>;
+    readonly modelSlots: Schema.$Array<Schema.Struct<{
+        readonly rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        readonly recordedCalls: Schema.Number;
+        readonly coveredCalls: Schema.Number;
+        readonly missingCacheReadCalls: Schema.Number;
+        readonly missingInputTotalCalls: Schema.Number;
+        readonly unknownStatusCalls: Schema.Number;
+        readonly collectionComplete: Schema.Boolean;
+        readonly reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+        readonly modelSlot: Schema.NullOr<Schema.String>;
+    }>>;
+    readonly models: Schema.$Array<Schema.Struct<{
+        readonly rate: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"exact">;
+            readonly value: Schema.Number;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"unavailable">;
+            readonly reason: Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>;
+        }>]>;
+        readonly recordedCalls: Schema.Number;
+        readonly coveredCalls: Schema.Number;
+        readonly missingCacheReadCalls: Schema.Number;
+        readonly missingInputTotalCalls: Schema.Number;
+        readonly unknownStatusCalls: Schema.Number;
+        readonly collectionComplete: Schema.Boolean;
+        readonly reasons: Schema.$Array<Schema.Literals<readonly ["usage-not-recorded", "source-invalid", "adapter-usage-required", "collection-incomplete", "call-status-unknown", "no-calls", "cache-read-missing", "input-total-missing", "zero-input-total", "unsafe-token-total"]>>;
+        readonly modelSlot: Schema.NullOr<Schema.String>;
+        readonly provider: Schema.NullOr<Schema.String>;
+        readonly model: Schema.NullOr<Schema.String>;
+    }>>;
+}>;
+/** Complete per-Attempt report; unknown model identities remain null. */
+export type CacheReadReport = typeof CacheReadReportSchema.Type;
+/** A historical collection marked complete is not proof of an explicit producer seal. */
+export declare function projectCacheRead(usage: ReadableAdapterUsageAttachment | null, slots: ResolvedModelSlots | undefined, producerCompletenessKnown: boolean, absent?: "usage-not-recorded" | "source-invalid" | "adapter-usage-required"): CacheReadReport;
+export {};

package/dist/o11y/cache-read.js

@@ -0,0 +1,8 @@
+import { createRequire as __niceevalCreateRequire } from "node:module";
+const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
+const __niceevalCanonical = __niceevalRequire("./cache-read.cjs");
+const __niceevalExport0 = __niceevalCanonical["CacheReadReportSchema"];
+export { __niceevalExport0 as CacheReadReportSchema };
+const __niceevalExport1 = __niceevalCanonical["projectCacheRead"];
+export { __niceevalExport1 as projectCacheRead };
+//# sourceMappingURL=cache-read.js.map

package/dist/o11y/cache-read.js.map

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

package/dist/o11y/eval-usage.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectAdapterEvalUsage = projectAdapterEvalUsage;
 exports.projectAgentEvalUsage = projectAgentEvalUsage;
+const cache_read_ts_1 = require("./cache-read.cjs");
 const pricing_ts_1 = require("../record/family/adapter-usage/pricing.cjs");
 const adapter_usage_projection_ts_1 = require("./adapter-usage-projection.cjs");
 function contributionCosts(calls, complete) {
@@ -19,12 +20,13 @@ function contributionCosts(calls, complete) {
         totalContributions: totals.totalCalls,
     });
 }
-function projectAdapterEvalUsage(usage) {
+function projectAdapterEvalUsage(usage, models) {
     return Object.freeze({
         source: "adapter",
         scope: "attempt",
         basis: "recorded-calls",
         cut: "call-time",
+        cacheRead: (0, cache_read_ts_1.projectCacheRead)(usage, models, true),
         inputTokens: (0, adapter_usage_projection_ts_1.adapterTokenMaterial)(usage, "inputTokens"),
         inputTotalTokens: (0, adapter_usage_projection_ts_1.adapterTokenMaterial)(usage, "inputTotalTokens"),
         outputTokens: (0, adapter_usage_projection_ts_1.adapterTokenMaterial)(usage, "outputTokens"),
@@ -135,6 +137,7 @@ function projectAgentEvalUsage(input) {
         scope: input.scope,
         basis: "reported-sends",
         cut: "call-time",
+        cacheRead: (0, cache_read_ts_1.projectCacheRead)(null, undefined, false, "adapter-usage-required"),
         inputTokens: agentTokenMaterial(input.contributions, "inputTokens", input.scope),
         inputTotalTokens: agentTokenMaterial(input.contributions, "inputTotalTokens", input.scope),
         outputTokens: agentTokenMaterial(input.contributions, "outputTokens", input.scope),

package/dist/o11y/eval-usage.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"eval-usage.js","sourceRoot":"","sources":["eval-usage.ts"],"names":[],"mappings":"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","sourcesContent":["import type { NumericMaterial } from \"../assertions/match.ts\";\nimport type { ResolvedEvidenceCoverage } from \"../assertions/coverage.ts\";\nimport type { PriceOverride, Usage } from \"../types.ts\";\nimport type { ReadableAdapterUsageAttachment } from \"../record/family/adapter-usage/schema.ts\";\nimport { addCanonicalDecimals, canonicalDecimalFromNumber, multiplyCanonicalDecimalPerMillion, } from \"../record/family/adapter-usage/pricing.ts\";\nimport { adapterTokenMaterial, effectiveCostTotals, effectiveUsageCalls, type EffectiveCallCost, } from \"./adapter-usage-projection.ts\";\n/** Internal source-owned shape; package-root exposure belongs to the author facade. */\nexport interface EvalUsage {\n    readonly source: \"agent\" | \"adapter\" | \"unavailable\";\n    readonly scope: \"turn\" | \"session\" | \"attempt\";\n    readonly basis: \"reported-sends\" | \"recorded-calls\" | \"unbound\";\n    readonly cut: \"call-time\";\n    readonly inputTokens: NumericMaterial;\n    readonly inputTotalTokens: NumericMaterial;\n    readonly outputTokens: NumericMaterial;\n    readonly cacheReadTokens: NumericMaterial;\n    readonly cacheWriteTokens: NumericMaterial;\n    readonly totalTokens: NumericMaterial;\n    readonly costs: {\n        readonly state: \"complete\" | \"partial\" | \"unavailable\";\n        readonly values: readonly {\n            readonly currency: string;\n            readonly value: string;\n            readonly source: \"reported\" | \"estimated\" | \"mixed\";\n            readonly coveredContributions: number;\n            readonly reportedContributions: number;\n            readonly estimatedContributions: number;\n        }[];\n        readonly totalContributions: number;\n    };\n}\nexport interface AgentUsageContribution {\n    readonly sessionScopeId: string;\n    readonly turnId: string;\n    readonly sendAttempt: number;\n    readonly state: \"pending\" | \"terminal\";\n    readonly outcome: \"completed\" | \"failed\" | \"interrupted\" | null;\n    readonly model: string | null;\n    readonly usage: Readonly<Usage> | null;\n    readonly coverage: ResolvedEvidenceCoverage[\"usage\"];\n}\ntype TokenMetric = \"inputTokens\" | \"inputTotalTokens\" | \"outputTokens\" | \"cacheReadTokens\" | \"cacheWriteTokens\" | \"totalTokens\";\nfunction contributionCosts(calls: readonly {\n    readonly effectiveCost: EffectiveCallCost | null;\n}[], complete: boolean): EvalUsage[\"costs\"] {\n    const totals = effectiveCostTotals(calls, complete ? \"complete\" : \"partial\");\n    return Object.freeze({\n        state: totals.state,\n        values: Object.freeze(totals.values.map((value) => Object.freeze({\n            currency: value.currency,\n            value: value.value,\n            source: value.source,\n            coveredContributions: value.coveredCalls,\n            reportedContributions: value.reportedCalls,\n            estimatedContributions: value.estimatedCalls,\n        }))),\n        totalContributions: totals.totalCalls,\n    });\n}\nexport function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment): EvalUsage {\n    return Object.freeze({\n        source: \"adapter\",\n        scope: \"attempt\",\n        basis: \"recorded-calls\",\n        cut: \"call-time\",\n        inputTokens: adapterTokenMaterial(usage, \"inputTokens\"),\n        inputTotalTokens: adapterTokenMaterial(usage, \"inputTotalTokens\"),\n        outputTokens: adapterTokenMaterial(usage, \"outputTokens\"),\n        cacheReadTokens: adapterTokenMaterial(usage, \"cacheReadTokens\"),\n        cacheWriteTokens: adapterTokenMaterial(usage, \"cacheWriteTokens\"),\n        totalTokens: adapterTokenMaterial(usage, \"totalTokens\"),\n        costs: contributionCosts(effectiveUsageCalls(usage), usage.collection.state === \"complete\"),\n    });\n}\nfunction tokenBuckets(contribution: AgentUsageContribution, metric: TokenMetric): readonly (number | undefined)[] {\n    // Some producers have an independent total. Missing totals retain the mutually exclusive bucket fallback.\n    const usage: (Readonly<Usage> & {\n        readonly inputTotalTokens?: number;\n    }) | null = contribution.usage;\n    if (contribution.state === \"pending\" || usage === null)\n        return [undefined];\n    const input = usage.inputTotalTokens !== undefined\n        ? [usage.inputTotalTokens]\n        : [usage.inputTokens, usage.cacheReadTokens, usage.cacheCreationTokens];\n    switch (metric) {\n        case \"inputTotalTokens\": return input;\n        case \"totalTokens\": return [...input, usage.outputTokens];\n        case \"cacheWriteTokens\": return [usage.cacheCreationTokens];\n        default: return [usage[metric]];\n    }\n}\nfunction agentTokenMaterial(contributions: readonly AgentUsageContribution[], metric: TokenMetric, scope: EvalUsage[\"scope\"]): NumericMaterial {\n    const provenance = Object.freeze({ source: \"agent\", scope, unit: \"tokens\", cut: \"call-time\" });\n    let value = 0;\n    let observed = false;\n    let complete = contributions.length > 0;\n    for (const contribution of contributions) {\n        if (contribution.state !== \"terminal\" || contribution.coverage.status !== \"complete\")\n            complete = false;\n        for (const bucket of tokenBuckets(contribution, metric)) {\n            if (bucket === undefined) {\n                complete = false;\n                continue;\n            }\n            if (!Number.isSafeInteger(bucket) || bucket < 0) {\n                return Object.freeze({ state: \"unavailable\", reason: \"usage-invalid-token-value\", provenance });\n            }\n            value += bucket;\n            observed = true;\n            if (!Number.isSafeInteger(value)) {\n                return Object.freeze({ state: \"unavailable\", reason: \"usage-exceeds-safe-integer\", provenance });\n            }\n        }\n    }\n    return Object.freeze(!observed\n        ? { state: \"unavailable\", reason: \"usage-not-reported\", provenance }\n        : { state: complete ? \"exact\" : \"lower-bound\", value, provenance });\n}\nfunction agentCost(contribution: AgentUsageContribution, pricing: Record<string, PriceOverride> | undefined): EffectiveCallCost | null {\n    const usage = contribution.usage;\n    if (contribution.state === \"pending\" || usage === null)\n        return null;\n    const coverageComplete = contribution.coverage.status === \"complete\";\n    if (usage.costUSD !== undefined) {\n        const amount = canonicalDecimalFromNumber(usage.costUSD);\n        return amount === undefined ? null : Object.freeze({\n            amount, currency: \"USD\", source: Object.freeze({ kind: \"reported\", id: \"agent-send\" }),\n            state: coverageComplete ? \"complete\" : \"partial\",\n        });\n    }\n    const model = contribution.model;\n    if (model === null || pricing === undefined)\n        return null;\n    const wildcard = model.includes(\"/\") ? `${model.slice(0, model.indexOf(\"/\"))}/*` : undefined;\n    const profile = Object.hasOwn(pricing, model) ? pricing[model]\n        : wildcard !== undefined && Object.hasOwn(pricing, wildcard) ? pricing[wildcard] : undefined;\n    if (profile === undefined || profile.currency !== undefined && profile.currency !== \"USD\" ||\n        profile.basis !== undefined && profile.basis !== \"catalog-reference\")\n        return null;\n    const buckets = [\n        [usage.inputTokens, profile.inputPerMTok],\n        [usage.outputTokens, profile.outputPerMTok],\n        [usage.cacheReadTokens, profile.cacheReadPerMTok],\n        [usage.cacheCreationTokens, profile.cacheWritePerMTok],\n    ] as const;\n    const charges: string[] = [];\n    let complete = coverageComplete;\n    for (const [tokens, price] of buckets) {\n        if (tokens === undefined || !Number.isSafeInteger(tokens) || tokens < 0) {\n            complete = false;\n            continue;\n        }\n        if (tokens === 0) {\n            charges.push(\"0\");\n            continue;\n        }\n        const rate = price === undefined ? undefined : canonicalDecimalFromNumber(price);\n        if (rate === undefined) {\n            complete = false;\n            continue;\n        }\n        charges.push(multiplyCanonicalDecimalPerMillion(rate, tokens));\n    }\n    return charges.length === 0 ? null : Object.freeze({\n        amount: addCanonicalDecimals(charges),\n        currency: \"USD\",\n        source: Object.freeze({ kind: \"estimated\", id: profile.source?.id ?? \"niceeval.config.pricing\" }),\n        state: complete ? \"complete\" : \"partial\",\n    });\n}\n/** The receiver selects scope membership before calling this pure projection. */\nexport function projectAgentEvalUsage(input: {\n    contributions: readonly AgentUsageContribution[];\n    scope: \"turn\" | \"session\" | \"attempt\";\n    pricing?: Record<string, PriceOverride>;\n}): EvalUsage {\n    return Object.freeze({\n        source: \"agent\",\n        scope: input.scope,\n        basis: \"reported-sends\",\n        cut: \"call-time\",\n        inputTokens: agentTokenMaterial(input.contributions, \"inputTokens\", input.scope),\n        inputTotalTokens: agentTokenMaterial(input.contributions, \"inputTotalTokens\", input.scope),\n        outputTokens: agentTokenMaterial(input.contributions, \"outputTokens\", input.scope),\n        cacheReadTokens: agentTokenMaterial(input.contributions, \"cacheReadTokens\", input.scope),\n        cacheWriteTokens: agentTokenMaterial(input.contributions, \"cacheWriteTokens\", input.scope),\n        totalTokens: agentTokenMaterial(input.contributions, \"totalTokens\", input.scope),\n        costs: contributionCosts(input.contributions.map((contribution) => ({\n            effectiveCost: agentCost(contribution, input.pricing),\n        })), input.contributions.every((contribution) => contribution.state === \"terminal\" && contribution.coverage.status === \"complete\")),\n    });\n}\n"]}
+{"version":3,"file":"eval-usage.js","sourceRoot":"","sources":["eval-usage.ts"],"names":[],"mappings":"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","sourcesContent":["import { projectCacheRead, type CacheReadReport } from \"./cache-read.ts\";\nimport type { ResolvedModelSlots } from \"../model-slots.ts\";\nimport type { NumericMaterial } from \"../assertions/match.ts\";\nimport type { ResolvedEvidenceCoverage } from \"../assertions/coverage.ts\";\nimport type { PriceOverride, Usage } from \"../types.ts\";\nimport type { ReadableAdapterUsageAttachment } from \"../record/family/adapter-usage/schema.ts\";\nimport { addCanonicalDecimals, canonicalDecimalFromNumber, multiplyCanonicalDecimalPerMillion, } from \"../record/family/adapter-usage/pricing.ts\";\nimport { adapterTokenMaterial, effectiveCostTotals, effectiveUsageCalls, type EffectiveCallCost, } from \"./adapter-usage-projection.ts\";\n/** Internal source-owned shape; package-root exposure belongs to the author facade. */\nexport interface EvalUsage {\n    readonly source: \"agent\" | \"adapter\" | \"unavailable\";\n    readonly scope: \"turn\" | \"session\" | \"attempt\";\n    readonly basis: \"reported-sends\" | \"recorded-calls\" | \"unbound\";\n    readonly cut: \"call-time\";\n    readonly cacheRead: CacheReadReport;\n    readonly inputTokens: NumericMaterial;\n    readonly inputTotalTokens: NumericMaterial;\n    readonly outputTokens: NumericMaterial;\n    readonly cacheReadTokens: NumericMaterial;\n    readonly cacheWriteTokens: NumericMaterial;\n    readonly totalTokens: NumericMaterial;\n    readonly costs: {\n        readonly state: \"complete\" | \"partial\" | \"unavailable\";\n        readonly values: readonly {\n            readonly currency: string;\n            readonly value: string;\n            readonly source: \"reported\" | \"estimated\" | \"mixed\";\n            readonly coveredContributions: number;\n            readonly reportedContributions: number;\n            readonly estimatedContributions: number;\n        }[];\n        readonly totalContributions: number;\n    };\n}\nexport interface AgentUsageContribution {\n    readonly sessionScopeId: string;\n    readonly turnId: string;\n    readonly sendAttempt: number;\n    readonly state: \"pending\" | \"terminal\";\n    readonly outcome: \"completed\" | \"failed\" | \"interrupted\" | null;\n    readonly model: string | null;\n    readonly usage: Readonly<Usage> | null;\n    readonly coverage: ResolvedEvidenceCoverage[\"usage\"];\n}\ntype TokenMetric = \"inputTokens\" | \"inputTotalTokens\" | \"outputTokens\" | \"cacheReadTokens\" | \"cacheWriteTokens\" | \"totalTokens\";\nfunction contributionCosts(calls: readonly {\n    readonly effectiveCost: EffectiveCallCost | null;\n}[], complete: boolean): EvalUsage[\"costs\"] {\n    const totals = effectiveCostTotals(calls, complete ? \"complete\" : \"partial\");\n    return Object.freeze({\n        state: totals.state,\n        values: Object.freeze(totals.values.map((value) => Object.freeze({\n            currency: value.currency,\n            value: value.value,\n            source: value.source,\n            coveredContributions: value.coveredCalls,\n            reportedContributions: value.reportedCalls,\n            estimatedContributions: value.estimatedCalls,\n        }))),\n        totalContributions: totals.totalCalls,\n    });\n}\nexport function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment, models?: ResolvedModelSlots): EvalUsage {\n    return Object.freeze({\n        source: \"adapter\",\n        scope: \"attempt\",\n        basis: \"recorded-calls\",\n        cut: \"call-time\",\n        cacheRead: projectCacheRead(usage, models, true),\n        inputTokens: adapterTokenMaterial(usage, \"inputTokens\"),\n        inputTotalTokens: adapterTokenMaterial(usage, \"inputTotalTokens\"),\n        outputTokens: adapterTokenMaterial(usage, \"outputTokens\"),\n        cacheReadTokens: adapterTokenMaterial(usage, \"cacheReadTokens\"),\n        cacheWriteTokens: adapterTokenMaterial(usage, \"cacheWriteTokens\"),\n        totalTokens: adapterTokenMaterial(usage, \"totalTokens\"),\n        costs: contributionCosts(effectiveUsageCalls(usage), usage.collection.state === \"complete\"),\n    });\n}\nfunction tokenBuckets(contribution: AgentUsageContribution, metric: TokenMetric): readonly (number | undefined)[] {\n    // Some producers have an independent total. Missing totals retain the mutually exclusive bucket fallback.\n    const usage: (Readonly<Usage> & {\n        readonly inputTotalTokens?: number;\n    }) | null = contribution.usage;\n    if (contribution.state === \"pending\" || usage === null)\n        return [undefined];\n    const input = usage.inputTotalTokens !== undefined\n        ? [usage.inputTotalTokens]\n        : [usage.inputTokens, usage.cacheReadTokens, usage.cacheCreationTokens];\n    switch (metric) {\n        case \"inputTotalTokens\": return input;\n        case \"totalTokens\": return [...input, usage.outputTokens];\n        case \"cacheWriteTokens\": return [usage.cacheCreationTokens];\n        default: return [usage[metric]];\n    }\n}\nfunction agentTokenMaterial(contributions: readonly AgentUsageContribution[], metric: TokenMetric, scope: EvalUsage[\"scope\"]): NumericMaterial {\n    const provenance = Object.freeze({ source: \"agent\", scope, unit: \"tokens\", cut: \"call-time\" });\n    let value = 0;\n    let observed = false;\n    let complete = contributions.length > 0;\n    for (const contribution of contributions) {\n        if (contribution.state !== \"terminal\" || contribution.coverage.status !== \"complete\")\n            complete = false;\n        for (const bucket of tokenBuckets(contribution, metric)) {\n            if (bucket === undefined) {\n                complete = false;\n                continue;\n            }\n            if (!Number.isSafeInteger(bucket) || bucket < 0) {\n                return Object.freeze({ state: \"unavailable\", reason: \"usage-invalid-token-value\", provenance });\n            }\n            value += bucket;\n            observed = true;\n            if (!Number.isSafeInteger(value)) {\n                return Object.freeze({ state: \"unavailable\", reason: \"usage-exceeds-safe-integer\", provenance });\n            }\n        }\n    }\n    return Object.freeze(!observed\n        ? { state: \"unavailable\", reason: \"usage-not-reported\", provenance }\n        : { state: complete ? \"exact\" : \"lower-bound\", value, provenance });\n}\nfunction agentCost(contribution: AgentUsageContribution, pricing: Record<string, PriceOverride> | undefined): EffectiveCallCost | null {\n    const usage = contribution.usage;\n    if (contribution.state === \"pending\" || usage === null)\n        return null;\n    const coverageComplete = contribution.coverage.status === \"complete\";\n    if (usage.costUSD !== undefined) {\n        const amount = canonicalDecimalFromNumber(usage.costUSD);\n        return amount === undefined ? null : Object.freeze({\n            amount, currency: \"USD\", source: Object.freeze({ kind: \"reported\", id: \"agent-send\" }),\n            state: coverageComplete ? \"complete\" : \"partial\",\n        });\n    }\n    const model = contribution.model;\n    if (model === null || pricing === undefined)\n        return null;\n    const wildcard = model.includes(\"/\") ? `${model.slice(0, model.indexOf(\"/\"))}/*` : undefined;\n    const profile = Object.hasOwn(pricing, model) ? pricing[model]\n        : wildcard !== undefined && Object.hasOwn(pricing, wildcard) ? pricing[wildcard] : undefined;\n    if (profile === undefined || profile.currency !== undefined && profile.currency !== \"USD\" ||\n        profile.basis !== undefined && profile.basis !== \"catalog-reference\")\n        return null;\n    const buckets = [\n        [usage.inputTokens, profile.inputPerMTok],\n        [usage.outputTokens, profile.outputPerMTok],\n        [usage.cacheReadTokens, profile.cacheReadPerMTok],\n        [usage.cacheCreationTokens, profile.cacheWritePerMTok],\n    ] as const;\n    const charges: string[] = [];\n    let complete = coverageComplete;\n    for (const [tokens, price] of buckets) {\n        if (tokens === undefined || !Number.isSafeInteger(tokens) || tokens < 0) {\n            complete = false;\n            continue;\n        }\n        if (tokens === 0) {\n            charges.push(\"0\");\n            continue;\n        }\n        const rate = price === undefined ? undefined : canonicalDecimalFromNumber(price);\n        if (rate === undefined) {\n            complete = false;\n            continue;\n        }\n        charges.push(multiplyCanonicalDecimalPerMillion(rate, tokens));\n    }\n    return charges.length === 0 ? null : Object.freeze({\n        amount: addCanonicalDecimals(charges),\n        currency: \"USD\",\n        source: Object.freeze({ kind: \"estimated\", id: profile.source?.id ?? \"niceeval.config.pricing\" }),\n        state: complete ? \"complete\" : \"partial\",\n    });\n}\n/** The receiver selects scope membership before calling this pure projection. */\nexport function projectAgentEvalUsage(input: {\n    contributions: readonly AgentUsageContribution[];\n    scope: \"turn\" | \"session\" | \"attempt\";\n    pricing?: Record<string, PriceOverride>;\n}): EvalUsage {\n    return Object.freeze({\n        source: \"agent\",\n        scope: input.scope,\n        basis: \"reported-sends\",\n        cut: \"call-time\",\n        cacheRead: projectCacheRead(null, undefined, false, \"adapter-usage-required\"),\n        inputTokens: agentTokenMaterial(input.contributions, \"inputTokens\", input.scope),\n        inputTotalTokens: agentTokenMaterial(input.contributions, \"inputTotalTokens\", input.scope),\n        outputTokens: agentTokenMaterial(input.contributions, \"outputTokens\", input.scope),\n        cacheReadTokens: agentTokenMaterial(input.contributions, \"cacheReadTokens\", input.scope),\n        cacheWriteTokens: agentTokenMaterial(input.contributions, \"cacheWriteTokens\", input.scope),\n        totalTokens: agentTokenMaterial(input.contributions, \"totalTokens\", input.scope),\n        costs: contributionCosts(input.contributions.map((contribution) => ({\n            effectiveCost: agentCost(contribution, input.pricing),\n        })), input.contributions.every((contribution) => contribution.state === \"terminal\" && contribution.coverage.status === \"complete\")),\n    });\n}\n"]}

package/dist/o11y/eval-usage.d.cts

@@ -1,3 +1,5 @@
+import { type CacheReadReport } from "./cache-read.cjs";
+import type { ResolvedModelSlots } from "../model-slots.cjs";
 import type { NumericMaterial } from "../assertions/match.cjs";
 import type { ResolvedEvidenceCoverage } from "../assertions/coverage.cjs";
 import type { PriceOverride, Usage } from "../types.cjs";
@@ -8,6 +10,7 @@ export interface EvalUsage {
     readonly scope: "turn" | "session" | "attempt";
     readonly basis: "reported-sends" | "recorded-calls" | "unbound";
     readonly cut: "call-time";
+    readonly cacheRead: CacheReadReport;
     readonly inputTokens: NumericMaterial;
     readonly inputTotalTokens: NumericMaterial;
     readonly outputTokens: NumericMaterial;
@@ -37,7 +40,7 @@ export interface AgentUsageContribution {
     readonly usage: Readonly<Usage> | null;
     readonly coverage: ResolvedEvidenceCoverage["usage"];
 }
-export declare function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment): EvalUsage;
+export declare function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment, models?: ResolvedModelSlots): EvalUsage;
 /** The receiver selects scope membership before calling this pure projection. */
 export declare function projectAgentEvalUsage(input: {
     contributions: readonly AgentUsageContribution[];

package/dist/o11y/eval-usage.d.mts

@@ -1,3 +1,5 @@
+import { type CacheReadReport } from "./cache-read.mjs";
+import type { ResolvedModelSlots } from "../model-slots.mjs";
 import type { NumericMaterial } from "../assertions/match.mjs";
 import type { ResolvedEvidenceCoverage } from "../assertions/coverage.mjs";
 import type { PriceOverride, Usage } from "../types.mjs";
@@ -8,6 +10,7 @@ export interface EvalUsage {
     readonly scope: "turn" | "session" | "attempt";
     readonly basis: "reported-sends" | "recorded-calls" | "unbound";
     readonly cut: "call-time";
+    readonly cacheRead: CacheReadReport;
     readonly inputTokens: NumericMaterial;
     readonly inputTotalTokens: NumericMaterial;
     readonly outputTokens: NumericMaterial;
@@ -37,7 +40,7 @@ export interface AgentUsageContribution {
     readonly usage: Readonly<Usage> | null;
     readonly coverage: ResolvedEvidenceCoverage["usage"];
 }
-export declare function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment): EvalUsage;
+export declare function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment, models?: ResolvedModelSlots): EvalUsage;
 /** The receiver selects scope membership before calling this pure projection. */
 export declare function projectAgentEvalUsage(input: {
     contributions: readonly AgentUsageContribution[];

package/dist/o11y/eval-usage.d.ts

@@ -1,3 +1,5 @@
+import { type CacheReadReport } from "./cache-read.js";
+import type { ResolvedModelSlots } from "../model-slots.js";
 import type { NumericMaterial } from "../assertions/match.js";
 import type { ResolvedEvidenceCoverage } from "../assertions/coverage.js";
 import type { PriceOverride, Usage } from "../types.js";
@@ -8,6 +10,7 @@ export interface EvalUsage {
     readonly scope: "turn" | "session" | "attempt";
     readonly basis: "reported-sends" | "recorded-calls" | "unbound";
     readonly cut: "call-time";
+    readonly cacheRead: CacheReadReport;
     readonly inputTokens: NumericMaterial;
     readonly inputTotalTokens: NumericMaterial;
     readonly outputTokens: NumericMaterial;
@@ -37,7 +40,7 @@ export interface AgentUsageContribution {
     readonly usage: Readonly<Usage> | null;
     readonly coverage: ResolvedEvidenceCoverage["usage"];
 }
-export declare function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment): EvalUsage;
+export declare function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment, models?: ResolvedModelSlots): EvalUsage;
 /** The receiver selects scope membership before calling this pure projection. */
 export declare function projectAgentEvalUsage(input: {
     contributions: readonly AgentUsageContribution[];