agentfootprint 13.0.0 → 14.0.0

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

@@ -0,0 +1,31 @@
+import { mermaidMatchCaption } from '../skillMatch.js';
+import { mermaidGuardCaption } from '../skillGuard.js';
+/** 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, '_');
+}
+export 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=graphDrawing.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphDrawing.js","sourceRoot":"","sources":["../../../../src/injection-engine/skillGraph/graphDrawing.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,mFAAmF;AACnF,SAAS,MAAM,CAAC,EAAU;IACxB,OAAO,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAA2B,EAAE,KAA2B;IACpF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAU,CAAC,CAAC,CAAC;IACpE,MAAM,GAAG,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACjF,MAAM,KAAK,GAAG,CAAC,cAAc,EAAE,wBAAwB,CAAC,CAAC;IACzD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CACR,CAAC,CAAC,IAAI,KAAK,WAAW;YACpB,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,sBAAsB;YAC1D,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,IAAI,CAC9C,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,qBAAqB;QACxE,2EAA2E;QAC3E,wEAAwE;QACxE,uEAAuE;QACvE,uEAAuE;QACvE,kBAAkB;QAClB,MAAM,OAAO,GACX,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAChG,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,KAAK,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/esm/injection-engine/skillGraph/graphRoutes.d.ts

@@ -0,0 +1,269 @@
+import type { InjectionContext } from '../types.js';
+import type { SkillMatch, SkillMatchData, RouteWitness } from '../skillMatch.js';
+import type { ToolResultStatus } from '../../semantics/toolOutcome.js';
+import type { SkillGuard, SkillGuardData, CompiledGuard } from '../skillGuard.js';
+/**
+ * One start rule: route the turn's start to `use` when the rule matches.
+ * Exactly ONE of `match` (data) / `when` (code) per rule — the union enforces it
+ * at the keystroke and the build refuses it for everyone else. A rule exists to
+ * be conditional; for an unconditional start use `start: 'id'` / `{ use }`.
+ */
+export type SkillStartRule = {
+    readonly use: string;
+    /** The code form — an opaque predicate over the iteration context. */
+    readonly when: (ctx: InjectionContext) => boolean;
+    readonly match?: never;
+    /** The phrasings this rule claims — build-time TEST material. See
+     *  {@link SkillEntryOptions.examples}. */
+    readonly examples?: readonly string[];
+} | {
+    readonly use: string;
+    /** The data form — comparable, drawable, stored. See {@link SkillMatch}. */
+    readonly match: SkillMatch;
+    readonly when?: never;
+    /** The phrasings this rule claims — build-time TEST material. See
+     *  {@link SkillEntryOptions.examples}. */
+    readonly examples?: readonly string[];
+};
+/** Deterministic routing into a skill, keyed on the last tool result. */
+export interface SkillRouteOptions {
+    /** Predicate on the previous iteration's tool result → activate the target
+     *  on the next iteration. The common, controllable edge. `status` is
+     *  present when the tool declared one on its result envelope (9.19.0).
+     *
+     *  `result` is the string the MODEL read — which artifact placement can
+     *  replace with a claim ticket, so an operator raising or lowering
+     *  `artifacts.placement.maxInlineChars` can change whether a text-matching
+     *  edge fires. See {@link InjectionContext.lastToolResult}; route on
+     *  `onToolReturn` / `onToolStatus` for a guard placement cannot move. */
+    readonly when?: (result: {
+        readonly toolName: string;
+        readonly result: string;
+        readonly status?: ToolResultStatus;
+    }) => boolean;
+    /** Sugar for "activate whenever this tool returns (any result)". String is an
+     *  exact match; RegExp is tested against the tool name. */
+    readonly onToolReturn?: string | RegExp;
+    /**
+     * Route on the result's declared OUTCOME, not its prose (9.19.0) — the
+     * data half of the outcome-status normalization: a `'denied'` call must
+     * never route like a `'success'`. Matches when a tool result of the batch
+     * carries one of the named statuses on its envelope; a result with NO
+     * declared status can never match (an undeclared outcome is not
+     * evidence). Compose with `onToolReturn` to pin the tool too ("when
+     * `refund` returns `'denied'`"); alone, any tool's matching status fires.
+     * Data — comparable, drawable (`toMermaid()` captions it), stored. At
+     * most one of `when` / `onToolStatus`: code or data, never both.
+     */
+    readonly onToolStatus?: ToolResultStatus | ReadonlyArray<ToolResultStatus>;
+    /**
+     * The DATA form of `when` (9.51.0) — the edge's condition declared as
+     * comparable, drawable, recordable conditions instead of an opaque
+     * predicate: `{ key: { eq | ne | gt | gte | lt | lte | in | notIn: value } }`,
+     * every condition ANDed (the operator grammar deliberately mirrors
+     * footprintjs's `WhereFilter` — see {@link SkillGuard}). This is the
+     * SkillWalker's guard mover as data: the map is data, entry matchers are
+     * data, `onToolStatus` arms are data — the guard was the last opaque
+     * function on a route edge.
+     *
+     * Judged per tool result of the previous iteration's batch, exactly where a
+     * `when` runs. Six hop keys read the hop directly (`toolName`, `result`,
+     * `status`, `iteration`, `userMessage`, `currentSkillId`); any OTHER key
+     * reads the top-level field of that name from the RESULT parsed as JSON —
+     * `guard: { riskLevel: { gte: 'high' } }` routes on a tool that returned
+     * `{"riskLevel":"high"}`. Being data buys four things a `when` can never
+     * have: the check-up proves contradictions (`guard-unsatisfiable`),
+     * `toMermaid()` captions the edge ("when riskLevel ≥ high"),
+     * `skill.graph_declared` carries it into every recording, and each
+     * evaluation that DECIDES a hop — taken or refused — leaves per-condition
+     * evidence on `cursorMove.guard` / `cursorMove.guardsClosed`.
+     *
+     * COMPOSES with `onToolReturn` / `onToolStatus` ("this tool, this outcome,
+     * AND these conditions"). At most one of `when` / `guard`: code or data,
+     * never both — to combine declared conditions with extra logic, fold the
+     * checks into your `when` predicate.
+     */
+    readonly guard?: SkillGuard;
+    /** Caption rendered on the edge. Defaults to a derived label. */
+    readonly label?: string;
+}
+/** Where a turn starts. `when` (optional) makes entry intent-conditional. */
+export interface SkillEntryOptions {
+    /**
+     * Which entry the turn STARTS on — a predicate over the iteration context
+     * (e.g. `ctx.userMessage`). The first entry whose `when` passes wins the
+     * cold-start cursor.
+     *
+     * **It decides the start; it does not keep the skill on the wire (8.15.0).**
+     * A conditional entry is active exactly while the cursor is on it — a route out
+     * of it ends its turn, and its rule cannot bring it back while the graph is
+     * somewhere else. Before 8.15.0 the rule re-activated it on every iteration, so an
+     * entry that routed onward stayed loaded beside its own successor.
+     *
+     * Omit `when` → the skill is `always` active: a persistent base procedure, on
+     * beside whatever the cursor is on. That is the declared way to ask for an
+     * always-on skill; `when: () => true` is NOT the same thing any more. For "on
+     * whenever this matches, wherever the graph is", use the flavor built for it —
+     * `.steering(...)` / `.skill(...)` with its own `rule` trigger — rather than an
+     * entry, which is a position in a state machine.
+     */
+    readonly when?: (ctx: InjectionContext) => boolean;
+    /**
+     * The DATA form of `when` — a declared matcher over the user's message instead
+     * of a predicate (see {@link SkillMatch}): comparable by the check-up, captioned
+     * by `toMermaid()`, stored on the compiled skill's provenance. Same start
+     * semantics as `when` in every other way. At most ONE of `match`/`when` — both
+     * set is refused at build time. Omitting both keeps this an `always` entry,
+     * exactly as before.
+     */
+    readonly match?: SkillMatch;
+    /**
+     * The phrasings this rule CLAIMS — real messages a user would type that
+     * should start the turn here. Optional, additive, and **fed to nothing at
+     * run time**: the check-up reads them at build time and the routing never
+     * sees them, so a rule with examples routes byte-identically to the same
+     * rule without them.
+     *
+     * Things become PROVABLE once a phrase is declared, by RUNNING the compiled
+     * matchers rather than comparing them:
+     *
+     *   • `example-misses-own-rule` — this rule does not claim its own example.
+     *     An ERROR for a data `match` (it reads the user message and nothing
+     *     else, so the no-match holds under every context) or for a predicate
+     *     that THREW; a WARNING for an opaque `when` that returned false, which
+     *     may be gated on conversation state and claim the phrase on a later
+     *     turn (see the context note below);
+     *   • `example-shadowed-by-earlier` (error) — an EARLIER rule claims the
+     *     phrase first, so the turn starts somewhere your own example denies.
+     *     This is the one `rules-shadowed-by-order` must stay silent about when
+     *     the two rules use different regexes (intersection is not decided
+     *     anywhere in this library) — a witness phrase decides it instead;
+     *   • `example-shadowed-by-default` (warning) — the earlier claimant is an
+     *     UNCONDITIONAL entry. The declaration-order cold start stops at a
+     *     default; the turn-start cascade (a classifier, or `continuity:
+     *     'conversation'`) reads the conditional rules only and skips it — and
+     *     which one applies is decided at AGENT MOUNT, so the report names both
+     *     readings instead of asserting one against the router;
+     *   • `example-unclaimed` (warning) — NO rule claims the phrase, so the turn
+     *     falls through to the model tier. Absence, which no matcher-vs-matcher
+     *     analysis can catch.
+     *
+     * **The context they are judged on.** Every condition here runs on ONE
+     * context — iteration 1, the phrase as `userMessage`, empty `history`, no
+     * cursor — the context a turn's FIRST iteration hands a start rule. Turn 2 of
+     * a conversation also starts cold in cursor terms while CARRYING history, so
+     * a `when` gated on conversation state may claim the phrase on a turn this
+     * check cannot run. That is why its no-match is a warning, and why every
+     * message names the context it judged under.
+     *
+     * **Tier difference, and it matters.** In `match: { intent, examples }`
+     * (tier 2) the examples are SCORING material: the classifier reads them at
+     * RUN time to judge new messages. Here (tier 1) they are TEST material only.
+     * The author-facing meaning is the same — "the phrasings this rule claims" —
+     * the runtime role is not, and a rule may not carry both lists (refused at
+     * build, naming the difference).
+     *
+     * The boundary: these checks prove things about the phrases you declared and
+     * nothing about phrases nobody wrote. No warning is not proof of coverage —
+     * `graph.checkup().notes` says so on the report itself.
+     *
+     * @example
+     *   .entry(arrayInventory, {
+     *     match: /\b(array|volume|pool)\b/i,
+     *     examples: ["what's running on shpstrprncl101"],
+     *   })
+     */
+    readonly examples?: readonly string[];
+    readonly label?: string;
+}
+export type SkillEdgeKind = 'entry' | 'predicate' | 'on-tool-return' | 'on-tool-status' | 'guard' | 'model';
+export interface SkillEdge {
+    /** Source skill id, or `null` for the synthetic START (an entry edge). */
+    readonly from: string | null;
+    readonly to: string;
+    readonly kind: SkillEdgeKind;
+    readonly label?: string;
+    /** The DATA matcher on an entry edge, when the rule was declared as data
+     *  (`match:`). `toMermaid()` captions the edge with it when no explicit
+     *  `label` was given. */
+    readonly match?: SkillMatchData;
+    /** The DATA guard on a route edge, when one was declared (9.51.0) — rides
+     *  additively beside the kind exactly as `match` rides entry edges (a
+     *  guard composed with `onToolReturn`/`onToolStatus` keeps that kind; a
+     *  guard alone is kind `'guard'`). `toMermaid()` captions a guard-only
+     *  edge with it when no explicit `label` was given, and
+     *  `skill.graph_declared` carries it into every recording. */
+    readonly guard?: SkillGuardData;
+}
+/** A node in the drawn graph — a `predicate` diamond or a `skill` box. */
+export interface SkillNode {
+    readonly id: string;
+    readonly kind: 'predicate' | 'skill';
+    readonly label?: string;
+}
+/** One predicate on a skill's root→leaf decision path, and the branch taken. */
+export interface SkillRoutingStep {
+    /** The predicate's caption (the `decide(...)` label). */
+    readonly label: string;
+    /** Which side of the predicate leads to this skill. */
+    readonly branch: 'yes' | 'no';
+}
+/**
+ * The routing PROVENANCE stamped onto a compiled skill's `metadata.skillGraph`
+ * — *why* this skill is reachable. It rides through to the `context.evaluated`
+ * event when the skill activates, so commentary + the lens can narrate the real
+ * routing (not just "a skill activated"). Observability only; the trigger logic
+ * is unchanged.
+ */
+export interface SkillRouting {
+    /** How the skill is reached: a decision `tree` leaf, a flat `entry`, a
+     *  deterministic `route` edge, or `model` (read_skill-reachable). */
+    readonly via: 'tree' | 'entry' | 'route' | 'model';
+    /** Decision path (tree only): the predicates from root→leaf + branch taken.
+     *  For a skill used as MULTIPLE tree leaves this is the FIRST path; all
+     *  paths are in `paths`. */
+    readonly path?: readonly SkillRoutingStep[];
+    /** All decision paths reaching this skill (tree only; present when the same
+     *  skill is the leaf of more than one branch — the compiler merges repeated
+     *  leaves into ONE injection whose trigger ORs the path predicates). */
+    readonly paths?: ReadonlyArray<readonly SkillRoutingStep[]>;
+    /** Entry/route edge caption. */
+    readonly label?: string;
+    /** Source skill id (route only). */
+    readonly from?: string;
+    /** The compiled trigger kind for a route (`rule` / `on-tool-return`). */
+    readonly triggerKind?: string;
+    /** The DATA matcher that routes here (entry only, when declared as `match:`) —
+     *  serializable, so commentary/lens can say WHICH pattern chose the skill. */
+    readonly match?: SkillMatchData;
+    /** The DATA guard on the first deterministic edge in (route only, when
+     *  declared as `guard:`, 9.51.0) — serializable, the `match` twin. */
+    readonly guard?: SkillGuardData;
+}
+export interface EntryDecl {
+    readonly id: string;
+    /** The condition (compiled from `match` when the rule was declared as data). */
+    readonly when?: (ctx: InjectionContext) => boolean;
+    /** The serializable matcher behind `when`, when declared as data — what the
+     *  check-up compares, `toMermaid()` captions, and the provenance stores. */
+    readonly match?: SkillMatchData;
+    /** The same compilation's EVIDENCE extractor (9.28.0) — what text in the user
+     *  message made `when` true. Present only for the data forms; a `when`
+     *  predicate is opaque code and has none. Called ONLY on the rule that won. */
+    readonly witness?: (ctx: InjectionContext) => RouteWitness | undefined;
+    /** The phrasings this rule claims (validated at declaration). Build-time TEST
+     *  material — never read by the resolver, never on the wire. */
+    readonly examples?: readonly string[];
+    readonly label?: string;
+}
+export interface RouteDecl {
+    readonly fromId: string;
+    readonly toId: string;
+    readonly when?: SkillRouteOptions['when'];
+    readonly onToolReturn?: string | RegExp;
+    readonly onToolStatus?: SkillRouteOptions['onToolStatus'];
+    /** The compiled guard (9.51.0): predicate + data + evidence evaluator, one
+     *  compilation (see skillGuard.ts). */
+    readonly guard?: CompiledGuard;
+    readonly label?: string;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=graphRoutes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphRoutes.js","sourceRoot":"","sources":["../../../../src/injection-engine/skillGraph/graphRoutes.ts"],"names":[],"mappings":""}

package/dist/esm/injection-engine/skillGraph/passMemo.d.ts

@@ -0,0 +1,24 @@
+import type { InjectionContext } from '../types.js';
+import type { CursorMove } from './graphCursor.js';
+/**
+ * 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.
+ */
+export declare function memoizePerPass(resolveCursor: (ctx: InjectionContext) => CursorMove): (ctx: InjectionContext) => string | undefined;
+export declare function warnMatcherThrew(edge: string, err: unknown): void;

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

@@ -0,0 +1,37 @@
+import { devWarn } from '../devWarn.js';
+/**
+ * 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.
+ */
+export 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;
+    };
+}
+export 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)}`);
+}
+//# sourceMappingURL=passMemo.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"passMemo.js","sourceRoot":"","sources":["../../../../src/injection-engine/skillGraph/passMemo.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAC5B,aAAoD;IAEpD,MAAM,KAAK,GAAG,IAAI,OAAO,EAAmD,CAAC;IAC7E,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC,KAAK,CAAC;QAC1B,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACpC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,GAAY;IACzD,OAAO,CACL,8BAA8B,IAAI,0CAA0C;QAC1E,oCAAoC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACzF,CAAC;AACJ,CAAC"}

package/dist/esm/injection-engine/skillGraph/reachability.d.ts

@@ -0,0 +1,71 @@
+import type { EntryDecl, RouteDecl } from './graphRoutes.js';
+/**
+ * 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.
+ */
+export declare function makeReachableSkills(entries: readonly EntryDecl[], routes: readonly RouteDecl[]): (currentSkillId?: string) => readonly string[];
+/**
+ * WHICH CLASS OF TARGET a `read_skill` id is, from one cursor — the ONE owner
+ * of the question every gate, description and refusal used to answer for
+ * itself (9.86.0).
+ *
+ * ── THE LAW ───────────────────────────────────────────────────────────────
+ *
+ *   THE CURSOR IS A LEGITIMATE TARGET OF A READ (a stay), NEVER OF A MOVE.
+ *
+ * {@link makeReachableSkills} filters the cursor out of its own successor set,
+ * and that is correct for a MOVE: there is nowhere to move to. It was then read
+ * by five different consumers as "not available", which is a different claim and
+ * a false one — the cursor's body is in the prompt and its tools are on the wire.
+ * Each consumer that noticed wrote its own `requested === cursor` check; the two
+ * that did not (the tool-effects `propose-transition` judge and the `skill_read`
+ * permission gate) refused a stay as if it were a move.
+ *
+ * Four classes, in the order the gate must consider them:
+ *
+ *   • `'self'`        — the cursor itself. A stay: nothing activates, nothing
+ *                       moves, nothing is read that was not already sent.
+ *   • `'hop'`         — a declared successor of the cursor. The one class that
+ *                       MOVES the cursor.
+ *   • `'open'`        — a skill the graph wires no edge into (a `.selfExplain()`
+ *                       skill, a `.skill()` registered beside the graph). It
+ *                       activates and never moves the cursor.
+ *   • `'unreachable'` — everything else.
+ *
+ * `'hop'` beats `'open'` when an id is in both sets: the move is the stronger
+ * fact, and a caller that reports the id as merely open would lose it.
+ *
+ * Pure and total: no cursor (cold start) simply means nothing can be `'self'`.
+ */
+export type SkillTargetClass = 'self' | 'hop' | 'open' | 'unreachable';
+/**
+ * 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 declare function classifySkillTarget(args: {
+    /** Where the cursor stands. `undefined` = cold start (nothing is a stay). */
+    readonly cursor?: string;
+    /** The id the model asked for. */
+    readonly target: string;
+    /** Declared successors of the cursor — `reachableSkills(cursor)`. */
+    readonly hops?: readonly string[];
+    /** Skills the graph wires no edge into. */
+    readonly open?: readonly string[];
+}): SkillTargetClass;

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

@@ -0,0 +1,62 @@
+// 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/routing/readSkillRoute.ts · `applyReadSkillRoute`).
+// 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.
+ */
+export 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/helpers/mountedCursor.ts · atMountedCursor, the propose-transition judge (toolCalls/routing/effectsOperations.ts · "── A PROPOSAL TO THE
+// CURSOR'S OWN SKILL IS A STAY") and the read_skill gate (toolCalls/routing/readSkillRoute.ts · `applyReadSkillRoute`) ·
+// 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)];
+}
+//# sourceMappingURL=reachability.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reachability.js","sourceRoot":"","sources":["../../../../src/injection-engine/skillGraph/reachability.ts"],"names":[],"mappings":"AAEA,8HAA8H;AAC9H,+GAA+G;AAC/G,kHAAkH;AAClH,sGAAsG;AACtG,iEAAiE;AACjE,sFAAsF;AACtF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA6B,EAC7B,MAA4B;IAE5B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,MAAM,GAAG,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;QAC5F,OAAO,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC1E,CAAC,CAAC;AACJ,CAAC;AAqCD,4HAA4H;AAC5H,oHAAoH;AACpH,+JAA+J;AAC/J,yHAAyH;AACzH,qDAAqD;AACrD,iFAAiF;AACjF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,IASnC;IACC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAC5C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IAC7D,IAAI,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClD,IAAI,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IACnD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,oFAAoF;AACpF,SAAS,YAAY,CAAC,IAAY,EAAE,MAA4B;IAC9D,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,MAAM,CAAC,GAAsB;IACpC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3B,CAAC"}

package/dist/esm/injection-engine/skillGraph/routePredicates.d.ts

@@ -0,0 +1,36 @@
+import type { RouteDecl, SkillRouteOptions } from './graphRoutes.js';
+import type { Injection } from '../types.js';
+import type { ToolResultStatus } from '../../semantics/toolOutcome.js';
+/** 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). */
+export declare function isDeterministicRoute(r: RouteDecl): boolean;
+/** The declared status set, normalized to an array. */
+export declare function statusesOf(onToolStatus: NonNullable<SkillRouteOptions['onToolStatus']>): ReadonlyArray<string>;
+/** 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). */
+export declare function describe(skill: Injection): string;
+export declare function plural(n: number, one: string, many: string): string;
+/** 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. */
+export declare function routeMatches(r: RouteDecl, res: {
+    readonly toolName: string;
+    readonly result: string;
+    readonly status?: ToolResultStatus;
+}): boolean;
+/** 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. */
+export declare function edgePreconditionsPass(r: RouteDecl, res: {
+    readonly toolName: string;
+    readonly status?: ToolResultStatus;
+}): boolean;

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

@@ -0,0 +1,57 @@
+/** 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). */
+export function isDeterministicRoute(r) {
+    return (r.when !== undefined ||
+        r.onToolReturn !== undefined ||
+        r.onToolStatus !== undefined ||
+        r.guard !== undefined);
+}
+/** The declared status set, normalized to an array. */
+export function statusesOf(onToolStatus) {
+    return Array.isArray(onToolStatus) ? onToolStatus : [onToolStatus];
+}
+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). */
+export function describe(skill) {
+    return skill.description ?? '(no description)';
+}
+export function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/** 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. */
+export 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. */
+export 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;
+}
+//# sourceMappingURL=routePredicates.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routePredicates.js","sourceRoot":"","sources":["../../../../src/injection-engine/skillGraph/routePredicates.ts"],"names":[],"mappings":"AAIA;;;gFAGgF;AAChF,MAAM,UAAU,oBAAoB,CAAC,CAAY;IAC/C,OAAO,CACL,CAAC,CAAC,IAAI,KAAK,SAAS;QACpB,CAAC,CAAC,YAAY,KAAK,SAAS;QAC5B,CAAC,CAAC,YAAY,KAAK,SAAS;QAC5B,CAAC,CAAC,KAAK,KAAK,SAAS,CACtB,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,UAAU,CACxB,YAA4D;IAE5D,OAAO,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAsB,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,WAAW,CAAC,QAAyB;IAC5C,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACxF,CAAC;AAED;qFACqF;AACrF,MAAM,UAAU,QAAQ,CAAC,KAAgB;IACvC,OAAO,KAAK,CAAC,WAAW,IAAI,kBAAkB,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,CAAS,EAAE,GAAW,EAAE,IAAY;IACzD,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACxC,CAAC;AAED;;;;;;;kDAOkD;AAClD,MAAM,UAAU,YAAY,CAC1B,CAAY,EACZ,GAIC;IAED,IAAI,CAAC,qBAAqB,CAAC,CAAC,EAAE,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9E,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACtC,CAAC;AAED;;;;+EAI+E;AAC/E,MAAM,UAAU,qBAAqB,CACnC,CAAY,EACZ,GAGC;IAED,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACjF,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,CAAC,YAAY;QAAE,OAAO,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/esm/injection-engine/skillGraph/routingView.d.ts

@@ -0,0 +1,3 @@
+import type { EntryDecl, RouteDecl, SkillRouting } from './graphRoutes.js';
+/** Routing provenance for a flat entry/route skill (the v1 model). */
+export declare function routingFor(id: string, entries: readonly EntryDecl[], routes: readonly RouteDecl[]): SkillRouting;