agentfootprint 10.3.0 → 10.3.1

package/dist/types/injection-engine/skillsFromDir.d.ts

@@ -0,0 +1,238 @@
+/**
+ * skillsFromDir — load Skills that were AUTHORED AS FILES.
+ *
+ * The just-in-time half of skills already ships: `defineSkill` produces an
+ * Injection whose `description` is all the model sees until it calls
+ * `read_skill(<id>)`, at which point the body enters the context. What did not
+ * ship was the other half — a way to keep those bodies where prose belongs, in
+ * files, next to the code they describe, reviewable in a diff.
+ *
+ * This is that loader, and nothing more. It reads a directory of `SKILL.md`
+ * files and hands each one to `defineSkill`. The progressive disclosure, the
+ * activation tool, the slot routing — all unchanged, all upstream of here.
+ *
+ *   skills/
+ *     billing/SKILL.md
+ *     refunds/SKILL.md
+ *
+ *   ---
+ *   name: billing
+ *   description: Use for refunds, charges and billing questions.
+ *   ---
+ *   When handling billing: confirm identity first, then …
+ *
+ *   const skills = await skillsFromDir('./skills');
+ *   const agent = Agent.create({ provider, model }).skills({ list: () => skills }).build();
+ *
+ * The frontmatter is the disclosure stub (`name` + `description` — what the
+ * model reads when deciding), and everything after the closing fence is the
+ * body (what it reads after deciding). That is the same file convention Claude
+ * Code made familiar, so a skill folder is portable between the two.
+ *
+ * ── What a SKILL.md can carry (9.36.0: the whole runbook) ────────────────────
+ * A runbook you already have on disk is three things — what to do (prose),
+ * what to do it WITH (tools), and in what order (steps). This door used to
+ * carry the first and drop the other two, so the one thing the library exists
+ * to say ("extract the workflow you already have") arrived two-thirds empty.
+ * All three now cross:
+ *
+ *   ---
+ *   name: billing
+ *   description: Use for refunds, charges and billing questions.
+ *   tools: lookup_order, issue_refund
+ *   steps:
+ *     - lookup_order: look up the order before touching money
+ *     - issue_refund: refund only what the lookup found
+ *   onSkip: hold
+ *   ---
+ *   When handling billing: confirm identity first, then …
+ *
+ *   const skills = await skillsFromDir('./skills', {
+ *     tools: [lookupOrder, issueRefund],   // the real Tools, from YOUR code
+ *   });
+ *
+ * The remaining limits, and why each one is a decision rather than an
+ * oversight:
+ *
+ *   - **the file names a tool; it never defines one.** A tool is code with an
+ *     `execute`, and a markdown file has none. `tools:` is a list of NAMES,
+ *     resolved against the `tools` registry the CALLER passes — so the file
+ *     can only ever pick from capabilities you already handed in, and reading a
+ *     directory can never introduce one. See "why this is not a code-execution
+ *     vector" below.
+ *   - **a name the registry does not carry is refused BY NAME at load** —
+ *     never a skill that quietly loads without the tool it asked for, because
+ *     that skill runs, sounds confident, and cannot do the job.
+ *   - **no per-step `produces` / `consumes`** — the artifact vocabularies
+ *     (9.25.0) are a build-time contract between skills, not runbook prose;
+ *     declare them with `defineSkill` where the rest of the agent is declared.
+ *   - **no `autoActivate`** — a directory does not decide the agent's tool
+ *     posture. Say it once on the agent with `.toolsFromActiveSkill()`
+ *     (9.36.0), which scopes every skill's tools to that skill's activation.
+ *     Without it, a loaded skill's tools are on the wire from iteration 1, the
+ *     same as any hand-written `defineSkill({ tools })`.
+ *   - **no per-file `surfaceMode` or `cache`** — `surfaceMode`
+ *     is settable for the WHOLE directory via `opts`, all of them or none; the
+ *     others take `defineSkill`'s defaults.
+ *   - unknown frontmatter keys are still IGNORED, not rejected, so a file
+ *     carrying another tool's metadata still loads here. `name`,
+ *     `description`, `tools`, `steps`, `onSkip` and `routes` are the KNOWN
+ *     keys — a file that used one of those six for something else is the one
+ *     case a release can change, and it changes it loudly.
+ *
+ * ── The routing, and the door that reads it (9.43.0) ─────────────────────────
+ * A runbook says what to do, what to do it with, in what order — and where the
+ * work goes NEXT. That last part is the graph, and until now it had to be
+ * hand-wired in code even when the files said it plainly. `routes:` closes it:
+ *
+ *   ---
+ *   name: billing
+ *   tools: lookup_order, issue_refund
+ *   routes:
+ *     - escalation: on issue_refund status=denied
+ *     - receipts: on issue_refund
+ *   ---
+ *
+ *   const runbook = await runbookFromDir('./skills', { tools: [...] });
+ *   const graph = skillGraph({ ...runbook, start: 'billing' });
+ *
+ * TWO DOORS, one truth: `skillsFromDir` returns skills and REFUSES a file that
+ * declares `routes:` (a door that dropped the routing would hand back a graph
+ * you believed was declared on disk); {@link runbookFromDir} returns
+ * `{ skills, steps }`. Same law as `tools:` — the file PICKS (a route names a
+ * skill id this directory declares; an unknown id is refused at load, by name,
+ * listing what is available), it never DEFINES. A guard is one of the two DATA
+ * conditions a route already has (`on <tool_name>`, `status=<outcome>`), and
+ * nothing else: a `when` predicate is CODE, no file can carry code, and that
+ * conditional stays in your source. See `skillsFromDirRoutes.ts` for the whole
+ * grammar and every refusal.
+ *
+ * A worked example feeding this into a graph:
+ * `examples/features/47-skills-from-dir-graph.ts`.
+ *
+ * ── Why authorship is decided here, at load time ─────────────────────────────
+ * A Skill body is *instructions to a model*. Where it came from is therefore a
+ * security property, not a convenience: content fetched at run time from
+ * somewhere else is content someone else can change after you reviewed it.
+ * This loader accepts a local directory and nothing else — a URL is refused BY
+ * NAME rather than fetched — because "these files are mine" is a claim you can
+ * only make about a path on your own disk at build time. Each file is read
+ * ONCE, here; a later edit does not reach a run already in flight.
+ *
+ * ── Why carrying tools is not a code-execution vector ───────────────────────
+ * Nothing in a SKILL.md is evaluated, imported, required or resolved as a
+ * path. `tools:` is a list of strings, and the only thing a string can do here
+ * is MATCH — against `tool.schema.name` in a registry the caller constructed in
+ * their own source, from their own imports. A hostile file can therefore ask
+ * for a tool you already gave the agent (and it would have to guess the name);
+ * it can never name a module, widen the agent's capabilities, or cause one byte
+ * of new code to run. The set of things this directory can do is a SUBSET of
+ * what the calling file already decided to do, which is the same property the
+ * local-path rule above buys for bodies.
+ *
+ * Node-only. `node:fs/promises` and `node:path` are imported lazily inside the
+ * call, the same gating `tool-lint/cli.ts` uses: this module is reachable
+ * from the `agentfootprint/context` barrel, and a TOP-LEVEL node:fs
+ * import detonates a browser bundle at module-eval even when nothing calls it.
+ */
+import type { Injection } from './types.js';
+import type { Tool } from '../tools/tools.js';
+import { type SurfaceMode } from './factories/defineSkill.js';
+import type { SkillGraphStep } from './skillGraph.js';
+export interface SkillsFromDirOptions {
+    /**
+     * Where a loaded skill's body lands once activated. Defaults to
+     * `defineSkill`'s own default, `'auto'`. See {@link SurfaceMode}.
+     */
+    readonly surfaceMode?: SurfaceMode;
+    /**
+     * The tools a file may NAME (9.36.0) — the resolution registry for every
+     * `tools:` declaration in the directory, matched by `tool.schema.name`.
+     *
+     * This is the half a markdown file cannot supply. The file picks; you decide
+     * what there is to pick FROM, in your own source, from your own imports. A
+     * declared name that is not in here is refused at load, naming the file, the
+     * name, and what this registry does carry.
+     *
+     * Pass every tool the directory might use; a tool nothing names is simply
+     * unused (no skill gets it, and no error). Omit the option entirely on a
+     * prose-only directory — a file that declares `tools:` with no registry
+     * passed is refused rather than loaded without them.
+     */
+    readonly tools?: readonly Tool[];
+}
+/**
+ * A whole runbook directory, read as the two things a graph is made of
+ * (9.43.0): the skills, and the edges between them.
+ *
+ * Spreads straight into the graph — the field names are the graph's own, so
+ * nothing has to be translated at the call site:
+ *
+ *   const runbook = await runbookFromDir('./skills', { tools });
+ *   const graph = skillGraph({ ...runbook, start: 'triage' });
+ */
+export interface DirRunbook {
+    /** Every `SKILL.md` under the directory, as Skill Injections — byte-identical
+     *  to what `skillsFromDir` returns for the same directory. */
+    readonly skills: readonly Injection[];
+    /**
+     * The declared edges, ready for `skillGraph({ steps })`. In skill-name order,
+     * then file order, so a graph built from a directory is stable.
+     *
+     * NAME NOTE, because two different things are spelled `steps` in this
+     * library: a file's own `steps:` key is that SKILL's tool sequence (which
+     * rides on the skill, unchanged); these `steps` are the GRAPH's edges, read
+     * from each file's `routes:` key. They never meet.
+     */
+    readonly steps: readonly SkillGraphStep[];
+}
+/**
+ * Load every `SKILL.md` under `dir` as a Skill Injection.
+ *
+ * Two layouts are accepted, and they can be mixed:
+ *   - `dir/<anything>/SKILL.md` — one folder per skill (the portable layout,
+ *     and the one to prefer: the folder can hold the skill's other assets).
+ *   - `dir/SKILL.md` — the directory IS one skill.
+ *
+ * The returned array is sorted by skill name, so a chart built from it is
+ * stable regardless of the order the filesystem happened to hand back.
+ *
+ * @param dir - A local filesystem path. A URL (or any `scheme://` string, or a
+ *   UNC network path) is refused by name — see the module header for why.
+ * @param opts - Applied uniformly to every loaded skill.
+ *
+ * @throws when `dir` is not a local path, does not exist, is not a directory,
+ *   or contains no `SKILL.md` at all; when a file's frontmatter is malformed
+ *   (the message names the file); when two files claim the same skill name
+ *   (the message names both); or when a file names a tool the `tools` registry
+ *   does not carry, or sequences a tool the file itself did not declare.
+ */
+export declare function skillsFromDir(dir: string, opts?: SkillsFromDirOptions): Promise<readonly Injection[]>;
+/**
+ * Load a directory as a whole RUNBOOK (9.43.0) — the skills AND the edges
+ * between them.
+ *
+ * `skillsFromDir` reads what one skill is; this reads what the skills are TO
+ * EACH OTHER, from each file's `routes:` key, and hands back both halves ready
+ * for `skillGraph({ ...runbook, start })`. Everything else is identical: same
+ * layouts, same frontmatter, same tool registry, same refusals.
+ *
+ * The routing a file may carry is deliberately small, and the boundary is a
+ * security property rather than a limitation — see `skillsFromDirRoutes.ts`:
+ * a route NAMES a skill this directory declares (an unknown id is refused at
+ * load, by name, listing what is available — never a half-graph), and a guard
+ * is one of the two DATA conditions a route already has (`on <tool>`,
+ * `status=<outcome>`). A `when` predicate is code, so no file can express one;
+ * that conditional stays in your source, where `skillGraph({ steps })` takes it.
+ *
+ * @param dir - A local filesystem path. Same rule as `skillsFromDir`.
+ * @param opts - Applied uniformly to every loaded skill.
+ *
+ * @throws everything `skillsFromDir` throws, plus: a route to an id no
+ *   `SKILL.md` in the directory declares (the message lists what is
+ *   available), a guard the grammar cannot express (the message quotes the
+ *   whole grammar), a guard naming a tool the file itself does not declare,
+ *   and a file routing to the same skill twice.
+ */
+export declare function runbookFromDir(dir: string, opts?: SkillsFromDirOptions): Promise<DirRunbook>;
+//# sourceMappingURL=skillsFromDir.d.ts.map

package/dist/types/injection-engine/skillsFromDir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillsFromDir.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/skillsFromDir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAoBtD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;CAClC;AA2BD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB;kEAC8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAoB/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,UAAU,CAAC,CASrB"}

package/dist/types/injection-engine/skillsFromDirRoutes.d.ts

@@ -0,0 +1,106 @@
+/**
+ * skillsFromDirRoutes — the `routes:` half of the on-disk runbook grammar.
+ *
+ * ## What a file may say about routing, and why it is this little
+ *
+ * `skillsFromDir` reads prose, `tools:` and `steps:` — everything about ONE
+ * skill — and stopped exactly where the value was supposed to start: the
+ * routing. A directory of runbooks still had to be hand-wired into a graph in
+ * code, which is the work the graph exists to remove.
+ *
+ * This module adds the missing key under the SAME security law the tools list
+ * follows: **the file PICKS, it never DEFINES.**
+ *
+ *   ---
+ *   name: billing
+ *   tools: lookup_order, issue_refund
+ *   routes:
+ *     - escalation: on issue_refund status=denied
+ *     - receipts: on issue_refund
+ *     - audit
+ *   ---
+ *
+ * A route names a SKILL ID and, optionally, a guard. Both halves are picks:
+ *
+ *   • the id is resolved against the skills THIS DIRECTORY declares — an id
+ *     nothing here declares is refused at load, by name, listing what is
+ *     available. Never a half-graph: one bad id fails the whole load, because
+ *     a graph missing one edge routes silently wrong, which is worse than a
+ *     graph that refuses to exist;
+ *   • the guard is one of the two DATA conditions a route already has
+ *     (`onToolReturn`, `onToolStatus`), and the tool it names must be one of
+ *     this file's own `tools:` — the same law `steps:` follows, for the same
+ *     reason (an edge out of this skill fires on this skill's work).
+ *
+ * Nothing is evaluated, imported or resolved as a path. The strings can only
+ * MATCH — against ids the loader already read off disk and against a closed
+ * status vocabulary.
+ *
+ * ## What a file CANNOT express, said plainly
+ *
+ * A `when:` predicate is CODE. There is no honest way for a markdown file to
+ * carry it: reading one would mean evaluating a string, which is the one thing
+ * this loader exists never to do. So the grammar has no `when` and no
+ * expression language of any kind — a conditional a file cannot express is a
+ * conditional that stays in code:
+ *
+ *   skillGraph({ skills, steps: [{ from: 'billing', to: 'escalation',
+ *                                  when: r => JSON.parse(r.result).tier > 2 }] });
+ *
+ * Anything that is not one of the three forms is refused with the whole grammar
+ * quoted, rather than half-understood by a parser inventing a mini-language.
+ *
+ * Zone: HOST (it belongs to the file loader). Pure over strings all the same —
+ * it reads no filesystem; `skillsFromDir.ts` hands it the parsed lines.
+ */
+import type { SkillGraphStep } from './skillGraph.js';
+import { type ToolResultStatus } from '../semantics/toolOutcome.js';
+/**
+ * One frontmatter list item, structurally — `skillsFromDir`'s module-private
+ * `ListItem` satisfies it unchanged, so the two never import each other.
+ */
+export interface RouteItem {
+    /** Text before the first `:` — the target skill id. */
+    readonly key: string;
+    /** Text after the first `:` — the guard. Undefined when the item has none. */
+    readonly value?: string;
+    /** 1-based line number in the file. Every refusal quotes it. */
+    readonly line: number;
+}
+/** One route as the FILE declared it: a target id and a parsed guard. The id is
+ *  still unresolved here — a file cannot know what the rest of the directory
+ *  carries, so that refusal waits for {@link toGraphSteps}. */
+export interface DeclaredRoute {
+    readonly to: string;
+    readonly onToolReturn?: string;
+    readonly onToolStatus?: readonly ToolResultStatus[];
+    readonly line: number;
+}
+/**
+ * Read one file's `routes:` items into declared routes, refusing every shape
+ * the grammar does not carry. Pure; every message names the file and the line,
+ * because "malformed routes" over a directory of forty runbooks has told the
+ * author nothing.
+ *
+ * @param items      the `routes:` block-list items, in file order.
+ * @param file       the path, quoted by every refusal.
+ * @param toolNames  this file's own `tools:` — a guard may only name one of
+ *                   them (undefined when the file declared no tools at all).
+ */
+export declare function readDeclaredRoutes(items: readonly RouteItem[], file: string, toolNames: readonly string[] | undefined): readonly DeclaredRoute[];
+/**
+ * Resolve one file's declared routes into graph steps, refusing an id no
+ * SKILL.md in the directory declares.
+ *
+ * The refusal lists what IS available and fails the whole load. A route to a
+ * name nothing declares is the one mistake that cannot be reported later: the
+ * loader would return a skill set the graph then wires with a missing edge, and
+ * a graph that silently does not route is exactly the failure the check-up
+ * exists to prevent. Half a graph is not a smaller version of the graph.
+ *
+ * @param from   the id of the skill whose file declared these routes.
+ * @param file   that skill's path, quoted by the refusal.
+ * @param known  every skill id the directory declared.
+ */
+export declare function toGraphSteps(from: string, routes: readonly DeclaredRoute[], file: string, known: ReadonlySet<string>): readonly SkillGraphStep[];
+//# sourceMappingURL=skillsFromDirRoutes.d.ts.map

package/dist/types/injection-engine/skillsFromDirRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillsFromDirRoutes.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/skillsFromDirRoutes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE1F;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;+DAE+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACvC,SAAS,aAAa,EAAE,CA4E1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACzB,SAAS,cAAc,EAAE,CAmB3B"}

package/dist/types/injection-engine/softmax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"softmax.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/softmax.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,SAAI,GAAG,MAAM,EAAE,CAW5E"}

package/dist/types/injection-engine/startRuleClaim.d.ts

@@ -0,0 +1,94 @@
+/**
+ * startRuleClaim — WHO CLAIMS A PHRASE. The one place that answers it.
+ *
+ * Two check-ups ask the same question of a graph's start rules and want
+ * opposite answers:
+ *
+ *   • `skillExamples.ts` declares a phrase and asserts THIS rule claims it;
+ *   • `skillNeverRoutes.ts` declares a phrase and asserts NO rule claims it.
+ *
+ * The question underneath is identical — run the compiled conditions over one
+ * concrete phrase, on the context a turn's first iteration really hands a start
+ * rule, and see who says yes. Two copies of that would drift the moment one of
+ * them learned something about the router the other did not, and the two would
+ * then disagree about the same graph. So it lives here, once, and the modules
+ * that report keep only their own sentences.
+ *
+ * Nothing here decides SEVERITY or writes a message — that is the reporting
+ * module's job, because the same "no" means different things to a positive and
+ * a negative assertion. This module only runs predicates and names conditions.
+ *
+ * Zone: PURE CORE (no engine, no loop). Pinned by
+ * `test/injection-engine/skill-graph-fence.test.ts`.
+ */
+import type { InjectionContext } from './types.js';
+import { type SkillMatchData } from './skillMatch.js';
+/**
+ * The slice of an entry declaration a claim question reads — structural, so
+ * `skillGraph.ts`'s module-private `EntryDecl` satisfies it unchanged (the same
+ * trick `skillIntent.ts` uses).
+ */
+export interface StartRuleDecl {
+    readonly id: string;
+    /** The compiled condition (from `match:`) or the author's `when`. Absent on
+     *  an unconditional entry and on an intent rule (no sync predicate). */
+    readonly when?: (ctx: InjectionContext) => boolean;
+    /** The serializable matcher behind `when`, when declared as data — quoted
+     *  back in the messages, and the one way to spot the intent arm. */
+    readonly match?: SkillMatchData;
+}
+/**
+ * Run one entry's condition over one phrase, on a COLD-START context — the
+ * context a turn's first iteration really hands a start rule: iteration 1, the
+ * phrase as `userMessage`, no history, no cursor, no tool results. A throw is
+ * reported as `'threw'` and treated as a no-match by every caller, which is
+ * exactly what the cursor resolver does with it at run time (so a claim made
+ * here stays true of the run).
+ *
+ * An entry with NO condition matches everything: that is the cold walk's law
+ * (`if (!e.when) return { to: e.id }`), not a shortcut.
+ */
+export declare function runsOn(entry: StartRuleDecl, phrase: string): 'match' | 'no-match' | 'threw';
+/** The one context every predicate in a phrase check is judged on. */
+export declare function coldContext(userMessage: string): InjectionContext;
+/** The one context every predicate here is judged on, spelled out for the
+ *  reader of a message — a check that names its own inputs can be argued with;
+ *  one that hides them can only be guessed at. Kept as ONE string so every
+ *  message describes the SAME context {@link coldContext} really builds. */
+export declare const COLD_CONTEXT_PHRASE: string;
+/** One claimant of a phrase: the entry, and its position in declaration order.
+ *  (Named Claimant since 9.58.0 — `Claim<T>` on the `/maps` door is the
+ *  honesty primitive, a different thing; one name, one meaning.) */
+export interface Claimant {
+    readonly entry: StartRuleDecl;
+    readonly index: number;
+}
+/** How a rule's condition is named in a message: the data matcher quoted back,
+ *  the honest word for opaque code — or, for an entry that declares neither,
+ *  what having no condition MEANS. Naming a `when` predicate an unconditional
+ *  entry does not have is how a report describes a graph nobody wrote. */
+export declare function describeCondition(entry: StartRuleDecl): string;
+/**
+ * The two claimant sets, mirroring the TWO start laws (see `skillExamples.ts`'s
+ * header for the whole statement) rather than re-inventing either:
+ *
+ *   • COLD WALK (`makeResolveCursor`, the default mount): every non-intent
+ *     entry, unconditional ones included — they claim everything from their
+ *     position onward.
+ *   • CASCADE tier 1 (`firstRuleMatch`, mounted by `.classify()` OR by
+ *     `continuity: 'conversation'`): the CONDITIONAL non-intent entries only —
+ *     an unconditional entry is a default, not a rule.
+ *
+ * Intent entries appear in NEITHER: they compile to no sync predicate at all,
+ * and the classifier judges them at run time with a scorer this pass does not
+ * run.
+ */
+export interface ClaimLaws {
+    /** First claimant under the declaration-order cold walk, or undefined. */
+    readonly underColdWalk: (phrase: string) => Claimant | undefined;
+    /** First claimant under the turn-start cascade's tier 1, or undefined. */
+    readonly underCascade: (phrase: string) => Claimant | undefined;
+}
+/** Build both laws' claim finders over one entry list, in declaration order. */
+export declare function claimLaws(entries: readonly StartRuleDecl[]): ClaimLaws;
+//# sourceMappingURL=startRuleClaim.d.ts.map

package/dist/types/injection-engine/startRuleClaim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startRuleClaim.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/startRuleClaim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;4EACwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACnD;wEACoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAO3F;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAEjE;AAED;;;4EAG4E;AAC5E,eAAO,MAAM,mBAAmB,QAEO,CAAC;AAExC;;oEAEoE;AACpE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;0EAG0E;AAC1E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAK9D;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;IACjE,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;CACjE;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAStE"}