agentfootprint/dist/esm/injection-engine/skillPartition.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * 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`.
 */
import type { GraphProblem } from './skillGraphCheckup.js';
import type { Injection } from './types.js';
/** What the partition check reads. Counts, because that is what the signals
 *  are about — no check here reasons about which edge goes where. */
export interface PartitionInput {
    /** Every skill in the graph (wired or not). */
    readonly skills: readonly Injection[];
    /** Declared routes, of any kind (a bare/model edge is still a declared
     *  handoff — the signal is about handoffs that were never written down at
     *  all, not about how deterministic they are). */
    readonly routeCount: number;
    /** Declared entries — quoted in the ratio message so the fact is complete. */
    readonly entryCount: number;
    /** A decision `tree()` owns its own routing and declares no routes by
     *  construction, so the edge-ratio signal does not apply there. */
    readonly isTree: boolean;
}
/**
 * Run the three partition signals. Pure, and cheap: one pass over the skills
 * and two integers. Every problem it produces is a WARNING.
 */
export declare function checkPartition(input: PartitionInput): GraphProblem[];