agentfootprint 13.0.0 → 14.0.0

package/dist/esm/injection-engine/skillGraph.js

@@ -57,75 +57,38 @@
  * at the same skill (8.5.0 — before, the drawn build-time provenance was read as the
  * per-hop cause, so a model pick was recorded under a declared edge's label).
  */
-import { devMode, devWarn } from './devWarn.js';
-import { isHiddenSkill, toolResultsOf } from './types.js';
+import { devWarn } from './devWarn.js';
+import './types.js';
 import { embeddingScorer } from './entryScorer.js';
-import { checkupGraph, formatCheckup, } from './skillGraphCheckup.js';
+import { formatCheckup, checkupGraph } from './skillGraphCheckup.js';
 import { checkSkillContracts } from './skillContract.js';
 import { checkArtifactVocabularies } from './skillVocabulary.js';
-import { checkStartRuleExamples, validateStartRuleExamples } from './skillExamples.js';
-import { checkNeverRoutes, neverRouteKey, validateNeverRoutes } from './skillNeverRoutes.js';
+import { validateStartRuleExamples, checkStartRuleExamples } from './skillExamples.js';
+import { validateNeverRoutes, neverRouteKey, checkNeverRoutes } from './skillNeverRoutes.js';
 import { checkPartition } from './skillPartition.js';
 import { checkEntryEvidence } from './skillEntryEvidence.js';
-import { compileMatch, mermaidMatchCaption, } from './skillMatch.js';
-import { compileGuard, mermaidGuardCaption, plainGuardCaption, } from './skillGuard.js';
+import { compileMatch } from './skillMatch.js';
+import { compileGuard, plainGuardCaption } from './skillGuard.js';
 import { resolveRoutingPolicy } from './routingPolicy.js';
-import { buildTurnRoutingPlan, findDuplicateIntentExamples, runCheckupIntents, } from './skillIntent.js';
+import { findDuplicateIntentExamples, buildTurnRoutingPlan, runCheckupIntents, } from './skillIntent.js';
+import { describe, statusesOf, plural, isDeterministicRoute, } from './skillGraph/routePredicates.js';
+import { compileTree, attachExactlyOneLeafMonitor } from './skillGraph/treeCompilation.js';
+import { makeResolveCursor } from './skillGraph/cursorResolution.js';
+import { memoizePerPass } from './skillGraph/passMemo.js';
+import { makeReachableSkills } from './skillGraph/reachability.js';
+import { makeSupersededEntries } from './skillGraph/entrySuppression.js';
+import { makeScoreEntries } from './skillGraph/entryScores.js';
+import { deriveTrigger } from './skillGraph/triggerCompilation.js';
+import { routingFor } from './skillGraph/routingView.js';
+import { SKILL_GRAPH_METADATA_KEY, SKILL_GRAPH_DEFERRED_CONTRACT_KEY, } from './skillGraph/graphContracts.js';
+import { renderMermaid } from './skillGraph/graphDrawing.js';
 export { formatCheckup } from './skillGraphCheckup.js';
 // The data-guard domain (`guard:` on route edges, 9.51.0) — one module owns the
 // type, the compiler, the evidence shape and the caption; see ./skillGuard.ts.
 export { GUARD_HOP_KEYS, plainGuardCaption, } from './skillGuard.js';
-/** Build a decision node. Leaves are skills (an `Injection`); internal nodes are
- *  other `decideSkill(...)` results. (Renamed from `decide` in v7 to avoid
- *  colliding with footprintjs's `decide()`.) */
-export function decideSkill(predicate, whenTrue, whenFalse, label) {
-    return { kind: 'decision', predicate, whenTrue, whenFalse, label };
-}
-function isDecisionNode(n) {
-    return n.kind === 'decision';
-}
-/** The metadata key carrying a skill's routing provenance. */
-export const SKILL_GRAPH_METADATA_KEY = 'skillGraph';
-/**
- * The metadata key carrying the {@link DeferredBodyContract} note on each COMPILED
- * skill. The graph-level `graph.deferredBodyContract` note names the deferral, but
- * skills reach an agent through more than one door — `.skillGraph(graph)` sees the
- * graph, `.skills({ list: () => graph.skills })` sees only the skills — so the note
- * also rides each skill's own metadata. Agent build collects it from the final
- * injection list, whichever door the skills came through, and runs the deferred
- * checks exactly once (skills found by BOTH the metadata and the graph note are
- * deduped by id).
- */
-export const SKILL_GRAPH_DEFERRED_CONTRACT_KEY = 'skillGraphDeferredBodyContract';
-/** A route edge that fires on its own evidence — `when` code, a tool-name
- *  match, a declared status, or a data guard. NOT a model edge. The ONE
- *  predicate every determinism filter shares (9.19.0 folded four replicas
- *  into it when `onToolStatus` joined the family; `guard` joined in 9.51.0). */
-function isDeterministicRoute(r) {
-    return (r.when !== undefined ||
-        r.onToolReturn !== undefined ||
-        r.onToolStatus !== undefined ||
-        r.guard !== undefined);
-}
-/** The declared status set, normalized to an array. */
-function statusesOf(onToolStatus) {
-    return Array.isArray(onToolStatus) ? onToolStatus : [onToolStatus];
-}
-/** Mermaid node ids must be identifier-safe; keep the original id as the label. */
-function nodeId(id) {
-    return 'n_' + id.replace(/[^A-Za-z0-9_]/g, '_');
-}
-function toolMatcher(toolName) {
-    return typeof toolName === 'string' ? (n) => n === toolName : (n) => toolName.test(n);
-}
-/** How a skill is identified back to its author in a refusal — the description is
- *  what tells two same-id skills apart (mirrors skillsFromDir naming both files). */
-function describe(skill) {
-    return skill.description ?? '(no description)';
-}
-function plural(n, one, many) {
-    return `${n} ${n === 1 ? one : many}`;
-}
+export { SKILL_GRAPH_METADATA_KEY, SKILL_GRAPH_DEFERRED_CONTRACT_KEY, } from './skillGraph/graphContracts.js';
+export { decideSkill } from './skillGraph/decision.js';
+export { classifySkillTarget } from './skillGraph/reachability.js';
 export function skillGraph(config) {
     const skillsById = new Map();
     const entries = [];
@@ -899,761 +862,4 @@ export function skillGraph(config) {
  *                  the degenerate guard).
  */
 export const defineSkillMap = skillGraph;
-// FOLD · the one owner of the skills reachable from where the cursor stands (declared successors ∪ entries, minus the cursor)
-// consumers read this and never re-derive it: the read_skill offer builder (Agent.ts · readSkillOfferFor), the
-// injection-engine config's `reachableSkills` and the read_skill gate's `allowedSkillIds` (both Agent.ts) — which
-// toolCalls reads back as deps.allowedSkillIds at the propose-transition judge and at the gate itself
-// (toolCalls.ts · "── Skill-graph read_skill GATE").
-// detached: yes — dedupe builds a fresh array per call; the declarations never leave.
-/**
- * The reachable-set resolver (the read_skill gate's allowed set). Pure +
- * deterministic over the build-time entries/routes:
- *   • cold start (cursor undefined) → the entry skills (you enter via entries);
- *   • otherwise → the cursor's direct successors (ANY declared edge out of it,
- *     deterministic OR bare/model) ∪ the entry skills, minus the cursor itself.
- *
- * That last exclusion is about MOVEMENT and nothing else: there is nowhere to
- * move to. It is NOT a statement that the cursor is unavailable, and five
- * consumers read it as one until {@link classifySkillTarget} was given the
- * question — read its doc comment before writing a `requested === cursor`
- * check anywhere. Declaration order preserved; ids de-duplicated.
- */
-function makeReachableSkills(entries, routes) {
-    const entryIds = entries.map((e) => e.id);
-    return (cur) => {
-        const ids = cur === undefined ? [...entryIds] : [...successorsOf(cur, routes), ...entryIds];
-        return dedupe(cur === undefined ? ids : ids.filter((id) => id !== cur));
-    };
-}
-// FOLD · the one owner of which class a read_skill target falls in from one cursor: 'self' | 'hop' | 'open' | 'unreachable'
-// consumers read this and never re-derive it: skillToolDescriptors.ts · grantableRows and skillToolDescriptors.ts ·
-// classOf · toolCalls.ts · atMountedCursor, the propose-transition judge (toolCalls.ts · "── A PROPOSAL TO THE
-// CURSOR'S OWN SKILL IS A STAY") and the read_skill gate (toolCalls.ts · "── Skill-graph read_skill GATE") ·
-// re-exported for consumers at doors/skill-graph.ts.
-// detached: yes — a string literal over readonly inputs the caller already owns.
-/**
- * Classify one `read_skill` target against one cursor. See
- * {@link SkillTargetClass} for the law this function owns.
- *
- * @example
- * ```ts
- * classifySkillTarget({ cursor: 'billing', target: 'billing' });               // 'self'
- * classifySkillTarget({ cursor: 'billing', target: 'refunds', hops: ['refunds'] }); // 'hop'
- * classifySkillTarget({ cursor: 'billing', target: 'debug', open: ['debug'] });     // 'open'
- * classifySkillTarget({ cursor: 'billing', target: 'vault' });                 // 'unreachable'
- * ```
- */
-export function classifySkillTarget(args) {
-    const { cursor, target, hops, open } = args;
-    if (cursor !== undefined && target === cursor)
-        return 'self';
-    if (hops?.includes(target) === true)
-        return 'hop';
-    if (open?.includes(target) === true)
-        return 'open';
-    return 'unreachable';
-}
-/** Direct successors of `from` — every declared route edge out of it (any kind). */
-function successorsOf(from, routes) {
-    return routes.filter((r) => r.fromId === from).map((r) => r.toId);
-}
-function dedupe(ids) {
-    return [...new Set(ids)];
-}
-/**
- * Bind the chosen `EntryScorer` strategy into `graph.scoreEntries`. The engine owns
- * the `when`-filtering (it needs `ctx` + the entry predicates); the scorer owns the
- * ranking. Filters the entries to the `when`-passing candidates, hands the scorer
- * `{ userMessage, candidates: { id, description } }`, and returns its `EntryScoring`.
- * Async wrapper so a sync scorer (`keywordScorer`) and an async one (`embeddingScorer`)
- * present identically; runs once per turn in the OFF-LOOP PickEntry stage, never in
- * the sync route triggers, so `nextSkill` stays synchronous. An empty candidate set
- * (or a throwing scorer, caught by PickEntry) falls back to the normal cold-start entry.
- */
-function makeScoreEntries(entries, skillsById, scorer) {
-    return async (ctx, signal) => {
-        const candidates = entries
-            .filter((e) => {
-            if (!e.when)
-                return true;
-            try {
-                return e.when(ctx);
-            }
-            catch (err) {
-                warnMatcherThrew(`entry "${e.id}"`, err);
-                return false;
-            }
-        })
-            .map((e) => ({ id: e.id, description: skillsById.get(e.id)?.description ?? e.id }));
-        return scorer.score({ userMessage: ctx.userMessage, candidates }, signal);
-    };
-}
-/** Does a single route edge fire for ONE tool result of the batch?
- *  `onToolStatus` matches the result's DECLARED status (composed with the
- *  tool name when `onToolReturn` is also set — a result with no status can
- *  never match a status edge); `onToolReturn` alone matches the tool NAME;
- *  `when` runs the predicate over the result (same `{ toolName, result }`
- *  shape it has always received, plus `status` when declared). The caller
- *  walks the batch in call order (9.16.0) — before that, only
- *  `ctx.lastToolResult` was ever offered here. */
-function routeMatches(r, res) {
-    if (!edgePreconditionsPass(r, res))
-        return false;
-    if (r.onToolStatus !== undefined || r.onToolReturn !== undefined)
-        return true;
-    return r.when ? r.when(res) : false;
-}
-/** The tool/status PRECONDITIONS of one edge against one result — the part a
- *  `guard` is judged AFTER (9.51.0). True when the edge declares neither.
- *  Split out of `routeMatches` because the resolver dispatches guard edges
- *  itself: the guard's evidence must be collected at the very statement that
- *  decides the hop, and "the guard decided" is only true once these passed. */
-function edgePreconditionsPass(r, res) {
-    if (r.onToolStatus !== undefined) {
-        if (res.status === undefined || !statusesOf(r.onToolStatus).includes(res.status)) {
-            return false;
-        }
-        return r.onToolReturn ? toolMatcher(r.onToolReturn)(res.toolName) : true;
-    }
-    if (r.onToolReturn)
-        return toolMatcher(r.onToolReturn)(res.toolName);
-    return true;
-}
-/**
- * The cursor resolver (the keystone). Pure + deterministic. Given the iteration
- * context, returns the skill the graph should be *in* after this iteration AND the
- * clause that decided it (`CursorMove`; `nextSkill` is the `.to` projection):
- *   • cold start (`currentSkillId` unset) → first `entry` whose `when` passes
- *     (an `always`-entry — no `when` — matches unconditionally), else the entry
- *     the MODEL picked with `read_skill` (see "the model's pick" below);
- *   • a `from`-gated route (`fromId === currentSkillId`) whose predicate matches
- *     a result of the iteration's tool batch — results in call order, edges per
- *     result in declaration order; the first result with a match wins, later
- *     results matching OTHER targets are reported as `conflict` (9.16.0) →
- *     its target (the transition);
- *   • else the model's pick, when the read_skill gate accepted one this turn;
- *   • otherwise the current cursor unchanged (sticky stay).
- *
- * **The model's pick (`ctx.pendingSkillPick`) — the D2 "validated volunteer".**
- * `read_skill(id)` is already GATED to `reachableSkills(cursor)` (the model may
- * only name a skill the graph declares as reachable from where it stands), and
- * the tool answers "Skill 'id' activated for the next iteration." Until 8.3.0 the
- * cursor ignored that answer for every form except `.entryByRead()`'s cold start,
- * so the sentence was false wherever the skill's activation was cursor-gated or
- * rule-gated. It is honoured here, at ONE place, with the precedence the design
- * pinned (docs/design/skill-graph.md §4A.1): a declared edge that fired this hop
- * WINS over a same-turn pick (`D1 > D2`) — the author's determinism is never
- * overridden by a model guess. The pick is one-shot (the tool-calls stage rewrites
- * it every iteration), so a pick can never drag the cursor backwards after a later
- * edge has moved it.
- *
- * Each candidate predicate runs in its OWN try/catch so one throwing edge can't
- * block its siblings or crash the loop — a throw is treated as "no match" and,
- * in dev mode, warned. This is the design's `routeForResult` pin-table target.
- *
- * The `by` on each return is decided at the same statement as the destination
- * (8.5.0). That matters most in the case an outside observer cannot reconstruct:
- * a declared edge and a same-turn model pick naming the SAME target. `D1 > D2`
- * makes it a `'route'`, and only this function knows.
- */
-/** The winning entry's recorded evidence, as a spreadable fragment: `{ witness }`
- *  when the rule was DATA and it yielded quotable text, `{}` otherwise (a `when`
- *  predicate, an unconditional entry, a match with nothing quotable). A throwing
- *  extractor is treated exactly as no evidence — a record is never worth a crash,
- *  and the hop itself already happened. */
-function witnessOf(entry, ctx) {
-    if (!entry.witness)
-        return {};
-    try {
-        const found = entry.witness(ctx);
-        return found === undefined ? {} : { witness: found };
-    }
-    catch {
-        return {};
-    }
-}
-// FOLD · the one owner of where the cursor goes next, and which clause decided it (CursorMove)
-// consumers read this and never re-derive it: the `nextSkill` and `explainNextSkill` hooks the Evaluate stage asks;
-// the memoized `nextSkillForTriggers` that `deriveTrigger` reads; and `makeSupersededEntries`.
-// NOT skillToolDescriptors: the read_skill description reads the ALREADY-RESOLVED cursor off the offer (offer.cursorId).
-// detached: yes — a POJO plus a string id, memoized per pass so two readers get one decided value.
-function makeResolveCursor(entries, routes, llmReadEntry = false) {
-    const isEntry = (id) => entries.some((e) => e.id === id);
-    return (ctx) => {
-        // ROLE VISIBILITY. The cursor never moves onto a skill this caller's role
-        // may not read (`isHiddenSkill`, the same rule the evaluator refuses
-        // activation by), so the stored cursor and the active set cannot
-        // disagree. Every clause below asks `may` before it names a destination:
-        // a keyword in the message, a declared edge, a tool proposal and a pick
-        // are all untrusted routes to the same place. A cursor already standing
-        // on a hidden skill (a restored conversation, a grant revoked mid-run) is
-        // treated as no cursor, so the turn re-enters through the visible entries.
-        const may = (id) => !isHiddenSkill(ctx, id);
-        const cur = ctx.currentSkillId !== undefined && may(ctx.currentSkillId) ? ctx.currentSkillId : undefined;
-        const from = cur !== undefined ? { from: cur } : {};
-        // The turn-start cascade's verdict (SG-C) — a PRECOMPUTED input consumed
-        // exactly as `pendingSkillPick` is, on iteration 1 only (the RouteTurn
-        // stage decided it off the hot loop; `userMessage` is fixed for the run,
-        // so iterations 2..N keep today's law byte-for-byte). Present only on
-        // cascade graphs (`classify` / `continuity: 'conversation'`); absent, not
-        // one line here behaves differently. A `menu`/`none` verdict carries no
-        // `to` and falls through — the model resolves the menu via the ordinary
-        // gated pick (D2), which is what keeps the offer and the verdict one
-        // machinery; the cold-start walk below is suppressed by the verdict's
-        // PRESENCE, so falling through can never enter an entry the record does
-        // not claim.
-        if (ctx.iteration === 1 && ctx.turnRoute?.to !== undefined && may(ctx.turnRoute.to)) {
-            const by = ctx.turnRoute.by === 'intent'
-                ? 'intent'
-                : ctx.turnRoute.by === 'continuity'
-                    ? 'continuity'
-                    : ctx.turnRoute.by === 'decider'
-                        ? 'decider'
-                        : 'entry';
-            return {
-                ...(ctx.turnRoute.from !== undefined && { from: ctx.turnRoute.from }),
-                to: ctx.turnRoute.to,
-                by,
-                // The cascade already extracted the tier-1 evidence (`turn_routed`
-                // carries it); the hop repeats it rather than re-deriving it, so the
-                // two records can never quote different text.
-                ...(ctx.turnRoute.witness !== undefined && { witness: ctx.turnRoute.witness }),
-            };
-        }
-        if (cur === undefined) {
-            // Cold start: declaration-order first entry whose intent predicate passes.
-            // `.entryByRead()` skips this — there the library deliberately does NOT
-            // auto-pick; the model reads the menu and picks (below), so no entry body
-            // loads until it does. A turn whose cascade left a VERDICT on scope
-            // (`ctx.turnRoute`, SG-C) skips it the same way: suppression follows the
-            // verdict, not only the compile-time flag, because an entry-scorer graph
-            // opts into the cascade at MOUNT time (`continuity: 'conversation'`) —
-            // it compiles with `llmReadEntry` false, yet its cold `menu`/`none`
-            // verdict (a near-tie, or the scorer-throw fallback) must reach the
-            // model, never be overridden by the declaration-order walk while the
-            // record claims a menu is outstanding. RouteTurn writes the POJO only
-            // when the cascade DECIDED something, so a graph whose cold start still
-            // belongs to this walk (no rules, no tier 2 — e.g. after a dropped
-            // resume) keeps it.
-            if (!llmReadEntry && ctx.turnRoute === undefined) {
-                for (const e of entries) {
-                    if (!may(e.id))
-                        continue;
-                    if (!e.when)
-                        return { to: e.id, by: 'entry' };
-                    try {
-                        // The witness is extracted HERE, on the winner only — the losing
-                        // rules never pay for evidence, and an unconditional/`when` entry
-                        // has none to give (`witnessOf` answers undefined).
-                        if (e.when(ctx))
-                            return { to: e.id, by: 'entry', ...witnessOf(e, ctx) };
-                    }
-                    catch (err) {
-                        warnMatcherThrew(`entry "${e.id}"`, err);
-                    }
-                }
-            }
-            // A cold ACCEPTED tool proposal enters exactly where a cold model pick
-            // may (an entry — the reachable-from-cold set), and OUTRANKS the pick:
-            // deterministic tool evidence over a model guess, the same order the
-            // mid-run walk applies below (9.19.0).
-            const coldProposal = ctx.pendingToolTransition?.targetSkillId;
-            if (coldProposal !== undefined && isEntry(coldProposal) && may(coldProposal)) {
-                return { to: coldProposal, by: 'tool-proposal' };
-            }
-            // The model's pick becomes the starting cursor. This is what `.entryByRead()`
-            // has always done; 8.3.0 makes it true for EVERY start form, which is what
-            // makes the rules form's documented fallback ("no rule matched → the model
-            // picks from the read_skill menu") actually work. An entry's `when` is the
-            // AUTOMATIC pick's condition, not a lock on the manual one: the model asked
-            // for this skill by name and the gate allowed it.
-            if (ctx.pendingSkillPick !== undefined &&
-                isEntry(ctx.pendingSkillPick) &&
-                may(ctx.pendingSkillPick)) {
-                return { to: ctx.pendingSkillPick, by: 'model-pick' };
-            }
-            for (const e of entries) {
-                if (may(e.id) && ctx.activatedInjectionIds.includes(e.id)) {
-                    return { to: e.id, by: 'model-pick' };
-                }
-            }
-            return { by: 'none' };
-        }
-        // D1 — transition: the whole tool batch, in CALL order (9.16.0). Per
-        // result, the first from-gated deterministic edge in DECLARATION order
-        // that fires names that result's target; the first RESULT with a target
-        // wins the cursor. Two orders, two jobs: declaration order is the
-        // author's tiebreak when one result could match several edges (the D1
-        // law, unchanged), call order is the run's tiebreak across results —
-        // the tool that returned first routed first. Before 9.16.0 only the
-        // LAST call of a batch was consulted, so identical batches routed
-        // differently depending on call order (the 9.15.0 L1 probe). A later
-        // result matching a DIFFERENT target is suppressed AND reported on the
-        // move (`conflict`), never silently dropped; a batch of one is
-        // byte-identical to the old singular walk. D1 still wins over a
-        // same-turn model pick — INCLUDING when both name the same target,
-        // which is why the cause is decided here and not inferred downstream
-        // from the destination.
-        let winner;
-        let losers;
-        // Guard evidence (9.51.0), collected at the very statements that decide:
-        // the winning edge's evaluation (verdict true) and — per guarded edge —
-        // the FIRST refusal whose preconditions a result met (verdict false).
-        // A guarded edge whose tool/status preconditions never matched leaves no
-        // record: its guard never decided anything.
-        let winnerGuard;
-        let guardsClosed;
-        let closedEdges;
-        for (const res of toolResultsOf(ctx)) {
-            let target;
-            let targetGuard;
-            for (const r of routes) {
-                if (r.fromId !== cur)
-                    continue;
-                if (!isDeterministicRoute(r))
-                    continue; // model edges don't auto-fire
-                if (!may(r.toId))
-                    continue; // an edge into a hidden skill never fires
-                try {
-                    if (r.guard !== undefined) {
-                        // The guard is judged AFTER the edge's own tool/status
-                        // preconditions, over the hop view (the six hop keys + the
-                        // result's JSON fields — see skillGuard.ts). `evaluate` and the
-                        // routing predicate are one compilation, so the recorded
-                        // conditions ARE the ones that routed.
-                        if (!edgePreconditionsPass(r, res))
-                            continue;
-                        const evaluation = r.guard.evaluate({
-                            toolName: res.toolName,
-                            result: res.result,
-                            ...(res.status !== undefined && { status: res.status }),
-                            iteration: ctx.iteration,
-                            userMessage: ctx.userMessage,
-                            currentSkillId: cur,
-                        });
-                        const record = {
-                            from: r.fromId,
-                            to: r.toId,
-                            toolName: res.toolName,
-                            ...(res.toolCallId !== undefined && { toolCallId: res.toolCallId }),
-                            verdict: evaluation.verdict,
-                            conditions: evaluation.conditions,
-                        };
-                        if (evaluation.verdict) {
-                            target = r.toId;
-                            targetGuard = record;
-                            break;
-                        }
-                        if (!(closedEdges ??= new Set()).has(r)) {
-                            closedEdges.add(r);
-                            (guardsClosed ??= []).push(record);
-                        }
-                        continue;
-                    }
-                    if (routeMatches(r, res)) {
-                        target = r.toId;
-                        break;
-                    }
-                }
-                catch (err) {
-                    warnMatcherThrew(`route ${r.fromId}→${r.toId}`, err);
-                }
-            }
-            if (target === undefined)
-                continue;
-            const outcome = {
-                ...(res.toolCallId !== undefined && { toolCallId: res.toolCallId }),
-                toolName: res.toolName,
-                target,
-            };
-            if (winner === undefined) {
-                winner = outcome;
-                winnerGuard = targetGuard;
-            }
-            else if (target !== winner.target)
-                (losers ??= []).push(outcome);
-        }
-        // The refusals ride WHATEVER move resulted — a closed guard explains a
-        // stay (or the hop that won instead) the same way `supersededEntries`
-        // explains a suppressed entry.
-        const closed = guardsClosed !== undefined ? { guardsClosed } : {};
-        if (winner !== undefined) {
-            return {
-                ...from,
-                to: winner.target,
-                by: 'route',
-                ...(winnerGuard !== undefined && { guard: winnerGuard }),
-                ...closed,
-                ...(losers !== undefined && { conflict: { winner, losers } }),
-            };
-        }
-        // D1.5 — the ACCEPTED tool proposal (9.19.0): no declared edge fired, so
-        // a `propose-transition` effect the gate validated moves the cursor. It
-        // sits BETWEEN the edges and the pick on purpose: a declared edge is the
-        // author's determinism (never overridden), a proposal is the tool
-        // author's determinism (code that shipped), a pick is the model's guess.
-        // A proposal of the CURRENT skill is a no-op stay, not a hop.
-        const proposal = ctx.pendingToolTransition?.targetSkillId;
-        if (proposal !== undefined && proposal !== cur && may(proposal)) {
-            return { ...from, to: proposal, by: 'tool-proposal', ...closed };
-        }
-        // D2 — the validated volunteer: no declared edge fired, so the model's own
-        // (already gated) pick moves the cursor. A pick of the CURRENT skill is a
-        // no-op stay, not a hop.
-        if (ctx.pendingSkillPick !== undefined &&
-            ctx.pendingSkillPick !== cur &&
-            may(ctx.pendingSkillPick)) {
-            return { ...from, to: ctx.pendingSkillPick, by: 'model-pick', ...closed };
-        }
-        return { ...from, to: cur, by: 'stay', ...closed }; // sticky stay — no edge out of cur fired
-    };
-}
-/**
- * The suppression reporter (8.15.0) — the honesty half of the one law.
- *
- * A conditional entry is active exactly while the cursor is on it, so an entry whose
- * own `when` matched while the graph is somewhere else is SUPPRESSED. Before 8.15.0
- * it would have loaded beside the cursor's skill, which is precisely the double
- * activation the law removes — so the run has to be able to SAY it happened, or an
- * author debugging "why isn't my entry loading?" has nothing to read.
- *
- * Pure: one resolver pass plus, at most, one predicate call per OTHER conditional
- * entry — O(E), inside the ceiling `memoizePerPass` sets for the whole evaluation.
- * The RAW resolver (not the memoized projection) is used deliberately, matching the
- * freshness policy of the other public resolvers: called once per iteration, always
- * recomputed.
- *
- * A throwing predicate is swallowed HERE and reported by the evaluator instead
- * (`skipped: 'predicate-threw'`) — one throw must not be told as two different
- * stories on the same event.
- */
-function makeSupersededEntries(entries, resolveCursor) {
-    const conditional = entries.filter((e) => e.when !== undefined);
-    if (conditional.length === 0)
-        return () => [];
-    return (ctx) => {
-        const to = resolveCursor(ctx).to;
-        // No cursor at all → the trigger falls back to the rule alone, so nothing is
-        // being superseded.
-        if (to === undefined)
-            return [];
-        const out = [];
-        for (const e of conditional) {
-            if (e.id === to)
-                continue; // this is the one that won
-            try {
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                if (e.when(ctx))
-                    out.push(e.id);
-            }
-            catch {
-                // Reported by the evaluator as `predicate-threw`, not as a suppression.
-            }
-        }
-        return out;
-    };
-}
-/**
- * Memoize `nextSkill` per EVALUATION PASS.
- *
- * `evaluateInjections` hands ONE `ctx` object to every trigger in a pass, and
- * (since 8.3.0) every graph-compiled trigger — entry and route target alike —
- * asks `nextSkill(ctx)`. Without this, a graph with E entries and R routes pays
- * O(E × (E + R)) predicate calls per iteration instead of O(E + R): a 15-entry
- * regex router would re-run all 15 regexes 15 times per turn.
- *
- * Keyed on ctx IDENTITY in a WeakMap, so entries vanish with the context object
- * and a fresh iteration always recomputes. Safe because the resolver is pure over
- * `ctx` (route/entry predicates are documented as "pure + total"); the memo can
- * only make a pass MORE self-consistent, never less. `graph.nextSkill` and
- * `graph.explainNextSkill` are left un-memoized — they are public API called once
- * per iteration, and a consumer that mutates a ctx object between calls must still
- * get a fresh answer.
- *
- * Memoizes the whole `CursorMove` and projects `.to` for the triggers (8.5.0), so
- * one pass computes the destination and the cause together, exactly once.
- */
-function memoizePerPass(resolveCursor) {
-    const cache = new WeakMap();
-    return (ctx) => {
-        const hit = cache.get(ctx);
-        if (hit)
-            return hit.value;
-        const value = resolveCursor(ctx).to;
-        cache.set(ctx, { value });
-        return value;
-    };
-}
-function warnMatcherThrew(edge, err) {
-    devWarn(`agentfootprint skillGraph: ${edge} predicate threw — treated as no-match. ` +
-        `Predicates must be pure + total. ${err instanceof Error ? err.message : String(err)}`);
-}
-/** Compile a skill's incoming edges → one injection trigger (or null = keep the
- *  skill's default `llm-activated` trigger, i.e. model-reachable via read_skill).
- *
- *  A route target B is active iff `nextSkill(ctx) === B`. That single expression
- *  delivers all three keystone properties from ONE source of truth:
- *    • `from`-gating  — `nextSkill` only fires an edge `A→B` while the cursor is
- *      on A, so the edge no longer bleeds into an unrelated skill D (the v1 bug);
- *    • stickiness     — when the cursor is on B and no edge leaves B, `nextSkill`
- *      returns B (sticky stay), so B re-activates each iteration;
- *    • clean handoff  — the iteration a `B→C` edge fires, `nextSkill` returns C,
- *      so B deactivates the SAME step C activates — no double-active overlap.
- *  Because the loop's cursor-update stage is ALSO `currentSkillId = nextSkill(ctx)`,
- *  the trigger and the cursor can never disagree. */
-function deriveTrigger(id, _skill, entries, routes, nextSkill, exclusiveEntries) {
-    const entry = entries.find((e) => e.id === id);
-    if (entry) {
-        // `.entryByRelevance()` / `.entryByRead()` make the entries EXCLUSIVE candidates:
-        // exactly ONE loads — the best match (embedder) or the model's pick (read_skill) —
-        // as the cursor, so only that entry's body lands (token-efficient). The same
-        // cursor-gated trigger as a route target delivers that for both modes.
-        if (exclusiveEntries) {
-            return { kind: 'rule', activeWhen: (ctx) => nextSkill(ctx) === id };
-        }
-        // Default (v1): a persistent base (always) or intent-conditional (rule).
-        // An unconditional entry is `always` — the cursor can add nothing to it. This is
-        // the ONE declared way to be co-active beside whatever the cursor is on, and it
-        // is untouched by 8.15.0.
-        if (!entry.when)
-            return { kind: 'always' };
-        // An intent-conditional entry is active EXACTLY WHILE THE CURSOR IS ON IT (8.15.0)
-        // — the same expression the exclusive-entry arm above and the route-target arm
-        // below already use. One law for a flat graph: a skill is active iff the cursor is
-        // on it, or it declared itself unconditional.
-        //
-        // 8.3.0 added the cursor clause to a rule-only trigger and left the rule clause
-        // standing as an OR. That leftover was the bug: an entry S with a `when` that
-        // routes to T stayed active on the hop (its rule reads the user's message, which
-        // does not change mid-turn), so S and T were both on the wire — two skill bodies,
-        // two tool sets — for a graph drawn as a single-file state machine. And it was the
-        // steady state, not a blip: every later iteration parked the cursor on T while S's
-        // rule still matched, so S came back. This finishes 8.3.0 rather than reverting
-        // it — both failures 8.3.0 names (a declared `step` INTO an entry skill; a
-        // `read_skill` pick onto one) are carried by the CURSOR clause, which survives.
-        //
-        // The rule is still evaluated FIRST, and deliberately: a throwing entry predicate
-        // must keep surfacing as the evaluator's `skipped: 'predicate-threw'`, which it
-        // only can if the trigger calls it. Its answer is then used for exactly one thing
-        // — the cold-start fallback below, when the graph has no cursor at all.
-        //
-        // A rule that matched while the cursor is elsewhere is a SUPPRESSION, and the run
-        // says so: `supersededEntries(ctx)` reports it and the Injection Engine stamps it
-        // on `agentfootprint.context.evaluated` as `supersededIds`.
-        const activeWhen = entry.when;
-        return {
-            kind: 'rule',
-            activeWhen: (ctx) => {
-                const matched = activeWhen(ctx);
-                const to = nextSkill(ctx);
-                if (to === id)
-                    return true; // the cursor lands here — my turn
-                if (to !== undefined)
-                    return false; // the graph is engaged elsewhere — not my turn
-                return matched; // no cursor at all → the rule alone
-            },
-        };
-    }
-    // Deterministic incoming edges (when / onToolReturn / onToolStatus) →
-    // cursor-gated + sticky.
-    const incoming = routes.filter(isDeterministicRoute).filter((r) => r.toId === id);
-    if (incoming.length === 0)
-        return null; // model-reachable — keep default trigger
-    return { kind: 'rule', activeWhen: (ctx) => nextSkill(ctx) === id };
-}
-/** Walk a decision tree → push each leaf skill (with its path-conjunction trigger,
- *  earlier-sibling negation baked into the path) plus predicate/skill nodes +
- *  branch edges for drawing. */
-function compileTree(node, pathCond, out, parent, counter, path, scopeTools, 
-/** Registers each leaf under its id — the duplicate-id refusal and the
- *  skill-contract checks both read that registry (8.4.0). */
-register) {
-    if (isDecisionNode(node)) {
-        const id = `d${counter.n++}`;
-        const label = node.label ?? 'decide';
-        out.nodes.push({ id, kind: 'predicate', label });
-        out.edges.push({
-            from: parent ? parent.id : null,
-            to: id,
-            kind: 'predicate',
-            label: parent?.branch,
-        });
-        compileTree(node.whenTrue, (ctx) => pathCond(ctx) && node.predicate(ctx), out, { id, branch: 'yes' }, counter, [...path, { label, branch: 'yes' }], scopeTools, register);
-        compileTree(node.whenFalse, (ctx) => pathCond(ctx) && !node.predicate(ctx), out, { id, branch: 'no' }, counter, [...path, { label, branch: 'no' }], scopeTools, register);
-    }
-    else {
-        if (node.flavor !== 'skill') {
-            throw new Error(`skillGraph.tree: leaf "${node.id}" is not a skill (flavor='${node.flavor}').`);
-        }
-        // Claim the id. The SAME object at two leaves is the merge below; two DIFFERENT
-        // skills under one id is refused here rather than merged (8.4.0) — the merge
-        // kept the first body and dropped the second one's silently.
-        register(node);
-        // The SAME skill may be the leaf of several branches ("ESXi questions" and
-        // "io questions" both route to the io-profile bundle). Compile it ONCE:
-        // merge repeated leaves into one injection whose trigger ORs the path
-        // predicates — pushing a second same-id injection would explode in
-        // Agent.injection()'s duplicate-id guard.
-        const existingIdx = out.skills.findIndex((skill) => skill.id === node.id);
-        if (existingIdx >= 0) {
-            const prev = out.skills[existingIdx];
-            const prevWhen = prev.trigger
-                .activeWhen;
-            const prevRouting = prev.metadata[SKILL_GRAPH_METADATA_KEY];
-            const allPaths = [
-                ...(prevRouting.paths ?? (prevRouting.path ? [prevRouting.path] : [])),
-                path,
-            ];
-            out.skills[existingIdx] = {
-                ...prev,
-                trigger: {
-                    kind: 'rule',
-                    activeWhen: (ctx) => prevWhen(ctx) || pathCond(ctx),
-                },
-                metadata: {
-                    ...prev.metadata,
-                    [SKILL_GRAPH_METADATA_KEY]: { ...prevRouting, paths: allPaths },
-                },
-            };
-            // Node already exists — add only the second parent edge (the drawing
-            // correctly shows two predicate diamonds converging on one leaf).
-            out.edges.push({
-                from: parent ? parent.id : null,
-                to: node.id,
-                kind: 'predicate',
-                label: parent?.branch,
-            });
-            return;
-        }
-        const routing = { via: 'tree', path };
-        // On-demand tools: a tree routes to exactly one leaf per iteration, so scope
-        // each leaf's tools to itself (`autoActivate: 'currentSkill'`) unless the user
-        // opted out (`scopeTools: false`) or the skill already declared its own mode.
-        const existingAuto = node.metadata?.autoActivate;
-        const autoActivate = existingAuto ?? (scopeTools ? 'currentSkill' : undefined);
-        out.skills.push({
-            ...node,
-            trigger: { kind: 'rule', activeWhen: pathCond },
-            metadata: {
-                ...node.metadata,
-                [SKILL_GRAPH_METADATA_KEY]: routing,
-                ...(autoActivate && { autoActivate }),
-            },
-        });
-        out.nodes.push({ id: node.id, kind: 'skill', label: node.id });
-        out.edges.push({
-            from: parent ? parent.id : null,
-            to: node.id,
-            kind: 'predicate',
-            label: parent?.branch,
-        });
-    }
-}
-/**
- * Dev-mode "exactly one leaf fires" monitor (backlog B11).
- *
- * A binary decision tree is exhaustive and non-overlapping BY CONSTRUCTION
- * (each leaf's trigger conjoins its root→leaf predicates with earlier-sibling
- * negation), so static analysis has nothing to check. The invariant breaks at
- * RUNTIME only — when a predicate is impure/non-deterministic: the evaluator
- * re-runs each `decide(...)` predicate once per leaf trigger, so a predicate
- * that answers differently across those calls can fire 0 or ≥2 leaves.
- *
- * In dev mode (footprintjs `enableDevMode()`), each compiled leaf trigger is
- * wrapped to tally fires per evaluation pass (keyed on the shared `ctx`
- * identity — `evaluateInjections` passes one ctx object to every trigger in a
- * pass). When all leaves have been evaluated for one ctx and the fired count
- * is not exactly 1, a console.warn names the leaves. Production pays one
- * `devMode()` check per evaluation; a throwing predicate is excluded here
- * because the evaluator already reports it (`skipped: 'predicate-threw'`).
- */
-function attachExactlyOneLeafMonitor(skills) {
-    const total = skills.length;
-    if (total < 2)
-        return; // single leaf — trivially exactly-one
-    const passes = new WeakMap();
-    for (let i = 0; i < skills.length; i++) {
-        const skill = skills[i];
-        const inner = skill.trigger.activeWhen;
-        skills[i] = {
-            ...skill,
-            trigger: {
-                kind: 'rule',
-                activeWhen: (ctx) => {
-                    if (!devMode())
-                        return inner(ctx);
-                    const fired = inner(ctx); // may throw → evaluator reports 'predicate-threw'
-                    let pass = passes.get(ctx);
-                    if (!pass) {
-                        pass = { evaluated: 0, fired: [] };
-                        passes.set(ctx, pass);
-                    }
-                    pass.evaluated += 1;
-                    if (fired)
-                        pass.fired.push(skill.id);
-                    if (pass.evaluated === total) {
-                        passes.delete(ctx); // reset so a reused ctx object starts a fresh pass
-                        if (pass.fired.length !== 1) {
-                            devWarn(pass.fired.length === 0
-                                ? `agentfootprint skillGraph.tree: NO leaf fired this iteration (expected exactly one). ` +
-                                    `The tree is exhaustive by construction, so a decide() predicate likely returned ` +
-                                    `different answers across leaf evaluations — predicates must be pure and deterministic. ` +
-                                    `Leaves: ${skills.map((s) => s.id).join(', ')}.`
-                                : `agentfootprint skillGraph.tree: ${pass.fired.length} leaves fired simultaneously ` +
-                                    `(expected exactly one): ${pass.fired.join(', ')}. Each decide() predicate is ` +
-                                    `re-evaluated per leaf, so impure/non-deterministic predicates break if/else exclusivity.`);
-                        }
-                    }
-                    return fired;
-                },
-            },
-        };
-    }
-}
-/** Routing provenance for a flat entry/route skill (the v1 model). */
-function routingFor(id, entries, routes) {
-    const entry = entries.find((e) => e.id === id);
-    if (entry)
-        return {
-            via: 'entry',
-            ...(entry.label && { label: entry.label }),
-            ...(entry.match && { match: entry.match }),
-        };
-    const incoming = routes.filter(isDeterministicRoute).filter((r) => r.toId === id);
-    const first = incoming[0];
-    if (first) {
-        return {
-            via: 'route',
-            from: first.fromId,
-            ...(first.label && { label: first.label }),
-            triggerKind: first.onToolReturn && !first.onToolStatus ? 'on-tool-return' : 'rule',
-            ...(first.guard && { guard: first.guard.data }),
-        };
-    }
-    return { via: 'model' }; // model-reachable via read_skill
-}
-function renderMermaid(nodes, edges) {
-    const kindById = new Map(nodes.map((n) => [n.id, n.kind]));
-    const ref = (id) => (kindById.get(id) === 'predicate' ? id : nodeId(id));
-    const lines = ['flowchart TD', '  __start__([▶ start])'];
-    for (const n of nodes) {
-        lines.push(n.kind === 'predicate'
-            ? `  ${n.id}{"${n.label ?? n.id}"}` // predicate → diamond
-            : `  ${nodeId(n.id)}["${n.label ?? n.id}"]`);
-    }
-    for (const e of edges) {
-        const from = e.from === null ? '__start__' : ref(e.from);
-        const arrow = e.kind === 'model' ? '-.->' : '-->'; // model edges dashed
-        // An explicit label wins unchanged; a data matcher captions its entry edge
-        // and a data guard captions its guard-only route edge (that is half the
-        // point of declaring the condition as data — it can be drawn). A guard
-        // composed with a tool/status part is already folded into that derived
-        // label at build.
-        const caption = e.label ??
-            (e.match ? mermaidMatchCaption(e.match) : e.guard ? mermaidGuardCaption(e.guard) : undefined);
-        const label = caption ? `|${caption}|` : '';
-        lines.push(`  ${from} ${arrow}${label} ${ref(e.to)}`);
-    }
-    return lines.join('\n');
-}
 //# sourceMappingURL=skillGraph.js.map