agentfootprint 7.1.0 → 7.2.0

package/dist/lib/context-ledger/types.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * context-ledger/types.ts — the bookkeeper's vocabulary.
+ *
+ * WHY THIS LIBRARY EXISTS: context engineering fails in one predictable
+ * direction — "include everything to be safe". Every injection, skill and
+ * tool schema costs tokens EVERY turn, whether or not it ever mattered. The
+ * ledger keeps score across runs: which pieces EARNED their tokens (were
+ * called, activated, or sat on the answer's dependency slice) and which
+ * never did. Its rows feed the L2 gates (gatedTools predicate, skill-graph
+ * EntryScorer, injection demotion) so future turns include less — the
+ * mechanism that makes lesser models viable.
+ *
+ * HONESTY (the discipline everything here inherits):
+ * - Every counter is a STRUCTURAL fact from the run's own commit log —
+ *   offers are recorded commits, uses are recorded calls/activations/slice
+ *   membership. Nothing is inferred from model internals.
+ * - Each kind's `used` definition is explicit ({@link UsedSignal}) and rides
+ *   every count — a consumer can always see WHY a piece counted as used.
+ * - Slice membership is slot-granular (all injections sharing a slot share
+ *   its write) — the signal name says so: `'answer-slice(slot)'`.
+ * - `approxTokens*` is a serialized-length estimate (JSON chars ÷ 4), named
+ *   so nobody mistakes it for a tokenizer count.
+ * - The ledger never claims causation. `earnRate` is bookkeeping;
+ *   ablation (context-bisect) can upgrade individual claims when you pay
+ *   for it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/lib/context-ledger/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/context-ledger/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/dist/observe.js

@@ -46,7 +46,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatRouteHop = exports.routeRecorder = exports.toolChoiceRecorder = exports.buildChoiceContext = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.skillRecorder = exports.permissionRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.attachLocalObservability = exports.traceToStepGraph = exports.redactContent = exports.serializeTrace = exports.buildStepGraphFromEvents = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
+exports.ledgerGated = exports.ledgerEntryScorer = exports.ledgerToolGate = exports.contextLedger = exports.formatRouteHop = exports.routeRecorder = exports.toolChoiceRecorder = exports.buildChoiceContext = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.skillRecorder = exports.permissionRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.attachLocalObservability = exports.traceToStepGraph = exports.redactContent = exports.serializeTrace = exports.buildStepGraphFromEvents = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
 // Tier 1 — context + stream
 var ContextRecorder_js_1 = require("./recorders/core/ContextRecorder.js");
 Object.defineProperty(exports, "ContextRecorder", { enumerable: true, get: function () { return ContextRecorder_js_1.ContextRecorder; } });
@@ -132,4 +132,12 @@ Object.defineProperty(exports, "toolChoiceRecorder", { enumerable: true, get: fu
 var RouteRecorder_js_1 = require("./recorders/observability/RouteRecorder.js");
 Object.defineProperty(exports, "routeRecorder", { enumerable: true, get: function () { return RouteRecorder_js_1.routeRecorder; } });
 Object.defineProperty(exports, "formatRouteHop", { enumerable: true, get: function () { return RouteRecorder_js_1.formatRouteHop; } });
+// context-ledger — which context pieces EARNED their tokens? Post-run
+// bookkeeping (offers/uses/outcomes from the commit log) feeding the gating
+// seams. See src/lib/context-ledger/README.md.
+var index_js_1 = require("./lib/context-ledger/index.js");
+Object.defineProperty(exports, "contextLedger", { enumerable: true, get: function () { return index_js_1.contextLedger; } });
+Object.defineProperty(exports, "ledgerToolGate", { enumerable: true, get: function () { return index_js_1.ledgerToolGate; } });
+Object.defineProperty(exports, "ledgerEntryScorer", { enumerable: true, get: function () { return index_js_1.ledgerEntryScorer; } });
+Object.defineProperty(exports, "ledgerGated", { enumerable: true, get: function () { return index_js_1.ledgerGated; } });
 //# sourceMappingURL=observe.js.map

package/dist/observe.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;;;;;;;;;;;;;;;AAEH,4BAA4B;AAC5B,0EAAmG;AAA1F,qHAAA,eAAe,OAAA;AACxB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AAEvB,+BAA+B;AAC/B,kFAGiD;AAF/C,6HAAA,mBAAmB,OAAA;AAGrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qFAkBuD;AAjBrD,uHAAA,gBAAgB,OAAA;AAChB,uHAAA,gBAAgB,OAAA;AAiBlB,mFAWsD;AAVpD,mHAAA,aAAa,OAAA;AACb,qHAAA,eAAe,OAAA;AACf,qHAAA,eAAe,OAAA;AASjB,uFAWwD;AAVtD,uHAAA,eAAe,OAAA;AACf,sHAAA,cAAc,OAAA;AACd,gIAAA,wBAAwB,OAAA;AAU1B,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,+DAQ4C;AAP1C,0GAAA,cAAc,OAAA;AACd,yGAAA,aAAa,OAAA;AACb,4GAAA,gBAAgB,OAAA;AAOlB,mFAAmF;AACnF,yFAIyD;AAHvD,iIAAA,wBAAwB,OAAA;AAK1B,uFAUwD;AATtD,yHAAA,iBAAiB,OAAA;AACjB,yHAAA,iBAAiB,OAAA;AACjB,sHAAA,cAAc,OAAA;AACd,uHAAA,eAAe,OAAA;AACf,4HAAA,oBAAoB,OAAA;AAOtB,6BAA6B;AAC7B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,4FAGsD;AAFpD,uIAAA,wBAAwB,OAAA;AAG1B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,mFAMsD;AALpD,mHAAA,aAAa,OAAA;AACb,oHAAA,cAAc,OAAA;AAKhB,iFAIqD;AAHnD,iHAAA,YAAY,OAAA;AAId,4EAA4E;AAC5E,gFAAgF;AAChF,2FAO0D;AANxD,6HAAA,mBAAmB,OAAA;AAOrB,gFAAgF;AAChF,gFAAgF;AAChF,yGASiE;AAR/D,mIAAA,kBAAkB,OAAA;AAUpB,uDAAuD;AACvD,8DAA0D;AAAjD,yGAAA,SAAS,OAAA;AAElB,kEAAkE;AAClE,uEAAuE;AACvE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,wEAAwE;AACxE,6CAA2B;AAC3B,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,yFASyD;AARvD,2HAAA,kBAAkB,OAAA;AAClB,2HAAA,kBAAkB,OAAA;AASpB,+EASoD;AARlD,iHAAA,aAAa,OAAA;AACb,kHAAA,cAAc,OAAA"}
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;;;;;;;;;;;;;;;AAEH,4BAA4B;AAC5B,0EAAmG;AAA1F,qHAAA,eAAe,OAAA;AACxB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AAEvB,+BAA+B;AAC/B,kFAGiD;AAF/C,6HAAA,mBAAmB,OAAA;AAGrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qFAkBuD;AAjBrD,uHAAA,gBAAgB,OAAA;AAChB,uHAAA,gBAAgB,OAAA;AAiBlB,mFAWsD;AAVpD,mHAAA,aAAa,OAAA;AACb,qHAAA,eAAe,OAAA;AACf,qHAAA,eAAe,OAAA;AASjB,uFAWwD;AAVtD,uHAAA,eAAe,OAAA;AACf,sHAAA,cAAc,OAAA;AACd,gIAAA,wBAAwB,OAAA;AAU1B,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,+DAQ4C;AAP1C,0GAAA,cAAc,OAAA;AACd,yGAAA,aAAa,OAAA;AACb,4GAAA,gBAAgB,OAAA;AAOlB,mFAAmF;AACnF,yFAIyD;AAHvD,iIAAA,wBAAwB,OAAA;AAK1B,uFAUwD;AATtD,yHAAA,iBAAiB,OAAA;AACjB,yHAAA,iBAAiB,OAAA;AACjB,sHAAA,cAAc,OAAA;AACd,uHAAA,eAAe,OAAA;AACf,4HAAA,oBAAoB,OAAA;AAOtB,6BAA6B;AAC7B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,4FAGsD;AAFpD,uIAAA,wBAAwB,OAAA;AAG1B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,mFAMsD;AALpD,mHAAA,aAAa,OAAA;AACb,oHAAA,cAAc,OAAA;AAKhB,iFAIqD;AAHnD,iHAAA,YAAY,OAAA;AAId,4EAA4E;AAC5E,gFAAgF;AAChF,2FAO0D;AANxD,6HAAA,mBAAmB,OAAA;AAOrB,gFAAgF;AAChF,gFAAgF;AAChF,yGASiE;AAR/D,mIAAA,kBAAkB,OAAA;AAUpB,uDAAuD;AACvD,8DAA0D;AAAjD,yGAAA,SAAS,OAAA;AAElB,kEAAkE;AAClE,uEAAuE;AACvE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,wEAAwE;AACxE,6CAA2B;AAC3B,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,yFASyD;AARvD,2HAAA,kBAAkB,OAAA;AAClB,2HAAA,kBAAkB,OAAA;AASpB,+EASoD;AARlD,iHAAA,aAAa,OAAA;AACb,kHAAA,cAAc,OAAA;AAShB,sEAAsE;AACtE,4EAA4E;AAC5E,+CAA+C;AAC/C,0DAA8G;AAArG,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,uGAAA,WAAW,OAAA"}

package/dist/types/lib/context-ledger/contextLedger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * contextLedger — the post-run bookkeeper (see types.ts for the WHY).
+ *
+ * DESIGN: a pure POST-RUN analyzer over the run's own commit log — no live
+ * recorder lifecycle, no event-order coupling. Everything it counts is
+ * already durably recorded by the engine (dogfooding: offers come from
+ * `commitValueAt` folds, answer attribution from `sliceForKey` — the same
+ * canonical queries every triage surface uses):
+ *
+ *   offers  — the context IN EFFECT at each LLM call. Call marker: a
+ *             commit that wrote `totalInputTokens` (monotonic — never
+ *             net-change-dropped) and did NOT write `userMessage` (which
+ *             only the seed writes). At each call index, fold
+ *             `activeInjections` + `dynamicToolSchemas`, and add the
+ *             STATIC tool registry (duck-read from the runner's public
+ *             `getUIGroup().extra.toolNames` — static registries live in a
+ *             closure, never in scope state). NOTE offers are deliberately
+ *             NOT "per context-key commit": the net-change filter drops
+ *             identical re-commits, so stable context appears once in the
+ *             log while still being offered (and paying tokens) per call.
+ *             Static-registry tools count offers with approxTokens 0 in L1
+ *             (their schema JSON isn't in the log) — earnRate, the gate
+ *             signal, is unaffected; dynamicToolSchemas carries real sizes.
+ *   uses    — tool: assistant messages' toolCalls in the final history;
+ *             skill: `activatedInjectionIds`;
+ *             injection: its SLOT's write sits on the final answer's
+ *             backward slice (slot-granular, labeled).
+ *   outcome — consumer label per run, credited to every offered piece.
+ *
+ * The slot→slice join needs NO id conventions: for each slot key
+ * (INJECTION_KEYS.*), `findLastWriter` names the commit that fed the final
+ * LLM call; membership of that writer in the answer slice IS the signal.
+ */
+import type { ContextLedger } from './types.js';
+export declare function contextLedger(): ContextLedger;
+//# sourceMappingURL=contextLedger.d.ts.map

package/dist/types/lib/context-ledger/contextLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextLedger.d.ts","sourceRoot":"","sources":["../../../../src/lib/context-ledger/contextLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAaH,OAAO,KAAK,EACV,aAAa,EAMd,MAAM,YAAY,CAAC;AAwEpB,wBAAgB,aAAa,IAAI,aAAa,CAmO7C"}

package/dist/types/lib/context-ledger/gates.d.ts

@@ -0,0 +1,64 @@
+/**
+ * context-ledger/gates.ts — L2: the ledger's rows feed what gets included.
+ *
+ * Three gates, one policy, each hooking an EXISTING seam (no new framework
+ * surface): `gatedTools(inner, predicate)` for tools, `skillGraph().entryBy`
+ * for skills, and a rule-trigger wrapper for injections.
+ *
+ * THE POLICY PRINCIPLE — demote, never starve: a piece the ledger judges
+ * poorly is demoted, but every `refreshEvery`-th decision lets it through
+ * anyway ("parole"), so it keeps generating fresh ledger data. Without
+ * parole a piece demoted once could never earn again — a self-fulfilling
+ * verdict. And the ledger never judges a piece it barely knows: below
+ * `minOffers` everything passes.
+ */
+import type { EntryScorer } from '../injection-engine/entryScorer.js';
+import type { Injection } from '../injection-engine/types.js';
+import type { ToolGatePredicate } from '../../tool-providers/types.js';
+import type { ContextLedger } from './types.js';
+/**
+ * When the ledger is allowed to judge, and how harshly.
+ * Plain-named knobs — a bookkeeper's rules, not ML hyperparameters.
+ */
+export interface LedgerPolicy {
+    /** Don't judge a piece until it has been offered this many times. Default 5. */
+    readonly minOffers?: number;
+    /** Demote below this used÷offered rate. Default 0.05 (essentially "never used"). */
+    readonly earnRateFloor?: number;
+    /**
+     * Parole: let a demoted piece through anyway every Nth demotion decision,
+     * so it keeps earning fresh data. Default 10. `Infinity` disables parole
+     * (NOT recommended — a starved piece can never redeem itself).
+     */
+    readonly refreshEvery?: number;
+}
+/**
+ * TOOL GATE — plug into the existing provider combinator:
+ *
+ * ```ts
+ * import { gatedTools, staticTools } from 'agentfootprint/tool-providers';
+ * builder.toolProvider(gatedTools(staticTools(tools), ledgerToolGate(ledger)));
+ * ```
+ *
+ * Unused tool schemas are usually the biggest silent token cost — this is
+ * the gate to start with.
+ */
+export declare function ledgerToolGate(ledger: ContextLedger, policy?: LedgerPolicy): ToolGatePredicate;
+/**
+ * SKILL GATE — an `EntryScorer` for `skillGraph().entryBy(...)` that wraps
+ * another scorer (keyword, embedding, …) and demotes candidates the ledger
+ * says never earn. Demotion multiplies the inner score toward the floor —
+ * ranking pressure, not exclusion — and parole restores full weight
+ * periodically, so a demoted skill can still win when nothing else fits.
+ */
+export declare function ledgerEntryScorer(ledger: ContextLedger, inner: EntryScorer, policy?: LedgerPolicy): EntryScorer;
+/**
+ * INJECTION GATE — wrap ONE injection so the ledger's verdict joins its
+ * trigger. `always` becomes a ledger-backed rule; an existing `rule` is
+ * AND-ed with the verdict. `on-tool-return` / `llm-activated` are returned
+ * UNCHANGED (they are already demand-driven — the ledger has nothing to
+ * add). `always` pieces are exempt unless you explicitly wrap them — the
+ * safety-first default from the design.
+ */
+export declare function ledgerGated(injection: Injection, ledger: ContextLedger, policy?: LedgerPolicy): Injection;
+//# sourceMappingURL=gates.d.ts.map

package/dist/types/lib/context-ledger/gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../../../src/lib/context-ledger/gates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAkC,MAAM,oCAAoC,CAAC;AACtG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,YAAY,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AA2BD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAG9F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,YAAY,GACpB,WAAW,CAqBb;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,aAAa,EACrB,MAAM,CAAC,EAAE,YAAY,GACpB,SAAS,CAeX"}

package/dist/types/lib/context-ledger/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * context-ledger — which context pieces EARNED their tokens?
+ *
+ * Post-run bookkeeping over the run's own commit log (offers, structural
+ * uses, consumer outcomes) whose rows feed the gating seams so future turns
+ * include less. See README.md for the honesty model and the L2 gates.
+ */
+export { contextLedger } from './contextLedger.js';
+export type { ContextLedger, LedgerJSON, LedgerRow, PieceKind, RecordedRun, UsedSignal, } from './types.js';
+export { ledgerToolGate, ledgerEntryScorer, ledgerGated, type LedgerPolicy } from './gates.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/context-ledger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/context-ledger/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,aAAa,EACb,UAAU,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/types/lib/context-ledger/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * context-ledger/types.ts — the bookkeeper's vocabulary.
+ *
+ * WHY THIS LIBRARY EXISTS: context engineering fails in one predictable
+ * direction — "include everything to be safe". Every injection, skill and
+ * tool schema costs tokens EVERY turn, whether or not it ever mattered. The
+ * ledger keeps score across runs: which pieces EARNED their tokens (were
+ * called, activated, or sat on the answer's dependency slice) and which
+ * never did. Its rows feed the L2 gates (gatedTools predicate, skill-graph
+ * EntryScorer, injection demotion) so future turns include less — the
+ * mechanism that makes lesser models viable.
+ *
+ * HONESTY (the discipline everything here inherits):
+ * - Every counter is a STRUCTURAL fact from the run's own commit log —
+ *   offers are recorded commits, uses are recorded calls/activations/slice
+ *   membership. Nothing is inferred from model internals.
+ * - Each kind's `used` definition is explicit ({@link UsedSignal}) and rides
+ *   every count — a consumer can always see WHY a piece counted as used.
+ * - Slice membership is slot-granular (all injections sharing a slot share
+ *   its write) — the signal name says so: `'answer-slice(slot)'`.
+ * - `approxTokens*` is a serialized-length estimate (JSON chars ÷ 4), named
+ *   so nobody mistakes it for a tokenizer count.
+ * - The ledger never claims causation. `earnRate` is bookkeeping;
+ *   ablation (context-bisect) can upgrade individual claims when you pay
+ *   for it.
+ */
+/** What kind of context piece a row tracks. Skills are injections with
+ *  flavor 'skill' — split out because their `used` signal differs. */
+export type PieceKind = 'injection' | 'skill' | 'tool';
+/**
+ * The per-kind structural definition of "used" — explicit, never blended:
+ * - `'tool-called'`        — an assistant message actually called the tool.
+ * - `'skill-activated'`    — the run activated the skill
+ *                            (`activatedInjectionIds`).
+ * - `'answer-slice(slot)'` — the injection's SLOT write sits on the final
+ *                            answer's backward dependency slice
+ *                            (slot-granular by construction).
+ */
+export type UsedSignal = 'tool-called' | 'skill-activated' | 'answer-slice(slot)';
+/** One context piece's accumulated bookkeeping across recorded runs. */
+export interface LedgerRow {
+    /** Injection/skill id, or tool name. Unique within its kind. */
+    readonly id: string;
+    readonly kind: PieceKind;
+    /** Offer events — once per iteration the piece was in context, across runs. */
+    readonly offered: number;
+    /** Serialized-length token ESTIMATE spent on those offers (chars ÷ 4). */
+    readonly approxTokensSpent: number;
+    /** Structural uses (per-kind definition — see breakdown in usedVia). */
+    readonly used: number;
+    /** Which signal(s) produced the `used` count, and how many each. */
+    readonly usedVia: Readonly<Partial<Record<UsedSignal, number>>>;
+    /** Distinct recorded runs in which the piece was offered at least once. */
+    readonly runsSeen: number;
+    /**
+     * Outcome labels of runs where the piece was OFFERED (label → run count).
+     * Labels are consumer-supplied via {@link ContextLedger.recordOutcome}
+     * (thumbs, eval scores bucketed by the consumer, triage verdicts).
+     * Presence-correlation bookkeeping — NOT a causal claim.
+     */
+    readonly outcomes: Readonly<Record<string, number>>;
+    /** used ÷ offered (0 when never offered). THE headline number. */
+    readonly earnRate: number;
+}
+/** What `recordRun` extracted from one run — returned for inspection/tests. */
+export interface RecordedRun {
+    /** Handle for {@link ContextLedger.recordOutcome}. */
+    readonly runRef: string;
+    /** Piece ids offered in this run (kind-qualified internal keys). */
+    readonly offeredPieces: readonly string[];
+    /** True when the answer slice could be computed (finalContent + reads). */
+    readonly sliceAvailable: boolean;
+}
+/** JSON-safe persisted shape (consumer owns storage). */
+export interface LedgerJSON {
+    readonly version: 1;
+    readonly rows: readonly LedgerRow[];
+    readonly runsRecorded: number;
+}
+/** Minimal runner surface the ledger reads (any agentfootprint Runner). */
+export interface RunnerLike {
+    getLastSnapshot(): unknown;
+}
+export interface ContextLedger {
+    /**
+     * Ingest one FINISHED run: walk its commit log for offers (activeInjections
+     * / dynamicToolSchemas per iteration), uses (assistant tool calls,
+     * activatedInjectionIds, the final answer's dependency slice), and
+     * accumulate. Accepts a runner (reads `getLastSnapshot()`) or a snapshot.
+     */
+    recordRun(source: RunnerLike | unknown): RecordedRun | undefined;
+    /**
+     * Label a recorded run's outcome ('good'/'bad'/any consumer label —
+     * thumbs, bucketed eval score, triage verdict). Defaults to the most
+     * recently recorded run. Increments the label for every piece OFFERED in
+     * that run.
+     */
+    recordOutcome(label: string, runRef?: string): boolean;
+    /** All rows, worst earnRate first (the review order that matters). */
+    rows(): readonly LedgerRow[];
+    /** One row (by kind + id). */
+    row(kind: PieceKind, id: string): LedgerRow | undefined;
+    /** JSON-safe export (consumer persists). */
+    exportJSON(): LedgerJSON;
+    /** Merge a previously exported ledger in (counts add). */
+    importJSON(json: LedgerJSON): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/context-ledger/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/context-ledger/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;sEACsE;AACtE,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAElF,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAChE,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAED,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,eAAe,IAAI,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;IACjE;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvD,sEAAsE;IACtE,IAAI,IAAI,SAAS,SAAS,EAAE,CAAC;IAC7B,8BAA8B;IAC9B,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACxD,4CAA4C;IAC5C,UAAU,IAAI,UAAU,CAAC;IACzB,0DAA0D;IAC1D,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CACpC"}

package/dist/types/observe.d.ts

@@ -55,4 +55,6 @@ export { typedEmit } from './recorders/core/typedEmit.js';
 export * from "./debug.js";
 export { buildChoiceContext, toolChoiceRecorder, type OfferedTool, type ToolChoiceCall, type ToolChoiceRecorderHandle, type ToolChoiceRecorderOptions, type ToolChoiceSkipReason, type ToolChoiceSummary, } from './recorders/observability/ToolChoiceRecorder.js';
 export { routeRecorder, formatRouteHop, type RouteRecorderHandle, type RouteRecorderOptions, type RouteHop, type RouteOutcome, type RouteTrip, type RouteTripKind, } from './recorders/observability/RouteRecorder.js';
+export { contextLedger, ledgerToolGate, ledgerEntryScorer, ledgerGated } from './lib/context-ledger/index.js';
+export type { ContextLedger, LedgerJSON, LedgerPolicy, LedgerRow, PieceKind, RecordedRun, UsedSignal, } from './lib/context-ledger/index.js';
 //# sourceMappingURL=observe.d.ts.map

package/dist/types/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",