agentfootprint 7.1.0 → 7.3.0

package/dist/esm/lib/context-ledger/contextLedger.js

@@ -0,0 +1,309 @@
+/**
+ * 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 { commitValueAt, findLastWriter, flattenCausalDAG, keysReadFromExecutionTree, sliceForKey, } from 'footprintjs/trace';
+import { parseRuntimeStageId, splitStageId } from 'footprintjs/trace';
+import { INJECTION_KEYS, SUBFLOW_IDS } from '../../conventions.js';
+/** chars ÷ 4 — a serialized-length ESTIMATE, deliberately rough and cheap. */
+function approxTokens(value) {
+    try {
+        return Math.ceil(JSON.stringify(value).length / 4);
+    }
+    catch {
+        return 0;
+    }
+}
+/** sf-llm-call mount keys in loop order — grouped-mode iterations live in
+ *  their own retained inner logs (the same projection context-bisect's
+ *  assembleGroupedTrajectory uses). */
+function llmCallMountKeys(subflowResults) {
+    if (!subflowResults)
+        return [];
+    return Object.keys(subflowResults)
+        .filter((k) => k.includes('#') && splitStageId(k.split('#')[0]).localStageId === SUBFLOW_IDS.LLM_CALL)
+        .sort((a, b) => parseRuntimeStageId(a).executionIndex - parseRuntimeStageId(b).executionIndex);
+}
+function snapshotOf(source) {
+    const maybeRunner = source;
+    if (typeof maybeRunner?.getLastSnapshot === 'function') {
+        return maybeRunner.getLastSnapshot();
+    }
+    return source;
+}
+/** Static tool registry names, duck-read from the runner's public UI-group
+ *  metadata (Agent fills `extra.toolNames`). Empty for non-runner sources. */
+function staticToolNamesOf(source) {
+    const maybeRunner = source;
+    if (typeof maybeRunner?.getUIGroup !== 'function')
+        return [];
+    try {
+        const names = maybeRunner.getUIGroup()?.extra?.toolNames;
+        return Array.isArray(names) ? names.filter((n) => typeof n === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function contextLedger() {
+    const table = new Map(); // key: `${kind}:${id}`
+    const runOffers = new Map(); // runRef → offered keys
+    let runsRecorded = 0;
+    let lastRunRef;
+    function rowOf(kind, id) {
+        const key = `${kind}:${id}`;
+        let row = table.get(key);
+        if (!row) {
+            row = { id, kind, offered: 0, approxTokensSpent: 0, used: 0, usedVia: {}, runsSeen: 0, outcomes: {} };
+            table.set(key, row);
+        }
+        return row;
+    }
+    function markUsed(kind, id, via) {
+        const row = rowOf(kind, id);
+        row.used += 1;
+        row.usedVia[via] = (row.usedVia[via] ?? 0) + 1;
+    }
+    function recordRun(source) {
+        const snapshot = snapshotOf(source);
+        const log = snapshot?.commitLog;
+        if (!log?.length)
+            return undefined;
+        runsRecorded += 1;
+        const runRef = `run-${runsRecorded}`;
+        const offeredKeys = new Set();
+        const offer = (kind, id, tokens) => {
+            const row = rowOf(kind, id);
+            row.offered += 1;
+            row.approxTokensSpent += tokens;
+            offeredKeys.add(`${kind}:${id}`);
+        };
+        // ── OFFERS: the context IN EFFECT at each LLM call ───────────────────
+        // Call marker: wrote totalInputTokens (monotonic — survives the
+        // net-change filter) and NOT userMessage (the seed's unique write).
+        // A SINGLE forward pass per log tracks the latest context values as
+        // writes appear (one commitValueAt per actual write — O(N), review
+        // finding #3), so each marker reads the context in effect exactly even
+        // though identical re-commits are dropped from the log.
+        //
+        // GROUPED reactMode (review finding #1): call-llm + the slots live
+        // INSIDE per-iteration `sf-llm-call#k` subflow logs (their context keys
+        // never bubble to the root), so offers fold over each retained inner
+        // log — the same projection context-bisect's grouped trajectory uses.
+        const staticTools = staticToolNamesOf(source);
+        let callMarkers = 0;
+        const foldOffersFrom = (bundles) => {
+            let injections = [];
+            let schemas = [];
+            for (let i = 0; i < bundles.length; i++) {
+                const paths = new Set(bundles[i].trace.map((t) => t.path));
+                if (paths.has('activeInjections')) {
+                    const v = commitValueAt(bundles, i, 'activeInjections');
+                    if (Array.isArray(v))
+                        injections = v;
+                }
+                if (paths.has('dynamicToolSchemas')) {
+                    const v = commitValueAt(bundles, i, 'dynamicToolSchemas');
+                    if (Array.isArray(v))
+                        schemas = v;
+                }
+                if (!paths.has('totalInputTokens') || paths.has('userMessage'))
+                    continue;
+                callMarkers += 1;
+                for (const inj of injections) {
+                    if (!inj?.id)
+                        continue;
+                    const kind = inj.flavor === 'skill' ? 'skill' : 'injection';
+                    offer(kind, inj.id, approxTokens(inj));
+                }
+                // Tools: dynamic schemas (real sizes) + the static registry (offer
+                // counted, size unknowable from the log in L1 — earnRate unaffected).
+                const offeredToolsThisCall = new Set();
+                for (const schema of schemas) {
+                    if (!schema?.name || offeredToolsThisCall.has(schema.name))
+                        continue;
+                    offeredToolsThisCall.add(schema.name);
+                    offer('tool', schema.name, approxTokens(schema));
+                }
+                for (const name of staticTools) {
+                    if (offeredToolsThisCall.has(name))
+                        continue;
+                    offeredToolsThisCall.add(name);
+                    offer('tool', name, 0);
+                }
+            }
+        };
+        const mountKeys = llmCallMountKeys(snapshot?.subflowResults);
+        if (mountKeys.length > 0) {
+            for (const key of mountKeys) {
+                const inner = snapshot?.subflowResults?.[key]?.treeContext?.history;
+                if (Array.isArray(inner))
+                    foldOffersFrom(inner);
+            }
+        }
+        else {
+            foldOffersFrom(log);
+        }
+        // A run with NO call markers anywhere is a shape this ledger cannot
+        // meter (e.g. the LLMCall runner, which never writes totalInputTokens)
+        // — report honestly instead of confidently recording zero offers.
+        if (callMarkers === 0) {
+            runsRecorded -= 1;
+            return undefined;
+        }
+        // ── USES: tool calls (assistant messages in the final history) ───────
+        const lastIdx = log.length - 1;
+        const history = commitValueAt(log, lastIdx, 'history');
+        if (Array.isArray(history)) {
+            for (const msg of history) {
+                if (msg?.role !== 'assistant' || !Array.isArray(msg.toolCalls))
+                    continue;
+                for (const call of msg.toolCalls) {
+                    if (call?.name)
+                        markUsed('tool', call.name, 'tool-called');
+                }
+            }
+        }
+        // ── USES: skill activations ──────────────────────────────────────────
+        const activated = commitValueAt(log, lastIdx, 'activatedInjectionIds');
+        if (Array.isArray(activated)) {
+            for (const id of activated) {
+                if (typeof id === 'string' && id.length > 0)
+                    markUsed('skill', id, 'skill-activated');
+            }
+        }
+        // ── USES: answer-slice membership per slot (slot-granular, honest) ───
+        // Slice the final answer; a slot counts as "on the answer's dependency
+        // chain" when its key's LAST WRITER is a slice member. Every injection
+        // in the FINAL context of that slot gets the (shared) credit.
+        let sliceAvailable = false;
+        const tree = snapshot?.executionTree;
+        if (tree) {
+            const reads = keysReadFromExecutionTree(tree);
+            const slice = sliceForKey(log, 'finalContent', reads);
+            if (slice.root) {
+                sliceAvailable = true;
+                const memberIds = new Set(flattenCausalDAG(slice.root).map((n) => n.runtimeStageId));
+                const finalInjections = commitValueAt(log, lastIdx, 'activeInjections');
+                const finalBySlotKey = new Map();
+                // Which slot carried each injection is projected per-slot into the
+                // INJECTION_KEYS records — fold each slot key's final value.
+                for (const slotKey of Object.values(INJECTION_KEYS)) {
+                    const writer = findLastWriter(log, slotKey);
+                    if (!writer || !memberIds.has(writer.runtimeStageId))
+                        continue;
+                    const slotRecords = commitValueAt(log, lastIdx, slotKey);
+                    if (Array.isArray(slotRecords))
+                        finalBySlotKey.set(slotKey, slotRecords);
+                }
+                // Credit: injections present in a slice-member slot's final records.
+                const activeById = new Map();
+                if (Array.isArray(finalInjections)) {
+                    for (const inj of finalInjections) {
+                        if (inj?.id)
+                            activeById.set(inj.id, inj);
+                    }
+                }
+                for (const records of finalBySlotKey.values()) {
+                    for (const rec of records) {
+                        const id = rec?.id;
+                        if (!id)
+                            continue;
+                        const flavor = activeById.get(id)?.flavor ?? rec.source;
+                        const kind = flavor === 'skill' ? 'skill' : 'injection';
+                        markUsed(kind, id, 'answer-slice(slot)');
+                    }
+                }
+            }
+        }
+        // runsSeen: once per run per offered piece.
+        for (const key of offeredKeys) {
+            const row = table.get(key);
+            if (row)
+                row.runsSeen += 1;
+        }
+        runOffers.set(runRef, offeredKeys);
+        lastRunRef = runRef;
+        return { runRef, offeredPieces: [...offeredKeys], sliceAvailable };
+    }
+    function recordOutcome(label, runRef) {
+        const ref = runRef ?? lastRunRef;
+        if (!ref)
+            return false;
+        const offered = runOffers.get(ref);
+        if (!offered)
+            return false;
+        for (const key of offered) {
+            const row = table.get(key);
+            if (row)
+                row.outcomes[label] = (row.outcomes[label] ?? 0) + 1;
+        }
+        return true;
+    }
+    function freeze(row) {
+        return {
+            ...row,
+            usedVia: { ...row.usedVia },
+            outcomes: { ...row.outcomes },
+            earnRate: row.offered > 0 ? row.used / row.offered : 0,
+        };
+    }
+    return {
+        recordRun,
+        recordOutcome,
+        rows: () => [...table.values()].map(freeze).sort((a, b) => a.earnRate - b.earnRate),
+        row: (kind, id) => {
+            const row = table.get(`${kind}:${id}`);
+            return row ? freeze(row) : undefined;
+        },
+        exportJSON: () => ({ version: 1, rows: [...table.values()].map(freeze), runsRecorded }),
+        importJSON: (json) => {
+            if (json?.version !== 1)
+                return;
+            for (const r of json.rows) {
+                const row = rowOf(r.kind, r.id);
+                row.offered += r.offered;
+                row.approxTokensSpent += r.approxTokensSpent;
+                row.used += r.used;
+                row.runsSeen += r.runsSeen;
+                for (const [via, n] of Object.entries(r.usedVia)) {
+                    row.usedVia[via] = (row.usedVia[via] ?? 0) + (n ?? 0);
+                }
+                for (const [label, n] of Object.entries(r.outcomes)) {
+                    row.outcomes[label] = (row.outcomes[label] ?? 0) + n;
+                }
+            }
+            runsRecorded += json.runsRecorded;
+        },
+    };
+}
+//# sourceMappingURL=contextLedger.js.map

package/dist/esm/lib/context-ledger/contextLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextLedger.js","sourceRoot":"","sources":["../../../../src/lib/context-ledger/contextLedger.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,63 @@
+/**
+ * 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;

package/dist/esm/lib/context-ledger/gates.js

@@ -0,0 +1,105 @@
+/**
+ * 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 { rankEntries } from '../injection-engine/entryScorer.js';
+const DEFAULTS = { minOffers: 5, earnRateFloor: 0.05, refreshEvery: 10 };
+/**
+ * The shared verdict: should this piece be included right now?
+ * Stateful per gate instance (the parole counter), pure otherwise.
+ */
+function makeVerdict(ledger, policy) {
+    const p = { ...DEFAULTS, ...policy };
+    const demotions = new Map();
+    return (kind, id) => {
+        const row = ledger.row(kind, id);
+        if (!row)
+            return true; // unknown to the ledger → always include
+        if (row.offered < p.minOffers)
+            return true; // not enough data to judge
+        if (row.earnRate >= p.earnRateFloor)
+            return true; // earning its tokens
+        // Demoted — but parole every Nth decision keeps the data flowing.
+        const key = `${kind}:${id}`;
+        const count = (demotions.get(key) ?? 0) + 1;
+        demotions.set(key, count);
+        return p.refreshEvery !== Infinity && count % p.refreshEvery === 0;
+    };
+}
+/**
+ * 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 function ledgerToolGate(ledger, policy) {
+    const verdict = makeVerdict(ledger, policy);
+    return (toolName) => verdict('tool', toolName);
+}
+/**
+ * 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 function ledgerEntryScorer(ledger, inner, policy) {
+    const verdict = makeVerdict(ledger, policy);
+    const DEMOTION_WEIGHT = 0.25;
+    return {
+        name: `ledger(${inner.name})`,
+        async score(input, signal) {
+            const base = await inner.score(input, signal);
+            // Re-rank through rankEntries so `chosen`, `score` AND `relevance` are
+            // recomputed TOGETHER from the demoted scores — preserving the
+            // entryScorer contract (argmax-score == argmax-relevance; the "Why
+            // this skill?" panel and the pick can never disagree).
+            const candidates = base.ranked.map((r) => ({
+                id: r.id,
+                description: input.candidates.find((c) => c.id === r.id)?.description ?? '',
+            }));
+            const demotedScores = base.ranked.map((r) => verdict('skill', r.id) ? r.score : r.score * DEMOTION_WEIGHT);
+            return rankEntries(`ledger(${base.scorer})`, candidates, demotedScores);
+        },
+    };
+}
+/**
+ * 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 function ledgerGated(injection, ledger, policy) {
+    const verdict = makeVerdict(ledger, policy);
+    const kind = injection.flavor === 'skill' ? 'skill' : 'injection';
+    const trigger = injection.trigger;
+    if (trigger.kind === 'always') {
+        return { ...injection, trigger: { kind: 'rule', activeWhen: () => verdict(kind, injection.id) } };
+    }
+    if (trigger.kind === 'rule') {
+        const original = trigger.activeWhen;
+        return {
+            ...injection,
+            trigger: { kind: 'rule', activeWhen: (ctx) => original(ctx) && verdict(kind, injection.id) },
+        };
+    }
+    return injection; // demand-driven triggers pass through untouched
+}
+//# sourceMappingURL=gates.js.map

package/dist/esm/lib/context-ledger/gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../../../../src/lib/context-ledger/gates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAuBjE,MAAM,QAAQ,GAA2B,EAAE,SAAS,EAAE,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;AAEjG;;;GAGG;AACH,SAAS,WAAW,CAClB,MAAqB,EACrB,MAAgC;IAEhC,MAAM,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC;IACrC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE;QAClB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC,CAAC,yCAAyC;QAChE,IAAI,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC,CAAC,2BAA2B;QACvE,IAAI,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,aAAa;YAAE,OAAO,IAAI,CAAC,CAAC,qBAAqB;QACvE,kEAAkE;QAClE,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC5C,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1B,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC;IACrE,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB,EAAE,MAAqB;IACzE,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAqB,EACrB,KAAkB,EAClB,MAAqB;IAErB,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,eAAe,GAAG,IAAI,CAAC;IAC7B,OAAO;QACL,IAAI,EAAE,UAAU,KAAK,CAAC,IAAI,GAAG;QAC7B,KAAK,CAAC,KAAK,CAAC,KAAuB,EAAE,MAAoB;YACvD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC9C,uEAAuE;YACvE,+DAA+D;YAC/D,mEAAmE;YACnE,uDAAuD;YACvD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACzC,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,IAAI,EAAE;aAC5E,CAAC,CAAC,CAAC;YACJ,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1C,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,eAAe,CAC7D,CAAC;YACF,OAAO,WAAW,CAAC,UAAU,IAAI,CAAC,MAAM,GAAG,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;QAC1E,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,SAAoB,EACpB,MAAqB,EACrB,MAAqB;IAErB,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAc,SAAS,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;IAC7E,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC;IAClC,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,EAAE,GAAG,SAAS,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;IACpG,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;QACpC,OAAO;YACL,GAAG,SAAS;YACZ,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE;SAC7F,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC,CAAC,gDAAgD;AACpE,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * 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';

package/dist/esm/lib/context-ledger/index.js

@@ -0,0 +1,10 @@
+/**
+ * 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 { ledgerToolGate, ledgerEntryScorer, ledgerGated } from './gates.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/lib/context-ledger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/context-ledger/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AASnD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,WAAW,EAAqB,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,107 @@
+/**
+ * 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;
+}