agentfootprint 10.2.0 → 10.3.1

package/dist/esm/context-bisect/arms/probe.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The arm probe — seeded runs in, shared statistics out.
+ *
+ * Split in two on purpose. `collectArmRuns` only RUNS (it cannot know the
+ * reference yet: when no prior answer was supplied, the reference IS the
+ * baseline arm's first answer). `scoreArmRuns` only SCORES. Keeping them apart
+ * is what lets the reference be chosen between the two halves without a second
+ * pass over the model — the same "one ablation, two readouts" thrift
+ * `runAblationProbe` applies to cost.
+ *
+ * Everything statistical is borrowed, not re-derived: `similarityStats`,
+ * `costStatsFrom` and `resolveSamples` come from `ablation.ts` unchanged, so an
+ * arm's `AblationRunStats` is the same number computed the same way as an
+ * ablation's — which is the point of sharing the statistics while keeping the
+ * spec types apart.
+ */
+import type { RunManifestLike } from '../../recorders/observability/recordedManifest.js';
+import type { AblationRunStats, Embedder, OutcomeComparator } from '../types.js';
+import type { ArmApplication, ArmRunner, NullBand, StrategyArm } from './types.js';
+/** The raw harvest of one arm's seeded runs — no scoring yet. */
+export interface ArmRuns {
+    readonly answers: readonly string[];
+    readonly loops: readonly number[];
+    readonly tokens: readonly number[];
+    readonly manifests: readonly RunManifestLike[];
+}
+/**
+ * Call the consumer's runner once per seed (0..samples-1) for ONE arm and
+ * normalize the two return shapes (`string` | `{output, cost?, manifest?}`) —
+ * the same normalization `runAblationProbe` performs, so a bare-string runner
+ * costs the caller nothing in ceremony.
+ */
+export declare function collectArmRuns(arm: StrategyArm, runner: ArmRunner, samples: number): Promise<ArmRuns>;
+/**
+ * Score one arm's harvested answers against the reference: similarity per seed
+ * (mean/min/max/stdev) plus the outcome-flip count. Shape-identical to what an
+ * ablation probe reports.
+ */
+export declare function scoreArmRuns(runs: ArmRuns, reference: string, embedder: Embedder, outcomeChanged: OutcomeComparator): Promise<AblationRunStats>;
+/**
+ * Build the inert-intervention control from the baseline arm's OWN seeded runs.
+ * See {@link NullBand} for why leave-one-out does not transfer and this does.
+ */
+export declare function nullBandFrom(baselineArmId: string, baselineStats: AblationRunStats, gates: boolean): NullBand;
+/**
+ * Did this arm actually take effect? Compares every manifest the runner
+ * reported against the arm's declared facets.
+ *
+ * `checked: false` — and therefore no refusal — in exactly two cases, both of
+ * which are absence of evidence rather than evidence of absence: the runner
+ * reported no manifest, or the arm declares only ablations (no manifest names a
+ * tool catalog). Refusing a verdict in either case would punish a consumer for
+ * a capture they were never required to make.
+ */
+export declare function checkArmApplication(arm: StrategyArm, manifests: readonly RunManifestLike[]): ArmApplication;

package/dist/esm/context-bisect/arms/probe.js

@@ -0,0 +1,125 @@
+/**
+ * The arm probe — seeded runs in, shared statistics out.
+ *
+ * Split in two on purpose. `collectArmRuns` only RUNS (it cannot know the
+ * reference yet: when no prior answer was supplied, the reference IS the
+ * baseline arm's first answer). `scoreArmRuns` only SCORES. Keeping them apart
+ * is what lets the reference be chosen between the two halves without a second
+ * pass over the model — the same "one ablation, two readouts" thrift
+ * `runAblationProbe` applies to cost.
+ *
+ * Everything statistical is borrowed, not re-derived: `similarityStats`,
+ * `costStatsFrom` and `resolveSamples` come from `ablation.ts` unchanged, so an
+ * arm's `AblationRunStats` is the same number computed the same way as an
+ * ablation's — which is the point of sharing the statistics while keeping the
+ * spec types apart.
+ */
+import { cosineSimilarity } from '../../memory/embedding/cosine.js';
+import { costStatsFrom, similarityStats } from '../ablation.js';
+import { checkArmApplied } from './manifest.js';
+import { declaredFacetCount } from './validate.js';
+/**
+ * Call the consumer's runner once per seed (0..samples-1) for ONE arm and
+ * normalize the two return shapes (`string` | `{output, cost?, manifest?}`) —
+ * the same normalization `runAblationProbe` performs, so a bare-string runner
+ * costs the caller nothing in ceremony.
+ */
+export async function collectArmRuns(arm, runner, samples) {
+    const answers = [];
+    const loops = [];
+    const tokens = [];
+    const manifests = [];
+    for (let seed = 0; seed < samples; seed++) {
+        const raw = await runner(arm, { seed });
+        if (typeof raw === 'string') {
+            answers.push(raw);
+            continue;
+        }
+        answers.push(raw.output);
+        if (raw.cost?.loops !== undefined)
+            loops.push(raw.cost.loops);
+        if (raw.cost?.tokens !== undefined)
+            tokens.push(raw.cost.tokens);
+        if (raw.manifest !== undefined)
+            manifests.push(raw.manifest);
+    }
+    return { answers, loops, tokens, manifests };
+}
+/**
+ * Score one arm's harvested answers against the reference: similarity per seed
+ * (mean/min/max/stdev) plus the outcome-flip count. Shape-identical to what an
+ * ablation probe reports.
+ */
+export async function scoreArmRuns(runs, reference, embedder, outcomeChanged) {
+    const referenceVec = await embedder.embed({ text: reference });
+    const similarities = [];
+    let flips = 0;
+    for (const answer of runs.answers) {
+        const vec = await embedder.embed({ text: answer });
+        similarities.push(cosineSimilarity(referenceVec, vec));
+        if (await outcomeChanged(reference, answer))
+            flips++;
+    }
+    const cost = costStatsFrom(runs.answers.length, runs.loops, runs.tokens);
+    return {
+        samples: runs.answers.length,
+        flips,
+        similarity: similarityStats(similarities),
+        ...(cost !== undefined ? { cost } : {}),
+    };
+}
+/**
+ * Build the inert-intervention control from the baseline arm's OWN seeded runs.
+ * See {@link NullBand} for why leave-one-out does not transfer and this does.
+ */
+export function nullBandFrom(baselineArmId, baselineStats, gates) {
+    const similarity = baselineStats.similarity;
+    const degenerate = similarity.stdev === 0;
+    const note = !gates
+        ? `Reported, not applied: a custom answerChanged comparator decides the flips, so an ` +
+            `embedding-similarity band is a different instrument and must not veto its findings. The ` +
+            `control on that axis is the baseline arm's own flip count, which must be zero.`
+        : degenerate
+            ? `The baseline arm '${baselineArmId}' reproduced identically on every seed (spread 0), so ` +
+                `the floor is a hard ${similarity.min.toFixed(3)}: any change clears it. That is honest ` +
+                `for a deterministic scenario and only as strong as the determinism.`
+            : `A challenger must sit further from the reference than the baseline arm '${baselineArmId}' ` +
+                `ever did across its own seeds (floor ${similarity.min.toFixed(3)}, spread ±${similarity.stdev.toFixed(3)}).`;
+    return { baselineArmId, similarity, floor: similarity.min, degenerate, gates, note };
+}
+/**
+ * Did this arm actually take effect? Compares every manifest the runner
+ * reported against the arm's declared facets.
+ *
+ * `checked: false` — and therefore no refusal — in exactly two cases, both of
+ * which are absence of evidence rather than evidence of absence: the runner
+ * reported no manifest, or the arm declares only ablations (no manifest names a
+ * tool catalog). Refusing a verdict in either case would punish a consumer for
+ * a capture they were never required to make.
+ */
+export function checkArmApplication(arm, manifests) {
+    const declares = declaredFacetCount(arm.facets) > 0;
+    if (!declares || manifests.length === 0) {
+        return { manifestsSeen: manifests.length, checked: false, applied: false, mismatches: [] };
+    }
+    // EVERY run must agree — one seed that quietly built the incumbent is enough
+    // to poison the arm's numbers, and it would be invisible in an average.
+    const mismatches = [];
+    const seen = new Set();
+    for (const manifest of manifests) {
+        for (const mismatch of checkArmApplied(arm, manifest)) {
+            const key = `${mismatch.facet}=${mismatch.observed ?? '<absent>'}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            mismatches.push(mismatch);
+        }
+    }
+    return {
+        manifestsSeen: manifests.length,
+        checked: true,
+        applied: mismatches.length === 0,
+        mismatches,
+    };
+}
+//# sourceMappingURL=probe.js.map

package/dist/esm/context-bisect/arms/probe.js.map

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

package/dist/esm/context-bisect/arms/types.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Strategy arms — the SUBSTITUTION tier of the counterfactual engine.
+ *
+ * Pattern: sibling spec type, shared statistics.
+ * Role:    answer "scorer A versus scorer B", "topK versus a re-ranker",
+ *          "sliding-window versus token-budget" with the SAME seeded-rerun
+ *          discipline the ablation tier uses — and without pretending a
+ *          substitution is a removal.
+ *
+ * ## Why this is NOT a fifth arm on `AblationSpec`
+ *
+ * Ablation is REMOVAL. `AblationSpec` names inputs an agent is BUILT from and
+ * `applyAblations` filters them out; the ablated agent is strictly smaller than
+ * the original. Substitution is REPLACEMENT: the agent that re-ranks instead of
+ * taking top-K is not smaller, it is different. Three concrete costs decided
+ * this, and each one is a place a shared union would have produced a
+ * confident-looking verdict for an incoherent comparison:
+ *
+ *  1. **`bisectCulprits` would accept it.** The union feeds a delta-debugging
+ *     search (`bisect.ts`) whose premise is that probes are SUBSETS of removals:
+ *     it halves the candidate set, probes each half, and returns a "minimal
+ *     culprit set". Substitutions do not compose that way — swapping the scorer
+ *     and swapping the window at once is a THIRD arm, not a bigger removal — and
+ *     the answer it would print ("minimal culprit set = {scorer swap}") is the
+ *     wrong tier of claim entirely: an arm is an alternative configuration, not
+ *     a culprit. A type that lets an incoherent comparison reach a verdict is
+ *     worse than the limitation it removes.
+ *  2. **`rerunWithoutSources` would report it under `removed`.** Its result
+ *     type, its `removableSources` vocabulary and every sentence it composes say
+ *     "removing X". A substitution arriving through its `ignore` escape hatch
+ *     would be described, in a field NAME, as something it is not.
+ *  3. **`applyAblations` has nowhere to put it.** It returns filtered
+ *     `{tools, injections, memoryEntries}`. A substitution is not a filter of
+ *     those inputs; it is a construction choice made before they exist.
+ *
+ * The rejected third option — a `'strategy'` arm that genuinely ABLATES, i.e.
+ * falls back to the library default — was rejected because "no retrieval at
+ * all" and "re-rank instead of top-K" are different experiments and only the
+ * second is what a researcher means. The manifest already treats `memories: []`
+ * as an arm of its own; an arm that silently meant "the default" would answer a
+ * question nobody asked while looking like it supported the one they did.
+ *
+ * So: sibling TYPE, shared STATISTICS. `AblationRunStats`, `SimilarityStats`,
+ * `resolveSamples`, `similarityStats`, `costStatsFrom`, `probeFlipped` and
+ * `defaultOutcomeComparator` are reused verbatim; nothing in `ablation.ts`,
+ * `bisect.ts`, `rerun.ts` or `cost.ts` changed, so the four existing spec arms
+ * behave identically (pinned by test/context-bisect/ablation-union-pinned).
+ *
+ * ## What the library can and cannot DO with an arm
+ *
+ * For a removal the library can perform the intervention: `applyAblations`
+ * filters the inputs. For a substitution it cannot — construction is the
+ * consumer's code, and no library can reach into it and replace a scorer. What
+ * it can do instead is DECLARE the arm and then VERIFY it took effect, because
+ * 9.41.0 made configuration self-describing: `agentfootprint.agent.run_configured`
+ * names the provider, model, react mode, window, each memory's strategy /
+ * retrieval / embedder, the graph's posture and classifier, and the evidence
+ * posture. {@link ArmFacets} is deliberately that same vocabulary, so a run's
+ * own manifest — not the experimenter's bookkeeping — says which arm it belonged
+ * to, and an arm whose runs contradict its declaration gets no verdict at all.
+ *
+ * An arm may ALSO carry `ablations`: removals ride inside an arm through the
+ * unchanged removal machinery (`applyArm` → `applyAblations`). Composition, not
+ * union — each type still means exactly one thing.
+ */
+import type { RunManifestLike } from '../../recorders/observability/recordedManifest.js';
+import type { Embedder } from '../../influence-core/index.js';
+import type { AblationRunStats, AblationSpec, AblationVerdict, OutcomeComparator, RunCost, SimilarityStats } from '../types.js';
+/** The memory facet of an arm — matched against the manifest's memory rows. */
+export interface ArmMemoryFacet {
+    /** Narrow the match to ONE mounted memory by `defineMemory({ id })`. Without
+     *  it, ANY mounted memory satisfying the other fields counts as a match. */
+    readonly id?: string;
+    readonly type?: string;
+    /** The compiled strategy KIND (`'window'`, `'topK'`, …). */
+    readonly strategy?: string;
+    /** `RetrievalStrategy.name` — the spelled-out retrieval rule. This is the
+     *  field a "topK versus re-rank" study varies. */
+    readonly retrieval?: string;
+    readonly embedderId?: string;
+    readonly flavor?: string;
+}
+/**
+ * What ONE arm holds constant, in the vocabulary the run manifest speaks.
+ *
+ * Every field here has a counterpart in `AgentRunConfiguredPayload`, and that
+ * is the whole point: a facet a consumer declares is a facet the engine can
+ * CHECK against the run that actually happened. A configuration difference the
+ * manifest cannot name (a prompt tweak, a temperature) is not expressible here
+ * on purpose — declaring it would produce an arm label nothing can verify.
+ */
+export interface ArmFacets {
+    /** `LLMProvider.name` of the effective provider. */
+    readonly provider?: string;
+    readonly model?: string;
+    readonly reactMode?: 'classic' | 'dynamic' | 'dynamic-grouped';
+    /** `WindowStrategy.name` — the "sliding-window versus token-budget" axis. */
+    readonly window?: string;
+    /** `IntentScorer.name` — the "scorer A versus scorer B" axis. */
+    readonly scorer?: string;
+    readonly routing?: 'assist' | 'guard' | 'rails';
+    readonly continuity?: 'turn' | 'conversation';
+    readonly evidenceGate?: 'assist' | 'guard' | 'rails';
+    readonly memory?: ArmMemoryFacet;
+}
+/**
+ * One configuration under test.
+ *
+ * `facets` is what the run manifest should say about this arm; `ablations` is
+ * anything this arm additionally REMOVES, applied by the unchanged removal
+ * machinery (`applyArm`). An arm needs at least one of the two — except the
+ * baseline arm, which may declare nothing at all and mean "the configuration as
+ * it stands".
+ */
+export interface StrategyArm {
+    /** Stable label. Appears in every verdict sentence and keys the readout. */
+    readonly id: string;
+    readonly facets?: ArmFacets;
+    /** Removals this arm also applies — the four `AblationSpec` kinds, unchanged. */
+    readonly ablations?: readonly AblationSpec[];
+}
+/**
+ * What one seeded run of one arm reported back.
+ *
+ * `manifest` is the connection to 9.41.0: capture it with
+ * `agent.on('agentfootprint.agent.run_configured', e => …)` inside the runner
+ * (or hand the run's captured events to `manifestFromEvents`). Supplying it
+ * turns "the experimenter says this run was arm B" into a checked fact.
+ */
+export interface ArmRunResult {
+    readonly output: string;
+    readonly cost?: RunCost;
+    readonly manifest?: RunManifestLike;
+}
+/**
+ * Consumer-supplied arm runner: BUILD the agent under `arm`'s configuration,
+ * run the same scenario, return the output.
+ *
+ * The engine takes a factory, not an instance — the same shape `AblationRunner`
+ * already has, and the reason a strategy comparison fits here at all. Contract,
+ * identical in spirit to `AblationRunner`:
+ * - `run.seed` varies 0..N-1 within ONE arm. Thread it into any stochastic
+ *   knob so reruns are deterministic-but-distinct.
+ * - Build a FRESH agent/provider per call (scripted mock providers are
+ *   stateful).
+ * - Apply `arm.ablations` with `applyArm` at construction.
+ * - Returning a bare string is fine; the object form additionally unlocks the
+ *   cost readout and the manifest check.
+ */
+export type ArmRunner = (arm: StrategyArm, run: {
+    readonly seed: number;
+}) => Promise<string | ArmRunResult>;
+/** One declared facet the run manifest contradicted. */
+export interface ArmFacetMismatch {
+    /** Dotted facet path — `'model'`, `'memory.retrieval'`, `'skillGraph.scorer'`. */
+    readonly facet: string;
+    readonly declared: string;
+    /** What the manifest said. ABSENT means the manifest did not declare that
+     *  field at all — which, per the manifest's own rule, means "not configured"
+     *  and is therefore still a contradiction of a declared arm. */
+    readonly observed?: string;
+}
+/** Did the arm the consumer DECLARED match the runs that actually happened? */
+export interface ArmApplication {
+    /** How many of this arm's seeded runs reported a manifest. */
+    readonly manifestsSeen: number;
+    /**
+     * The declared facets were really compared against a manifest. FALSE when the
+     * runner reported none, or when the arm declares only `ablations` (no
+     * manifest names a tool catalog). Read this BEFORE `applied`.
+     */
+    readonly checked: boolean;
+    /** Every seen manifest agreed with every declared facet. Meaningless when
+     *  `checked` is false. */
+    readonly applied: boolean;
+    readonly mismatches: readonly ArmFacetMismatch[];
+}
+/**
+ * The inert-intervention control for an arm comparison.
+ *
+ * The cost tier's leave-one-out placebo does NOT transfer: it works by holding
+ * out one member of a POPULATION of peer suspects, and a comparison of two arms
+ * has no such population — leaving an arm out leaves an experiment, not a
+ * control. What does transfer is the placebo IDEA, in a stronger form: the
+ * inert intervention is RE-RUNNING THE SAME CONFIGURATION, and the engine
+ * already pays for it (the baseline arm's own seeded runs). Its similarity
+ * spread against the reference is the null distribution a challenger must fall
+ * outside of; `floor` is the strictest point of it.
+ *
+ * Two axes, two controls, and they are not interchangeable:
+ *  - the COMPARATOR axis's control is the baseline arm's own flip count, which
+ *    must be ZERO (the stability gate — same zero-tolerance rule `bisect.ts`
+ *    and `localize.ts` use);
+ *  - the SIMILARITY axis's control is this band.
+ * The band only participates in a verdict when the flip comparator IS the
+ * similarity comparator (`gates`). With a domain comparator the two axes are
+ * different instruments, and vetoing a genuine decision flip with an embedding
+ * statistic would suppress a true finding — so it is reported and not applied.
+ */
+export interface NullBand {
+    readonly baselineArmId: string;
+    /** The baseline arm's own similarity to the reference across its seeds. */
+    readonly similarity: SimilarityStats;
+    /** The floor a challenger's mean similarity must fall BELOW to be
+     *  distinguishable from seed-to-seed noise (`similarity.min`). */
+    readonly floor: number;
+    /** The baseline reproduced EXACTLY on every seed (zero spread). The band is
+     *  then a hard floor that any change clears — honest for a deterministic
+     *  scenario, and only as strong as that determinism (a mock provider is
+     *  reproducible in a way a real one is not). */
+    readonly degenerate: boolean;
+    /** The band participated in the verdicts (default comparator only). */
+    readonly gates: boolean;
+    /** Plain-language recap. PRESENTATION ONLY — read the fields as data. */
+    readonly note: string;
+}
+/** One arm's evidence. */
+export interface ArmOutcome {
+    readonly armId: string;
+    readonly isBaseline: boolean;
+    /** The same per-probe statistics the ablation tier reports (samples, flips,
+     *  similarity mean/min/max/stdev, and `cost` when the runner reported one). */
+    readonly runs: AblationRunStats;
+    /** Every seeded answer, in seed order. */
+    readonly answers: readonly string[];
+    /** Mean similarity to the reference fell below the null band's floor. Always
+     *  false for the baseline arm — an arm cannot be outside its own band. */
+    readonly outsideNullBand: boolean;
+    readonly application: ArmApplication;
+    /**
+     * The CAUSAL-tier claim for this arm versus the baseline arm. Absent on the
+     * baseline arm itself (it is the reference, not a challenger).
+     */
+    readonly verdict?: AblationVerdict;
+}
+/** The finished comparison. */
+export interface StrategyComparison {
+    /**
+     * The answer every arm's similarity and flip count was measured against.
+     * `'prior-run'` — the caller's `originalAnswer`, i.e. the run that actually
+     * happened. `'baseline-arm'` — no prior answer was supplied, so the baseline
+     * arm's seed-0 answer became the reference; that seed then contributes a
+     * trivially identical comparison and stability rests on the remaining N−1.
+     */
+    readonly reference: {
+        readonly from: 'prior-run' | 'baseline-arm';
+        readonly text: string;
+    };
+    readonly baselineArmId: string;
+    /** The baseline arm reproduced the reference on EVERY seed. False ⇒ every
+     *  verdict is `'inconclusive'`; nothing is trustworthy on an unstable
+     *  scenario. */
+    readonly baselineStable: boolean;
+    readonly nullBand: NullBand;
+    /** One row per arm, declaration order, baseline included. */
+    readonly arms: readonly ArmOutcome[];
+    /** Consumer-runner invocations spent (`samples × arms`). */
+    readonly runsUsed: number;
+    /** Plain-language recap. PRESENTATION ONLY — read the fields as data. */
+    readonly summary: string;
+}
+export interface CompareStrategyArmsOptions {
+    /** At least two, distinct, each non-baseline arm declaring something. */
+    readonly arms: readonly StrategyArm[];
+    readonly runner: ArmRunner;
+    /** Embedder for the similarity readout, the null band and the default
+     *  comparator. `mockEmbedder()` is fine offline. */
+    readonly embedder: Embedder;
+    /** Which arm is the incumbent. Default: the first arm. */
+    readonly baselineArmId?: string;
+    /** The answer the run that actually happened produced. Omit for a fresh A/B
+     *  — the baseline arm's seed-0 answer becomes the reference. */
+    readonly originalAnswer?: string;
+    /** Seeded runs PER ARM. Default 3; clamped to ≥ 2 (never single-run claims). */
+    readonly samples?: number;
+    /** Did the answer CHANGE? Default: embedding similarity < `flipThreshold`.
+     *  Passing one turns the null band OFF as a gate (see {@link NullBand}). */
+    readonly answerChanged?: OutcomeComparator;
+    /** Similarity floor for the DEFAULT comparator. Default 0.8. */
+    readonly flipThreshold?: number;
+}

package/dist/esm/context-bisect/arms/types.js

@@ -0,0 +1,67 @@
+/**
+ * Strategy arms — the SUBSTITUTION tier of the counterfactual engine.
+ *
+ * Pattern: sibling spec type, shared statistics.
+ * Role:    answer "scorer A versus scorer B", "topK versus a re-ranker",
+ *          "sliding-window versus token-budget" with the SAME seeded-rerun
+ *          discipline the ablation tier uses — and without pretending a
+ *          substitution is a removal.
+ *
+ * ## Why this is NOT a fifth arm on `AblationSpec`
+ *
+ * Ablation is REMOVAL. `AblationSpec` names inputs an agent is BUILT from and
+ * `applyAblations` filters them out; the ablated agent is strictly smaller than
+ * the original. Substitution is REPLACEMENT: the agent that re-ranks instead of
+ * taking top-K is not smaller, it is different. Three concrete costs decided
+ * this, and each one is a place a shared union would have produced a
+ * confident-looking verdict for an incoherent comparison:
+ *
+ *  1. **`bisectCulprits` would accept it.** The union feeds a delta-debugging
+ *     search (`bisect.ts`) whose premise is that probes are SUBSETS of removals:
+ *     it halves the candidate set, probes each half, and returns a "minimal
+ *     culprit set". Substitutions do not compose that way — swapping the scorer
+ *     and swapping the window at once is a THIRD arm, not a bigger removal — and
+ *     the answer it would print ("minimal culprit set = {scorer swap}") is the
+ *     wrong tier of claim entirely: an arm is an alternative configuration, not
+ *     a culprit. A type that lets an incoherent comparison reach a verdict is
+ *     worse than the limitation it removes.
+ *  2. **`rerunWithoutSources` would report it under `removed`.** Its result
+ *     type, its `removableSources` vocabulary and every sentence it composes say
+ *     "removing X". A substitution arriving through its `ignore` escape hatch
+ *     would be described, in a field NAME, as something it is not.
+ *  3. **`applyAblations` has nowhere to put it.** It returns filtered
+ *     `{tools, injections, memoryEntries}`. A substitution is not a filter of
+ *     those inputs; it is a construction choice made before they exist.
+ *
+ * The rejected third option — a `'strategy'` arm that genuinely ABLATES, i.e.
+ * falls back to the library default — was rejected because "no retrieval at
+ * all" and "re-rank instead of top-K" are different experiments and only the
+ * second is what a researcher means. The manifest already treats `memories: []`
+ * as an arm of its own; an arm that silently meant "the default" would answer a
+ * question nobody asked while looking like it supported the one they did.
+ *
+ * So: sibling TYPE, shared STATISTICS. `AblationRunStats`, `SimilarityStats`,
+ * `resolveSamples`, `similarityStats`, `costStatsFrom`, `probeFlipped` and
+ * `defaultOutcomeComparator` are reused verbatim; nothing in `ablation.ts`,
+ * `bisect.ts`, `rerun.ts` or `cost.ts` changed, so the four existing spec arms
+ * behave identically (pinned by test/context-bisect/ablation-union-pinned).
+ *
+ * ## What the library can and cannot DO with an arm
+ *
+ * For a removal the library can perform the intervention: `applyAblations`
+ * filters the inputs. For a substitution it cannot — construction is the
+ * consumer's code, and no library can reach into it and replace a scorer. What
+ * it can do instead is DECLARE the arm and then VERIFY it took effect, because
+ * 9.41.0 made configuration self-describing: `agentfootprint.agent.run_configured`
+ * names the provider, model, react mode, window, each memory's strategy /
+ * retrieval / embedder, the graph's posture and classifier, and the evidence
+ * posture. {@link ArmFacets} is deliberately that same vocabulary, so a run's
+ * own manifest — not the experimenter's bookkeeping — says which arm it belonged
+ * to, and an arm whose runs contradict its declaration gets no verdict at all.
+ *
+ * An arm may ALSO carry `ablations`: removals ride inside an arm through the
+ * unchanged removal machinery (`applyArm` → `applyAblations`). Composition, not
+ * union — each type still means exactly one thing.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/context-bisect/arms/types.js.map

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

package/dist/esm/context-bisect/arms/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../../src/context-bisect/arms/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,qEAAqE;AACrE,MAAM,MAAM,GAAG,sBAAsB,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAgB;IAC3C,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7E,OAAO,GAAG,MAAM,KAAK,SAAS,EAAE,CAAC;AACnC,CAAC;AAED,8DAA8D;AAC9D,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC5C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,4EAA4E;QAC5E,6EAA6E;QAC7E,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACtD,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;SAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClC,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,kBAAkB,CAAC,MAA6B;IAC9D,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,GAAG,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAClD,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAgC,CAAC,CAAC,MAAM,CAC7D,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CACvB,CAAC,MAAM,CAAC;YACT,SAAS;QACX,CAAC;QACD,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAA4B,EAC5B,aAAiC;IAEjC,wEAAwE;IACxE,6DAA6D;IAC7D,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,+CAA+C,IAAI,CAAC,MAAM,mBAAmB;YACpF,sFAAsF;YACtF,8EAA8E,CACjF,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,uEAAuE;IACvE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,8EAA8E;gBACrF,wEAAwE,CAC3E,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,2BAA2B,GAAG,CAAC,EAAE,+CAA+C;gBACvF,8DAA8D,CACjE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IAED,sEAAsE;IACtE,MAAM,QAAQ,GAAG,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,mBAAmB,QAAQ,oCAAoC;YACtE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,oDAAoD;YACxF,+EAA+E,CAClF,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,4EAA4E;IAC5E,gCAAgC;IAChC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,EAAE,KAAK,QAAQ;YAAE,SAAS;QAClC,IAAI,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/E,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,SAAS,GAAG,CAAC,EAAE,+DAA+D;gBACrF,uFAAuF;gBACvF,gCAAgC,QAAQ,sCAAsC;gBAC9E,sDAAsD,CACzD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,6EAA6E;IAC7E,yCAAyC;IACzC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,UAAU,IAAI,UAAU,GAAG,CAAC,EAAE,kDAAkD;gBACvF,uFAAuF;gBACvF,wFAAwF;gBACxF,cAAc,CACjB,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/esm/context-bisect/arms/verdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.js","sourceRoot":"","sources":["../../../../src/context-bisect/arms/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAgB9C,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,KAAuB,EACvB,OAA0B;IAE1B,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IAExC,oEAAoE;IACpE,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QAC5B,OAAO;YACL,OAAO,EAAE,cAAc;YACvB,KAAK,EACH,mCAAmC,aAAa,2CAA2C;gBAC3F,iCAAiC,OAAO,CAAC,aAAa,CAAC,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC,OAAO,GAAG;gBAChG,6CAA6C,KAAK,2CAA2C;SAChG,CAAC;IACJ,CAAC;IAED,6DAA6D;IAC7D,IAAI,OAAO,CAAC,WAAW,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;QAChE,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAChD,MAAM,QAAQ,GAAG,KAAK,EAAE,QAAQ,IAAI,yCAAyC,CAAC;QAC9E,OAAO;YACL,OAAO,EAAE,cAAc;YACvB,KAAK,EACH,sBAAsB,KAAK,cAAc,KAAK,EAAE,KAAK,IAAI,SAAS,IAChE,KAAK,EAAE,QAAQ,IAAI,GACrB,kCAAkC,QAAQ,yCAAyC;gBACnF,oDAAoD;SACvD,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9C,qEAAqE;IACrE,IAAI,OAAO,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QACtD,OAAO;YACL,OAAO,EAAE,cAAc;YACvB,KAAK,EACH,mCAAmC,KAAK,2BAA2B,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,GAAG;gBAClG,4DAA4D,IAAI,6BAA6B;gBAC7F,sCAAsC,IAAI,CAAC,KAAK,CAAC,OAAO,CACtD,CAAC,CACF,oCAAoC;gBACrC,0DAA0D;SAC7D,CAAC;IACJ,CAAC;IAED,sBAAsB;IACtB,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK;YAC3B,CAAC,CAAC,gDAAgD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAC1E,CAAC,CAAC,EAAE,CAAC;QACP,OAAO;YACL,OAAO,EAAE,WAAW;YACpB,KAAK,EACH,wCAAwC,aAAa,SAAS,KAAK,0BAA0B;gBAC7F,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,oDAAoD,IAAI,KAAK;gBAC5F,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAC/B,CAAC,CACF,IAAI,UAAU,2CAA2C;gBAC1D,uCAAuC;SAC1C,CAAC;IACJ,CAAC;IAED,+CAA+C;IAC/C,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO;YACL,OAAO,EAAE,cAAc;YACvB,KAAK,EACH,mCAAmC,KAAK,gCAAgC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,GAAG;gBACvG,4EAA4E;SAC/E,CAAC;IACJ,CAAC;IAED,yBAAyB;IACzB,OAAO;QACL,OAAO,EAAE,eAAe;QACxB,KAAK,EACH,oCAAoC,KAAK,kCAAkC,KAAK,CAAC,OAAO,UAAU;YAClG,6FAA6F;YAC7F,IAAI,aAAa,qEAAqE;KACzF,CAAC;AACJ,CAAC"}

package/dist/esm/context-bisect/bisect.js.map

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

package/dist/esm/context-bisect/cost.js.map

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

package/dist/esm/context-bisect/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * context-bisect — RFC-003 Part B: the contextual-bug LOCALIZER,
+ * "git bisect for context".
+ *
+ * Assembly over shipped pieces: footprintjs 9.8.0's complete causal DAG
+ * (control edges, honesty markers, `EdgeWeigher` hook) × influence-core
+ * scoring (D6) × consumer-run counterfactual ablation.
+ *
+ *   D7 — `llmEdgeWeigher`     influence-weighted LLM-call slice edges
+ *   D8 — `localizeContextBug` trigger → slice → ranked suspects → ablation
+ *   D9 — `bisectCulprits`     seeded multi-culprit bisection + variance
+ *
+ * §B2 claim tiers (spelled out on every type): weights/scores are
+ * embedding-geometry PROXIES; ablation verdicts are the ONLY causal
+ * claims; slice completeness is bounded by tracking — and says so.
+ *
+ * @beta Beta feature (RFC-003 Part B). The API works and is tested, but
+ * may change before GA.
+ */
+export { llmEdgeWeigher, stepOutputText, type LlmEdgeWeigherHandle, type LlmEdgeWeigherOptions, type RankedParentEdge, } from './llmEdgeWeigher.js';
+export { findDroppedContext, type ContextUnit, type DroppedUnit, type MissingContextResult, } from './missingContext.js';
+export { runRestorationProbe, type RestorationProbeConfig, type RestorationRerun, type RestorationRunner, } from './restoration.js';
+export { defaultSuspectClassifier, formatContextBugReport, llmCallIdsFromEvents, localizeContextBug, suspectLabel, type ClassifyContext, type LocalizeContextBugOptions, type SuspectClassifier, type SuspectSeed, } from './localize.js';
+export { toBacktrackTrace, type BacktrackCustodyHop, type BacktrackHop, type BacktrackSuspectCard, type BacktrackTrace, type BacktrackTrail, type ToBacktrackTraceOptions, } from './toBacktrackTrace.js';
+export { sliceToBacktrackTrace, type SliceToBacktrackTraceOptions, } from './sliceToBacktrackTrace.js';
+export { ablationForSuspect, applyAblations, costStatsFrom, defaultOutcomeComparator, median, probeFlipped, runAblationProbe, verdictFor, type AblationTargets, type ProbeConfig, } from './ablation.js';
+export { assignCostVerdicts, classifySuspect, MIN_LOOPS_SAVED } from './cost.js';
+export { removableSources, rerunWithoutSources, type IgnoredSource, type RemovableSource, type RerunWithoutSourcesOptions, type RerunWithoutSourcesResult, type WhatChanged, } from './rerun.js';
+export { applyArm, armConfigKey, armFacetsFromManifest, armLabel, checkArmApplication, checkArmApplied, collectArmRuns, compareStrategyArms, declaredFacetCount, manifestFromEvents, matchArm, nullBandFrom, RUN_CONFIGURED_EVENT, scoreArmRuns, validateStrategyArms, verdictForArm, type ArmApplication, type ArmFacetMismatch, type ArmFacets, type ArmMemoryFacet, type ArmOutcome, type ArmRunResult, type ArmRunner, type ArmRuns, type ArmVerdictContext, type CompareStrategyArmsOptions, type ManifestMemoryLike, type NullBand, type RunManifestLike, type StrategyArm, type StrategyComparison, } from './arms/index.js';
+export { shortlistEarlyCulprits, DEFAULT_RECENCY_DECAY, type LoopCandidate, type LoopRecallShortlist, type ShortlistEarlyCulpritsOptions, } from './loop-recall.js';
+export { walkToRoot, walkTrajectory, buildWriterFrameIndex, type HopNarrowedBy, type RootCauseHop, type RootCauseNote, type RootCausePath, type WalkToRootOptions, } from './walk-to-root.js';
+export { joinVariableSlice, traceVariable, type AgentKeyMoment, type AgentVariableSlice, type DataflowCoverage, type JoinVariableSliceOptions, type TraceVariableOptions, type VariableAblationHook, } from './variable-recall.js';
+export { variableToBacktrackTrace, type VariableToBacktrackTraceOptions, } from './variableToBacktrackTrace.js';
+export { assembleTrajectory, bucketByAnchors, findLoopHeads, type AnchorBucket, type AssembleTrajectoryOptions, type ContextSource, type LoopFrame, type SyntheticQuestionNode, type Trajectory, } from './trajectory.js';
+export { bisectCulprits, type BisectCulpritsOptions, type BisectionProbe, type BisectionResult, } from './bisect.js';
+export { CONTEXT_BISECT_DEFAULTS, type AblationRerun, type AblationRunner, type AblationRunStats, type AblationSpec, type AblationVerdict, type AblationVerdictKind, type ContextBugArtifacts, type ContextBugReport, type CostRange, type CostStats, type CostVerdict, type EdgePathStep, type HonestyFlag, type HonestyFlagKind, type OutcomeComparator, type QualityTriggerLookup, type RestoredCandidate, type RunCost, type SimilarityStats, type SliceStats, type Suspect, type SuspectClass, type SuspectDetail, type SuspectKind, } from './types.js';
+export type { CapturedEventLike } from '../recorders/observability/recordedManifest.js';