agentfootprint 9.14.0 → 9.16.0

package/dist/lib/injection-engine/evaluator.js

@@ -14,15 +14,21 @@
  *   • `rule`               → predicate runs against `ctx`. Errors are
  *                            caught + reported in `skipped`; never
  *                            propagate. Run never crashes.
- *   • `on-tool-return`     → active when `ctx.lastToolResult.toolName`
- *                            matches `trigger.toolName` (string equal
- *                            or regex test).
+ *   • `on-tool-return`     → active when ANY tool result of the previous
+ *                            iteration's batch (`toolResultsOf(ctx)` —
+ *                            `ctx.toolResults`, falling back to the
+ *                            singular `ctx.lastToolResult`) has a
+ *                            `toolName` matching `trigger.toolName`
+ *                            (string equal or regex test). Before 9.16.0
+ *                            only the LAST call of a parallel batch was
+ *                            consulted — earlier calls were dropped.
  *   • `llm-activated`      → active when the Injection's `id` is in
  *                            `ctx.activatedInjectionIds` (the LLM
  *                            previously called `viaToolName(<id>)`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluateInjections = void 0;
+const types_js_1 = require("./types.js");
 function evaluateInjections(injections, ctx) {
     const active = [];
     const skipped = [];
@@ -48,10 +54,10 @@ function evaluateInjections(injections, ctx) {
                 break;
             }
             case 'on-tool-return': {
-                const toolName = ctx.lastToolResult?.toolName;
-                if (!toolName)
-                    break;
-                const matches = typeof t.toolName === 'string' ? t.toolName === toolName : t.toolName.test(toolName);
+                // The WHOLE batch, in call order (9.16.0) — a trigger fires when any
+                // call of the previous iteration returned from the named tool, not
+                // only when that tool happened to be last in a parallel batch.
+                const matches = (0, types_js_1.toolResultsOf)(ctx).some((r) => typeof t.toolName === 'string' ? t.toolName === r.toolName : t.toolName.test(r.toolName));
                 if (matches)
                     active.push(inj);
                 break;

package/dist/lib/injection-engine/evaluator.js.map

@@ -1 +1 @@
-{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../../src/lib/injection-engine/evaluator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAIH,SAAgB,kBAAkB,CAChC,UAAgC,EAChC,GAAqB;IAErB,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,OAAO,GAIR,EAAE,CAAC;IAER,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC;QACtB,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;YACf,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACjB,MAAM;YACR,CAAC;YACD,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,IAAI,CAAC;oBACH,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;wBAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC1C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,IAAI,CAAC;wBACX,EAAE,EAAE,GAAG,CAAC,EAAE;wBACV,MAAM,EAAE,iBAAiB;wBACzB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBACxD,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;YACR,CAAC;YACD,KAAK,gBAAgB,CAAC,CAAC,CAAC;gBACtB,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAC;gBAC9C,IAAI,CAAC,QAAQ;oBAAE,MAAM;gBACrB,MAAM,OAAO,GACX,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACvF,IAAI,OAAO;oBAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC9B,MAAM;YACR,CAAC;YACD,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,IAAI,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;oBAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACjE,MAAM;YACR,CAAC;YACD,OAAO,CAAC,CAAC,CAAC;gBACR,yDAAyD;gBACzD,+DAA+D;gBAC/D,MAAM,WAAW,GAAU,CAAC,CAAC;gBAC7B,OAAO,CAAC,IAAI,CAAC;oBACX,EAAE,EAAE,GAAG,CAAC,EAAE;oBACV,MAAM,EAAE,sBAAsB;oBAC9B,KAAK,EAAE,sBAAsB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE;iBAC3D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AAxDD,gDAwDC"}
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../../src/lib/injection-engine/evaluator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAEH,yCAA2C;AAG3C,SAAgB,kBAAkB,CAChC,UAAgC,EAChC,GAAqB;IAErB,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,OAAO,GAIR,EAAE,CAAC;IAER,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC;QACtB,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;YACf,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACjB,MAAM;YACR,CAAC;YACD,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,IAAI,CAAC;oBACH,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;wBAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC1C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,IAAI,CAAC;wBACX,EAAE,EAAE,GAAG,CAAC,EAAE;wBACV,MAAM,EAAE,iBAAiB;wBACzB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;qBACxD,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM;YACR,CAAC;YACD,KAAK,gBAAgB,CAAC,CAAC,CAAC;gBACtB,qEAAqE;gBACrE,mEAAmE;gBACnE,+DAA+D;gBAC/D,MAAM,OAAO,GAAG,IAAA,wBAAa,EAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAC5C,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CACzF,CAAC;gBACF,IAAI,OAAO;oBAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC9B,MAAM;YACR,CAAC;YACD,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,IAAI,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;oBAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACjE,MAAM;YACR,CAAC;YACD,OAAO,CAAC,CAAC,CAAC;gBACR,yDAAyD;gBACzD,+DAA+D;gBAC/D,MAAM,WAAW,GAAU,CAAC,CAAC;gBAC7B,OAAO,CAAC,IAAI,CAAC;oBACX,EAAE,EAAE,GAAG,CAAC,EAAE;oBACV,MAAM,EAAE,sBAAsB;oBAC9B,KAAK,EAAE,sBAAsB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE;iBAC3D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AA1DD,gDA0DC"}

package/dist/lib/injection-engine/factories/defineSkill.js

@@ -11,6 +11,16 @@
  * and callable from iteration 1 unless the Skill sets
  * `autoActivate: 'currentSkill'` — see that option.
  *
+ * **Activation lifetime: the rest of the turn.** Once the model picks a
+ * skill with `read_skill`, the activation lasts until the turn ends — every
+ * later iteration of that `run()` keeps the body active, and there is no
+ * mid-turn deactivation (nothing removes an id from
+ * `ctx.activatedInjectionIds`; the next `run()` starts clean). This is
+ * deliberate: the cache layer's skill history and the context ledger both
+ * lean on the cumulative property. A skill that should stop applying
+ * mid-turn is a `rule` trigger or a `skillGraph()` route, not a read_skill
+ * pick.
+ *
  * Produces an `Injection` with:
  *   - flavor: `'skill'`
  *   - trigger: `{ kind: 'llm-activated', viaToolName: 'read_skill' }`
@@ -34,6 +44,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineSkill = exports.resolveSurfaceMode = void 0;
+const footprintjs_1 = require("footprintjs");
 const applyCachePolicy_js_1 = require("../../../cache/applyCachePolicy.js");
 /**
  * Resolve `surfaceMode: 'auto'` to a concrete mode based on provider
@@ -89,6 +100,25 @@ function assertNoViaToolName(where, opts) {
         `skills already share ONE activation tool and the model picks WHICH skill by id. If you ` +
         `need the skill gated on something else, use a \`rule\` trigger or a skillGraph() edge.`);
 }
+/** One warn per process for the deprecated `refreshPolicy` — the field is
+ *  accepted (additive-only law) but a declaration that does nothing should
+ *  say so ONCE, not on every skill of a 40-skill catalog. */
+let warnedRefreshPolicyDeprecated = false;
+/**
+ * The dev-mode deprecation warn for `refreshPolicy` (9.16.0). Named, not
+ * inlined, so the once-flag and the message live beside each other.
+ */
+function warnRefreshPolicyDeprecated(skillId) {
+    if (warnedRefreshPolicyDeprecated || !(0, footprintjs_1.isDevMode)())
+        return;
+    warnedRefreshPolicyDeprecated = true;
+    // eslint-disable-next-line no-console
+    console.warn(`agentfootprint defineSkill('${skillId}'): \`refreshPolicy\` is DEPRECATED-pending-steps — ` +
+        'it is stored on skill.metadata and nothing in the engine reads it, so NO re-injection ' +
+        'happens. It is superseded by a planned steps-as-data feature and will not be wired up. ' +
+        "To re-surface a body in a long run today, use surfaceMode: 'both' (read_skill returns " +
+        'the body afresh) or deliver it yourself. This warning fires once per process.');
+}
 function defineSkill(opts) {
     if (!opts.id || opts.id.trim().length === 0) {
         throw new Error('defineSkill: `id` is required and must be non-empty.');
@@ -100,6 +130,8 @@ function defineSkill(opts) {
         throw new Error(`defineSkill(${opts.id}): \`body\` is required.`);
     }
     assertNoViaToolName(`defineSkill(${opts.id})`, opts);
+    if (opts.refreshPolicy)
+        warnRefreshPolicyDeprecated(opts.id);
     return Object.freeze({
         id: opts.id,
         description: opts.description,

package/dist/lib/injection-engine/factories/defineSkill.js.map

@@ -1 +1 @@
-{"version":3,"file":"defineSkill.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"defineSkill.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;;;AAEH,6CAAwC;AAGxC,4EAAwE;AA8IxE;;;;;;;;;;;GAWG;AACH,SAAgB,kBAAkB,CAAC,QAAgB,EAAE,KAAc;IACjE,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK,WAAW,EAAE,CAAC;QACtB,2CAA2C;QAC3C,4CAA4C;QAC5C,+EAA+E;QAC/E,gFAAgF;QAChF,IAAI,KAAK,IAAI,iEAAiE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3F,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAbD,gDAaC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,mBAAmB,CAAC,KAAa,EAAE,IAAY;IACtD,MAAM,MAAM,GAAI,IAA2C,CAAC,WAAW,CAAC;IACxE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IACjC,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,iFAAiF;QACvF,WAAW,MAAM,CAAC,MAAM,CAAC,gEAAgE;QACzF,uFAAuF;QACvF,yFAAyF;QACzF,yFAAyF;QACzF,wFAAwF,CAC3F,CAAC;AACJ,CAAC;AAED;;6DAE6D;AAC7D,IAAI,6BAA6B,GAAG,KAAK,CAAC;AAE1C;;;GAGG;AACH,SAAS,2BAA2B,CAAC,OAAe;IAClD,IAAI,6BAA6B,IAAI,CAAC,IAAA,uBAAS,GAAE;QAAE,OAAO;IAC1D,6BAA6B,GAAG,IAAI,CAAC;IACrC,sCAAsC;IACtC,OAAO,CAAC,IAAI,CACV,+BAA+B,OAAO,sDAAsD;QAC1F,wFAAwF;QACxF,yFAAyF;QACzF,wFAAwF;QACxF,+EAA+E,CAClF,CAAC;AACJ,CAAC;AAED,SAAgB,WAAW,CAAC,IAAwB;IAClD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,CAAC,EAAE,0EAA0E,CACjG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,CAAC,EAAE,0BAA0B,CAAC,CAAC;IACpE,CAAC;IACD,mBAAmB,CAAC,eAAe,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,aAAa;QAAE,2BAA2B,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,OAAgB;QACxB,OAAO,EAAE;YACP,IAAI,EAAE,eAAwB;YAC9B,WAAW,EAAE,YAAY;SAC1B;QACD,MAAM,EAAE;YACN,YAAY,EAAE,IAAI,CAAC,IAAI;YACvB,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;SAClE;QACD,iEAAiE;QACjE,sEAAsE;QACtE,uEAAuE;QACvE,sEAAsE;QACtE,iBAAiB;QACjB,EAAE;QACF,qDAAqD;QACrD,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;YACtB,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,MAAM;YACvC,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC;YAChE,GAAG,CAAC,IAAI,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;YAC7D,KAAK,EAAE,IAAA,wCAAkB,EAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;SAC/C,CAAC;KACH,CAAyB,CAAC;AAC7B,CAAC;AAxCD,kCAwCC"}

package/dist/lib/injection-engine/index.js

@@ -7,10 +7,15 @@
  * factories. See `README.md` in this folder for the full concept.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.skillToolNames = exports.checkSkillContracts = exports.checkSkillContract = exports.rankEntries = exports.embeddingScorer = exports.keywordScorer = exports.SKILL_GRAPH_METADATA_KEY = exports.formatCheckup = exports.decideSkill = exports.skillGraph = exports.defineInjection = exports.defineFact = exports.defineSteering = exports.buildReadSkillTool = exports.buildListSkillsTool = exports.skillsFromDir = exports.SkillRegistry = exports.resolveSurfaceMode = exports.defineSkill = exports.READS_ENTRY_SCORES_METADATA_KEY = exports.defineRelevanceHint = exports.defineInstruction = exports.buildInjectionEngineSubflow = exports.evaluateInjections = exports.projectActiveInjection = void 0;
+exports.skillToolNames = exports.checkSkillContracts = exports.checkSkillContract = exports.rankEntries = exports.embeddingScorer = exports.keywordScorer = exports.SKILL_GRAPH_DEFERRED_CONTRACT_KEY = exports.SKILL_GRAPH_METADATA_KEY = exports.formatCheckup = exports.decideSkill = exports.skillGraph = exports.defineInjection = exports.defineFact = exports.defineSteering = exports.buildReadSkillTool = exports.buildListSkillsTool = exports.skillsFromDir = exports.SkillRegistry = exports.resolveSurfaceMode = exports.defineSkill = exports.READS_ENTRY_SCORES_METADATA_KEY = exports.defineRelevanceHint = exports.defineInstruction = exports.buildInjectionEngineSubflow = exports.evaluateInjections = exports.toolResultsOf = exports.projectActiveInjection = void 0;
 // POJO projection — used by slot subflows + advanced consumers
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "projectActiveInjection", { enumerable: true, get: function () { return types_js_1.projectActiveInjection; } });
+// The iteration's tool-result batch with the singular fallback applied
+// (9.16.0) — the one reader `rule` predicates should use to see every call of
+// a parallel batch, not only the last (`ctx.toolResults ?? [ctx.lastToolResult]`).
+var types_js_2 = require("./types.js");
+Object.defineProperty(exports, "toolResultsOf", { enumerable: true, get: function () { return types_js_2.toolResultsOf; } });
 // Engine
 var evaluator_js_1 = require("./evaluator.js");
 Object.defineProperty(exports, "evaluateInjections", { enumerable: true, get: function () { return evaluator_js_1.evaluateInjections; } });
@@ -59,6 +64,12 @@ Object.defineProperty(exports, "decideSkill", { enumerable: true, get: function
 // is already the door to it.
 Object.defineProperty(exports, "formatCheckup", { enumerable: true, get: function () { return skillGraph_js_1.formatCheckup; } });
 Object.defineProperty(exports, "SKILL_GRAPH_METADATA_KEY", { enumerable: true, get: function () { return skillGraph_js_1.SKILL_GRAPH_METADATA_KEY; } });
+// The graph's note that its body-contract checks wait for Agent build (present
+// only when built without `knownTools`) — see SkillGraph.deferredBodyContract.
+// The note rides the graph AND each compiled skill's metadata (under
+// SKILL_GRAPH_DEFERRED_CONTRACT_KEY), so Agent build honors it whichever way
+// the skills arrive — `.skillGraph(graph)` or `.skills({ list: () => graph.skills })`.
+Object.defineProperty(exports, "SKILL_GRAPH_DEFERRED_CONTRACT_KEY", { enumerable: true, get: function () { return skillGraph_js_1.SKILL_GRAPH_DEFERRED_CONTRACT_KEY; } });
 var entryScorer_js_1 = require("./entryScorer.js");
 Object.defineProperty(exports, "keywordScorer", { enumerable: true, get: function () { return entryScorer_js_1.keywordScorer; } });
 Object.defineProperty(exports, "embeddingScorer", { enumerable: true, get: function () { return entryScorer_js_1.embeddingScorer; } });

package/dist/lib/injection-engine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAYH,+DAA+D;AAC/D,uCAAoD;AAA3C,kHAAA,sBAAsB,OAAA;AAE/B,SAAS;AACT,+CAAoD;AAA3C,kHAAA,kBAAkB,OAAA;AAC3B,mFAG0C;AAFxC,6IAAA,2BAA2B,OAAA;AAI7B,gFAAgF;AAChF,yEAAoG;AAA3F,yHAAA,iBAAiB,OAAA;AAC1B,6EAI4C;AAH1C,6HAAA,mBAAmB,OAAA;AACnB,yIAAA,+BAA+B,OAAA;AAIjC,6DAOoC;AANlC,6GAAA,WAAW,OAAA;AACX,oHAAA,kBAAkB,OAAA;AAOpB,uDAA8E;AAArE,iHAAA,aAAa,OAAA;AAEtB,8EAA8E;AAC9E,+EAA+E;AAC/E,6DAA6D;AAC7D,uDAA8E;AAArE,iHAAA,aAAa,OAAA;AAEtB,wEAAwE;AACxE,sEAAsE;AACtE,iEAAiE;AACjE,+BAA+B;AAC/B,iDAA8F;AAArF,oHAAA,mBAAmB,OAAA;AAAE,mHAAA,kBAAkB,OAAA;AAEhD,mEAA2F;AAAlF,mHAAA,cAAc,OAAA;AAEvB,2DAA+E;AAAtE,2GAAA,UAAU,OAAA;AAEnB,6EAA6E;AAC7E,0EAA0E;AAC1E,qDAAqD;AACrD,qEAIwC;AAHtC,qHAAA,eAAe,OAAA;AAKjB,4EAA4E;AAC5E,8EAA8E;AAC9E,iDAqCyB;AApCvB,2GAAA,UAAU,OAAA;AACV,4GAAA,WAAW,OAAA;AACX,mFAAmF;AACnF,qFAAqF;AACrF,uFAAuF;AACvF,6BAA6B;AAC7B,8GAAA,aAAa,OAAA;AACb,yHAAA,wBAAwB,OAAA;AA8B1B,mDAO0B;AANxB,+GAAA,aAAa,OAAA;AACb,iHAAA,eAAe,OAAA;AACf,6GAAA,WAAW,OAAA;AAKb,uDAK4B;AAJ1B,sHAAA,kBAAkB,OAAA;AAClB,uHAAA,mBAAmB,OAAA;AACnB,kHAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAYH,+DAA+D;AAC/D,uCAAoD;AAA3C,kHAAA,sBAAsB,OAAA;AAE/B,uEAAuE;AACvE,8EAA8E;AAC9E,mFAAmF;AACnF,uCAA2C;AAAlC,yGAAA,aAAa,OAAA;AAEtB,SAAS;AACT,+CAAoD;AAA3C,kHAAA,kBAAkB,OAAA;AAC3B,mFAG0C;AAFxC,6IAAA,2BAA2B,OAAA;AAI7B,gFAAgF;AAChF,yEAAoG;AAA3F,yHAAA,iBAAiB,OAAA;AAC1B,6EAI4C;AAH1C,6HAAA,mBAAmB,OAAA;AACnB,yIAAA,+BAA+B,OAAA;AAIjC,6DAOoC;AANlC,6GAAA,WAAW,OAAA;AACX,oHAAA,kBAAkB,OAAA;AAOpB,uDAA8E;AAArE,iHAAA,aAAa,OAAA;AAEtB,8EAA8E;AAC9E,+EAA+E;AAC/E,6DAA6D;AAC7D,uDAA8E;AAArE,iHAAA,aAAa,OAAA;AAEtB,wEAAwE;AACxE,sEAAsE;AACtE,iEAAiE;AACjE,+BAA+B;AAC/B,iDAA8F;AAArF,oHAAA,mBAAmB,OAAA;AAAE,mHAAA,kBAAkB,OAAA;AAEhD,mEAA2F;AAAlF,mHAAA,cAAc,OAAA;AAEvB,2DAA+E;AAAtE,2GAAA,UAAU,OAAA;AAEnB,6EAA6E;AAC7E,0EAA0E;AAC1E,qDAAqD;AACrD,qEAIwC;AAHtC,qHAAA,eAAe,OAAA;AAKjB,4EAA4E;AAC5E,8EAA8E;AAC9E,iDAsDyB;AArDvB,2GAAA,UAAU,OAAA;AACV,4GAAA,WAAW,OAAA;AACX,mFAAmF;AACnF,qFAAqF;AACrF,uFAAuF;AACvF,6BAA6B;AAC7B,8GAAA,aAAa,OAAA;AACb,yHAAA,wBAAwB,OAAA;AAiCxB,+EAA+E;AAC/E,+EAA+E;AAC/E,qEAAqE;AACrE,6EAA6E;AAC7E,uFAAuF;AACvF,kIAAA,iCAAiC,OAAA;AASnC,mDAO0B;AANxB,+GAAA,aAAa,OAAA;AACb,iHAAA,eAAe,OAAA;AACf,6GAAA,WAAW,OAAA;AAKb,uDAK4B;AAJ1B,sHAAA,kBAAkB,OAAA;AAClB,uHAAA,mBAAmB,OAAA;AACnB,kHAAA,cAAc,OAAA"}

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

@@ -59,11 +59,13 @@
  * per-hop cause, so a model pick was recorded under a declared edge's label).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.skillGraph = exports.SKILL_GRAPH_METADATA_KEY = exports.decideSkill = exports.formatCheckup = void 0;
+exports.skillGraph = exports.SKILL_GRAPH_DEFERRED_CONTRACT_KEY = exports.SKILL_GRAPH_METADATA_KEY = exports.decideSkill = exports.formatCheckup = void 0;
 const footprintjs_1 = require("footprintjs");
+const types_js_1 = require("./types.js");
 const entryScorer_js_1 = require("./entryScorer.js");
 const skillGraphCheckup_js_1 = require("./skillGraphCheckup.js");
 const skillContract_js_1 = require("./skillContract.js");
+const skillMatch_js_1 = require("./skillMatch.js");
 var skillGraphCheckup_js_2 = require("./skillGraphCheckup.js");
 Object.defineProperty(exports, "formatCheckup", { enumerable: true, get: function () { return skillGraphCheckup_js_2.formatCheckup; } });
 /** Build a decision node. Leaves are skills (an `Injection`); internal nodes are
@@ -78,6 +80,17 @@ function isDecisionNode(n) {
 }
 /** The metadata key carrying a skill's routing provenance. */
 exports.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).
+ */
+exports.SKILL_GRAPH_DEFERRED_CONTRACT_KEY = 'skillGraphDeferredBodyContract';
 /** 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, '_');
@@ -133,7 +146,25 @@ function skillGraph(config) {
     const builder = {
         entry(skill, opts) {
             const id = remember(skill);
-            entries.push({ id, when: opts?.when, label: opts?.label });
+            // Exactly one condition per entry: `match` (data) or `when` (code). Both set
+            // is a contradiction — which one starts the turn? — refused rather than
+            // silently ANDed or ORed. (Neither set stays the `always` entry it has
+            // always been; the rules form additionally refuses "neither", because a
+            // rule exists to be conditional — see the config translation below.)
+            if (opts?.when !== undefined && opts?.match !== undefined) {
+                throw new Error(`skillGraph: entry "${id}" sets both \`match\` and \`when\` — an entry takes ` +
+                    `exactly one condition. Use \`match\` (a RegExp or { keywords: [...] } over the ` +
+                    `user message — comparable and drawable) OR \`when\` (a predicate over the ` +
+                    `iteration context). To combine a pattern with extra logic, fold the pattern ` +
+                    `into your \`when\` predicate.`);
+            }
+            const compiled = opts?.match !== undefined ? (0, skillMatch_js_1.compileMatch)(opts.match, `entry "${id}"`) : undefined;
+            entries.push({
+                id,
+                when: compiled ? compiled.predicate : opts?.when,
+                ...(compiled && { match: compiled.data }),
+                label: opts?.label,
+            });
             return builder;
         },
         route(from, to, opts) {
@@ -182,6 +213,14 @@ function skillGraph(config) {
                 throw new Error('skillGraph: .entryBy()/.entryByRelevance() is for flat entry/route graphs; a ' +
                     '.tree() already routes by predicate (the scorer would be ignored).');
             }
+            // One dial, one home: a tree declares tool scoping on `.tree(root, { scopeTools })`
+            // (object form: the tree arm's own field). Accepting it here too would let the two
+            // homes disagree, and only one of them would win — silently.
+            if (treeRoot && opts.scopeTools !== undefined) {
+                throw new Error('skillGraph: `scopeTools` on build() is the FLAT arm\'s dial. This graph is a ' +
+                    '.tree(), which declares tool scoping on .tree(root, { scopeTools }) (object ' +
+                    'form: the tree arm\'s own `scopeTools` field) — set it there instead.');
+            }
             // A tree and the flat entry/route wiring are two ways to declare the same
             // thing, and only ONE of them compiles: the tree branch below never reads
             // `entries` or `routes`. Until 8.4.0 that was silent — the tree won and every
@@ -212,7 +251,16 @@ function skillGraph(config) {
             const checkup = (options = {}) => {
                 const wiring = (0, skillGraphCheckup_js_1.checkupGraph)({
                     skillIds: new Set(skillsById.keys()),
-                    entries: entries.map((e) => ({ id: e.id, conditional: e.when !== undefined })),
+                    // `conditional` counts a data `match` exactly like a `when` (it compiled
+                    // to one), so a rule-router built from matchers is never read as a
+                    // fan-out. The match DATA rides along so the pairwise rule checks
+                    // (`overlapping-rules` / `rules-shadowed-by-order`) have something they
+                    // can honestly compare.
+                    entries: entries.map((e) => ({
+                        id: e.id,
+                        conditional: e.when !== undefined,
+                        ...(e.match && { match: e.match }),
+                    })),
                     routes: routes.map((r) => ({
                         fromId: r.fromId,
                         toId: r.toId,
@@ -316,17 +364,39 @@ function skillGraph(config) {
                 }
                 if (entryScorer)
                     scoreEntries = makeScoreEntries(entries, skillsById, entryScorer);
+                // `scopeTools: true` (flat) — the WIRED skills, i.e. everything an entry or a
+                // route mentions. Stamped exactly as the tree stamps its leaves: a graph-level
+                // DEFAULT (`existingAuto ?? …`), never an override of a skill's own declaration.
+                // A listed-but-unwired skill stays additive — the graph does not route it, so
+                // the graph does not scope it (it remains an OPEN, read_skill-reachable skill).
+                // Default `false` keeps today's bytes; 10.0.0 flips the default.
+                const scopedIds = opts.scopeTools === true
+                    ? new Set([...entries.map((e) => e.id), ...routes.flatMap((r) => [r.fromId, r.toId])])
+                    : undefined;
                 for (const [id, skill] of skillsById) {
                     const trigger = deriveTrigger(id, skill, entries, routes, nextSkillForTriggers, entryScorer !== undefined || llmReadEntry);
                     const routing = routingFor(id, entries, routes);
+                    const existingAuto = skill.metadata
+                        ?.autoActivate;
+                    const autoActivate = existingAuto ?? (scopedIds?.has(id) ? 'currentSkill' : undefined);
                     skills.push({
                         ...skill,
                         ...(trigger && { trigger }),
-                        metadata: { ...skill.metadata, [exports.SKILL_GRAPH_METADATA_KEY]: routing },
+                        metadata: {
+                            ...skill.metadata,
+                            [exports.SKILL_GRAPH_METADATA_KEY]: routing,
+                            ...(autoActivate && { autoActivate }),
+                        },
                     });
                     nodes.push({ id, kind: 'skill', label: id });
                 }
-                edges.push(...entries.map((e) => ({ from: null, to: e.id, kind: 'entry', label: e.label })), ...routes.map((r) => ({
+                edges.push(...entries.map((e) => ({
+                    from: null,
+                    to: e.id,
+                    kind: 'entry',
+                    label: e.label,
+                    ...(e.match && { match: e.match }),
+                })), ...routes.map((r) => ({
                     from: r.fromId,
                     to: r.toId,
                     kind: r.onToolReturn ? 'on-tool-return' : r.when ? 'predicate' : 'model',
@@ -342,20 +412,53 @@ function skillGraph(config) {
             // surfaced as a run that entered no skill. An explicit `check: 'warn'` still
             // never throws, so the opt-down survives with its name intact.
             const check = opts.check ?? 'throw';
+            // Without `knownTools`, the body-contract checks (`body-foreign-tool` /
+            // `body-unknown-tool`) cannot tell a typo from a baseline tool the agent
+            // registers later — the graph builds before `.tool()` runs. So this PASS
+            // defers them (reports nothing it cannot prove) and leaves a
+            // `deferredBodyContract` note in TWO places that say the same thing: on the
+            // graph, and on each compiled skill's metadata — because skills reach an
+            // agent through more than one door (`.skillGraph(graph)` sees the graph;
+            // `.skills({ list: () => graph.skills })` sees only the skills). Agent build
+            // collects the note from its final injection list and runs the checks exactly
+            // once against the full tool registry, whichever door was used. With
+            // `knownTools` given, the author supplied the full picture and the checks run
+            // right here, as always — no note anywhere, and the agent never re-runs them
+            // (one problem, one report). `graph.checkup()` is untouched either way: the
+            // explicit lint call always runs every check over what it can see.
+            const deferBodyContract = check !== 'off' && opts.knownTools === undefined;
+            const deferredNote = deferBodyContract
+                ? { mode: check }
+                : undefined;
             if (check !== 'off') {
                 const result = checkup({ ...(opts.knownTools && { knownTools: opts.knownTools }) });
-                if (check === 'throw' && !result.ok) {
-                    throw new Error(`skillGraph: build-time check-up failed:\n${(0, skillGraphCheckup_js_1.formatCheckup)(result)}`);
+                const reported = deferBodyContract
+                    ? {
+                        ok: result.ok, // body-contract problems are warnings — they never decide `ok`
+                        problems: result.problems.filter((p) => p.code !== 'body-foreign-tool' && p.code !== 'body-unknown-tool'),
+                    }
+                    : result;
+                if (check === 'throw' && !reported.ok) {
+                    throw new Error(`skillGraph: build-time check-up failed:\n${(0, skillGraphCheckup_js_1.formatCheckup)(reported)}`);
                 }
-                if (result.problems.length > 0 && (0, footprintjs_1.isDevMode)()) {
+                if (reported.problems.length > 0 && (0, footprintjs_1.isDevMode)()) {
                     // eslint-disable-next-line no-console
-                    console.warn(`skillGraph: build-time check-up found problems:\n${(0, skillGraphCheckup_js_1.formatCheckup)(result)}`);
+                    console.warn(`skillGraph: build-time check-up found problems:\n${(0, skillGraphCheckup_js_1.formatCheckup)(reported)}`);
                 }
             }
             return {
-                skills,
+                // Deferring? The note rides each skill too (dedup at agent build is by id,
+                // so the double stamp can never double-report). No deferral → the exact
+                // same objects as always: zero cost when unused.
+                skills: deferredNote
+                    ? skills.map((s) => ({
+                        ...s,
+                        metadata: { ...s.metadata, [exports.SKILL_GRAPH_DEFERRED_CONTRACT_KEY]: deferredNote },
+                    }))
+                    : skills,
                 edges,
                 nodes,
+                ...(deferredNote && { deferredBodyContract: deferredNote }),
                 toMermaid: () => renderMermaid(nodes, edges),
                 // `nextSkill` is the `.to` PROJECTION of the one resolver, not a second
                 // implementation — the two cannot answer differently.
@@ -412,9 +515,51 @@ function skillGraph(config) {
                 builder.entry(resolve(start));
             else if ('use' in start)
                 builder.entry(resolve(start.use));
-            else if ('rules' in start)
-                for (const r of start.rules)
-                    builder.entry(resolve(r.use), { when: r.when });
+            else if ('rules' in start) {
+                // (a) rule-id-exists — validate EVERY rule's target before compiling any of
+                // them, so the refusal lists every bad id at once (not just the first) and
+                // names what IS allowed. An unknown id cannot compile into an entry at all,
+                // so this refuses under every `check` mode — a rule silently dropped under
+                // `check: 'warn'` would be the accepted-and-silently-wrong build.
+                const missing = start.rules
+                    .map((r, i) => ({ use: r.use, i }))
+                    .filter(({ use }) => !skillsById.has(use));
+                if (missing.length > 0) {
+                    const known = [...skillsById.keys()].map((k) => `"${k}"`).join(', ');
+                    const problems = missing.map(({ use, i }) => ({
+                        kind: 'error',
+                        code: 'rule-id-exists',
+                        message: `start.rules[${i}] routes to skill "${use}", which is not in skills[]. ` +
+                            `Known skill ids: ${known || '(none)'}. Fix the rule's \`use\`, or add the ` +
+                            `skill to skills[].`,
+                        skill: use,
+                    }));
+                    throw new Error(`skillGraph: build-time check-up failed:\n${(0, skillGraphCheckup_js_1.formatCheckup)({ ok: false, problems })}`);
+                }
+                for (const [i, r] of start.rules.entries()) {
+                    // Exactly one of `match`/`when` per rule. The type already says so
+                    // (`SkillStartRule` is a union with `never` on the other arm); this is the
+                    // runtime half, for JavaScript callers and configs assembled through `any`.
+                    // "Neither" is refused too — a rule exists to be conditional; the
+                    // unconditional start is `start: 'id'` / `{ use }`, and saying so beats
+                    // compiling a rule that would swallow every turn.
+                    const use = r.use; // read before the narrowing checks — TS collapses the
+                    // union to `never` inside the refusal branch (the type says it can't happen;
+                    // this is the runtime half for callers the compiler never saw).
+                    const both = r.when !== undefined && r.match !== undefined;
+                    const neither = r.when === undefined && r.match === undefined;
+                    if (both || neither) {
+                        throw new Error(`skillGraph: start.rules[${i}] (use: "${use}") ${both ? 'sets both `match` and `when`' : 'sets neither `match` nor `when`'} — a rule takes exactly one condition. Say when it applies with \`match\` ` +
+                            `(a RegExp or { keywords: [...] } tested against the user message) or ` +
+                            `\`when\` (a predicate over the iteration context). For an unconditional ` +
+                            `start, use \`start: '${use}'\` instead of a rule.`);
+                    }
+                    builder.entry(resolve(r.use), {
+                        ...(r.when && { when: r.when }),
+                        ...(r.match !== undefined && { match: r.match }),
+                    });
+                }
+            }
             else {
                 for (const id of start.entries)
                     builder.entry(resolve(id));
@@ -437,6 +582,11 @@ function skillGraph(config) {
         return builder.build({
             check: config.check ?? 'throw',
             ...(config.knownTools && { knownTools: config.knownTools }),
+            // The FLAT arm's tool-scoping dial rides through to the one compiler below.
+            // (The tree arm's `scopeTools` was already handed to `.tree()` above — passing
+            // it here too would trip build()'s one-dial-one-home refusal.)
+            ...(config.tree === undefined &&
+                config.scopeTools !== undefined && { scopeTools: config.scopeTools }),
         });
     }
     return builder;
@@ -493,16 +643,15 @@ function makeScoreEntries(entries, skillsById, scorer) {
         return scorer.score({ userMessage: ctx.userMessage, candidates }, signal);
     };
 }
-/** Does a single route edge fire for this context? Reads the previous
- *  iteration's tool result; `onToolReturn` matches the tool NAME, `when` runs
- *  the predicate over the result. No match (and no tool result) → false. */
-function routeMatches(r, ctx) {
-    const ltr = ctx.lastToolResult;
-    if (!ltr)
-        return false;
+/** Does a single route edge fire for ONE tool result of the batch?
+ *  `onToolReturn` matches the tool NAME, `when` runs the predicate over the
+ *  result (same `{ toolName, result }` shape it has always received). 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 (r.onToolReturn)
-        return toolMatcher(r.onToolReturn)(ltr.toolName);
-    return r.when ? r.when(ltr) : false;
+        return toolMatcher(r.onToolReturn)(res.toolName);
+    return r.when ? r.when(res) : false;
 }
 /**
  * The cursor resolver (the keystone). Pure + deterministic. Given the iteration
@@ -512,7 +661,10 @@ function routeMatches(r, ctx) {
  *     (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
- *     `lastToolResult`, first by declaration order → its target (the transition);
+ *     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).
  *
@@ -576,22 +728,59 @@ function makeResolveCursor(entries, routes, llmReadEntry = false) {
             }
             return { by: 'none' };
         }
-        // D1 — transition: first from-gated deterministic edge that fires. Wins over
-        // a same-turn model pick (the author's declared edge is never overridden) —
-        // INCLUDING when both name the same target, which is why the cause is decided
-        // here and not inferred downstream from the destination.
-        for (const r of routes) {
-            if (r.fromId !== cur)
-                continue;
-            if (!r.when && !r.onToolReturn)
-                continue; // model edges don't auto-fire
-            try {
-                if (routeMatches(r, ctx))
-                    return { ...from, to: r.toId, by: 'route' };
-            }
-            catch (err) {
-                warnMatcherThrew(`route ${r.fromId}→${r.toId}`, err);
+        // 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;
+        for (const res of (0, types_js_1.toolResultsOf)(ctx)) {
+            let target;
+            for (const r of routes) {
+                if (r.fromId !== cur)
+                    continue;
+                if (!r.when && !r.onToolReturn)
+                    continue; // model edges don't auto-fire
+                try {
+                    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;
+            else if (target !== winner.target)
+                (losers ??= []).push(outcome);
+        }
+        if (winner !== undefined) {
+            return {
+                ...from,
+                to: winner.target,
+                by: 'route',
+                ...(losers !== undefined && { conflict: { winner, losers } }),
+            };
         }
         // 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
@@ -911,7 +1100,11 @@ function attachExactlyOneLeafMonitor(skills) {
 function routingFor(id, entries, routes) {
     const entry = entries.find((e) => e.id === id);
     if (entry)
-        return { via: 'entry', ...(entry.label && { label: entry.label }) };
+        return {
+            via: 'entry',
+            ...(entry.label && { label: entry.label }),
+            ...(entry.match && { match: entry.match }),
+        };
     const incoming = routes.filter((r) => r.toId === id && (r.when || r.onToolReturn));
     const first = incoming[0];
     if (first) {
@@ -936,7 +1129,10 @@ function renderMermaid(nodes, edges) {
     for (const e of edges) {
         const from = e.from === null ? '__start__' : ref(e.from);
         const arrow = e.kind === 'model' ? '-.->' : '-->'; // model edges dashed
-        const label = e.label ? `|${e.label}|` : '';
+        // An explicit label wins unchanged; a data matcher captions its entry edge
+        // (that is half the point of declaring the rule as data — it can be drawn).
+        const caption = e.label ?? (e.match ? (0, skillMatch_js_1.mermaidMatchCaption)(e.match) : undefined);
+        const label = caption ? `|${caption}|` : '';
         lines.push(`  ${from} ${arrow}${label} ${ref(e.to)}`);
     }
     return lines.join('\n');