agentfootprint 9.57.0 → 9.59.0

package/dist/esm/cache/cacheRecorder.d.ts

@@ -1,58 +1,96 @@
 /**
- * cacheRecorder() — observability for the v2.6 cache layer.
+ * cacheRecorder() — the cache layer's meter.
  *
  * Subscribes to:
- *   - `FlowRecorder.onDecision` — captures CacheGate routing decisions
- *     (apply-markers / no-markers + the rule that fired + evidence
- *     from `decide()`). Read directly from `event.evidence.rules[matched]`
- *     since footprintjs already auto-captures predicate `inputs[]`.
- *   - `agentfootprint.stream.llm_end` events — read provider's `usage`
- *     and call the agent's CacheStrategy.extractMetrics() to normalize
- *     into CacheMetrics (cacheReadTokens / cacheWriteTokens / fresh).
+ *   - `FlowRecorder.onDecision` — CacheGate routing decisions
+ *     (apply-markers / no-markers + the rule that fired + evidence from
+ *     `decide()`).
+ *   - `agentfootprint.stream.llm_end` — reads that event's `usage` (the PORT
+ *     shape: `{ input, output, cacheRead?, cacheWrite? }`) and asks the
+ *     agent's `CacheStrategy.extractMetrics` what is known about it.
  *
- * Produces:
- *   - per-iteration `agentfootprint.cache.applied` events (markers
- *     applied this iter or empty if skipped) — for Lens trace
- *   - per-iteration `agentfootprint.cache.metrics` events (hit/write
- *     token counts + estimated dollars via PricingTable) — for
- *     dashboards
- *   - a turn-end summary printable via `recorder.report()` —
- *     numeric tally plus dollars saved
+ * Produces: a per-turn report via `recorder.report()` — token tallies, hit
+ * rate and dollar estimates, each carried as a `Claim` so an UNMEASURED turn
+ * can never render as a zero one.
  *
- * v2.6 LIMITATION: doesn't yet write `scope.recentHitRate` back into
- * agent state. CacheGate's hit-rate-floor rule won't fire automatically;
- * consumers can manually wire feedback via `Agent.create(...).attach(rec)`.
- * Full feedback loop deferred to v2.7 (needs an agent-side accessor
- * convention since recorders don't normally write to scope).
+ * ── Why every number here is a Claim (9.59.0) ─────────────────────────
+ * The shipped 9.58.0 meter reported `hitRate: 0` for a 20-call turn that hit
+ * cache on every call. Two faults, and the second is why the first went
+ * unnoticed for so long: (1) the strategies parsed RAW WIRE field names off a
+ * value that carries the PORT shape, so every field read `undefined`; (2) the
+ * report typed its aggregates as bare `number`, so "nobody measured" and
+ * "measured, and it was zero" rendered identically. Fixing (1) alone would
+ * have left a meter that still cannot say "unmeasured" — hence `Claim<T>`,
+ * plus `measuredIterations` / `unmeasuredIterations` so a rate computed from
+ * 3 of 20 calls states its own denominator.
+ *
+ * Read the number through `isKnown(report.hitRate)` (or `describeClaim` for a
+ * one-line render). There is deliberately no door that hands you a bare
+ * number without your having branched.
+ *
+ * ── What this recorder does NOT do ────────────────────────────────────
+ * It emits no events. (Earlier prose here promised per-iteration
+ * `agentfootprint.cache.applied` / `agentfootprint.cache.metrics` events;
+ * neither name has ever existed in the event registry and no `typedEmit` has
+ * ever been in this file. The prose was the bug.)
+ *
+ * It does not write `scope.recentHitRate` back into agent state either, so
+ * CacheGate's hit-rate-floor rule never fires on its own — the loop is
+ * severed at both ends (the key is seeded `undefined` and written by
+ * nothing). Recorders do not write to chart scope, so closing that loop needs
+ * an agent-side accessor convention; it is separable work from measuring the
+ * number, which is what this file now does.
  */
 import type { CombinedRecorder } from 'footprintjs';
 import type { CacheMetrics, CacheStrategy } from './types.js';
 import type { PricingTable } from '../adapters/types.js';
-interface PerIterEntry {
+import { type Claim } from '../lib/claim/claim.js';
+/** One LLM call's row on the record. */
+export interface PerIterEntry {
     readonly iteration: number;
     readonly branch: 'apply-markers' | 'no-markers';
     readonly rule?: string;
-    readonly metrics?: CacheMetrics;
-    readonly dollarsSpent: number;
-    readonly dollarsSavedVsNoCache: number;
+    /**
+     * What the strategy could say about this call's cache traffic. `known` =
+     * the provider reported counts; `unknown` = nothing was measured;
+     * `not-applicable` = this adapter cannot report cache usage at all.
+     */
+    readonly metrics: Claim<CacheMetrics>;
+    /** Dollar estimates, `unknown` on any call whose metrics were not known. */
+    readonly dollarsSpent: Claim<number>;
+    readonly dollarsSavedVsNoCache: Claim<number>;
 }
-interface CacheReportSummary {
+/**
+ * The turn's tally. Every quantity derived from provider usage is a
+ * {@link Claim}: unmeasured is a first-class answer, never a zero.
+ */
+export interface CacheReportSummary {
+    /** LLM calls seen. Always known — the recorder counted them itself. */
     readonly totalIterations: number;
     readonly applyMarkersIterations: number;
     readonly noMarkersIterations: number;
-    readonly cacheReadTokensTotal: number;
-    readonly cacheWriteTokensTotal: number;
-    readonly freshInputTokensTotal: number;
-    readonly hitRate: number;
-    readonly estimatedDollarsSpent: number;
-    readonly estimatedDollarsSavedVsNoCache: number;
+    /**
+     * Calls whose cache traffic the provider actually reported. The DENOMINATOR
+     * every claim below is computed over — a rate from 3 of 20 calls is not the
+     * turn's rate, and this is how a reader can tell.
+     */
+    readonly measuredIterations: number;
+    /** Calls that reported nothing (no usage, no cache fields, or an adapter that cannot). */
+    readonly unmeasuredIterations: number;
+    readonly cacheReadTokensTotal: Claim<number>;
+    readonly cacheWriteTokensTotal: Claim<number>;
+    readonly freshInputTokensTotal: Claim<number>;
+    /** cacheRead / (cacheRead + cacheWrite + fresh), over MEASURED calls only. */
+    readonly hitRate: Claim<number>;
+    readonly estimatedDollarsSpent: Claim<number>;
+    readonly estimatedDollarsSavedVsNoCache: Claim<number>;
     readonly perIter: readonly PerIterEntry[];
 }
 export interface CacheRecorderOptions {
     /**
-     * The agent's CacheStrategy. Required for `extractMetrics` —
-     * normalizes provider-specific `usage` shapes into CacheMetrics.
-     * If not provided, recorder logs the raw usage and skips dollar math.
+     * The agent's CacheStrategy — the thing that reads the port usage. Without
+     * one every row's metrics are `unknown` (with that as the stated reason),
+     * which is the honest answer: nothing read the usage.
      */
     readonly strategy?: CacheStrategy;
     /**
@@ -82,4 +120,3 @@ export interface CacheRecorderHandle extends CombinedRecorder {
     reset(): void;
 }
 export declare function cacheRecorder(options?: CacheRecorderOptions): CacheRecorderHandle;
-export {};

package/dist/esm/cache/cacheRecorder.js

@@ -1,32 +1,55 @@
 /**
- * cacheRecorder() — observability for the v2.6 cache layer.
+ * cacheRecorder() — the cache layer's meter.
  *
  * Subscribes to:
- *   - `FlowRecorder.onDecision` — captures CacheGate routing decisions
- *     (apply-markers / no-markers + the rule that fired + evidence
- *     from `decide()`). Read directly from `event.evidence.rules[matched]`
- *     since footprintjs already auto-captures predicate `inputs[]`.
- *   - `agentfootprint.stream.llm_end` events — read provider's `usage`
- *     and call the agent's CacheStrategy.extractMetrics() to normalize
- *     into CacheMetrics (cacheReadTokens / cacheWriteTokens / fresh).
+ *   - `FlowRecorder.onDecision` — CacheGate routing decisions
+ *     (apply-markers / no-markers + the rule that fired + evidence from
+ *     `decide()`).
+ *   - `agentfootprint.stream.llm_end` — reads that event's `usage` (the PORT
+ *     shape: `{ input, output, cacheRead?, cacheWrite? }`) and asks the
+ *     agent's `CacheStrategy.extractMetrics` what is known about it.
  *
- * Produces:
- *   - per-iteration `agentfootprint.cache.applied` events (markers
- *     applied this iter or empty if skipped) — for Lens trace
- *   - per-iteration `agentfootprint.cache.metrics` events (hit/write
- *     token counts + estimated dollars via PricingTable) — for
- *     dashboards
- *   - a turn-end summary printable via `recorder.report()` —
- *     numeric tally plus dollars saved
+ * Produces: a per-turn report via `recorder.report()` — token tallies, hit
+ * rate and dollar estimates, each carried as a `Claim` so an UNMEASURED turn
+ * can never render as a zero one.
  *
- * v2.6 LIMITATION: doesn't yet write `scope.recentHitRate` back into
- * agent state. CacheGate's hit-rate-floor rule won't fire automatically;
- * consumers can manually wire feedback via `Agent.create(...).attach(rec)`.
- * Full feedback loop deferred to v2.7 (needs an agent-side accessor
- * convention since recorders don't normally write to scope).
+ * ── Why every number here is a Claim (9.59.0) ─────────────────────────
+ * The shipped 9.58.0 meter reported `hitRate: 0` for a 20-call turn that hit
+ * cache on every call. Two faults, and the second is why the first went
+ * unnoticed for so long: (1) the strategies parsed RAW WIRE field names off a
+ * value that carries the PORT shape, so every field read `undefined`; (2) the
+ * report typed its aggregates as bare `number`, so "nobody measured" and
+ * "measured, and it was zero" rendered identically. Fixing (1) alone would
+ * have left a meter that still cannot say "unmeasured" — hence `Claim<T>`,
+ * plus `measuredIterations` / `unmeasuredIterations` so a rate computed from
+ * 3 of 20 calls states its own denominator.
+ *
+ * Read the number through `isKnown(report.hitRate)` (or `describeClaim` for a
+ * one-line render). There is deliberately no door that hands you a bare
+ * number without your having branched.
+ *
+ * ── What this recorder does NOT do ────────────────────────────────────
+ * It emits no events. (Earlier prose here promised per-iteration
+ * `agentfootprint.cache.applied` / `agentfootprint.cache.metrics` events;
+ * neither name has ever existed in the event registry and no `typedEmit` has
+ * ever been in this file. The prose was the bug.)
+ *
+ * It does not write `scope.recentHitRate` back into agent state either, so
+ * CacheGate's hit-rate-floor rule never fires on its own — the loop is
+ * severed at both ends (the key is seeded `undefined` and written by
+ * nothing). Recorders do not write to chart scope, so closing that loop needs
+ * an agent-side accessor convention; it is separable work from measuring the
+ * number, which is what this file now does.
  */
 import { splitStageId } from 'footprintjs/trace';
 import { STAGE_IDS } from '../conventions.js';
+import { known, unknown, isKnown } from '../lib/claim/claim.js';
+/** The metrics of a row already filtered by `isKnown`. Narrowing helper only. */
+function valueOfMetrics(entry) {
+    return isKnown(entry.metrics)
+        ? entry.metrics.value
+        : { cacheReadTokens: 0, cacheWriteTokens: 0, freshInputTokens: 0 };
+}
 export function cacheRecorder(options = {}) {
     const perIter = [];
     let lastDecision;
@@ -61,8 +84,11 @@ export function cacheRecorder(options = {}) {
             if (event.type !== 'agentfootprint.stream.llm_end')
                 return;
             iterationCounter++;
+            // The PORT shape, which is the only shape this event has ever carried.
             const usage = event.payload.usage;
-            const metrics = options.strategy?.extractMetrics(usage);
+            const metrics = options.strategy === undefined
+                ? unknown('no CacheStrategy was given to cacheRecorder(), so nothing read the usage')
+                : options.strategy.extractMetrics(usage);
             const branch = lastDecision?.branch ?? 'apply-markers';
             // Compute dollar math:
             //   spent = freshInput * inputPrice
@@ -70,21 +96,34 @@ export function cacheRecorder(options = {}) {
             //         + cacheWrite * cacheWritePrice
             //   no-cache cost = (freshInput + cacheRead + cacheWrite) * inputPrice
             //   saved        = no-cache cost - spent
-            let dollarsSpent = 0;
-            let savedVsNoCache = 0;
-            if (metrics) {
-                dollarsSpent =
-                    dollars(metrics.freshInputTokens, 'input') +
-                        dollars(metrics.cacheReadTokens, 'cacheRead') +
-                        dollars(metrics.cacheWriteTokens, 'cacheWrite');
-                const noCacheCost = dollars(metrics.freshInputTokens + metrics.cacheReadTokens + metrics.cacheWriteTokens, 'input');
-                savedVsNoCache = noCacheCost - dollarsSpent;
+            let dollarsSpent;
+            let savedVsNoCache;
+            if (isKnown(metrics)) {
+                const m = metrics.value;
+                const spent = dollars(m.freshInputTokens, 'input') +
+                    dollars(m.cacheReadTokens, 'cacheRead') +
+                    dollars(m.cacheWriteTokens, 'cacheWrite');
+                const noCacheCost = dollars(m.freshInputTokens + m.cacheReadTokens + m.cacheWriteTokens, 'input');
+                const ev = options.pricing === undefined
+                    ? 'measured tokens, but no PricingTable was given — every price is 0'
+                    : 'measured tokens priced with the given PricingTable';
+                dollarsSpent = known(spent, ev);
+                savedVsNoCache = known(noCacheCost - spent, ev);
+            }
+            else {
+                // No tokens measured ⇒ no dollars. Carrying the metrics claim's own
+                // reason forward is what keeps a $0 estimate from reading as "free".
+                const why = metrics.kind === 'unknown'
+                    ? metrics.reason
+                    : `no cache tokens are measurable here — ${metrics.evidence}`;
+                dollarsSpent = unknown(why);
+                savedVsNoCache = unknown(why);
             }
             const entry = {
                 iteration: iterationCounter,
                 branch,
                 ...(lastDecision?.rule !== undefined && { rule: lastDecision.rule }),
-                ...(metrics !== undefined && { metrics }),
+                metrics,
                 dollarsSpent,
                 dollarsSavedVsNoCache: savedVsNoCache,
             };
@@ -94,23 +133,43 @@ export function cacheRecorder(options = {}) {
         report() {
             const apply = perIter.filter((p) => p.branch === 'apply-markers').length;
             const skip = perIter.filter((p) => p.branch === 'no-markers').length;
-            const cacheRead = perIter.reduce((s, p) => s + (p.metrics?.cacheReadTokens ?? 0), 0);
-            const cacheWrite = perIter.reduce((s, p) => s + (p.metrics?.cacheWriteTokens ?? 0), 0);
-            const fresh = perIter.reduce((s, p) => s + (p.metrics?.freshInputTokens ?? 0), 0);
-            const totalRequest = cacheRead + cacheWrite + fresh;
-            const hitRate = totalRequest > 0 ? cacheRead / totalRequest : 0;
-            const dollarsSpent = perIter.reduce((s, p) => s + p.dollarsSpent, 0);
-            const dollarsSaved = perIter.reduce((s, p) => s + p.dollarsSavedVsNoCache, 0);
+            const measured = perIter.filter((p) => isKnown(p.metrics));
+            const n = measured.length;
+            const total = perIter.length;
+            // ONE reason, stated once, reused by every claim below — so a reader
+            // who prints any single field learns why the whole report is empty.
+            const why = total === 0
+                ? 'no LLM call was observed, so there is nothing to measure'
+                : `none of the ${total} observed call(s) reported cache usage — ` +
+                    (perIter[0]?.metrics.kind === 'not-applicable'
+                        ? `this provider cannot report it (${perIter[0].metrics.evidence})`
+                        : 'the provider reported no cache fields');
+            const evidence = `summed over the ${n} of ${total} call(s) whose usage was measured`;
+            const claimOf = (value) => n === 0 ? unknown(why) : known(value, evidence);
+            const cacheRead = measured.reduce((s2, p) => s2 + valueOfMetrics(p).cacheReadTokens, 0);
+            const cacheWrite = measured.reduce((s2, p) => s2 + valueOfMetrics(p).cacheWriteTokens, 0);
+            const fresh = measured.reduce((s2, p) => s2 + valueOfMetrics(p).freshInputTokens, 0);
+            const requestTotal = cacheRead + cacheWrite + fresh;
+            const dollarsSpent = measured.reduce((s2, p) => s2 + (isKnown(p.dollarsSpent) ? p.dollarsSpent.value : 0), 0);
+            const dollarsSaved = measured.reduce((s2, p) => s2 + (isKnown(p.dollarsSavedVsNoCache) ? p.dollarsSavedVsNoCache.value : 0), 0);
             return Object.freeze({
-                totalIterations: perIter.length,
+                totalIterations: total,
                 applyMarkersIterations: apply,
                 noMarkersIterations: skip,
-                cacheReadTokensTotal: cacheRead,
-                cacheWriteTokensTotal: cacheWrite,
-                freshInputTokensTotal: fresh,
-                hitRate,
-                estimatedDollarsSpent: dollarsSpent,
-                estimatedDollarsSavedVsNoCache: dollarsSaved,
+                measuredIterations: n,
+                unmeasuredIterations: total - n,
+                cacheReadTokensTotal: claimOf(cacheRead),
+                cacheWriteTokensTotal: claimOf(cacheWrite),
+                freshInputTokensTotal: claimOf(fresh),
+                // A measured turn with zero prompt tokens is not a thing; guard it
+                // anyway rather than divide by zero and hand back NaN as a rate.
+                hitRate: n === 0
+                    ? unknown(why)
+                    : requestTotal === 0
+                        ? unknown(`the ${n} measured call(s) reported 0 prompt tokens in total, so a hit rate has no denominator`)
+                        : known(cacheRead / requestTotal, evidence),
+                estimatedDollarsSpent: claimOf(dollarsSpent),
+                estimatedDollarsSavedVsNoCache: claimOf(dollarsSaved),
                 perIter: Object.freeze([...perIter]),
             });
         },

package/dist/esm/cache/cacheRecorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"cacheRecorder.js","sourceRoot":"","sources":["../../../src/cache/cacheRecorder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cacheRecorder.js","sourceRoot":"","sources":["../../../src/cache/cacheRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAI9C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAc,MAAM,uBAAuB,CAAC;AAgF5E,iFAAiF;AACjF,SAAS,cAAc,CAAC,KAAmB;IACzC,OAAO,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;QAC3B,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK;QACrB,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,IAAI,YAAmF,CAAC;IACxF,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,SAAS,OAAO,CAAC,MAAc,EAAE,IAA0C;QACzE,IAAI,CAAC,OAAO,CAAC,OAAO;YAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC;QACzC,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,MAAM,GAAG;QACb,EAAE,EAAE,gBAAgB;QAEpB,UAAU,CAAC,KAAwB;YACjC,sEAAsE;YACtE,kEAAkE;YAClE,uEAAuE;YACvE,yEAAyE;YACzE,mEAAmE;YACnE,iEAAiE;YACjE,0EAA0E;YAC1E,oDAAoD;YACpD,MAAM,OAAO,GAAG,KAAK,CAAC,gBAAgB,EAAE,OAAO,CAAC;YAChD,IAAI,CAAC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC,YAAY,KAAK,SAAS,CAAC,UAAU;gBAAE,OAAO;YACpF,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAC7D,YAAY,GAAG;gBACb,MAAM,EAAE,KAAK,CAAC,MAAwC;gBACtD,GAAG,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;aAC7D,CAAC;QACJ,CAAC;QAED,MAAM,CAAC,KAA0B;YAC/B,IAAI,KAAK,CAAC,IAAI,KAAK,+BAA+B;gBAAE,OAAO;YAC3D,gBAAgB,EAAE,CAAC;YACnB,uEAAuE;YACvE,MAAM,KAAK,GAAI,KAAK,CAAC,OAAkC,CAAC,KAAK,CAAC;YAC9D,MAAM,OAAO,GACX,OAAO,CAAC,QAAQ,KAAK,SAAS;gBAC5B,CAAC,CAAC,OAAO,CAAC,0EAA0E,CAAC;gBACrF,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YAC7C,MAAM,MAAM,GAAG,YAAY,EAAE,MAAM,IAAI,eAAe,CAAC;YACvD,uBAAuB;YACvB,oCAAoC;YACpC,uCAAuC;YACvC,yCAAyC;YACzC,uEAAuE;YACvE,yCAAyC;YACzC,IAAI,YAA2B,CAAC;YAChC,IAAI,cAA6B,CAAC;YAClC,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrB,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;gBACxB,MAAM,KAAK,GACT,OAAO,CAAC,CAAC,CAAC,gBAAgB,EAAE,OAAO,CAAC;oBACpC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,WAAW,CAAC;oBACvC,OAAO,CAAC,CAAC,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;gBAC5C,MAAM,WAAW,GAAG,OAAO,CACzB,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,gBAAgB,EAC3D,OAAO,CACR,CAAC;gBACF,MAAM,EAAE,GACN,OAAO,CAAC,OAAO,KAAK,SAAS;oBAC3B,CAAC,CAAC,mEAAmE;oBACrE,CAAC,CAAC,oDAAoD,CAAC;gBAC3D,YAAY,GAAG,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAChC,cAAc,GAAG,KAAK,CAAC,WAAW,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACN,oEAAoE;gBACpE,qEAAqE;gBACrE,MAAM,GAAG,GACP,OAAO,CAAC,IAAI,KAAK,SAAS;oBACxB,CAAC,CAAC,OAAO,CAAC,MAAM;oBAChB,CAAC,CAAC,yCAAyC,OAAO,CAAC,QAAQ,EAAE,CAAC;gBAClE,YAAY,GAAG,OAAO,CAAS,GAAG,CAAC,CAAC;gBACpC,cAAc,GAAG,OAAO,CAAS,GAAG,CAAC,CAAC;YACxC,CAAC;YACD,MAAM,KAAK,GAAiB;gBAC1B,SAAS,EAAE,gBAAgB;gBAC3B,MAAM;gBACN,GAAG,CAAC,YAAY,EAAE,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC;gBACpE,OAAO;gBACP,YAAY;gBACZ,qBAAqB,EAAE,cAAc;aACtC,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,YAAY,GAAG,SAAS,CAAC;QAC3B,CAAC;QAED,MAAM;YACJ,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,eAAe,CAAC,CAAC,MAAM,CAAC;YACzE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,YAAY,CAAC,CAAC,MAAM,CAAC;YACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;YAC3D,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;YAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC;YAE7B,qEAAqE;YACrE,oEAAoE;YACpE,MAAM,GAAG,GACP,KAAK,KAAK,CAAC;gBACT,CAAC,CAAC,0DAA0D;gBAC5D,CAAC,CAAC,eAAe,KAAK,2CAA2C;oBAC/D,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,gBAAgB;wBAC5C,CAAC,CAAC,mCAAmC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,GAAG;wBACnE,CAAC,CAAC,uCAAuC,CAAC,CAAC;YACnD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,KAAK,mCAAmC,CAAC;YACrF,MAAM,OAAO,GAAG,CAAC,KAAa,EAAiB,EAAE,CAC/C,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAS,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YAE1D,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;YACxF,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;YAC1F,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;YACrF,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,KAAK,CAAC;YACpD,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAClC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EACpE,CAAC,CACF,CAAC;YACF,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAClC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EACtF,CAAC,CACF,CAAC;YAEF,OAAO,MAAM,CAAC,MAAM,CAAC;gBACnB,eAAe,EAAE,KAAK;gBACtB,sBAAsB,EAAE,KAAK;gBAC7B,mBAAmB,EAAE,IAAI;gBACzB,kBAAkB,EAAE,CAAC;gBACrB,oBAAoB,EAAE,KAAK,GAAG,CAAC;gBAC/B,oBAAoB,EAAE,OAAO,CAAC,SAAS,CAAC;gBACxC,qBAAqB,EAAE,OAAO,CAAC,UAAU,CAAC;gBAC1C,qBAAqB,EAAE,OAAO,CAAC,KAAK,CAAC;gBACrC,mEAAmE;gBACnE,iEAAiE;gBACjE,OAAO,EACL,CAAC,KAAK,CAAC;oBACL,CAAC,CAAC,OAAO,CAAS,GAAG,CAAC;oBACtB,CAAC,CAAC,YAAY,KAAK,CAAC;wBAClB,CAAC,CAAC,OAAO,CACL,OAAO,CAAC,uFAAuF,CAChG;wBACH,CAAC,CAAC,KAAK,CAAC,SAAS,GAAG,YAAY,EAAE,QAAQ,CAAC;gBACjD,qBAAqB,EAAE,OAAO,CAAC,YAAY,CAAC;gBAC5C,8BAA8B,EAAE,OAAO,CAAC,YAAY,CAAC;gBACrD,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;aACrC,CAAC,CAAC;QACL,CAAC;QAED,KAAK;YACH,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;YACnB,YAAY,GAAG,SAAS,CAAC;YACzB,gBAAgB,GAAG,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;IAEF,OAAO,MAAwC,CAAC;AAClD,CAAC"}

package/dist/esm/cache/index.d.ts

@@ -9,12 +9,16 @@
  * Strategies registered as of v2.6:
  *   - NoOp (wildcard '*' fallback) — always available, registered by
  *     the registry module itself
- *   - AnthropicCacheStrategy ('anthropic', 'browser-anthropic')
+ *   - AnthropicCacheStrategy ('anthropic', 'browser-anthropic') — the one
+ *     end-to-end strategy: the adapter sends markers AND reads cache usage
+ *   - OpenAICacheStrategy ('openai', 'browser-openai') — pass-through
+ *     (OpenAI auto-caches); reports `not-applicable` metrics until the
+ *     adapter lifts `prompt_tokens_details.cached_tokens` onto the port
+ *   - BedrockCacheStrategy ('bedrock') — `enabled: false`; the Bedrock
+ *     adapter implements neither half of the cache contract
  *
- * Future strategies (Phase 8+):
- *   - OpenAICacheStrategy
- *   - BedrockCacheStrategy
- *   - GeminiCacheStrategy (v2.7+, async handle-based)
+ * Future strategies:
+ *   - GeminiCacheStrategy (async handle-based)
  *
  * Public types (re-exported for consumers):
  *   - CachePolicy, CacheMarker, CacheStrategy, CacheCapabilities,
@@ -23,11 +27,12 @@
 import './strategies/AnthropicCacheStrategy.js';
 import './strategies/OpenAICacheStrategy.js';
 import './strategies/BedrockCacheStrategy.js';
-export type { CachePolicy, CachePolicyContext, CacheMarker, CacheStrategy, CacheStrategyContext, CacheCapabilities, CacheMetrics, } from './types.js';
+export type { CachePolicy, CachePolicyContext, CacheMarker, CacheStrategy, CacheStrategyContext, CacheCapabilities, CacheMetrics, CacheUsage, } from './types.js';
+export { known, unknown, notApplicable, isKnown, valueOr, describeClaim, type Claim, } from '../lib/claim/claim.js';
 export { getDefaultCacheStrategy, registerCacheStrategy, listRegisteredStrategies, } from './strategyRegistry.js';
 export { NoOpCacheStrategy } from './strategies/NoOpCacheStrategy.js';
 export { AnthropicCacheStrategy } from './strategies/AnthropicCacheStrategy.js';
 export { OpenAICacheStrategy } from './strategies/OpenAICacheStrategy.js';
 export { BedrockCacheStrategy } from './strategies/BedrockCacheStrategy.js';
 export { cacheRecorder } from './cacheRecorder.js';
-export type { CacheRecorderOptions, CacheRecorderHandle } from './cacheRecorder.js';
+export type { CacheRecorderOptions, CacheRecorderHandle, CacheReportSummary, PerIterEntry, } from './cacheRecorder.js';

package/dist/esm/cache/index.js

@@ -9,12 +9,16 @@
  * Strategies registered as of v2.6:
  *   - NoOp (wildcard '*' fallback) — always available, registered by
  *     the registry module itself
- *   - AnthropicCacheStrategy ('anthropic', 'browser-anthropic')
+ *   - AnthropicCacheStrategy ('anthropic', 'browser-anthropic') — the one
+ *     end-to-end strategy: the adapter sends markers AND reads cache usage
+ *   - OpenAICacheStrategy ('openai', 'browser-openai') — pass-through
+ *     (OpenAI auto-caches); reports `not-applicable` metrics until the
+ *     adapter lifts `prompt_tokens_details.cached_tokens` onto the port
+ *   - BedrockCacheStrategy ('bedrock') — `enabled: false`; the Bedrock
+ *     adapter implements neither half of the cache contract
  *
- * Future strategies (Phase 8+):
- *   - OpenAICacheStrategy
- *   - BedrockCacheStrategy
- *   - GeminiCacheStrategy (v2.7+, async handle-based)
+ * Future strategies:
+ *   - GeminiCacheStrategy (async handle-based)
  *
  * Public types (re-exported for consumers):
  *   - CachePolicy, CacheMarker, CacheStrategy, CacheCapabilities,
@@ -24,6 +28,10 @@
 import './strategies/AnthropicCacheStrategy.js';
 import './strategies/OpenAICacheStrategy.js';
 import './strategies/BedrockCacheStrategy.js';
+// The honesty primitive the meter is typed in (9.59.0). Re-exported
+// reference-equal from `src/lib/claim/` — the SAME symbols
+// `agentfootprint/maps` exports, so `known` from either door is one function.
+export { known, unknown, notApplicable, isKnown, valueOr, describeClaim, } from '../lib/claim/claim.js';
 // Strategy registry
 export { getDefaultCacheStrategy, registerCacheStrategy, listRegisteredStrategies, } from './strategyRegistry.js';
 // Built-in strategy classes (for consumers who want explicit overrides)

package/dist/esm/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4DAA4D;AAC5D,OAAO,wCAAwC,CAAC;AAChD,OAAO,qCAAqC,CAAC;AAC7C,OAAO,sCAAsC,CAAC;AAa9C,oBAAoB;AACpB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAE5E,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,4DAA4D;AAC5D,OAAO,wCAAwC,CAAC;AAChD,OAAO,qCAAqC,CAAC;AAC7C,OAAO,sCAAsC,CAAC;AAc9C,oEAAoE;AACpE,2DAA2D;AAC3D,8EAA8E;AAC9E,OAAO,EACL,KAAK,EACL,OAAO,EACP,aAAa,EACb,OAAO,EACP,OAAO,EACP,aAAa,GAEd,MAAM,uBAAuB,CAAC;AAE/B,oBAAoB;AACpB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAE5E,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/esm/cache/portUsage.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The one reader of PORT-shaped usage for the cache meter.
+ *
+ * Pattern: pure function, one job. Given the `usage` the framework put on
+ *          `agentfootprint.stream.llm_end`, answer what is actually known
+ *          about cache traffic on that call.
+ * Role:    the honest half of the 9.59.0 meter fix. Before it, three
+ *          strategies each parsed RAW WIRE field names (`cache_read_input_tokens`,
+ *          `prompt_tokens_details.cached_tokens`) off a value that has never
+ *          carried them — the framework normalises the wire at the ADAPTER
+ *          ring (`readCacheUsage`) and only ever hands a strategy the port
+ *          shape. Every field read `undefined`, `?? 0` turned that into a
+ *          zero, the guard tripped, and a 20-call turn that hit cache on
+ *          every call reported hitRate 0.
+ *
+ * The distinction this function exists to preserve: an adapter sets
+ * `cacheRead` / `cacheWrite` ONLY when the provider reported a number, so
+ *   • both absent      → nobody measured  → `unknown`
+ *   • either present   → measured         → `known` (a present 0 is a real 0)
+ * That is exactly the line `Claim<T>` was written to hold.
+ */
+import { type Claim } from '../lib/claim/claim.js';
+import type { CacheMetrics, CacheUsage } from './types.js';
+/**
+ * Read cache metrics off port usage.
+ *
+ * @param usage  the `usage` field of `agentfootprint.stream.llm_end`
+ * @param who    the adapter named in the evidence sentence, e.g. `'the Anthropic adapter'`
+ */
+export declare function readPortCacheUsage(usage: CacheUsage | undefined, who: string): Claim<CacheMetrics>;

package/dist/esm/cache/portUsage.js

@@ -0,0 +1,43 @@
+/**
+ * The one reader of PORT-shaped usage for the cache meter.
+ *
+ * Pattern: pure function, one job. Given the `usage` the framework put on
+ *          `agentfootprint.stream.llm_end`, answer what is actually known
+ *          about cache traffic on that call.
+ * Role:    the honest half of the 9.59.0 meter fix. Before it, three
+ *          strategies each parsed RAW WIRE field names (`cache_read_input_tokens`,
+ *          `prompt_tokens_details.cached_tokens`) off a value that has never
+ *          carried them — the framework normalises the wire at the ADAPTER
+ *          ring (`readCacheUsage`) and only ever hands a strategy the port
+ *          shape. Every field read `undefined`, `?? 0` turned that into a
+ *          zero, the guard tripped, and a 20-call turn that hit cache on
+ *          every call reported hitRate 0.
+ *
+ * The distinction this function exists to preserve: an adapter sets
+ * `cacheRead` / `cacheWrite` ONLY when the provider reported a number, so
+ *   • both absent      → nobody measured  → `unknown`
+ *   • either present   → measured         → `known` (a present 0 is a real 0)
+ * That is exactly the line `Claim<T>` was written to hold.
+ */
+import { known, unknown } from '../lib/claim/claim.js';
+/**
+ * Read cache metrics off port usage.
+ *
+ * @param usage  the `usage` field of `agentfootprint.stream.llm_end`
+ * @param who    the adapter named in the evidence sentence, e.g. `'the Anthropic adapter'`
+ */
+export function readPortCacheUsage(usage, who) {
+    if (usage === undefined || usage === null || typeof usage !== 'object') {
+        return unknown('the llm_end event carried no usage payload, so nothing about cache traffic was measured', 'agentfootprint.stream.llm_end');
+    }
+    const { cacheRead, cacheWrite, input } = usage;
+    if (cacheRead === undefined && cacheWrite === undefined) {
+        return unknown(`${who} reported no cache fields on this call — that is "nobody measured", not "no cache traffic"`, 'agentfootprint.stream.llm_end usage (port shape)');
+    }
+    return known({
+        cacheReadTokens: cacheRead ?? 0,
+        cacheWriteTokens: cacheWrite ?? 0,
+        freshInputTokens: typeof input === 'number' ? input : 0,
+    }, `${who} reported cache token counts on the port usage`);
+}
+//# sourceMappingURL=portUsage.js.map

package/dist/esm/cache/portUsage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portUsage.js","sourceRoot":"","sources":["../../../src/cache/portUsage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAc,MAAM,uBAAuB,CAAC;AAGnE;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAA6B,EAC7B,GAAW;IAEX,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvE,OAAO,OAAO,CACZ,yFAAyF,EACzF,+BAA+B,CAChC,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAC/C,IAAI,SAAS,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QACxD,OAAO,OAAO,CACZ,GAAG,GAAG,4FAA4F,EAClG,kDAAkD,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CACV;QACE,eAAe,EAAE,SAAS,IAAI,CAAC;QAC/B,gBAAgB,EAAE,UAAU,IAAI,CAAC;QACjC,gBAAgB,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACxD,EACD,GAAG,GAAG,gDAAgD,CACvD,CAAC;AACJ,CAAC"}

package/dist/esm/cache/strategies/AnthropicCacheStrategy.d.ts

@@ -15,7 +15,9 @@
  *
  * What this strategy DOES vs DOESN'T do:
  *   - DOES: clamp markers, attach to LLMRequest.cacheMarkers,
- *     extract metrics from response.usage
+ *     read cache metrics off the PORT usage the framework hands it
+ *     (`{ input, output, cacheRead?, cacheWrite? }`) — never off the raw
+ *     Anthropic wire, which the adapter has already normalised
  *   - DOES NOT: rewrite the wire body. The provider
  *     (BrowserAnthropicProvider) reads `cacheMarkers` and applies
  *     `cache_control` blocks during body construction. Separation of
@@ -25,7 +27,8 @@
  * Auto-registers in the strategy registry on module import for
  * provider names: 'anthropic', 'browser-anthropic'.
  */
-import type { CacheCapabilities, CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext } from '../types.js';
+import type { CacheCapabilities, CacheMarker, CacheMetrics, CacheStrategy, CacheStrategyContext, CacheUsage } from '../types.js';
+import type { Claim } from '../../lib/claim/claim.js';
 import type { LLMRequest } from '../../adapters/types.js';
 export declare class AnthropicCacheStrategy implements CacheStrategy {
     readonly providerName = "anthropic";
@@ -34,5 +37,5 @@ export declare class AnthropicCacheStrategy implements CacheStrategy {
         readonly request: LLMRequest;
         readonly markersApplied: readonly CacheMarker[];
     }>;
-    extractMetrics(usage: unknown): CacheMetrics | undefined;
+    extractMetrics(usage: CacheUsage | undefined): Claim<CacheMetrics>;
 }

package/dist/esm/cache/strategies/AnthropicCacheStrategy.js

@@ -15,7 +15,9 @@
  *
  * What this strategy DOES vs DOESN'T do:
  *   - DOES: clamp markers, attach to LLMRequest.cacheMarkers,
- *     extract metrics from response.usage
+ *     read cache metrics off the PORT usage the framework hands it
+ *     (`{ input, output, cacheRead?, cacheWrite? }`) — never off the raw
+ *     Anthropic wire, which the adapter has already normalised
  *   - DOES NOT: rewrite the wire body. The provider
  *     (BrowserAnthropicProvider) reads `cacheMarkers` and applies
  *     `cache_control` blocks during body construction. Separation of
@@ -25,6 +27,7 @@
  * Auto-registers in the strategy registry on module import for
  * provider names: 'anthropic', 'browser-anthropic'.
  */
+import { readPortCacheUsage } from '../portUsage.js';
 import { registerCacheStrategy } from '../strategyRegistry.js';
 /** Anthropic enforces 4 cache breakpoints per request. */
 const ANTHROPIC_MAX_MARKERS = 4;
@@ -62,22 +65,7 @@ export class AnthropicCacheStrategy {
         return { request, markersApplied };
     }
     extractMetrics(usage) {
-        if (!usage || typeof usage !== 'object')
-            return undefined;
-        const u = usage;
-        const cacheRead = u.cache_read_input_tokens ?? 0;
-        const cacheWrite = u.cache_creation_input_tokens ?? 0;
-        const fresh = u.input_tokens ?? 0;
-        // If neither cache field present, response didn't involve caching.
-        // Returning undefined signals "no cache info" so cacheRecorder
-        // doesn't compute a misleading 0% hit rate.
-        if (cacheRead === 0 && cacheWrite === 0)
-            return undefined;
-        return {
-            cacheReadTokens: cacheRead,
-            cacheWriteTokens: cacheWrite,
-            freshInputTokens: fresh,
-        };
+        return readPortCacheUsage(usage, 'the Anthropic adapter');
     }
 }
 // Auto-register on module import. Both 'anthropic' (server-side) and

package/dist/esm/cache/strategies/AnthropicCacheStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"AnthropicCacheStrategy.js","sourceRoot":"","sources":["../../../../src/cache/strategies/AnthropicCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAUH,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,0DAA0D;AAC1D,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC9D,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,qBAAqB;IACjC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAkC;IACxD,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAiD;IACvF,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,OAAO,sBAAsB;IACxB,YAAY,GAAG,WAAW,CAAC;IAC3B,YAAY,GAAG,sBAAsB,CAAC;IAE/C,KAAK,CAAC,cAAc,CAClB,GAAe,EACf,UAAkC,EAClC,GAAyB;QAKzB,8DAA8D;QAC9D,kEAAkE;QAClE,gEAAgE;QAChE,kEAAkE;QAClE,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;YACxB,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,2DAA2D;QAC3D,4DAA4D;QAC5D,kEAAkE;QAClE,MAAM,cAAc,GAClB,UAAU,CAAC,MAAM,IAAI,qBAAqB;YACxC,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAe;YAC1B,GAAG,GAAG;YACN,YAAY,EAAE,cAAc;SAC7B,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACrC,CAAC;IAED,cAAc,CAAC,KAAc;QAC3B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC1D,MAAM,CAAC,GAAG,KAIT,CAAC;QACF,MAAM,SAAS,GAAG,CAAC,CAAC,uBAAuB,IAAI,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,CAAC,CAAC,2BAA2B,IAAI,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;QAClC,mEAAmE;QACnE,+DAA+D;QAC/D,4CAA4C;QAC5C,IAAI,SAAS,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC1D,OAAO;YACL,eAAe,EAAE,SAAS;YAC1B,gBAAgB,EAAE,UAAU;YAC5B,gBAAgB,EAAE,KAAK;SACxB,CAAC;IACJ,CAAC;CACF;AAED,qEAAqE;AACrE,sEAAsE;AACtE,CAAC;IACC,MAAM,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAC9C,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAChC,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,eAAe,GAAkB;QACrC,YAAY,EAAE,mBAAmB;QACjC,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;QACtD,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;KACvD,CAAC;IACF,qBAAqB,CAAC,eAAe,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"AnthropicCacheStrategy.js","sourceRoot":"","sources":["../../../../src/cache/strategies/AnthropicCacheStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,0DAA0D;AAC1D,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC9D,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,qBAAqB;IACjC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAkC;IACxD,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAiD;IACvF,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,OAAO,sBAAsB;IACxB,YAAY,GAAG,WAAW,CAAC;IAC3B,YAAY,GAAG,sBAAsB,CAAC;IAE/C,KAAK,CAAC,cAAc,CAClB,GAAe,EACf,UAAkC,EAClC,GAAyB;QAKzB,8DAA8D;QAC9D,kEAAkE;QAClE,gEAAgE;QAChE,kEAAkE;QAClE,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;YACxB,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;QAC9C,CAAC;QAED,2DAA2D;QAC3D,4DAA4D;QAC5D,kEAAkE;QAClE,MAAM,cAAc,GAClB,UAAU,CAAC,MAAM,IAAI,qBAAqB;YACxC,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAe;YAC1B,GAAG,GAAG;YACN,YAAY,EAAE,cAAc;SAC7B,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACrC,CAAC;IAED,cAAc,CAAC,KAA6B;QAC1C,OAAO,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,CAAC,CAAC;IAC5D,CAAC;CACF;AAED,qEAAqE;AACrE,sEAAsE;AACtE,CAAC;IACC,MAAM,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAC9C,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAChC,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,eAAe,GAAkB;QACrC,YAAY,EAAE,mBAAmB;QACjC,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;QACtD,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;KACvD,CAAC;IACF,qBAAqB,CAAC,eAAe,CAAC,CAAC;AACzC,CAAC"}