agentfootprint 9.41.0 → 9.44.0

package/dist/types/lib/context-bisect/arms/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../../../../src/lib/context-bisect/arms/probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,KAAK,EACV,cAAc,EAEd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,WAAW,EACZ,MAAM,YAAY,CAAC;AAIpB,iEAAiE;AACjE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;CAChD;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAiBlB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,iBAAiB,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAgB3B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,gBAAgB,EAC/B,KAAK,EAAE,OAAO,GACb,QAAQ,CAgBV;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC,cAAc,CAuBhB"}

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

@@ -0,0 +1,320 @@
+/**
+ * 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/lib/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 { Embedder } from '../../influence-core/index.js';
+import type { AblationRunStats, AblationSpec, AblationVerdict, OutcomeComparator, RunCost, SimilarityStats } from '../types.js';
+/**
+ * One mounted memory as the run manifest describes it — structurally satisfied
+ * by `RunConfiguredMemoryPayload`.
+ */
+export interface ManifestMemoryLike {
+    readonly id?: string;
+    readonly type?: string;
+    readonly strategy?: string;
+    readonly retrieval?: string;
+    readonly embedderId?: string;
+    readonly flavor?: string;
+}
+/**
+ * The run-configuration manifest, structurally — satisfied by
+ * `AgentRunConfiguredPayload` (the payload of
+ * `agentfootprint.agent.run_configured`, 9.41.0).
+ *
+ * Declared structurally, and every member optional, for the same reason
+ * `CapturedEventLike` and `QualityTriggerLookup` are: `context-bisect` is a
+ * LEAF. It must not import the event registry to read one payload, and a
+ * consumer replaying manifests out of a saved recording must be able to hand in
+ * any bag shaped like this.
+ */
+export interface RunManifestLike {
+    readonly agentId?: string;
+    readonly llm?: {
+        readonly provider?: string;
+        readonly model?: string;
+    };
+    readonly reactMode?: string;
+    readonly memories?: readonly ManifestMemoryLike[];
+    readonly window?: string;
+    readonly skillGraph?: {
+        readonly routing?: string;
+        readonly continuity?: string;
+        readonly scorer?: string;
+    };
+    readonly evidenceGate?: string;
+}
+/** 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/context-bisect/arms/types.d.ts.map

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

package/dist/types/lib/context-bisect/arms/validate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Arm validation — the teaching refusals.
+ *
+ * Every refusal here fires BEFORE a single model call. That is the whole design
+ * rule: an incoherent comparison must cost nothing. The engine's other refusals
+ * (an unstable baseline, an arm that did not take effect) can only be known
+ * after the runs, and those refuse a VERDICT rather than throw — refusing after
+ * spending N model calls would be hostile. These six can be known from the
+ * declaration alone, so they throw.
+ */
+import type { ArmFacets, StrategyArm } from './types.js';
+/**
+ * A canonical key for one arm's CONFIGURATION (facets + removals), used only to
+ * detect two arms that are secretly the same arm. Hand-rolled rather than
+ * `JSON.stringify` because key order in an object literal is authoring
+ * accident, and two arms written `{model, scorer}` and `{scorer, model}` are
+ * the same arm.
+ */
+export declare function armConfigKey(arm: StrategyArm): string;
+/** How many facet leaves an arm declares — 0 means it names no configuration. */
+export declare function declaredFacetCount(facets: ArmFacets | undefined): number;
+/**
+ * Refuse every comparison that cannot mean anything, and resolve which arm is
+ * the incumbent. Returns the resolved baseline arm id.
+ */
+export declare function validateStrategyArms(arms: readonly StrategyArm[], baselineArmId: string | undefined): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/types/lib/context-bisect/arms/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../../src/lib/context-bisect/arms/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAKzD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAIrD;AAkBD,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAcxE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,aAAa,EAAE,MAAM,GAAG,SAAS,GAChC,MAAM,CA2ER"}

package/dist/types/lib/context-bisect/arms/verdict.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The arm verdict — the same three tiers, phrased for a substitution.
+ *
+ * ## Why not widen `verdictFor`
+ *
+ * `verdictFor` already carries an `action` word (`'ablating'` | `'restoring'`)
+ * and a third would have been one line. It ends its NOT-CONFIRMED sentence with
+ * "its ranking remains a correlational proxy only" — true of a suspect, which
+ * was RANKED before it was probed, and meaningless for an arm, which was never
+ * ranked at all. Widening the union would have forced that sentence onto the
+ * new tier or edited a string three existing tests pin byte-for-byte. So the
+ * tier LOGIC is shared (`probeFlipped`, the majority rule, the zero-tolerance
+ * baseline gate) and only the prose is new.
+ *
+ * ## The tiers, in refusal order
+ *
+ * 1. **Unstable baseline** → inconclusive. The incumbent could not reproduce
+ *    the reference answer across its own seeds, so a difference measured
+ *    against it is measuring the scenario, not the arm. Zero tolerance, exactly
+ *    as `bisect.ts` and `localize.ts` apply it: ONE un-intervened flip is
+ *    enough, because the majority rule would let a 1-in-3 flaky scenario reach
+ *    a causal verdict.
+ * 2. **Arm did not take effect** → inconclusive. The run manifest contradicted
+ *    what the arm declared. Any difference here is evidence about a
+ *    configuration nobody meant to test.
+ * 3. **Inside the null band** → inconclusive. A majority flip whose mean
+ *    similarity still sits within the baseline arm's own seed-to-seed spread is
+ *    not separable from noise. Only applied when the flip comparator and the
+ *    band are the same instrument (see `NullBand.gates`).
+ * 4. **Majority flip, outside the band, stable baseline** → confirmed. This is
+ *    a causal claim of the same tier an ablation verdict makes: a
+ *    counterfactual intervention, seeded reruns, variance reported, and a
+ *    baseline that held.
+ * 5. **Minority flips** → inconclusive. 6. **No flips** → not-confirmed.
+ *
+ * Every claim is bounded by the scenario and the comparator, and says so — an
+ * arm confirmed on one question has been confirmed on one question.
+ */
+import type { AblationRunStats, AblationVerdict } from '../types.js';
+import type { ArmApplication, NullBand } from './types.js';
+/** Everything the verdict needs beyond the arm's own numbers. */
+export interface ArmVerdictContext {
+    readonly baselineArmId: string;
+    /** The baseline arm reproduced the reference on EVERY seed. */
+    readonly baselineStable: boolean;
+    readonly baselineStats: AblationRunStats;
+    readonly band: NullBand;
+    /** Mean similarity fell below the band's floor. */
+    readonly outsideNullBand: boolean;
+    readonly application: ArmApplication;
+}
+/** Translate one arm's probe evidence into its verdict. See module docs. */
+export declare function verdictForArm(armId: string, stats: AblationRunStats, context: ArmVerdictContext): AblationVerdict;
+//# sourceMappingURL=verdict.d.ts.map

package/dist/types/lib/context-bisect/arms/verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.d.ts","sourceRoot":"","sources":["../../../../../src/lib/context-bisect/arms/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3D,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;CACtC;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,iBAAiB,GACzB,eAAe,CAgFjB"}

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

@@ -26,6 +26,7 @@ export { sliceToBacktrackTrace, type SliceToBacktrackTraceOptions, } from './sli
 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';

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

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

package/dist/types/lib/injection-engine/index.d.ts

@@ -19,7 +19,7 @@ export { pointerOf, SKIP_STEP_TOOL_NAME, skipStepDescriptor, type OnSkipPolicy,
 export { defineStepsHint, STEPS_HINT_METADATA_KEY, type StepsHintOptions, } from './factories/defineStepsHint.js';
 export { checkArtifactVocabularies, vocabularyOf, type ArtifactVocabulary, } from './skillVocabulary.js';
 export { SkillRegistry, type SkillRegistryOptions } from './SkillRegistry.js';
-export { skillsFromDir, type SkillsFromDirOptions } from './skillsFromDir.js';
+export { skillsFromDir, runbookFromDir, type SkillsFromDirOptions, type DirRunbook, } from './skillsFromDir.js';
 export { buildListSkillsTool, buildReadSkillTool, buildSkipStepTool, type ReadSkillOffer, type SkillToolPair, } from './skillTools.js';
 export { listSkillsDescriptor, readSkillDescriptor } from './skillToolDescriptors.js';
 export type { SkillCachePolicy, SkillCachePolicyContext, SkillGraphHost, SkillGraphIterationContext, SkillTool, SkillToolDescriptor, SkillToolSchema, } from './hostContract.js';

package/dist/types/lib/injection-engine/index.d.ts.map

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

package/dist/types/lib/injection-engine/skillExamples.d.ts

@@ -93,12 +93,21 @@
  * visible wherever the graph reports its problems — because a reader who meets
  * it only in prose docs will meet a clean report first.
  *
+ * ## The opposite assertion lives next door
+ *
+ * Everything here is POSITIVE: this rule claims this phrase. The negative form
+ * — a phrase that must claim NO skill, which is the assertion that catches
+ * over-triggering — is `skillNeverRoutes.ts`, declared on the GRAPH rather than
+ * on a rule (a phrase that must route nowhere belongs to no skill). Both ask
+ * `startRuleClaim.ts` the same question and differ only in which answer is a
+ * defect; a phrase declared BOTH ways is reported there as the contradiction it
+ * is.
+ *
  * Composed into `graph.checkup()` by `skillGraph.ts`, exactly like
  * `skillContract`/`skillIntent`/`skillVocabulary`: this module owns the rule
  * AND its boundaries, and reports in the shared `GraphProblem` voice.
  */
-import type { InjectionContext } from './types.js';
-import { type SkillMatchData } from './skillMatch.js';
+import { type StartRuleDecl } from './startRuleClaim.js';
 import type { GraphProblem } from './skillGraphCheckup.js';
 /**
  * The statement the check-up makes about its own reach, carried on
@@ -111,18 +120,12 @@ export declare const EXAMPLES_BOUNDARY: string;
  *  only the order-independent check (self-match) could run. */
 export declare const EXAMPLES_ORDER_NOT_CHECKED: string;
 /**
- * The slice of an entry declaration this module reads — structural, so
- * `skillGraph.ts`'s module-private `EntryDecl` satisfies it unchanged (the
- * same trick `skillIntent.ts` uses).
+ * The slice of an entry declaration this module reads — the shared claim shape
+ * ({@link StartRuleDecl}, which owns "who claims a phrase") plus the one field
+ * only this check reads. Structural, so `skillGraph.ts`'s module-private
+ * `EntryDecl` satisfies it unchanged (the same trick `skillIntent.ts` uses).
  */
-export interface ExampleRuleDecl {
-    readonly id: string;
-    /** The compiled condition (from `match:`) or the author's `when`. Absent on
-     *  an unconditional entry and on an intent rule (no sync predicate). */
-    readonly when?: (ctx: InjectionContext) => boolean;
-    /** The serializable matcher behind `when`, when declared as data — quoted
-     *  back in the messages, and the one way to spot the intent arm. */
-    readonly match?: SkillMatchData;
+export interface ExampleRuleDecl extends StartRuleDecl {
     /** The phrasings this rule claims (build-time TEST material). */
     readonly examples?: readonly string[];
 }

package/dist/types/lib/injection-engine/skillExamples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skillExamples.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillExamples.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAEsC,CAAC;AAErE;+DAC+D;AAC/D,eAAO,MAAM,0BAA0B,QAG4B,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;4EACwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACnD;wEACoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;gEACgE;AAChE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GACnE,SAAS,MAAM,EAAE,GAAG,SAAS,CAgD/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,GAAG,eAAe,CAwMlB"}
+{"version":3,"file":"skillExamples.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillExamples.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AAEH,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAEsC,CAAC;AAErE;+DAC+D;AAC/D,eAAO,MAAM,0BAA0B,QAG4B,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;gEACgE;AAChE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GACnE,SAAS,MAAM,EAAE,GAAG,SAAS,CAgD/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,GAAG,eAAe,CAyLlB"}

package/dist/types/lib/injection-engine/skillGraph.d.ts

@@ -208,6 +208,16 @@ export interface SkillGraphFlatConfig {
      * See {@link BuildOptions.scopeTools}.
      */
     readonly scopeTools?: boolean;
+    /**
+     * Phrasings this graph must claim NOWHERE — the negative routing rows. Same
+     * machine as `.neverRoutes([...])`; see that method for what the check
+     * proves and what it deliberately does not. A row a declared start rule
+     * claims is an ERROR (`never-routes-claimed`), naming the rule.
+     *
+     * @example
+     *   skillGraph({ skills, start: { rules }, neverRoutes: ['what is the weather'] });
+     */
+    readonly neverRoutes?: readonly string[];
     readonly check?: GraphCheckMode;
     /** Baseline agent tool names — see {@link BuildOptions.knownTools}. */
     readonly knownTools?: readonly string[];
@@ -232,6 +242,10 @@ export interface SkillGraphTreeConfig {
     readonly scopeTools?: boolean;
     readonly start?: never;
     readonly steps?: never;
+    /** A tree has no start RULES for a negative row to be judged against, so the
+     *  type refuses it here and `build()` refuses it at runtime (see
+     *  {@link SkillGraphBuilder.neverRoutes}). */
+    readonly neverRoutes?: never;
     readonly check?: GraphCheckMode;
     /** Baseline agent tool names — see {@link BuildOptions.knownTools}. */
     readonly knownTools?: readonly string[];
@@ -815,6 +829,42 @@ export interface SkillGraphBuilder {
      * router per graph. Flat graphs only.
      */
     classify(scorer: IntentScorer, policy?: Partial<RoutingPolicy>): SkillGraphBuilder;
+    /**
+     * Declare phrasings this graph must claim **NOWHERE** — the negative form of
+     * a rule's `examples`, and the one that catches the expensive failure.
+     *
+     * An under-triggering skill costs a turn (the model tier picks instead). An
+     * OVER-triggering skill costs the answer: the wrong body enters the system
+     * prompt and the wrong tools enter the tools slot, and everything said after
+     * that is shaped by a skill with no business in the turn.
+     *
+     * It is declared on the GRAPH, not on a skill, because a phrase that must
+     * route nowhere belongs to no skill: the assertion is satisfied only when
+     * EVERY rule declines, and a row hung on one skill would vanish the day that
+     * skill was deleted — exactly when a graph is re-partitioned, which is
+     * exactly when over-triggering appears.
+     *
+     * `graph.checkup()` runs every declared start condition over the phrase on a
+     * cold-start context and reports the rule that claims it, BY NAME, as an
+     * ERROR (`never-routes-claimed`) — so a default `.build()` refuses.
+     *
+     * **What it proves, exactly:** no declared start RULE claims the phrase. Not
+     * "no routing at all": an intent rule is judged by a classifier at run time, a
+     * scorer / `.entryByRead()` menu ranks descriptions, and `read_skill` can
+     * always open an open skill by name. That statement rides the report itself
+     * (`checkup().notes`).
+     *
+     * Accepts one phrase or a list; call it as often as you like (rows
+     * accumulate). A duplicate row is refused — one row already asserts it
+     * against every rule.
+     *
+     * @example
+     *   skillGraph()
+     *     .entry(billing, { match: { keywords: ['refund', 'charge'] } })
+     *     .neverRoutes(["what's the weather in Berlin"])
+     *     .build();
+     */
+    neverRoutes(phrases: string | readonly string[]): SkillGraphBuilder;
     build(opts?: BuildOptions): SkillGraph;
 }
 export declare function skillGraph(): SkillGraphBuilder;