agentfootprint 7.1.0 → 7.3.0

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/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/esm/lib/influence-core/attribute.d.ts

@@ -0,0 +1,27 @@
+import type { ChoiceAttribution, AttributionUnit, Embedder } from './types.js';
+export interface AttributeChoiceArgs {
+    /**
+     * The chosen tool being explained. `text` is what gets embedded — pass
+     * name + description (the name matters: rules that NAME a tool, e.g.
+     * "call report_gap", are its strongest citation).
+     */
+    readonly tool: {
+        readonly name: string;
+        readonly text: string;
+    };
+    /** The context units to attribute to — the system-prompt rules, the task, … */
+    readonly units: readonly AttributionUnit[];
+    /** Injected embedder. Wrap in an `EmbeddingCache` so rule texts embed once. */
+    readonly embedder: Embedder;
+    /** Abort signal threaded to the embedder (network backends). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Embed the tool text and every unit once (deduplicated batch), rank the
+ * units by cosine to the tool, and report the top unit plus the per-channel
+ * share of positive similarity mass.
+ *
+ * Fail-loud validation: empty units or duplicate unit ids throw — those are
+ * caller wiring bugs, not runtime conditions.
+ */
+export declare function attributeChoice(args: AttributeChoiceArgs): Promise<ChoiceAttribution>;

package/dist/esm/lib/influence-core/attribute.js

@@ -0,0 +1,91 @@
+/**
+ * attributeChoice — which context UNIT best explains one tool choice
+ * (the transpose of `scoreMargin`).
+ *
+ * `scoreMargin` fixes the context and ranks candidate tools against it —
+ * so a CONSTANT part of the context (the system prompt, identical on every
+ * call) is excluded, because it adds no power to tell one call apart from
+ * another. But that exclusion also makes procedural picks unexplainable:
+ * the agent calls `whats_here` because a RULE in the system prompt says
+ * "orient first", and margin scoring can never see that rule.
+ *
+ * `attributeChoice` fixes the CHOSEN TOOL and ranks the context units
+ * against it. Here a constant-but-load-bearing rule is exactly what we
+ * want surfaced: cosine(tool, "call whats_here first") is high and
+ * specific, so the answer becomes a citation — "picked because rule-1".
+ * The units are tagged by channel (`'system' | 'task' | 'result' | …`) so
+ * the result also reports HOW procedural vs topical the pick was.
+ *
+ * Pattern: pure async function, embedder-injected. No agent/runtime
+ *          imports — `src/lib/influence-core/` leaf, same as `scoreMargin`.
+ *
+ * Honest claim (RFC-002 §2): `score` is embedding geometry between the
+ * tool text and each instruction unit — a PROXY for which instruction the
+ * pick ALIGNS with, never proof the model used that rule. This is Tier 1
+ * (similarity); Tier 3 (counterfactual ablation of each unit) is the
+ * ground truth that would validate it.
+ */
+import { cosineSimilarity } from '../../memory/embedding/cosine.js';
+/**
+ * Embed the tool text and every unit once (deduplicated batch), rank the
+ * units by cosine to the tool, and report the top unit plus the per-channel
+ * share of positive similarity mass.
+ *
+ * Fail-loud validation: empty units or duplicate unit ids throw — those are
+ * caller wiring bugs, not runtime conditions.
+ */
+export async function attributeChoice(args) {
+    const { tool, units, embedder } = args;
+    validate(units);
+    // One deduplicated embedding pass: the tool text + each distinct unit text.
+    const distinct = [...new Set([tool.text, ...units.map((u) => u.text)])];
+    const vectors = embedder.embedBatch
+        ? await embedder.embedBatch({ texts: distinct, ...(args.signal ? { signal: args.signal } : {}) })
+        : await sequentialEmbed(embedder, distinct, args.signal);
+    const vectorByText = new Map();
+    for (let i = 0; i < distinct.length; i++)
+        vectorByText.set(distinct[i], vectors[i]);
+    const toolVec = vectorByText.get(tool.text);
+    const scored = units.map((u) => ({
+        id: u.id,
+        channel: u.channel,
+        score: cosineSimilarity(toolVec, vectorByText.get(u.text)),
+    }));
+    // Stable sort — ties keep input order.
+    scored.sort((a, b) => b.score - a.score);
+    // Per-channel share of POSITIVE mass (negatives are anti-alignment, not
+    // evidence FOR a channel — clamp to 0 so they neither add nor subtract).
+    const positiveByChannel = {};
+    let total = 0;
+    for (const s of scored) {
+        const w = Math.max(0, s.score);
+        if (w === 0)
+            continue;
+        positiveByChannel[s.channel] = (positiveByChannel[s.channel] ?? 0) + w;
+        total += w;
+    }
+    const byChannel = {};
+    if (total > 0)
+        for (const [ch, w] of Object.entries(positiveByChannel))
+            byChannel[ch] = w / total;
+    return { tool: tool.name, units: scored, top: scored[0], byChannel };
+}
+async function sequentialEmbed(embedder, texts, signal) {
+    const out = [];
+    for (const text of texts)
+        out.push(await embedder.embed({ text, ...(signal ? { signal } : {}) }));
+    return out;
+}
+function validate(units) {
+    if (units.length === 0) {
+        throw new Error('attributeChoice: units must be non-empty — nothing to attribute to');
+    }
+    const ids = new Set();
+    for (const u of units) {
+        if (ids.has(u.id)) {
+            throw new Error(`attributeChoice: duplicate unit id '${u.id}' — ids must be unique`);
+        }
+        ids.add(u.id);
+    }
+}
+//# sourceMappingURL=attribute.js.map

package/dist/esm/lib/influence-core/attribute.js.map

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

package/dist/esm/lib/influence-core/explain.d.ts

@@ -0,0 +1,67 @@
+import type { AttributionUnit, Embedder, UnitScore } from './types.js';
+export interface ExplainChoiceArgs {
+    /**
+     * The chosen tool being explained. `text` is what gets embedded — pass
+     * name + description (the name matters: a data snippet that NAMES the
+     * thing the tool acts on, e.g. "id: d42", is its strongest citation).
+     */
+    readonly tool: {
+        readonly name: string;
+        readonly text: string;
+    };
+    /**
+     * The context units, tagged by channel — e.g. `'system'` rules,
+     * the `'task'`, `'data'` snippets from `snippetUnits`. Channels are
+     * free-form strings; the verdict reports whatever labels it is given.
+     */
+    readonly units: readonly AttributionUnit[];
+    /** Injected embedder. Wrap in an `EmbeddingCache` so rule texts embed once. */
+    readonly embedder: Embedder;
+    /** Abort signal threaded to the embedder (network backends). */
+    readonly signal?: AbortSignal;
+}
+/** One channel's verdict: how much of the pick's positive similarity
+ *  mass it owns, and the best unit inside it to quote. */
+export interface ChannelVerdict {
+    readonly channel: string;
+    /**
+     * 0..1 share of POSITIVE similarity mass (negatives are clamped out,
+     * same as `attributeChoice.byChannel`). Shares across all channels sum
+     * to ~1 — or are all 0 when no unit had positive similarity.
+     */
+    readonly share: number;
+    /** The best-scoring unit IN this channel, text included for quoting.
+     *  Omitted only when the channel has no units. */
+    readonly top?: UnitScore & {
+        readonly text: string;
+    };
+}
+/** The full explanation for one tool pick — `attributeChoice` reshaped
+ *  for display: text carried through, channels ranked. */
+export interface ChoiceExplanation {
+    /** The chosen tool being explained. */
+    readonly tool: string;
+    /**
+     * One verdict per channel present in the units, sorted by share
+     * descending (ties keep first-appearance order). Zero-share channels
+     * are listed too — absence of pull is part of the verdict.
+     */
+    readonly channels: readonly ChannelVerdict[];
+    /** The overall best unit — the citation ("picked because …"). */
+    readonly top: UnitScore & {
+        readonly text: string;
+    };
+    /** Every unit ranked descending (ties keep input order), text included. */
+    readonly units: readonly (UnitScore & {
+        readonly text: string;
+    })[];
+}
+/**
+ * Run `attributeChoice` and reshape the result for a UI: join each unit's
+ * text back by id, pick the best unit per channel, and rank the channels
+ * by their share of positive similarity mass.
+ *
+ * Fail-loud validation is inherited from `attributeChoice`: empty units
+ * or duplicate unit ids throw — caller wiring bugs, not runtime conditions.
+ */
+export declare function explainChoice(args: ExplainChoiceArgs): Promise<ChoiceExplanation>;

package/dist/esm/lib/influence-core/explain.js

@@ -0,0 +1,80 @@
+/**
+ * explainChoice — a UI-ready VERDICT for one tool pick: which context
+ * CHANNEL (system rules / user task / data from earlier tool results)
+ * best explains it, with the exact unit text to quote.
+ *
+ * Thin composite over `attributeChoice` — same math, zero duplication:
+ * the ranking, the top unit, and the per-channel share of positive
+ * similarity mass all come from the one existing engine. What this adds
+ * is presentation shape: the unit TEXT carried through (so a UI can
+ * quote the citation verbatim), a per-channel top unit, and a channels
+ * array sorted by share that lists EVERY channel present in the units —
+ * including zero-share ones, so "the data channel contributed nothing"
+ * is a visible verdict, not a missing key.
+ *
+ * Pattern: pure async function, embedder-injected. No agent/runtime
+ *          imports — `src/lib/influence-core/` leaf, same as
+ *          `attributeChoice` / `scoreMargin`.
+ *
+ * Honest claim (RFC-002 §2): every score and share here is embedding
+ * geometry between the tool text and each unit — a PROXY for which
+ * context the pick ALIGNS with, never proof the model used that unit.
+ * This is Tier 1 (similarity); counterfactual ablation (Tier 3) is the
+ * ground truth that would validate it.
+ */
+import { attributeChoice } from './attribute.js';
+/**
+ * Run `attributeChoice` and reshape the result for a UI: join each unit's
+ * text back by id, pick the best unit per channel, and rank the channels
+ * by their share of positive similarity mass.
+ *
+ * Fail-loud validation is inherited from `attributeChoice`: empty units
+ * or duplicate unit ids throw — caller wiring bugs, not runtime conditions.
+ */
+export async function explainChoice(args) {
+    const attribution = await attributeChoice({
+        tool: args.tool,
+        units: args.units,
+        embedder: args.embedder,
+        ...(args.signal ? { signal: args.signal } : {}),
+    });
+    // Join the unit text back by id (ids are unique — attributeChoice validated).
+    const textById = new Map();
+    for (const u of args.units)
+        textById.set(u.id, u.text);
+    const withText = (score) => ({
+        ...score,
+        text: textById.get(score.id),
+    });
+    const ranked = attribution.units.map(withText);
+    // One verdict per channel, in first-appearance order (stable tiebreak),
+    // then sorted by share descending. `ranked` is already descending, so
+    // the first unit seen per channel is that channel's top.
+    const channelOrder = [];
+    const topByChannel = new Map();
+    for (const u of args.units) {
+        if (!channelOrder.includes(u.channel))
+            channelOrder.push(u.channel);
+    }
+    for (const unit of ranked) {
+        if (!topByChannel.has(unit.channel))
+            topByChannel.set(unit.channel, unit);
+    }
+    const channels = channelOrder.map((channel) => {
+        const top = topByChannel.get(channel);
+        return {
+            channel,
+            share: attribution.byChannel[channel] ?? 0,
+            ...(top ? { top } : {}),
+        };
+    });
+    // Stable sort — zero-share channels sink to the end, ties keep order.
+    channels.sort((a, b) => b.share - a.share);
+    return {
+        tool: attribution.tool,
+        channels,
+        top: withText(attribution.top),
+        units: ranked,
+    };
+}
+//# sourceMappingURL=explain.js.map

package/dist/esm/lib/influence-core/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAsDjD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAuB;IACzD,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC;QACxC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC,CAAC;IAEH,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK;QAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,CAAC,KAAgB,EAAyC,EAAE,CAAC,CAAC;QAC7E,GAAG,KAAK;QACR,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAW;KACvC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE/C,wEAAwE;IACxE,sEAAsE;IACtE,yDAAyD;IACzD,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAiD,CAAC;IAC9E,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;YAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACtE,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,QAAQ,GAAqB,YAAY,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9D,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtC,OAAO;YACL,OAAO;YACP,KAAK,EAAE,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;YAC1C,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxB,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,IAAI;QACtB,QAAQ;QACR,GAAG,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC;QAC9B,KAAK,EAAE,MAAM;KACd,CAAC;AACJ,CAAC"}

package/dist/esm/lib/influence-core/index.d.ts

@@ -24,7 +24,7 @@
  * embedding-geometry PROXY — semantic alignment, never model internals
  * and never causal attribution.
  */
-export type { CandidateScore, ConfidenceStrategy, EmbedArgs, EmbedBatchArgs, Embedder, EvidenceInput, InfluenceScore, InfluenceWeights, MarginCandidate, MarginResult, PairwiseSimilarityResult, RankingConfidence, SignalScores, SimilarityItem, SimilarityPair, } from './types.js';
+export type { CandidateScore, AttributionUnit, ChoiceAttribution, ConfidenceStrategy, EmbedArgs, EmbedBatchArgs, Embedder, EvidenceInput, InfluenceScore, InfluenceWeights, MarginCandidate, MarginResult, PairwiseSimilarityResult, RankingConfidence, SignalScores, SimilarityItem, SimilarityPair, UnitScore, } from './types.js';
 export { DEFAULT_CLEAR_WINNER_MARGIN, DEFAULT_CLEAR_WINNER_RATIO, DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, DEFAULT_SHORTLIST_BAND, } from './types.js';
 export { marginStrategy, rankingConfidence, ratioStrategy, type RankingConfidenceOptions, } from './attributability.js';
 export { scoreContrastiveInfluence, type ScoreContrastiveInfluenceArgs } from './contrastive.js';
@@ -32,3 +32,6 @@ export { contentHash, EmbeddingCache, embeddingCache, type EmbeddingCacheOptions
 export { adaptWeights, averageRelevancy, compositeScore, finalAnswerSimilarity, persistence, scoreInfluence, structuralProximity, type InfluenceScorer, type ScoreInfluenceArgs, } from './signals.js';
 export { pairwiseSimilarity, type PairwiseSimilarityArgs } from './similarity.js';
 export { scoreMargin, type ScoreMarginArgs } from './margin.js';
+export { attributeChoice, type AttributeChoiceArgs } from './attribute.js';
+export { explainChoice, type ChannelVerdict, type ChoiceExplanation, type ExplainChoiceArgs, } from './explain.js';
+export { snippetUnits, type SnippetUnitsOptions } from './snippets.js';

package/dist/esm/lib/influence-core/index.js

@@ -31,4 +31,7 @@ export { contentHash, EmbeddingCache, embeddingCache, } from './cache.js';
 export { adaptWeights, averageRelevancy, compositeScore, finalAnswerSimilarity, persistence, scoreInfluence, structuralProximity, } from './signals.js';
 export { pairwiseSimilarity } from './similarity.js';
 export { scoreMargin } from './margin.js';
+export { attributeChoice } from './attribute.js';
+export { explainChoice, } from './explain.js';
+export { snippetUnits } from './snippets.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/lib/influence-core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAmBH,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,yBAAyB,EAAsC,MAAM,kBAAkB,CAAC;AAEjG,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,GAGf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,GAGpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAA+B,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAsBH,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,yBAAyB,EAAsC,MAAM,kBAAkB,CAAC;AAEjG,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,GAGf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,GAGpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAA+B,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,eAAe,EAA4B,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EACL,aAAa,GAId,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAA4B,MAAM,eAAe,CAAC"}

package/dist/esm/lib/influence-core/snippets.d.ts

@@ -0,0 +1,45 @@
+/**
+ * snippetUnits — cut a tool result into citable AttributionUnits for the
+ * `'data'` channel.
+ *
+ * `explainChoice` can only credit the data channel with units to point
+ * at — a raw tool result (arbitrary JSON or prose) is not citable as one
+ * blob. This helper cuts it at the natural citation grain so a pick like
+ * "open dress d42" can be attributed to the exact search-result snippet
+ * that returned d42:
+ *
+ *   • a string → one unit per sentence/line (non-empty, trimmed),
+ *   • an array element that is an object → ONE unit summarizing it — its
+ *     primitive fields joined as `key: value` pairs (a search hit, a row),
+ *   • any other object → its primitive fields grouped into one unit,
+ *     then the walk continues into nested objects/arrays,
+ *   • null/undefined/booleans/empty strings/functions/symbols → skipped.
+ *
+ * Bounded and total: at most `max` units, each truncated to `maxLength`
+ * characters; circular references are guarded (WeakSet) — weird input
+ * yields fewer units, never a throw.
+ *
+ * Pattern: pure synchronous function, zero imports beyond the shared
+ *          types — `src/lib/influence-core/` leaf. No embedding happens
+ *          here; the units feed `attributeChoice` / `explainChoice`.
+ *
+ * Honest claim: this is a CUTTER, not a ranker — it decides what is
+ * quotable, not what mattered. Whether a snippet explains the pick is
+ * the (proxy) verdict of the similarity scoring downstream.
+ */
+import type { AttributionUnit } from './types.js';
+export interface SnippetUnitsOptions {
+    /** Channel tag stamped on every unit. Default `'data'`. */
+    readonly channel?: string;
+    /** Unit id prefix — ids become `'<prefix>-1'`, `'<prefix>-2'`, … Default `'data'`. */
+    readonly idPrefix?: string;
+    /** Cap on units returned. Default 12. */
+    readonly max?: number;
+    /** Cap on characters per unit text (ellipsis included). Default 200. */
+    readonly maxLength?: number;
+}
+/**
+ * Cut `value` (a tool result — arbitrary JSON value or prose string)
+ * into at most `max` citable units for the data channel.
+ */
+export declare function snippetUnits(value: unknown, options?: SnippetUnitsOptions): AttributionUnit[];

package/dist/esm/lib/influence-core/snippets.js

@@ -0,0 +1,114 @@
+/**
+ * Cut `value` (a tool result — arbitrary JSON value or prose string)
+ * into at most `max` citable units for the data channel.
+ */
+export function snippetUnits(value, options = {}) {
+    const channel = options.channel ?? 'data';
+    const idPrefix = options.idPrefix ?? 'data';
+    const max = options.max ?? 12;
+    const maxLength = options.maxLength ?? 200;
+    const texts = [];
+    collect(value, texts, max, new WeakSet());
+    return texts.map((text, i) => ({
+        id: `${idPrefix}-${i + 1}`,
+        channel,
+        text: truncate(text, maxLength),
+    }));
+}
+/** Walk `value` depth-first, pushing snippet texts until `max` is reached. */
+function collect(value, out, max, seen) {
+    if (out.length >= max)
+        return;
+    if (typeof value === 'string') {
+        for (const sentence of splitSentences(value)) {
+            if (out.length >= max)
+                return;
+            out.push(sentence);
+        }
+        return;
+    }
+    if (isCitablePrimitive(value)) {
+        out.push(String(value));
+        return;
+    }
+    if (typeof value !== 'object' || value === null)
+        return; // boolean/null/undefined/function/symbol
+    if (seen.has(value))
+        return; // circular reference — already visited
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const element of value) {
+            if (out.length >= max)
+                return;
+            if (isPlainRecord(element)) {
+                // The natural citation grain: one unit per row/hit, then walk its
+                // nested values (a hit may itself contain an array of hits).
+                if (seen.has(element))
+                    continue;
+                seen.add(element);
+                const summary = summarizeFields(element);
+                if (summary !== '')
+                    out.push(summary);
+                for (const nested of Object.values(element)) {
+                    if (typeof nested === 'object' && nested !== null)
+                        collect(nested, out, max, seen);
+                }
+            }
+            else {
+                collect(element, out, max, seen);
+            }
+        }
+        return;
+    }
+    // Non-array object: group its primitive fields into one unit, recurse
+    // into the rest.
+    const summary = summarizeFields(value);
+    if (summary !== '')
+        out.push(summary);
+    for (const nested of Object.values(value)) {
+        if (out.length >= max)
+            return;
+        if (typeof nested === 'object' && nested !== null)
+            collect(nested, out, max, seen);
+    }
+}
+/** Join an object's own citable primitive fields as `key: value` pairs. */
+function summarizeFields(record) {
+    const pairs = [];
+    for (const [key, v] of Object.entries(record)) {
+        if (typeof v === 'string') {
+            const trimmed = v.trim();
+            if (trimmed !== '')
+                pairs.push(`${key}: ${trimmed}`);
+        }
+        else if (isCitablePrimitive(v)) {
+            pairs.push(`${key}: ${String(v)}`);
+        }
+    }
+    return pairs.join(', ');
+}
+/** Non-string primitives worth quoting: numbers and bigints. Booleans,
+ *  null, and undefined carry no citable content — skipped. */
+function isCitablePrimitive(value) {
+    return typeof value === 'number' || typeof value === 'bigint';
+}
+/** A record-shaped object (not an array) — the row/hit case. */
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Split prose into sentences/lines; non-empty, trimmed. */
+function splitSentences(text) {
+    return text
+        .split(/(?<=[.!?])\s+|\n+/)
+        .map((s) => s.trim())
+        .filter((s) => s !== '');
+}
+/** Cap text at `maxLength` characters, ellipsis included. */
+function truncate(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    if (maxLength <= 1)
+        return '…';
+    return `${text.slice(0, maxLength - 1)}…`;
+}
+//# sourceMappingURL=snippets.js.map

package/dist/esm/lib/influence-core/snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippets.js","sourceRoot":"","sources":["../../../../src/lib/influence-core/snippets.ts"],"names":[],"mappings":"AA0CA;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,UAA+B,EAAE;IAC5E,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC;IAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IAE3C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,OAAO,EAAE,CAAC,CAAC;IAE1C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7B,EAAE,EAAE,GAAG,QAAQ,IAAI,CAAC,GAAG,CAAC,EAAE;QAC1B,OAAO;QACP,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;KAChC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,8EAA8E;AAC9E,SAAS,OAAO,CAAC,KAAc,EAAE,GAAa,EAAE,GAAW,EAAE,IAAqB;IAChF,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,KAAK,MAAM,QAAQ,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7C,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;gBAAE,OAAO;YAC9B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrB,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACxB,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,CAAC,yCAAyC;IAClG,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,uCAAuC;IACpE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAEhB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;YAC5B,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;gBAAE,OAAO;YAC9B,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3B,kEAAkE;gBAClE,6DAA6D;gBAC7D,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;oBAAE,SAAS;gBAChC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAClB,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;gBACzC,IAAI,OAAO,KAAK,EAAE;oBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACtC,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC5C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;wBAAE,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBACrF,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QACD,OAAO;IACT,CAAC;IAED,sEAAsE;IACtE,iBAAiB;IACjB,MAAM,OAAO,GAAG,eAAe,CAAC,KAAgC,CAAC,CAAC;IAClE,IAAI,OAAO,KAAK,EAAE;QAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtC,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;YAAE,OAAO;QAC9B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACrF,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,SAAS,eAAe,CAAC,MAA+B;IACtD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9C,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;YACzB,IAAI,OAAO,KAAK,EAAE;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;QACvD,CAAC;aAAM,IAAI,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;8DAC8D;AAC9D,SAAS,kBAAkB,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;AAChE,CAAC;AAED,gEAAgE;AAChE,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,4DAA4D;AAC5D,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI;SACR,KAAK,CAAC,mBAAmB,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED,6DAA6D;AAC7D,SAAS,QAAQ,CAAC,IAAY,EAAE,SAAiB;IAC/C,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAC/B,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC;AAC5C,CAAC"}

package/dist/esm/lib/influence-core/types.d.ts

@@ -250,3 +250,53 @@ export interface MarginResult {
         readonly proxyDisagreement: boolean;
     };
 }
+/**
+ * One piece of the context the chooser saw, tagged by which channel it
+ * came from. `scoreMargin` asks "which tool best fits ONE context";
+ * `attributeChoice` asks the transpose — "which context UNIT best explains
+ * ONE chosen tool" — so the unit is the thing being scored here.
+ *
+ * A channel groups units by origin so the attribution can report where the
+ * pull came from: `'system'` (a rule in the system prompt), `'task'` (the
+ * user's request), `'result'` (data a prior tool returned), `'history'`
+ * (an earlier turn). Channels are free-form strings — the caller decides
+ * the taxonomy; the engine only sums by whatever labels it is given.
+ *
+ * (Named `AttributionUnit`, not `ContextUnit`, to stay distinct from
+ * context-bisect's own `ContextUnit`, which is a different subsystem.)
+ */
+export interface AttributionUnit {
+    /** Unique id — the citation the attribution points at, e.g. `'rule-1'`. */
+    readonly id: string;
+    /** Origin group, e.g. `'system' | 'task' | 'result' | 'history'`. */
+    readonly channel: string;
+    /** The text of the unit (a rule sentence, the user task, …). */
+    readonly text: string;
+}
+/** One context unit's proximity to the chosen tool, ranked. */
+export interface UnitScore {
+    readonly id: string;
+    readonly channel: string;
+    /** cosine(embed(tool text), embed(unit.text)). */
+    readonly score: number;
+}
+/**
+ * Which context best explains one tool choice — the transpose of a
+ * `MarginResult`. Same honesty caveat: `score` is embedding geometry
+ * between the tool text and each instruction unit, a PROXY for which
+ * instruction the pick aligns with, never proof the model used that rule.
+ */
+export interface ChoiceAttribution {
+    /** The chosen tool being explained. */
+    readonly tool: string;
+    /** Every unit scored against the tool, descending (ties keep input order). */
+    readonly units: readonly UnitScore[];
+    /** The single best-attributing unit — the citation ("picked because …"). */
+    readonly top: UnitScore;
+    /**
+     * Share of total POSITIVE similarity mass per channel, summing to ~1
+     * (empty when no unit had positive similarity). A pick dominated by the
+     * `system` channel is procedural; one dominated by `task` is topical.
+     */
+    readonly byChannel: Readonly<Record<string, number>>;
+}

package/dist/esm/observe.d.ts

@@ -55,3 +55,5 @@ 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';

package/dist/esm/observe.js

@@ -77,4 +77,8 @@ export * from "./debug.js";
 // LAZILY on first read; flags narrow margins + proxy disagreements.
 export { buildChoiceContext, toolChoiceRecorder, } from './recorders/observability/ToolChoiceRecorder.js';
 export { routeRecorder, formatRouteHop, } from './recorders/observability/RouteRecorder.js';
+// 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.
+export { contextLedger, ledgerToolGate, ledgerEntryScorer, ledgerGated } from './lib/context-ledger/index.js';
 //# sourceMappingURL=observe.js.map

package/dist/esm/observe.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAA+B,MAAM,qCAAqC,CAAC;AACnG,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAEhG,+BAA+B;AAC/B,OAAO,EACL,mBAAmB,GAEpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAgBjB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,GAQhB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,eAAe,EACf,cAAc,EACd,wBAAwB,GAQzB,MAAM,gDAAgD,CAAC;AAExD,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,OAAO,EACL,cAAc,EACd,aAAa,EACb,gBAAgB,GAKjB,MAAM,oCAAoC,CAAC;AAE5C,mFAAmF;AACnF,OAAO,EACL,wBAAwB,GAGzB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,oBAAoB,GAKrB,MAAM,gDAAgD,CAAC;AAExD,6BAA6B;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,wBAAwB,GAEzB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAChG,OAAO,EACL,kBAAkB,GAEnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,cAAc,GAIf,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,YAAY,GAGb,MAAM,6CAA6C,CAAC;AACrD,4EAA4E;AAC5E,gFAAgF;AAChF,OAAO,EACL,mBAAmB,GAMpB,MAAM,kDAAkD,CAAC;AAC1D,gFAAgF;AAChF,gFAAgF;AAChF,OAAO,EACL,kBAAkB,GAQnB,MAAM,yDAAyD,CAAC;AAEjE,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D,kEAAkE;AAClE,uEAAuE;AACvE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,wEAAwE;AACxE,cAAc,YAAY,CAAC;AAC3B,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GAOnB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EACL,aAAa,EACb,cAAc,GAOf,MAAM,4CAA4C,CAAC"}
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAA+B,MAAM,qCAAqC,CAAC;AACnG,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAEhG,+BAA+B;AAC/B,OAAO,EACL,mBAAmB,GAEpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAgBjB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,GAQhB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,eAAe,EACf,cAAc,EACd,wBAAwB,GAQzB,MAAM,gDAAgD,CAAC;AAExD,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,OAAO,EACL,cAAc,EACd,aAAa,EACb,gBAAgB,GAKjB,MAAM,oCAAoC,CAAC;AAE5C,mFAAmF;AACnF,OAAO,EACL,wBAAwB,GAGzB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,oBAAoB,GAKrB,MAAM,gDAAgD,CAAC;AAExD,6BAA6B;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,wBAAwB,GAEzB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAChG,OAAO,EACL,kBAAkB,GAEnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,cAAc,GAIf,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,YAAY,GAGb,MAAM,6CAA6C,CAAC;AACrD,4EAA4E;AAC5E,gFAAgF;AAChF,OAAO,EACL,mBAAmB,GAMpB,MAAM,kDAAkD,CAAC;AAC1D,gFAAgF;AAChF,gFAAgF;AAChF,OAAO,EACL,kBAAkB,GAQnB,MAAM,yDAAyD,CAAC;AAEjE,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D,kEAAkE;AAClE,uEAAuE;AACvE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,wEAAwE;AACxE,cAAc,YAAY,CAAC;AAC3B,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GAOnB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EACL,aAAa,EACb,cAAc,GAOf,MAAM,4CAA4C,CAAC;AAEpD,sEAAsE;AACtE,4EAA4E;AAC5E,+CAA+C;AAC/C,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/esm/recorders/observability/ToolChoiceRecorder.d.ts

@@ -69,8 +69,13 @@
  */
 import type { EmitEvent } from 'footprintjs';
 import { type Embedder, type MarginResult } from '../../lib/influence-core/index.js';
-/** Minimal structural slice of footprintjs's FlowRunEvent (runId is all
- *  we read — Convention 4). */
+/** Minimal structural slice of footprintjs's run-boundary events — the
+ *  `FlowRunEvent` (`onRunStart`/`onRunEnd`/`onRunFailed`) and the
+ *  control-flow `FlowResumeEvent` (`onResume`). runId is all we read
+ *  (Convention 4). The scope-channel `ResumeEvent` this recorder also
+ *  receives (it lands on the scope channel via `onEmit`) carries no
+ *  `traversalContext`, so `traversalContext?.runId` is `undefined` there
+ *  and the handler ignores it. */
 interface RunBoundaryEvent {
     readonly traversalContext?: {
         readonly runId?: string;
@@ -149,6 +154,7 @@ export interface ToolChoiceRecorderHandle {
     clear(): void;
     onEmit(event: EmitEvent): void;
     onRunStart(event: RunBoundaryEvent): void;
+    onResume(event: RunBoundaryEvent): void;
     onRunEnd(event: RunBoundaryEvent): void;
     onRunFailed(event: RunBoundaryEvent): void;
 }