/**
 * skillGraph — a declarative, visualizable skill-dependency graph (proposal 002).
 *
 * The consumer declares skills + routing EDGES; `skillGraph()` compiles each edge
 * to the existing injection-engine TRIGGER on the target skill — so the dynamic,
 * token-efficient loading the engine already does becomes *declared* and *drawn*.
 *
 *   .entry(skill, { when? })              → trigger: `always` (or `rule` if when)
 *   .route(a, b, { onToolReturn | when }) → b compiles to a CURSOR-GATED `rule`
 *   (a skill with no declared incoming edge keeps its default `llm-activated`
 *    trigger — still reachable via `read_skill`, drawn as a dashed "model" edge)
 *
 * **v2 keystone — `from` IS enforced (a sticky cursor state machine).** A skill
 * graph is a state machine over skills; the engine tracks which node it is in via
 * `InjectionContext.currentSkillId` (the cursor). One pure resolver — `resolveCursor`
 * (see `makeResolveCursor`), of which `nextSkill(ctx)` is the `.to` projection — is the
 * single source of truth: each route target B
 * compiles to the trigger `nextSkill(ctx) === B`, which delivers `from`-gating
 * (an edge `A→B` fires only while the cursor is on A — no cross-skill edge bleed),
 * stickiness (the cursor stays on B until an edge leaves B), and a clean handoff
 * (B deactivates the same iteration C activates). The Injection Engine's Evaluate
 * stage advances the cursor with the SAME ctx (`currentSkillId = nextSkill(ctx)`),
 * so the active set and the persisted cursor never disagree. The DRAWN edge kind
 * (`on-tool-return` vs `predicate`) is preserved for rendering even though the
 * compiled trigger is always a `rule`. `toMermaid()` renders declared === drawn.
 *
 * A decision `tree()` routes per-iteration by stable `ctx` predicates (no cursor)
 * and is unaffected by `from`-gating. It has no cursor for `read_skill` to move
 * either, so `reachableSkills()` is EMPTY there and the gate refuses a leaf pick
 * (8.5.0) — see `reachableSkills` for why honouring it would break three of this
 * module's own invariants.
 *
 * **One skill's turn at a time (8.15.0).** The keystone's third property — "B
 * deactivates the same iteration C activates" — now holds for EVERY node in a flat
 * graph, including an entry that carries a `when`. Such an entry used to compile to
 * `when(ctx) || cursor === id`, and the leftover rule clause meant an entry that
 * routed onward stayed loaded beside its own successor, on that iteration and every
 * one after it. A conditional entry is active exactly while the cursor is on it;
 * `when` decides where a turn STARTS. The one declared way to be co-active beside
 * the cursor is an entry with no `when` at all (`{ kind: 'always' }`), which is
 * untouched. A rule that matched while the cursor was elsewhere is reported, not
 * swallowed — see `supersededEntries`.
 *
 * **The model moves too (`read_skill`).** Scoped `read_skill` bounds the model to
 * `reachableSkills(cursor)` — the declared successors of where it stands, plus the
 * entries. A pick the gate ACCEPTS moves the cursor exactly like a declared edge
 * does (`ctx.pendingSkillPick`, honoured in `makeResolveCursor`), so what the gate
 * allows and what actually takes effect are the same set. A declared edge that
 * fires the same turn wins (`D1 > D2`, docs/design/skill-graph.md §4A.1) and the
 * run emits `agentfootprint.skill.reroute_superseded` rather than leaving the
 * model's answered-"activated" claim quietly unmet.
 *
 * **The resolver says WHY, it is not asked to be guessed.** `explainNextSkill(ctx)`
 * returns the destination AND the winning clause (`CursorMove`), decided at the same
 * `return`. The agent stamps it on `context.evaluated` as `cursorMove`, which is how
 * `routeRecorder()` can tell a model pick from a declared edge that happens to point
 * at the same skill (8.5.0 — before, the drawn build-time provenance was read as the
 * per-hop cause, so a model pick was recorded under a declared edge's label).
 */
import type { ToolResultStatus } from './toolOutcome.js';
import type { Injection, InjectionContext } from './types.js';
import type { Embedder } from '../../memory/embedding/types.js';
import type { EntryScore, EntryScoring, EntryScorer } from './entryScorer.js';
import { type GraphCheckup } from './skillGraphCheckup.js';
import { type RouteWitness, type SkillMatch, type SkillMatchData } from './skillMatch.js';
import { type GuardConditionEvidence, type SkillGuard, type SkillGuardData } from './skillGuard.js';
import type { IntentScorer } from './intentScorer.js';
import { type RoutingPolicy } from './routingPolicy.js';
import { type TurnRoutingPlan } from './skillIntent.js';
export { formatCheckup } from './skillGraphCheckup.js';
export type { GraphCheckup, GraphProblem, GraphProblemCode } from './skillGraphCheckup.js';
export type { SkillMatch, SkillMatchData, RouteWitness } from './skillMatch.js';
export { GUARD_HOP_KEYS, plainGuardCaption, type GuardConditionData, type GuardConditionEvidence, type GuardOperator, type GuardValue, type SkillGuard, type SkillGuardData, type SkillGuardOps, } from './skillGuard.js';
export type { TurnRoutingPlan } from './skillIntent.js';
export type { TurnRoute } from './routingPolicy.js';
/** How `.build({ check })` reacts to the graph check-up. */
export type GraphCheckMode = 'throw' | 'warn' | 'off';
/** Options for `.build()`. */
export interface BuildOptions {
    /**
     * Run the build-time check-up (see `graph.checkup()`):
     *   • `'throw'` — throw if any ERROR-level problem (unknown-skill / no-entry);
     *   • `'warn'`  — console.warn every problem in dev mode (`enableDevMode()`), silent otherwise;
     *   • `'off'`   — skip it entirely.
     *
     * **Default `'throw'` since 8.7.0** (was `'warn'`), matching the object-literal
     * form. A graph with an error-level problem cannot start a turn at all, and under
     * the old default it built silently outside dev mode and failed at run time
     * instead. `'warn'` still means exactly what it says — never throws — so an
     * explicit `check: 'warn'` keeps the old soft behavior.
     *
     * `graph.checkup()` is always available regardless.
     */
    readonly check?: GraphCheckMode;
    /**
     * Tool names the AGENT exposes to every skill (`.tool()` / `.tools()` / a baseline
     * `ToolProvider`). Without them the skill-body contract check reads a body's
     * `lookup_order(id)` as a typo, because the graph only knows the tools its own
     * skills carry. Same field as `checkup({ knownTools })` — see `SkillGraph.checkup`.
     *
     * Omitted, the body-contract checks (`body-foreign-tool` / `body-unknown-tool`)
     * are DEFERRED out of this build pass and run once at Agent build instead, where
     * the full tool registry exists — see {@link SkillGraph.deferredBodyContract}.
     */
    readonly knownTools?: readonly string[];
    /**
     * FLAT graphs: stamp `autoActivate: 'currentSkill'` on every WIRED skill (every
     * skill an entry or a route mentions), exactly as a decision `.tree()` stamps its
     * leaves — so a skill's tools reach the LLM only while the graph is on it, instead
     * of every skill's tools landing in the always-on registry from iteration 1.
     *
     * Default `false` — today's additive behavior (10.0.0 flips the default to `true`).
     * A skill that declared its OWN `autoActivate` in `defineSkill(...)` always keeps
     * it: this fills the default, it never overrides. A listed-but-unwired skill is
     * not stamped — the graph does not route it, so the graph does not scope it.
     *
     * A decision `.tree()` takes this dial on `.tree(root, { scopeTools })` (object
     * form: the tree arm's own `scopeTools` field); setting it here alongside a tree
     * is refused so one dial cannot live in two homes.
     */
    readonly scopeTools?: boolean;
}
/** Options for `graph.checkup()`. */
export interface CheckupOptions {
    /**
     * Tool names the AGENT exposes to every skill — `.tool()` / `.tools()`
     * registrations and any always-on `ToolProvider`. A skill body may name them
     * freely: they are callable from every skill, so they are neither `body-unknown-tool`
     * (they exist) nor `body-foreign-tool` (they are not somebody else's).
     *
     * @example
     *   graph.checkup({ knownTools: ['lookup_order', 'list_skills'] });
     */
    readonly knownTools?: readonly string[];
}
/**
 * One start rule: route the turn's start to `use` when the rule matches.
 * Exactly ONE of `match` (data) / `when` (code) per rule — the union enforces it
 * at the keystroke and the build refuses it for everyone else. A rule exists to
 * be conditional; for an unconditional start use `start: 'id'` / `{ use }`.
 */
export type SkillStartRule = {
    readonly use: string;
    /** The code form — an opaque predicate over the iteration context. */
    readonly when: (ctx: InjectionContext) => boolean;
    readonly match?: never;
    /** The phrasings this rule claims — build-time TEST material. See
     *  {@link SkillEntryOptions.examples}. */
    readonly examples?: readonly string[];
} | {
    readonly use: string;
    /** The data form — comparable, drawable, stored. See {@link SkillMatch}. */
    readonly match: SkillMatch;
    readonly when?: never;
    /** The phrasings this rule claims — build-time TEST material. See
     *  {@link SkillEntryOptions.examples}. */
    readonly examples?: readonly string[];
};
/** Where a turn starts, in the object-literal (flat) form. */
export type SkillGraphStart = string | {
    readonly use: string;
} | {
    readonly rules: ReadonlyArray<SkillStartRule>;
    /** The intent classifier (SG-C) — REQUIRED iff any rule declares
     *  `match: { intent }`. Same machine as `.classify(scorer)`. */
    readonly classify?: IntentScorer;
    /** Tie-policy override — the ONE override home, beside the scorer it
     *  governs. Same machine as `.classify(scorer, policy)`. */
    readonly routing?: Partial<RoutingPolicy>;
} | {
    readonly entries: readonly string[];
    /** Rank the entries with a scorer strategy (`keywordScorer()`,
     *  `embeddingScorer(e)`, or your own). Takes precedence over `byRelevance`. */
    readonly scoredBy?: EntryScorer;
    /** Sugar: rank the entries with an embedder (cosine/softmax). Omit both → the
     *  LLM reads the menu and picks (`.entryByRead()`) — no model call. */
    readonly byRelevance?: Embedder;
};
/** One tool-result transition in the object-literal (flat) form. */
export interface SkillGraphStep {
    readonly from: string;
    readonly to: string;
    readonly when?: SkillRouteOptions['when'];
    readonly onToolReturn?: string | RegExp;
    /** Route on the result's declared outcome status (9.19.0) — see
     *  {@link SkillRouteOptions.onToolStatus}. */
    readonly onToolStatus?: SkillRouteOptions['onToolStatus'];
    /** The edge's condition as DATA (9.51.0) — see
     *  {@link SkillRouteOptions.guard}. */
    readonly guard?: SkillRouteOptions['guard'];
    readonly label?: string;
}
/**
 * Object-literal form, FLAT arm — `start` + `steps` declare the routing.
 * `tree` is typed `never` here so `{ tree, start }` is a COMPILE error, not just
 * a build-time refusal (see `SkillGraphConfig`).
 */
export interface SkillGraphFlatConfig {
    /** Every skill in the graph (wired or not). */
    readonly skills: readonly Injection[];
    /** Where a turn starts. */
    readonly start?: SkillGraphStart;
    /** Tool-result transitions; `from`/`to` are skill ids resolved against `skills`. */
    readonly steps?: readonly SkillGraphStep[];
    readonly tree?: never;
    /**
     * Stamp `autoActivate: 'currentSkill'` on every WIRED skill (every skill an
     * entry or a step mentions), exactly as the tree arm already stamps its leaves —
     * a skill's tools reach the LLM only while the graph is on it. **Default `false`**
     * (today's additive behavior — every skill's tools visible from iteration 1);
     * 10.0.0 flips the default to `true`. A skill whose author set its own
     * `autoActivate` keeps it: the graph level is a default, never an override.
     * See {@link BuildOptions.scopeTools}.
     */
    readonly scopeTools?: boolean;
    /**
     * Phrasings this graph must claim NOWHERE — the negative routing rows. Same
     * machine as `.neverRoutes([...])`; see that method for what the check
     * proves and what it deliberately does not. A row a declared start rule
     * claims is an ERROR (`never-routes-claimed`), naming the rule.
     *
     * @example
     *   skillGraph({ skills, start: { rules }, neverRoutes: ['what is the weather'] });
     */
    readonly neverRoutes?: readonly string[];
    readonly check?: GraphCheckMode;
    /** Baseline agent tool names — see {@link BuildOptions.knownTools}. */
    readonly knownTools?: readonly string[];
}
/**
 * Object-literal form, TREE arm — a decision tree owns the routing, so there is
 * no entry menu and no cursor for `start`/`steps` to describe. Both are typed
 * `never` so the contradiction is a compile error.
 */
export interface SkillGraphTreeConfig {
    /** Every skill in the graph. Under `tree` this must be exactly the leaf set —
     *  a listed skill that is not a leaf would never load, and is refused. */
    readonly skills: readonly Injection[];
    /** A decision tree (instead of `start` + `steps`). */
    readonly tree: DecisionNode | Injection;
    /**
     * Scope each leaf's tools to the routed leaf. The object form's half of
     * `.tree(root, { scopeTools })` — added in 8.7.0, because until then this form
     * hard-coded `true` and the fluent form's only opt-out had no object-form twin.
     * Default `true`. See {@link TreeOptions.scopeTools}.
     */
    readonly scopeTools?: boolean;
    readonly start?: never;
    readonly steps?: never;
    /** A tree has no start RULES for a negative row to be judged against, so the
     *  type refuses it here and `build()` refuses it at runtime (see
     *  {@link SkillGraphBuilder.neverRoutes}). */
    readonly neverRoutes?: never;
    readonly check?: GraphCheckMode;
    /** Baseline agent tool names — see {@link BuildOptions.knownTools}. */
    readonly knownTools?: readonly string[];
}
/**
 * Object-literal form of a skill graph — an alternative to the fluent builder.
 * Listing `skills` INDEPENDENTLY of the wiring is the point: the check-up can then
 * flag a skill that was listed but never wired (the fluent builder only ever sees
 * skills that appear in an edge). Compiles to the SAME `SkillGraph`. `check`
 * defaults to `'throw'` here (a new surface, fail-loud).
 *
 * A UNION of two arms, because `tree` and `start`/`steps` are two ways to declare
 * the same thing and only one of them compiles: `{ tree, start }` is a type error
 * for a TypeScript consumer and a build-time refusal for everyone else (8.4.0 —
 * before, the tree silently won and the flat wiring was discarded). Valid tree-only
 * and flat-only configs typecheck exactly as they did.
 */
export type SkillGraphConfig = SkillGraphFlatConfig | SkillGraphTreeConfig;
export type { EntryScore, EntryScoring };
/** Deterministic routing into a skill, keyed on the last tool result. */
export interface SkillRouteOptions {
    /** Predicate on the previous iteration's tool result → activate the target
     *  on the next iteration. The common, controllable edge. `status` is
     *  present when the tool declared one on its result envelope (9.19.0).
     *
     *  `result` is the string the MODEL read — which artifact placement can
     *  replace with a claim ticket, so an operator raising or lowering
     *  `artifacts.placement.maxInlineChars` can change whether a text-matching
     *  edge fires. See {@link InjectionContext.lastToolResult}; route on
     *  `onToolReturn` / `onToolStatus` for a guard placement cannot move. */
    readonly when?: (result: {
        readonly toolName: string;
        readonly result: string;
        readonly status?: ToolResultStatus;
    }) => boolean;
    /** Sugar for "activate whenever this tool returns (any result)". String is an
     *  exact match; RegExp is tested against the tool name. */
    readonly onToolReturn?: string | RegExp;
    /**
     * Route on the result's declared OUTCOME, not its prose (9.19.0) — the
     * data half of the outcome-status normalization: a `'denied'` call must
     * never route like a `'success'`. Matches when a tool result of the batch
     * carries one of the named statuses on its envelope; a result with NO
     * declared status can never match (an undeclared outcome is not
     * evidence). Compose with `onToolReturn` to pin the tool too ("when
     * `refund` returns `'denied'`"); alone, any tool's matching status fires.
     * Data — comparable, drawable (`toMermaid()` captions it), stored. At
     * most one of `when` / `onToolStatus`: code or data, never both.
     */
    readonly onToolStatus?: ToolResultStatus | ReadonlyArray<ToolResultStatus>;
    /**
     * The DATA form of `when` (9.51.0) — the edge's condition declared as
     * comparable, drawable, recordable conditions instead of an opaque
     * predicate: `{ key: { eq | ne | gt | gte | lt | lte | in | notIn: value } }`,
     * every condition ANDed (the operator grammar deliberately mirrors
     * footprintjs's `WhereFilter` — see {@link SkillGuard}). This is the
     * SkillWalker's guard mover as data: the map is data, entry matchers are
     * data, `onToolStatus` arms are data — the guard was the last opaque
     * function on a route edge.
     *
     * Judged per tool result of the previous iteration's batch, exactly where a
     * `when` runs. Six hop keys read the hop directly (`toolName`, `result`,
     * `status`, `iteration`, `userMessage`, `currentSkillId`); any OTHER key
     * reads the top-level field of that name from the RESULT parsed as JSON —
     * `guard: { riskLevel: { gte: 'high' } }` routes on a tool that returned
     * `{"riskLevel":"high"}`. Being data buys four things a `when` can never
     * have: the check-up proves contradictions (`guard-unsatisfiable`),
     * `toMermaid()` captions the edge ("when riskLevel ≥ high"),
     * `skill.graph_declared` carries it into every recording, and each
     * evaluation that DECIDES a hop — taken or refused — leaves per-condition
     * evidence on `cursorMove.guard` / `cursorMove.guardsClosed`.
     *
     * COMPOSES with `onToolReturn` / `onToolStatus` ("this tool, this outcome,
     * AND these conditions"). At most one of `when` / `guard`: code or data,
     * never both — to combine declared conditions with extra logic, fold the
     * checks into your `when` predicate.
     */
    readonly guard?: SkillGuard;
    /** Caption rendered on the edge. Defaults to a derived label. */
    readonly label?: string;
}
/** Where a turn starts. `when` (optional) makes entry intent-conditional. */
export interface SkillEntryOptions {
    /**
     * Which entry the turn STARTS on — a predicate over the iteration context
     * (e.g. `ctx.userMessage`). The first entry whose `when` passes wins the
     * cold-start cursor.
     *
     * **It decides the start; it does not keep the skill on the wire (8.15.0).**
     * A conditional entry is active exactly while the cursor is on it — a route out
     * of it ends its turn, and its rule cannot bring it back while the graph is
     * somewhere else. Before 8.15.0 the rule re-activated it on every iteration, so an
     * entry that routed onward stayed loaded beside its own successor.
     *
     * Omit `when` → the skill is `always` active: a persistent base procedure, on
     * beside whatever the cursor is on. That is the declared way to ask for an
     * always-on skill; `when: () => true` is NOT the same thing any more. For "on
     * whenever this matches, wherever the graph is", use the flavor built for it —
     * `.steering(...)` / `.skill(...)` with its own `rule` trigger — rather than an
     * entry, which is a position in a state machine.
     */
    readonly when?: (ctx: InjectionContext) => boolean;
    /**
     * The DATA form of `when` — a declared matcher over the user's message instead
     * of a predicate (see {@link SkillMatch}): comparable by the check-up, captioned
     * by `toMermaid()`, stored on the compiled skill's provenance. Same start
     * semantics as `when` in every other way. At most ONE of `match`/`when` — both
     * set is refused at build time. Omitting both keeps this an `always` entry,
     * exactly as before.
     */
    readonly match?: SkillMatch;
    /**
     * The phrasings this rule CLAIMS — real messages a user would type that
     * should start the turn here. Optional, additive, and **fed to nothing at
     * run time**: the check-up reads them at build time and the routing never
     * sees them, so a rule with examples routes byte-identically to the same
     * rule without them.
     *
     * Things become PROVABLE once a phrase is declared, by RUNNING the compiled
     * matchers rather than comparing them:
     *
     *   • `example-misses-own-rule` — this rule does not claim its own example.
     *     An ERROR for a data `match` (it reads the user message and nothing
     *     else, so the no-match holds under every context) or for a predicate
     *     that THREW; a WARNING for an opaque `when` that returned false, which
     *     may be gated on conversation state and claim the phrase on a later
     *     turn (see the context note below);
     *   • `example-shadowed-by-earlier` (error) — an EARLIER rule claims the
     *     phrase first, so the turn starts somewhere your own example denies.
     *     This is the one `rules-shadowed-by-order` must stay silent about when
     *     the two rules use different regexes (intersection is not decided
     *     anywhere in this library) — a witness phrase decides it instead;
     *   • `example-shadowed-by-default` (warning) — the earlier claimant is an
     *     UNCONDITIONAL entry. The declaration-order cold start stops at a
     *     default; the turn-start cascade (a classifier, or `continuity:
     *     'conversation'`) reads the conditional rules only and skips it — and
     *     which one applies is decided at AGENT MOUNT, so the report names both
     *     readings instead of asserting one against the router;
     *   • `example-unclaimed` (warning) — NO rule claims the phrase, so the turn
     *     falls through to the model tier. Absence, which no matcher-vs-matcher
     *     analysis can catch.
     *
     * **The context they are judged on.** Every condition here runs on ONE
     * context — iteration 1, the phrase as `userMessage`, empty `history`, no
     * cursor — the context a turn's FIRST iteration hands a start rule. Turn 2 of
     * a conversation also starts cold in cursor terms while CARRYING history, so
     * a `when` gated on conversation state may claim the phrase on a turn this
     * check cannot run. That is why its no-match is a warning, and why every
     * message names the context it judged under.
     *
     * **Tier difference, and it matters.** In `match: { intent, examples }`
     * (tier 2) the examples are SCORING material: the classifier reads them at
     * RUN time to judge new messages. Here (tier 1) they are TEST material only.
     * The author-facing meaning is the same — "the phrasings this rule claims" —
     * the runtime role is not, and a rule may not carry both lists (refused at
     * build, naming the difference).
     *
     * The boundary: these checks prove things about the phrases you declared and
     * nothing about phrases nobody wrote. No warning is not proof of coverage —
     * `graph.checkup().notes` says so on the report itself.
     *
     * @example
     *   .entry(arrayInventory, {
     *     match: /\b(array|volume|pool)\b/i,
     *     examples: ["what's running on shpstrprncl101"],
     *   })
     */
    readonly examples?: readonly string[];
    readonly label?: string;
}
/** Options for a decision `tree()`. */
export interface TreeOptions {
    /**
     * Scope the tool list to the routed leaf (the on-demand-tools default).
     *
     * A decision tree routes to EXACTLY ONE skill per iteration, so each leaf is
     * stamped `autoActivate: 'currentSkill'` — its `inject.tools` reach the LLM
     * ONLY when the tree routes there, instead of every skill's tools landing in
     * the always-on static registry on every call.
     *
     * `read_skill` cannot reach another LEAF mid-run (8.5.0): a tree has no cursor to
     * move, and this "exactly one leaf" property is one of the reasons — admitting a
     * second leaf would put two leaves' tools on the wire and make the dev-mode
     * exactly-one monitor warn. It said otherwise until 8.5.0, and the pick was
     * accepted and then silently dropped. The escape hatch is a skill registered
     * BESIDE the graph (`.skill(x)`, `.selfExplain()`), which really does activate by
     * `read_skill` and is admitted from anywhere.
     *
     * Default `true`. Set `false` for the legacy additive behavior (all leaves'
     * tools always visible). A leaf that sets its OWN `autoActivate` in
     * `defineSkill(...)` is always respected — this only fills the default.
     */
    readonly scopeTools?: boolean;
}
export type SkillEdgeKind = 'entry' | 'predicate' | 'on-tool-return' | 'on-tool-status' | 'guard' | 'model';
export interface SkillEdge {
    /** Source skill id, or `null` for the synthetic START (an entry edge). */
    readonly from: string | null;
    readonly to: string;
    readonly kind: SkillEdgeKind;
    readonly label?: string;
    /** The DATA matcher on an entry edge, when the rule was declared as data
     *  (`match:`). `toMermaid()` captions the edge with it when no explicit
     *  `label` was given. */
    readonly match?: SkillMatchData;
    /** The DATA guard on a route edge, when one was declared (9.51.0) — rides
     *  additively beside the kind exactly as `match` rides entry edges (a
     *  guard composed with `onToolReturn`/`onToolStatus` keeps that kind; a
     *  guard alone is kind `'guard'`). `toMermaid()` captions a guard-only
     *  edge with it when no explicit `label` was given, and
     *  `skill.graph_declared` carries it into every recording. */
    readonly guard?: SkillGuardData;
}
/**
 * A decision-tree node (v3): a predicate that branches to a subtree (or a skill
 * LEAF) on each side. The tree compiles to per-skill triggers — each leaf's
 * trigger is the conjunction of the predicates on its root→leaf path (with
 * earlier-sibling negation for if/else exclusivity), evaluated per iteration. So
 * "predicate nodes that route" needs NO engine change — same evaluator.
 */
export interface DecisionNode {
    readonly kind: 'decision';
    readonly predicate: (ctx: InjectionContext) => boolean;
    readonly whenTrue: DecisionNode | Injection;
    readonly whenFalse: DecisionNode | Injection;
    /** Caption for the predicate node when drawn (e.g. "io intent?"). */
    readonly label?: string;
}
/** Build a decision node. Leaves are skills (an `Injection`); internal nodes are
 *  other `decideSkill(...)` results. (Renamed from `decide` in v7 to avoid
 *  colliding with footprintjs's `decide()`.) */
export declare function decideSkill(predicate: (ctx: InjectionContext) => boolean, whenTrue: DecisionNode | Injection, whenFalse: DecisionNode | Injection, label?: string): DecisionNode;
/**
 * WHY the cursor landed where it did on one iteration — the winning clause of the
 * one cursor resolver, reported rather than guessed (8.5.0).
 *
 *   • `'entry'`      — cold start: the first entry whose `when` passed (or, on a
 *                      cascade graph, a tier-1 start rule won the turn);
 *   • `'route'`      — a declared, `from`-gated edge fired (D1);
 *   • `'model-pick'` — no declared edge fired, so the model's gate-accepted
 *                      `read_skill` pick moved the cursor (D2), at cold start or mid-run;
 *   • `'tool-proposal'` — no declared edge fired and an ACCEPTED
 *                      `propose-transition` tool effect moved the cursor
 *                      (9.19.0) — deterministic tool evidence, ranked between
 *                      the author's edges (D1 still wins) and the model's
 *                      pick (a tool outranks a guess);
 *   • `'intent'`     — the turn-start cascade's tier-2 scorer decisively routed
 *                      the turn (SG-C; `turn_routed` carries the numbers);
 *   • `'continuity'` — the inherited conversation cursor held the turn's start
 *                      (SG-C, `continuity: 'conversation'`);
 *   • `'decider'`    — the configured tier-3 decider resolved an outstanding
 *                      menu out-of-band and the turn starts on its pick
 *                      (9.19.0);
 *   • `'stay'`       — nothing fired; the cursor is sticky and stayed put;
 *   • `'none'`       — no cursor at all (cold start with nothing to enter, or a
 *                      decision `tree()`, which routes by predicate and has no cursor).
 *
 * This exists because the DRAWN provenance on a skill (`metadata.skillGraph`) answers
 * "how is this skill reachable" — a build-time fact — and was being read as "how did
 * we get here this turn". A model pick into a skill that also has a declared edge was
 * therefore attributed to that edge, label and all, in the recorded route.
 */
export type CursorMoveCause = 'entry' | 'route' | 'model-pick' | 'tool-proposal' | 'intent' | 'continuity' | 'decider' | 'stay' | 'none';
/**
 * One tool result's routing implication inside a parallel batch (9.16.0) —
 * which call it was, and the edge target it matched. Named by
 * `skill.route_conflict` as the winner or a suppressed loser.
 */
export interface RouteBatchOutcome {
    /** The provider's tool_use id for the call. Absent only for a context that
     *  supplied the singular `lastToolResult` (which can never conflict). */
    readonly toolCallId?: string;
    /** The tool whose result matched an edge. */
    readonly toolName: string;
    /** The edge target that result routed to. */
    readonly target: string;
}
/**
 * Two or more results of ONE parallel batch matched edges to DIFFERENT
 * targets (9.16.0). The first in call order wins the cursor; the rest are
 * suppressed — and reported here rather than silently dropped, so the record
 * explains the hop the run did NOT take. Same-target matches are not a
 * conflict (they all asked for the move that happened).
 */
export interface RouteBatchConflict {
    /** The call-order-first match — the one that moved the cursor. */
    readonly winner: RouteBatchOutcome;
    /** Later matches to other targets, in call order, that did not move it. */
    readonly losers: readonly RouteBatchOutcome[];
}
/**
 * One guard's evaluation against one tool result (9.51.0) — the evidence a
 * data guard leaves whenever it DECIDES a hop: which edge, which result it
 * judged, and every condition with the value it saw. Two homes on the move:
 * `CursorMove.guard` (the taken hop's evaluation, verdict `true`) and
 * `CursorMove.guardsClosed` (the refusals, verdict `false`) — both ride
 * `context.evaluated.cursorMove` onto the record.
 */
export interface GuardEvaluation {
    /** The guarded edge. */
    readonly from: string;
    readonly to: string;
    /** The tool result this evaluation judged. */
    readonly toolName: string;
    /** The provider's tool_use id for that call, when the batch carried one. */
    readonly toolCallId?: string;
    /** `true` — the guard passed and the edge fired; `false` — the guard
     *  refused a hop whose other declared conditions were already met. */
    readonly verdict: boolean;
    /** Per-condition evidence, in declaration order — every condition, the
     *  summarized value it was judged against, and whether it passed. */
    readonly conditions: readonly GuardConditionEvidence[];
}
/** The cursor resolver's full answer: where, and by which clause. */
export interface CursorMove {
    /** The cursor after this iteration (what `nextSkill` returns). */
    readonly to?: string;
    /** The cursor before it. */
    readonly from?: string;
    /** The winning clause. */
    readonly by: CursorMoveCause;
    /** Present only when `by: 'route'` resolved a parallel batch whose results
     *  matched edges to different targets — the suppression, on the record.
     *  The Evaluate stage emits it as `agentfootprint.skill.route_conflict`. */
    readonly conflict?: RouteBatchConflict;
    /**
     * The EVIDENCE a tier-1 DATA matcher routed on (9.28.0) — the text out of the
     * user message that made the entry's rule true, bounded (see
     * {@link RouteWitness}). Present only for `by: 'entry'` moves decided by a
     * `match:` (RegExp / `{ keywords }` / `{ all }`) rule; a `when` predicate is
     * opaque code, an unconditional entry matched nothing, and a scorer's
     * evidence is its scores — all three record no witness.
     */
    readonly witness?: RouteWitness;
    /**
     * The EVIDENCE the winning guard routed on (9.51.0) — present only for a
     * `by: 'route'` move whose firing edge declared a `guard:`. The full
     * per-condition evaluation (verdict `true`), decided at the same return as
     * the destination, so the record can never quote a different judgment than
     * the one that routed.
     */
    readonly guard?: GuardEvaluation;
    /**
     * The guards that REFUSED this iteration (9.51.0) — every guarded edge out
     * of the cursor whose OTHER declared conditions a result met and whose
     * guard said no (verdict `false`; at most one record per edge, the first
     * refusal in call order). Present on whatever move resulted — including a
     * `'stay'`, where it answers "why didn't my guarded edge fire?" with the
     * conditions and the values that closed it, the same honesty
     * `supersededEntries` gives suppressed entries. An edge whose
     * `onToolReturn`/`onToolStatus` preconditions never matched is NOT here:
     * its guard never decided anything.
     */
    readonly guardsClosed?: readonly GuardEvaluation[];
}
/** A node in the drawn graph — a `predicate` diamond or a `skill` box. */
export interface SkillNode {
    readonly id: string;
    readonly kind: 'predicate' | 'skill';
    readonly label?: string;
}
/** One predicate on a skill's root→leaf decision path, and the branch taken. */
export interface SkillRoutingStep {
    /** The predicate's caption (the `decide(...)` label). */
    readonly label: string;
    /** Which side of the predicate leads to this skill. */
    readonly branch: 'yes' | 'no';
}
/**
 * The routing PROVENANCE stamped onto a compiled skill's `metadata.skillGraph`
 * — *why* this skill is reachable. It rides through to the `context.evaluated`
 * event when the skill activates, so commentary + the lens can narrate the real
 * routing (not just "a skill activated"). Observability only; the trigger logic
 * is unchanged.
 */
export interface SkillRouting {
    /** How the skill is reached: a decision `tree` leaf, a flat `entry`, a
     *  deterministic `route` edge, or `model` (read_skill-reachable). */
    readonly via: 'tree' | 'entry' | 'route' | 'model';
    /** Decision path (tree only): the predicates from root→leaf + branch taken.
     *  For a skill used as MULTIPLE tree leaves this is the FIRST path; all
     *  paths are in `paths`. */
    readonly path?: readonly SkillRoutingStep[];
    /** All decision paths reaching this skill (tree only; present when the same
     *  skill is the leaf of more than one branch — the compiler merges repeated
     *  leaves into ONE injection whose trigger ORs the path predicates). */
    readonly paths?: ReadonlyArray<readonly SkillRoutingStep[]>;
    /** Entry/route edge caption. */
    readonly label?: string;
    /** Source skill id (route only). */
    readonly from?: string;
    /** The compiled trigger kind for a route (`rule` / `on-tool-return`). */
    readonly triggerKind?: string;
    /** The DATA matcher that routes here (entry only, when declared as `match:`) —
     *  serializable, so commentary/lens can say WHICH pattern chose the skill. */
    readonly match?: SkillMatchData;
    /** The DATA guard on the first deterministic edge in (route only, when
     *  declared as `guard:`, 9.51.0) — serializable, the `match` twin. */
    readonly guard?: SkillGuardData;
}
/** The metadata key carrying a skill's routing provenance. */
export declare const SKILL_GRAPH_METADATA_KEY: "skillGraph";
/**
 * The note a graph leaves for Agent build when its own build pass DEFERRED the
 * skill-body ↔ tool-contract checks (`body-foreign-tool` / `body-unknown-tool`) —
 * see {@link SkillGraph.deferredBodyContract}.
 */
export interface DeferredBodyContract {
    /** The graph's `check` mode — the severity the deferred run respects
     *  (`'off'` never defers: it stays off at agent build too). */
    readonly mode: 'throw' | 'warn';
}
/**
 * The metadata key carrying the {@link DeferredBodyContract} note on each COMPILED
 * skill. The graph-level `graph.deferredBodyContract` note names the deferral, but
 * skills reach an agent through more than one door — `.skillGraph(graph)` sees the
 * graph, `.skills({ list: () => graph.skills })` sees only the skills — so the note
 * also rides each skill's own metadata. Agent build collects it from the final
 * injection list, whichever door the skills came through, and runs the deferred
 * checks exactly once (skills found by BOTH the metadata and the graph note are
 * deduped by id).
 */
export declare const SKILL_GRAPH_DEFERRED_CONTRACT_KEY: "skillGraphDeferredBodyContract";
export interface SkillGraph {
    /** Skills with graph-derived triggers — feed to the Agent (`.skillGraph()` or
     *  `.skills({ list: () => graph.skills })`). */
    readonly skills: readonly Injection[];
    /** The declared edges (for tooling, overlays, tests). */
    readonly edges: readonly SkillEdge[];
    /** Drawn nodes: skill boxes for the flat entry/route model; predicate diamonds
     *  + skill leaves for a decision `tree`. Always present. */
    readonly nodes: readonly SkillNode[];
    /** A Mermaid flowchart of the declared graph — declared === drawn. */
    toMermaid(): string;
    /**
     * The CURSOR resolver — given an iteration context, where is the graph next?
     * Returns the skill id the graph should be *in* after this iteration:
     *   • cold start (`ctx.currentSkillId` unset) → the first matching `entry`,
     *     else the entry the model picked with `read_skill`;
     *   • a `from`-gated route whose predicate matches a result of the previous
     *     iteration's tool batch (`ctx.toolResults`, in call order; falls back to
     *     the singular `ctx.lastToolResult`) → its target;
     *   • else the model's `read_skill` pick (`ctx.pendingSkillPick`), which the
     *     runtime sets only after the reachability gate accepted it;
     *   • otherwise the current cursor unchanged (sticky stay).
     * A declared edge that fires always beats a same-turn model pick.
     * Pure + deterministic — the single source of truth shared by the compiled
     * route triggers and the agent loop's cursor-update stage, so the two can never
     * disagree. Flat entry/route graphs only; a decision `tree()` routes per-iteration
     * by predicate (no cursor) and returns the unchanged `ctx.currentSkillId`.
     *
     * **The cursor is PER RUN.** It describes where the graph is inside ONE
     * `agent.run()`, across that run's iterations. A second `run()` on the same agent
     * starts cold — at the entry — whatever skill the first run ended on: a skill graph
     * is a per-turn state machine, not conversation memory, and `currentSkillId` lives
     * in the run's own state. To resume where the last turn stopped, persist the id
     * yourself and start the next turn's graph from it (`start: { rules: [...] }`);
     * nothing in the graph will carry it across for you.
     */
    nextSkill(ctx: InjectionContext): string | undefined;
    /**
     * The same answer as `nextSkill`, plus WHICH CLAUSE produced it — the resolver
     * reporting its own reasoning instead of a consumer inferring it from the drawn
     * provenance (8.5.0). `explainNextSkill(ctx).to === nextSkill(ctx)`, always: there
     * is one resolver and `nextSkill` is a thin projection of this one, so the two can
     * never drift.
     *
     * The agent threads this into the injection engine, which stamps the result on
     * `agentfootprint.context.evaluated` as `cursorMove` — that is what lets
     * `routeRecorder()` mark a model-pick hop as a model pick instead of borrowing the
     * label of a declared edge that never fired.
     */
    explainNextSkill(ctx: InjectionContext): CursorMove;
    /**
     * The entries whose OWN `when` matched this iteration but which the cursor
     * SUPERSEDED — declaration order, ids only (8.15.0). Empty for a graph with no
     * conditional entries, for a decision `tree()`, and whenever the graph has no
     * cursor at all.
     *
     * A conditional entry is active exactly while the cursor is on it. That is a
     * suppression, and a suppression the run must not swallow: the agent threads this
     * into the injection engine, which stamps it on `agentfootprint.context.evaluated`
     * as `supersededIds`, beside the `cursorMove` that says where the graph went
     * instead. Reading the two together answers "why isn't my entry loading?" without
     * anyone having to re-run a predicate to guess.
     *
     * It rides the per-iteration event rather than `skill.reroute_superseded` on
     * purpose: this is a CONTINUOUS condition (an entry whose rule stays true while
     * the cursor is parked elsewhere is suppressed every iteration), while that event
     * means a discrete broken promise — a `read_skill` pick the gate accepted and
     * something else outranked. Per-iteration state belongs on the per-iteration event.
     *
     * Pure + deterministic. A predicate that throws is reported by the evaluator as
     * `skipped: 'predicate-threw'`, not here.
     */
    supersededEntries(ctx: InjectionContext): readonly string[];
    /**
     * The REACHABLE set — which skills the model may `read_skill`-jump to from the
     * current cursor. The agent's runtime gate rejects any `read_skill('id')` whose
     * `id` is not in this set (so the model can't leave the graph mid-run).
     *   • cold start (`currentSkillId` undefined) → the entry skills;
     *   • otherwise → the current skill's direct successors ∪ the entry skills, minus
     *     the current skill itself (deliberate "stay" is the no-tool-call ReAct stop).
     *
     * A decision `tree()` returns EMPTY (8.5.0). A tree routes by predicate on every
     * iteration and has no cursor to jump: its leaves compile to `rule` triggers, and a
     * `read_skill` call writes only `activatedInjectionIds`, which a `rule` trigger does
     * not read. Until 8.5.0 this returned all the leaves, so the gate accepted a leaf
     * pick, the tool answered "activated for the next iteration", and the leaf never
     * activated. That is the same clause 8.4.0 already applies everywhere else — a skill
     * is open only when its trigger is `llm-activated` — reaching the one set that had
     * escaped it. The escape hatch under a tree is the OPEN skills (anything registered
     * beside the graph: `.skill(x)`, `.selfExplain()`), which the agent's gate still
     * admits from any cursor.
     *
     * Pure + deterministic.
     */
    reachableSkills(currentSkillId?: string): readonly string[];
    /**
     * Score the entry candidates by relevance to the user's message — present ONLY
     * when the graph was built with `.entryByRelevance(embedder)`. Embeds
     * `ctx.userMessage` and each `when`-passing entry's `description`, cosine-scores
     * them, and softmaxes into a `relevance` share. The agent's PickEntry stage uses
     * `chosen` as the starting cursor (LLM-free, off the hot loop). Flat graphs only.
     */
    scoreEntries?(ctx: InjectionContext, signal?: AbortSignal): Promise<EntryScoring>;
    /**
     * Build-time check-up — inspect the declared graph for wiring mistakes (a skill
     * nobody can reach, an edge to an unknown skill, two un-prioritized edges from one
     * skill, no entry, a self-loop, an entry menu with no way to choose from it, a
     * transition the cold-start cursor can never take). Pure + side-effect-free; call
     * it whenever. `ok` is false iff there's an error-level problem (`unknown-skill` /
     * `no-entry`) — everything else is a warning, because a graph the model can still
     * navigate is not a broken graph.
     *
     * Pass `knownTools` when the agent registers baseline tools with `.tool()`: the
     * graph only knows the tools its own skills carry, so without them a body that
     * says `lookup_order(id)` is reported as naming a tool that exists nowhere.
     *
     * @example
     *   const report = graph.checkup({ knownTools: ['lookup_order'] });
     *   if (!report.ok) throw new Error(formatCheckup(report));
     */
    checkup(options?: CheckupOptions): GraphCheckup;
    /**
     * The turn-routing plan (SG-C) — what the agent's RouteTurn stage consumes:
     * the configured classifier (if any), the resolved tie policy, tier-1 rule
     * evaluation and the intent-candidate projection. Present on every FLAT
     * graph (a decision `tree()` routes by predicate and has no turn start to
     * route). Consumers never call it directly; `.skillGraph()` threads it.
     */
    readonly turnRouting?: TurnRoutingPlan;
    /**
     * How a turn's starting entry is chosen (SG-C) — `'scorer'`
     * (`.entryBy()`/`.entryByRelevance()`), `'model-read'` (`.entryByRead()`),
     * `'classify'` (`.classify()`), absent = the declaration-order cold walk.
     * Read by the agent mount for exactly one refusal: `strictness: 'rails'`
     * cannot honor `'model-read'` (that mode's entire entry mechanism is a
     * model pick).
     */
    readonly entrySelection?: 'scorer' | 'model-read' | 'classify';
    /**
     * The ASYNC intent audit (SG-C) — present ONLY when a classifier is
     * configured. Leave-one-out over the declared example corpus with the
     * CONFIGURED scorer (the router that will actually run — auditing with a
     * different scorer would prove nothing about production): each example is
     * scored against every intent, its own intent represented by its remaining
     * examples; a cross-match or near-tie is an `overlapping-intents` warning
     * naming the example, both intents and both numbers.
     *
     * Costs one scorer call per declared example — on `llmClassifier` that is
     * one MODEL call per example, so run it in CI, not per request. Honesty
     * boundaries ride every message: only the configured scorer's view is
     * checked, `when` predicates are opaque and never claimed checked, and
     * tier-1 rules that fire before the classifier are named as unaudited
     * shadowers. Absent without a classifier rather than answering
     * `{ ok: true }` for a question it cannot ask.
     */
    checkupIntents?(signal?: AbortSignal): Promise<GraphCheckup>;
    /**
     * Present when this graph's own build pass DEFERRED the skill-body ↔
     * tool-contract checks (`body-foreign-tool` / `body-unknown-tool`): built
     * WITHOUT `knownTools`, the graph cannot tell a typo from a baseline tool the
     * agent registers later — `lookup_order(id)` in a body and `lokup_order(id)`
     * look identical to it — so instead of reporting what it cannot prove, it
     * leaves this note and Agent build runs those checks exactly once, against the
     * agent's full tool registry. The note also rides each compiled skill's own
     * metadata ({@link SKILL_GRAPH_DEFERRED_CONTRACT_KEY}), so it is honored
     * whichever way the skills arrive — `.skillGraph(graph)` or
     * `.skills({ list: () => graph.skills })`.
     *
     * Absent when the checks already ran at graph build (`knownTools` was given —
     * the manual override stays an override) or were switched off (`check: 'off'`);
     * the agent then never re-runs them, so one problem is reported at one build
     * point, never both. `graph.checkup()` is unaffected — it always runs every
     * check over what it can see, and remains the graph-only lint surface.
     */
    readonly deferredBodyContract?: DeferredBodyContract;
}
export interface SkillGraphBuilder {
    /** Mark a skill as reachable at turn start (optionally intent-conditional). */
    entry(skill: Injection, opts?: SkillEntryOptions): SkillGraphBuilder;
    /** Declare an edge: after `from`'s work, `to` activates when the edge fires. */
    route(from: Injection, to: Injection, opts?: SkillRouteOptions): SkillGraphBuilder;
    /** Declare a decision TREE (v3): predicate nodes → skill leaves. Compiles each
     *  leaf to a path-conjunction trigger; renders as diamonds → boxes. By default
     *  each leaf is tool-scoped (`autoActivate: 'currentSkill'`) so only the routed
     *  skill's tools reach the LLM — opt out with `{ scopeTools: false }`. */
    tree(root: DecisionNode | Injection, opts?: TreeOptions): SkillGraphBuilder;
    /**
     * Pick the STARTING entry with a pluggable scorer STRATEGY — `keywordScorer()`
     * (no dependency, word overlap), `embeddingScorer(embedder)` (semantic), or your
     * own `EntryScorer`. The agent's PickEntry stage runs it ONCE per turn off the
     * hot loop and starts the cursor at the winner. Like `.entryByRead()`, this makes
     * the entries EXCLUSIVE (only the chosen one loads, token-efficient). The surfaced
     * `relevance` % powers the "Why this skill?" panel. Flat graphs only (a decision
     * `tree()` already routes by predicate). Mutually exclusive with `.entryByRead()`.
     */
    entryBy(scorer: EntryScorer): SkillGraphBuilder;
    /**
     * Sugar for `.entryBy(embeddingScorer(embedder))` — pick the starting entry by
     * SEMANTIC relevance (embed the message + each entry's `description`, cosine-score,
     * softmax → best match). LLM-free (an embedder, no extra model call), reproducible.
     * For a no-embedder router, use `.entryBy(keywordScorer())`.
     */
    entryByRelevance(embedder: Embedder): SkillGraphBuilder;
    /**
     * Let the LLM pick the STARTING entry by reading the menu — no embedder, no extra
     * model call. Like `.entryByRelevance()`, the entries become EXCLUSIVE (only the
     * chosen one loads, token-efficient), but the choice is the model's: on the first
     * turn no entry auto-loads, the agent is offered the entries via `read_skill`, and
     * its pick becomes the cursor. Use this when you have NO embedder (or embeddings
     * route poorly for your domain) — the agent's own LLM understands the request.
     * Flat graphs only; mutually exclusive with `.entryByRelevance()`.
     *
     * A `when` on an entry gates the AUTOMATIC pick only: if the model explicitly
     * picks a `when`-gated entry from the menu, it loads (8.3.0 — before, the pick
     * was accepted, reported as activated, and then silently dropped). Use `when`
     * here to say "don't route here on your own", never as a lock.
     */
    entryByRead(): SkillGraphBuilder;
    /**
     * Configure the turn-start INTENT CLASSIFIER (SG-C) — the tier-2 judge of
     * `match: { intent, examples }` entries. `classify` is the honest verb: it
     * classifies the NEW message against declared intents, where `.entryBy()`
     * means "rank descriptions and pick" — a different machine (menu-exclusive
     * winner, no floor, no stay). The entries become EXCLUSIVE (only the routed
     * one loads); the cold-start declaration-order walk is suppressed (the
     * cascade decides, or offers a menu — never the first-declared entry by
     * accident).
     *
     * The cascade, per turn: tier 1 — regex/keyword/`when` rules in declaration
     * order (binary, decisive); tier 2 — `scorer` over the declared intents,
     * judged under `policy` (defaults: `NEAR_TIE_MARGIN`/`MENU_SIZE`); tier 3 —
     * a near-tie or unmatched verdict offers a MENU through `read_skill`'s own
     * description, and the model picks (or stays). Every verdict is recorded on
     * `agentfootprint.skill.turn_routed` with the losers and the thresholds.
     *
     * `policy` here is the ONE override home for the tie policy (mirrors the
     * one-dial-one-home law `scopeTools` follows). Mutually exclusive with
     * `.entryBy()` / `.entryByRelevance()` / `.entryByRead()` — one entry
     * router per graph. Flat graphs only.
     */
    classify(scorer: IntentScorer, policy?: Partial<RoutingPolicy>): SkillGraphBuilder;
    /**
     * Declare phrasings this graph must claim **NOWHERE** — the negative form of
     * a rule's `examples`, and the one that catches the expensive failure.
     *
     * An under-triggering skill costs a turn (the model tier picks instead). An
     * OVER-triggering skill costs the answer: the wrong body enters the system
     * prompt and the wrong tools enter the tools slot, and everything said after
     * that is shaped by a skill with no business in the turn.
     *
     * It is declared on the GRAPH, not on a skill, because a phrase that must
     * route nowhere belongs to no skill: the assertion is satisfied only when
     * EVERY rule declines, and a row hung on one skill would vanish the day that
     * skill was deleted — exactly when a graph is re-partitioned, which is
     * exactly when over-triggering appears.
     *
     * `graph.checkup()` runs every declared start condition over the phrase on a
     * cold-start context and reports the rule that claims it, BY NAME, as an
     * ERROR (`never-routes-claimed`) — so a default `.build()` refuses.
     *
     * **What it proves, exactly:** no declared start RULE claims the phrase. Not
     * "no routing at all": an intent rule is judged by a classifier at run time, a
     * scorer / `.entryByRead()` menu ranks descriptions, and `read_skill` can
     * always open an open skill by name. That statement rides the report itself
     * (`checkup().notes`).
     *
     * Accepts one phrase or a list; call it as often as you like (rows
     * accumulate). A duplicate row is refused — one row already asserts it
     * against every rule.
     *
     * @example
     *   skillGraph()
     *     .entry(billing, { match: { keywords: ['refund', 'charge'] } })
     *     .neverRoutes(["what's the weather in Berlin"])
     *     .build();
     */
    neverRoutes(phrases: string | readonly string[]): SkillGraphBuilder;
    build(opts?: BuildOptions): SkillGraph;
}
export declare function skillGraph(): SkillGraphBuilder;
export declare function skillGraph(config: SkillGraphConfig): SkillGraph;
/**
 * The official vocabulary (9.51.0): you declare the **SkillMap**; the agent
 * is the **SkillWalker**; the recording carries both.
 *
 * `defineSkillMap` is a PERMANENT thin alias of {@link skillGraph} — the same
 * function object (reference-equal), same overloads, both names exported
 * forever; neither is a rename of the other. Use whichever reads better:
 * `defineSkillMap({...})` beside `defineSkill({...})` says what you are
 * doing; `skillGraph()` says what you get.
 *
 * There is deliberately NO `SkillWalker` export. The walker is not a thing
 * you construct — it is the agent itself (`.skillGraph(map)` mounts the map;
 * the agent walks it), moving the cursor by exactly three movers, every move
 * on the record as `cursorMove`:
 *
 *   • **llm**    — the model picks via `read_skill`, bounded by the gate
 *                  (`by: 'model-pick'`; refusals are `skill.rejected`);
 *   • **guard**  — your DATA decides: a `when`/`onToolReturn`/`onToolStatus`/
 *                  `guard:` edge fires, evidence recorded (`by: 'route'`,
 *                  with `cursorMove.guard` when a data guard judged it);
 *   • **linear** — no choice: a bare hand-off that fires every time its
 *                  source finishes (an `onToolReturn` edge with one target —
 *                  the degenerate guard).
 */
export declare const defineSkillMap: typeof skillGraph;
/** The declared graph a SkillWalker walks — a permanent alias of
 *  {@link SkillGraph}, exported forever beside it (9.51.0). */
export type SkillMap = SkillGraph;
/**
 * WHICH CLASS OF TARGET a `read_skill` id is, from one cursor — the ONE owner
 * of the question every gate, description and refusal used to answer for
 * itself (9.86.0).
 *
 * ── THE LAW ───────────────────────────────────────────────────────────────
 *
 *   THE CURSOR IS A LEGITIMATE TARGET OF A READ (a stay), NEVER OF A MOVE.
 *
 * {@link makeReachableSkills} filters the cursor out of its own successor set,
 * and that is correct for a MOVE: there is nowhere to move to. It was then read
 * by five different consumers as "not available", which is a different claim and
 * a false one — the cursor's body is in the prompt and its tools are on the wire.
 * Each consumer that noticed wrote its own `requested === cursor` check; the two
 * that did not (the tool-effects `propose-transition` judge and the `skill_read`
 * permission gate) refused a stay as if it were a move.
 *
 * Four classes, in the order the gate must consider them:
 *
 *   • `'self'`        — the cursor itself. A stay: nothing activates, nothing
 *                       moves, nothing is read that was not already sent.
 *   • `'hop'`         — a declared successor of the cursor. The one class that
 *                       MOVES the cursor.
 *   • `'open'`        — a skill the graph wires no edge into (a `.selfExplain()`
 *                       skill, a `.skill()` registered beside the graph). It
 *                       activates and never moves the cursor.
 *   • `'unreachable'` — everything else.
 *
 * `'hop'` beats `'open'` when an id is in both sets: the move is the stronger
 * fact, and a caller that reports the id as merely open would lose it.
 *
 * Pure and total: no cursor (cold start) simply means nothing can be `'self'`.
 */
export type SkillTargetClass = 'self' | 'hop' | 'open' | 'unreachable';
/**
 * Classify one `read_skill` target against one cursor. See
 * {@link SkillTargetClass} for the law this function owns.
 *
 * @example
 * ```ts
 * classifySkillTarget({ cursor: 'billing', target: 'billing' });               // 'self'
 * classifySkillTarget({ cursor: 'billing', target: 'refunds', hops: ['refunds'] }); // 'hop'
 * classifySkillTarget({ cursor: 'billing', target: 'debug', open: ['debug'] });     // 'open'
 * classifySkillTarget({ cursor: 'billing', target: 'vault' });                 // 'unreachable'
 * ```
 */
export declare function classifySkillTarget(args: {
    /** Where the cursor stands. `undefined` = cold start (nothing is a stay). */
    readonly cursor?: string;
    /** The id the model asked for. */
    readonly target: string;
    /** Declared successors of the cursor — `reachableSkills(cursor)`. */
    readonly hops?: readonly string[];
    /** Skills the graph wires no edge into. */
    readonly open?: readonly string[];
}): SkillTargetClass;