agentfootprint 10.3.0 → 10.3.1

package/dist/injection-engine/skillNeverRoutes.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * skillNeverRoutes — the NEGATIVE routing row: a phrase this graph must claim
+ * NOWHERE.
+ *
+ * ## Why the negative form is the valuable one
+ *
+ * `skillExamples.ts` pins the positive assertion — this rule claims this
+ * phrasing — and it cannot state the opposite. Field use says the opposite is
+ * the one that catches the expensive failure. An UNDER-triggering skill costs a
+ * turn: the deterministic layer declines, the model tier picks, and the answer
+ * is usually still reachable. An OVER-triggering skill costs the whole answer:
+ * the wrong body enters the system prompt, the wrong tools enter the tools
+ * slot, and everything the model then says is shaped by a skill that had no
+ * business in the turn. One reviewer of a production graph had written his own
+ * harness for exactly this, outside the library, because the library could only
+ * express the cheap half.
+ *
+ * ## Where a negative row lives, and why it is NOT on a skill
+ *
+ * `examples` sits on the rule it is about. A negative row cannot: the phrase it
+ * describes belongs to NO skill, and hanging it on one would make three things
+ * wrong at once —
+ *
+ *   • it would read as that skill's business ("weather questions, filed under
+ *     billing") when the point is that it is nobody's;
+ *   • the assertion is satisfied only when EVERY rule declines, so a row read
+ *     as one rule's property would be checked against one rule and pass while
+ *     another rule swallowed the phrase;
+ *   • deleting the skill would delete the assertion — exactly when a graph is
+ *     re-partitioned, which is exactly when over-triggering is introduced.
+ *
+ * A negative row is a property of the PARTITION, so it is declared at the graph
+ * level (`.neverRoutes([...])` / `neverRoutes: [...]`) and judged against every
+ * rule in declaration order.
+ *
+ * ## What is asserted — precisely, and what it does NOT cover
+ *
+ * The claim this module proves is: **no declared start RULE claims the
+ * phrase.** It runs the compiled conditions on a cold-start context, exactly as
+ * `skillExamples.ts` does, and reports the rule that says yes.
+ *
+ * It does NOT prove "no routing at all occurs", and could not without becoming
+ * a different kind of check:
+ *
+ *   • an INTENT rule compiles to no sync predicate — a classifier judges it at
+ *     run time, with a scorer (and, for `llmClassifier`, a model call). Running
+ *     that would make the check async, non-deterministic, and in the LLM case
+ *     billable — `graph.checkupIntents()` is where scorer-dependent auditing
+ *     already lives;
+ *   • a scorer menu (`.entryBy()`) and `.entryByRead()` RANK descriptions;
+ *     there is no claim to run;
+ *   • the model tier can open any open skill by name with `read_skill`, at
+ *     which point no declaration is deciding anything.
+ *
+ * That statement ships on the report as {@link NEVER_ROUTES_BOUNDARY}, next to
+ * the problems, for the same reason the examples boundary does: a reader who
+ * meets a boundary only in prose docs meets a clean report first.
+ *
+ * A predicate that THROWS on the cold context counts as a no-match here, and is
+ * not reported — because routing itself treats a throw as a no-match, so the
+ * phrase really does not route through that rule. Its own rule's `examples`
+ * report the throw as an error (that is a defect in the rule, not in the
+ * partition).
+ *
+ * Composed into `graph.checkup()` by `skillGraph.ts`, like every other domain
+ * check, and reporting in the shared `GraphProblem` voice.
+ *
+ * Zone: PURE CORE. Pinned by
+ * `test/injection-engine/skill-graph-fence.test.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkNeverRoutes = exports.validateNeverRoutes = exports.neverRouteKey = exports.NEVER_ROUTES_BOUNDARY = void 0;
+const startRuleClaim_js_1 = require("./startRuleClaim.js");
+/**
+ * The statement the negative check makes about its own reach, carried on
+ * `GraphCheckup.notes` whenever a graph declared any negative row. Same voice
+ * as `EXAMPLES_BOUNDARY` (skillExamples.ts): silence here is evidence about the declared
+ * RULES, and about nothing downstream of them.
+ */
+exports.NEVER_ROUTES_BOUNDARY = 'A `neverRoutes` row proves that no DECLARED start rule claims the phrase. It does not ' +
+    'prove the turn routes nowhere: an intent rule is judged by a classifier at run time, a ' +
+    'scorer / `.entryByRead()` menu ranks descriptions, and the model can always open an open ' +
+    'skill by name with read_skill — none of those are run here.';
+const NOTHING = Object.freeze({
+    problems: Object.freeze([]),
+    notes: Object.freeze([]),
+});
+/** How two phrases are compared for "the same phrase": trimmed and
+ *  case-folded, the same normalization `duplicate-intent-example` uses — an
+ *  author who writes one row in two casings meant one row. Exported so the
+ *  builder's accumulated-rows set is keyed the SAME way the refusal is; two
+ *  spellings of one rule is how a duplicate slips through. */
+function neverRouteKey(phrase) {
+    return phrase.trim().toLowerCase();
+}
+exports.neverRouteKey = neverRouteKey;
+/**
+ * Validate a graph-level `neverRoutes` list at DECLARATION time, refusing every
+ * shape whose check-up answer could only mislead — each refusal naming the fix:
+ *
+ *   • not an array / an EMPTY array — nothing to assert, and a check-up that
+ *     passes in silence reads as coverage;
+ *   • a non-string or blank entry — there is no phrase to run a matcher on;
+ *   • a phrase already declared — a repeat asserts nothing the first one did
+ *     not, and reads as if two different phrasings were meant.
+ *
+ * A single string is accepted and read as a one-row list: `.neverRoutes('what
+ * is the weather')` is the commonest call, and making the author type brackets
+ * for it buys nothing.
+ *
+ * Returns a frozen copy of the ROWS THIS CALL ADDS, so the stored list cannot
+ * drift from the validated one.
+ */
+function validateNeverRoutes(phrases, where, alreadyDeclared) {
+    const list = typeof phrases === 'string' ? [phrases] : phrases;
+    if (!Array.isArray(list) || list.length === 0) {
+        throw new Error(`skillGraph: ${where} declares a \`neverRoutes\` list this library cannot honor. ` +
+            `\`neverRoutes\` is the phrasings this graph must claim NOWHERE — a non-empty array ` +
+            `of non-empty strings (or one string), e.g. neverRoutes: ['what is the weather']. ` +
+            `${Array.isArray(list)
+                ? 'An empty list asserts nothing, so the check-up would pass in silence and you ' +
+                    'would read that as proof no rule over-triggers. '
+                : ''}List at least one phrasing, or drop the field.`);
+    }
+    const bad = list.findIndex((p) => typeof p !== 'string' || p.trim().length === 0);
+    if (bad >= 0) {
+        throw new Error(`skillGraph: ${where} declares \`neverRoutes[${bad}]\` = ${JSON.stringify(list[bad])}, which is not a usable phrasing. Every row must be a NON-EMPTY string — the words a ` +
+            `user would really type and that no skill here should take. Fix that entry, or drop it.`);
+    }
+    const seen = new Set(alreadyDeclared);
+    for (const phrase of list) {
+        const key = neverRouteKey(phrase);
+        if (seen.has(key)) {
+            throw new Error(`skillGraph: ${where} declares the \`neverRoutes\` row ${JSON.stringify(phrase)} twice (compared trimmed and case-folded). One row already asserts it against every ` +
+                `rule in the graph; the repeat proves nothing further. Drop the duplicate.`);
+        }
+        seen.add(key);
+    }
+    return Object.freeze([...list]);
+}
+exports.validateNeverRoutes = validateNeverRoutes;
+/**
+ * Run the negative rows against the declared start rules. Pure, and
+ * byte-identically silent when the graph declared none (one length check and
+ * out).
+ *
+ * Unlike the positive examples, this needs NO `orderDecides` gate: the
+ * assertion is "nobody claims it", which every rule has to satisfy, so the
+ * order they are read in cannot change the answer. That is also why it is the
+ * one phrase check that stays meaningful under a classifier — tier 1 is still
+ * read first there, and a rule that claims the phrase still takes the turn
+ * before any scorer runs.
+ */
+function checkNeverRoutes(input) {
+    const { entries, phrases } = input;
+    if (phrases.length === 0)
+        return NOTHING;
+    const laws = (0, startRuleClaim_js_1.claimLaws)(entries);
+    const problems = [];
+    for (const phrase of phrases) {
+        // (a) CONTRADICTION — the author declared the same phrase as a POSITIVE
+        //     example on some rule. Reported first and alone: whichever way the
+        //     router lands, one of the two declarations is wrong, and no fact about
+        //     matchers helps until the author decides which. (Checked before the
+        //     matchers are run, because a rule can declare an example its own
+        //     matcher misses — the contradiction is in the declarations, not in the
+        //     routing.)
+        const contradicting = entries.find((e) => (e.examples ?? []).some((ex) => neverRouteKey(ex) === neverRouteKey(phrase)));
+        if (contradicting !== undefined) {
+            problems.push({
+                kind: 'error',
+                code: 'never-routes-contradicts-example',
+                message: `The graph declares that "${phrase}" must route NOWHERE, and the start rule for ` +
+                    `"${contradicting.id}" declares the SAME phrase in its own \`examples\` — the list ` +
+                    `of phrasings that rule CLAIMS. Two of your own declarations contradict each other ` +
+                    `about one phrase, so one of them is wrong wherever the router lands, and the ` +
+                    `check-up cannot tell which you meant. Decide: drop the \`neverRoutes\` row, or ` +
+                    `drop the phrase from "${contradicting.id}"'s \`examples\`.`,
+                skill: contradicting.id,
+                example: phrase,
+            });
+            continue;
+        }
+        // (b) CLAIMED BY A RULE — the failure this row exists to catch. An ERROR:
+        //     the author personally wrote that no skill should take this phrase, a
+        //     rule takes it, and both start laws agree it does (a CONDITIONAL
+        //     claimant is read by tier 1 AND by the cold walk). The turn would open
+        //     with that skill's body and tools on the wire.
+        const byRule = laws.underCascade(phrase);
+        if (byRule !== undefined) {
+            problems.push({
+                kind: 'error',
+                code: 'never-routes-claimed',
+                message: `The graph declares that "${phrase}" must route NOWHERE, but the start rule for ` +
+                    `"${byRule.entry.id}" claims it — ${(0, startRuleClaim_js_1.describeCondition)(byRule.entry)} matches the phrase, so a turn phrased that way STARTS on "${byRule.entry.id}", ` +
+                    `with that skill's body in the system prompt and that skill's tools on the wire ` +
+                    `shaping the whole answer. Narrow "${byRule.entry.id}"'s ${byRule.entry.match === undefined ? 'predicate' : 'matcher'} until it stops claiming this phrasing, or drop the row if "${byRule.entry.id}" ` +
+                    `really should take it. (Proved by running the declared conditions on the phrase on ` +
+                    `${startRuleClaim_js_1.COLD_CONTEXT_PHRASE} — no regex intersection was decided.)`,
+                skill: byRule.entry.id,
+                example: phrase,
+            });
+            continue;
+        }
+        // (c) CLAIMED BY A DEFAULT — no RULE claims it, but an unconditional entry
+        //     does under one of the two start laws. That is the one place the laws
+        //     differ (`skillExamples.ts` header), and which one applies is decided
+        //     at AGENT MOUNT, not here — so a WARNING naming both readings, never
+        //     an error the router might disagree with.
+        const byWalk = laws.underColdWalk(phrase);
+        if (byWalk === undefined)
+            continue;
+        problems.push({
+            kind: 'warning',
+            code: 'never-routes-by-default',
+            message: `The graph declares that "${phrase}" must route NOWHERE, and no start RULE claims it ` +
+                `— but the entry "${byWalk.entry.id}" ${(0, startRuleClaim_js_1.describeCondition)(byWalk.entry)}, so whether the phrase routes depends on how this graph is MOUNTED and the check-up ` +
+                `cannot decide it. Mounted the default way (continuity: 'turn'), the declaration-order ` +
+                `cold start stops at "${byWalk.entry.id}" and every message starts there, this one ` +
+                `included. Mounted with a classifier or with continuity: 'conversation', the turn-start ` +
+                `cascade's tier 1 reads the CONDITIONAL rules only — an unconditional entry is a ` +
+                `default, not a rule — so nothing claims the phrase and the turn falls onward. Give ` +
+                `"${byWalk.entry.id}" a \`match\`/\`when\` if it is meant to be a rule; if it is meant ` +
+                `to be the catch-all, a negative row can only ever be a statement about the RULES ` +
+                `above it (which is what this warning reports).`,
+            skill: byWalk.entry.id,
+            example: phrase,
+        });
+    }
+    return { problems, notes: [exports.NEVER_ROUTES_BOUNDARY] };
+}
+exports.checkNeverRoutes = checkNeverRoutes;
+//# sourceMappingURL=skillNeverRoutes.js.map

package/dist/injection-engine/skillNeverRoutes.js.map

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

package/dist/injection-engine/skillPartition.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * skillPartition — three ADVISORY signals about the shape of the partition
+ * itself: how a graph cut the world into skills.
+ *
+ * ## Why the partition is worth a check at all
+ *
+ * Everything else the check-up reports is a wiring fact — an edge to a skill
+ * that is not there, a rule that can never win. The partition is upstream of
+ * all of it, and it is the decision with the most leverage: a graph whose
+ * skills follow SYSTEMS rather than CAPABILITIES makes one ordinary question
+ * cross four skills, and the capability the user actually wanted ends up
+ * implemented outside the graph, by hand, where nothing can see it. Field use
+ * produced exactly that shape — nineteen skills, ONE declared edge, and tool
+ * names carrying the system that owns them (`influx_*`, `pmax_*`, `pstore_*`,
+ * `rvtools_*`) with the skills following the prefixes.
+ *
+ * The important part: all three of those are visible from NAMES AND STRUCTURE
+ * ALONE, at build time, with no run and no model. So the runtime can say them.
+ *
+ * ## Why every one of them is an advisory, and stays one
+ *
+ * Each signal has a legitimate design behind it:
+ *
+ *   • a skill really can be one system's capability (a weather skill wrapping a
+ *     weather API is not a mistake);
+ *   • a deliberately FLAT menu of independent skills really does declare almost
+ *     no edges — a scorer or the model picks, and there is nothing to hand off;
+ *   • a one-call capability really can be one tool with a short body.
+ *
+ * So none of them is ever an error, and none of them says "this is wrong". Each
+ * message states the SIGNAL AS A FACT the author can check against their own
+ * intent — "your 19 skills declare 1 route", "every tool in `powerstore` shares
+ * the prefix `pstore_`" — and then names the design each fact usually indicates
+ * and the design it is also consistent with. This library's check-up teaches;
+ * it does not grade.
+ *
+ * ## The thresholds, and why each one is where it is
+ *
+ * Named constants below, each with the argument beside it. They are chosen so a
+ * SMALL graph is silent (small graphs have no partition problem worth naming),
+ * so a trivially-true observation is never dressed up as a finding (one tool
+ * shares a prefix with itself), and so the commonest honest naming convention —
+ * a VERB first — never fires.
+ *
+ * Zone: PURE CORE. Pinned by
+ * `test/injection-engine/skill-graph-fence.test.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkPartition = void 0;
+const skillContract_js_1 = require("./skillContract.js");
+/**
+ * How many tools a skill needs before "they all share a prefix" is evidence of
+ * anything. ONE tool shares a prefix with itself — a trivial truth, and the
+ * skill it describes has its own signal below. TWO is two coin flips; a
+ * `get_order` / `get_invoice` pair is a naming habit, not a system boundary.
+ * At THREE the shared prefix is a decision somebody made about scope.
+ */
+const MIN_TOOLS_FOR_PREFIX = 3;
+/**
+ * First segments that are NOT a system — they are the verb half of the house
+ * naming convention (`get_price`, `issue_refund`, `lookup_order`). Verified
+ * against this repo's real tool names, where the ten commonest first segments
+ * are all verbs and outnumber every system prefix put together: without this
+ * list the check would fire on the best-named skills in the library, which is
+ * the fastest way to teach an author to ignore a check-up.
+ *
+ * The test is deliberately crude — a first segment either IS one of these words
+ * or it is not. A cleverer part-of-speech guess would be wrong more quietly.
+ */
+const VERB_PREFIXES = new Set([
+    'get',
+    'set',
+    'put',
+    'post',
+    'add',
+    'read',
+    'write',
+    'list',
+    'find',
+    'fetch',
+    'load',
+    'save',
+    'open',
+    'close',
+    'make',
+    'create',
+    'update',
+    'delete',
+    'remove',
+    'search',
+    'query',
+    'count',
+    'check',
+    'verify',
+    'validate',
+    'run',
+    'exec',
+    'execute',
+    'send',
+    'call',
+    'ask',
+    'show',
+    'lookup',
+    'issue',
+    'approve',
+    'deny',
+    'pay',
+    'process',
+    'resolve',
+    'respond',
+    'inspect',
+    'export',
+    'import',
+    'start',
+    'stop',
+    'cancel',
+    'compute',
+    'calculate',
+    'generate',
+    'summarize',
+    'transform',
+]);
+/**
+ * The floor under ALL THREE signals: below this many skills there is no
+ * partition to have an opinion about.
+ *
+ * This is the module's one structural decision, and it is what keeps the
+ * advisories quiet by construction. Every signal here is a statement about how
+ * a graph CUT THE WORLD; a two-skill graph with no edge is a menu, one skill
+ * wrapping one tool is a choice about that skill, and a pair of tools sharing a
+ * prefix is a naming habit. None of those become a partition question until
+ * there are enough skills for the cut itself to be the design — and the field
+ * case that motivated all three had nineteen. A check that fires on a
+ * three-skill graph teaches an author to stop reading the check-up, which costs
+ * more than the finding is worth.
+ */
+const MIN_SKILLS_FOR_PARTITION = 5;
+/**
+ * The ratio that counts as "almost no declared edges". A graph needs N−1 edges
+ * to connect N skills into one routed structure; this fires below ONE EDGE PER
+ * FOUR SKILLS, which is four times sparser than a bare chain — far enough from
+ * the boundary that a graph tripping it is not a matter of taste. (The field
+ * case: 19 skills, 1 route — a ratio of 0.05.)
+ */
+const MIN_ROUTES_PER_SKILL = 0.25;
+/**
+ * Word count below which a body carries no knowledge the tool schema does not
+ * already carry. One sentence of real guidance — when to reach for this, what
+ * to check first, what the failure looks like — does not fit in 25 words, so a
+ * body under it is either a restatement of the tool's own description or a
+ * placeholder. Counted in whitespace-separated words, the only measure that
+ * means the same thing in prose as in markdown.
+ */
+const THIN_BODY_WORDS = 25;
+/**
+ * Run the three partition signals. Pure, and cheap: one pass over the skills
+ * and two integers. Every problem it produces is a WARNING.
+ */
+function checkPartition(input) {
+    const skillCount = input.skills.length;
+    // The floor, applied once for all three signals — see
+    // MIN_SKILLS_FOR_PARTITION. A small graph reports byte-identically to the
+    // way it did before this module existed.
+    if (skillCount < MIN_SKILLS_FOR_PARTITION)
+        return [];
+    const problems = [];
+    for (const skill of input.skills) {
+        const tools = (0, skillContract_js_1.skillToolNames)(skill);
+        const id = idOf(skill);
+        // 1. tools-share-prefix — every tool in the skill comes from one system.
+        //    Computed from the first `_`-delimited segment, which is where a system
+        //    prefix lives when there is one (`pstore_list_volumes` → `pstore`), and
+        //    silent when that segment is a verb (see VERB_PREFIXES).
+        const prefix = sharedPrefix(tools);
+        if (tools.length >= MIN_TOOLS_FOR_PREFIX && prefix !== undefined) {
+            problems.push({
+                kind: 'warning',
+                code: 'tools-share-prefix',
+                message: `Every tool in "${id}" shares the prefix \`${prefix}_\` (${tools.join(', ')}). ` +
+                    `A skill whose whole tool set comes from one system is usually a wrapper around ` +
+                    `that SYSTEM rather than a CAPABILITY — and when the skills follow the systems, one ` +
+                    `ordinary question crosses several of them, so the thing the user actually asked ` +
+                    `for gets built outside the graph where nothing can route it. Worth checking: ` +
+                    `could a user's question be answered by "${id}" alone, or does answering it need ` +
+                    `two of these skills at once? If it needs two, the capability is the skill and ` +
+                    `\`${prefix}_\` is just where its tools happen to come from. If "${id}" really is ` +
+                    `one system's capability, this is exactly right and there is nothing to fix.`,
+                skill: id,
+            });
+        }
+        // 2. skill-wraps-one-tool — one tool, and a body that adds nothing to its
+        //    schema. The body is what the model reads to decide HOW to use the
+        //    tool; when it is this short there is no procedure in the graph, only
+        //    an endpoint with a name.
+        if (tools.length === 1 && tools[0] !== undefined) {
+            const words = wordCount(bodyOf(skill));
+            if (words < THIN_BODY_WORDS) {
+                problems.push({
+                    kind: 'warning',
+                    code: 'skill-wraps-one-tool',
+                    message: `Skill "${id}" carries one tool (\`${tools[0]}\`) and a ${words}-word body — ` +
+                        `under the ${THIN_BODY_WORDS} words it takes to say when to reach for it, what to ` +
+                        `check first, or what a bad answer looks like. A skill whose body adds nothing to ` +
+                        `the tool's own schema is an endpoint wrapper: the model already sees the tool, so ` +
+                        `the skill buys nothing but a name and an activation. Either put the knowledge in ` +
+                        `the body (that is the half a schema cannot carry), or drop the skill and register ` +
+                        `\`${tools[0]}\` on the agent directly. If it is genuinely a one-call capability ` +
+                        `with nothing to say about it, registering the tool is the smaller thing.`,
+                    skill: id,
+                });
+            }
+        }
+    }
+    // 3. few-declared-edges — many skills, almost no declared handoffs. A graph
+    //    level fact, reported once, and never for a tree (a tree declares its
+    //    routing as the tree).
+    if (!input.isTree && input.routeCount < skillCount * MIN_ROUTES_PER_SKILL) {
+        problems.push({
+            kind: 'warning',
+            code: 'few-declared-edges',
+            message: `This graph declares ${plural(skillCount, 'skill', 'skills')}, ${plural(input.entryCount, 'entry', 'entries')} and ${plural(input.routeCount, 'route', 'routes')} — fewer than one route per four ` +
+                `skills, where connecting ${skillCount} skills into one routed structure takes at ` +
+                `least ${skillCount - 1}. When skills hand off to each other in PROSE ("then use the ` +
+                `capacity skill"), the handoff is invisible: nothing draws it, \`checkup()\` cannot ` +
+                `check it, the reachability walk cannot see it, and \`read_skill\`'s gate cannot ` +
+                `offer it — the model is left to infer the sequence every turn. Declaring the ones ` +
+                `you already rely on (\`.route(a, b, { onToolReturn })\`) turns each into something ` +
+                `the graph can route and a reader can see. If this is a deliberately flat menu of ` +
+                `independent skills — a scorer or the model picks one and it answers alone — then ` +
+                `there is nothing to hand off and this is the shape you meant.`,
+        });
+    }
+    return problems;
+}
+exports.checkPartition = checkPartition;
+/** The id, read structurally like every other check in this family. */
+function idOf(skill) {
+    return skill.id;
+}
+/** The skill's BODY — the prose that lands in the system slot when it
+ *  activates. Same accessor `skillContract.ts` reads. */
+function bodyOf(skill) {
+    return skill.inject?.systemPrompt ?? '';
+}
+function wordCount(text) {
+    const trimmed = text.trim();
+    return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+}
+/**
+ * The first `_`-delimited segment shared by EVERY name, or undefined when there
+ * is none, when a name carries no `_` at all, or when the shared segment is a
+ * verb (a convention, not a system — see {@link VERB_PREFIXES}).
+ *
+ * Case-folded, because a tool registry that mixes `PSTORE_get` and
+ * `pstore_list` is still one system.
+ */
+function sharedPrefix(names) {
+    if (names.length === 0)
+        return undefined;
+    let shared;
+    for (const name of names) {
+        const separator = name.indexOf('_');
+        if (separator <= 0)
+            return undefined; // no prefix segment to speak of
+        const segment = name.slice(0, separator).toLowerCase();
+        if (shared === undefined)
+            shared = segment;
+        else if (shared !== segment)
+            return undefined;
+    }
+    return shared !== undefined && !VERB_PREFIXES.has(shared) ? shared : undefined;
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+//# sourceMappingURL=skillPartition.js.map

package/dist/injection-engine/skillPartition.js.map

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