bantamkit-mcp 0.26.0

package/dist/shiftwork.d.ts

@@ -0,0 +1,60 @@
+import { type PyValue } from './pyjson.js';
+export declare const SCHEMA_NAME = "shiftwork-checkpoint";
+/** The driver's SUCCESS test. */
+export declare const TERMINAL_UNIT_STATUS: ReadonlySet<string>;
+/** The schema's `maxItems` — older entries fall off the ring. */
+export declare const HISTORY_RING_SIZE = 5;
+/**
+ * `time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now))` — UTC, SECOND precision.
+ *
+ * `Date.prototype.toISOString` would write `2025-08-23T06:20:00.000Z`: three digits and a
+ * dot that no line Python ever appended to a `.log.jsonl` contains. `gmtime` also FLOORS
+ * its float argument rather than rounding it, which is visible for every `.999`.
+ */
+export declare function timestamp(now: number): string;
+/** The injectable clock. Python reads `time.time()`; a test and the differential pin it. */
+export interface ClockOptions {
+    /** Seconds since the epoch, as `time.time()` returns them. */
+    now?: number;
+}
+/**
+ * Validate the checkpoint and return the cursor unit's brief, or a refusal.
+ *
+ * `invariants` IS SYNTHESIZED HERE. It is not a key of the checkpoint — it is
+ * `document["job"]["constraints"]` under a different name — which is precisely why a brief
+ * has to be handed to a subagent verbatim and not as a path: the file at that path does not
+ * contain the array. Same for `do_not`, which is `handoff.do_not`, and `files`, which is
+ * `state.artifacts`.
+ *
+ * Order is load-bearing: open questions are checked BEFORE the all-terminal test, and the
+ * all-terminal test before the cursor lookup — so an empty plan reports success rather than
+ * escalating on its dangling cursor, because `all([])` is true.
+ */
+export declare function clockIn(checkpoint: string): PyValue;
+/**
+ * Apply the cursor unit's result, validate the WHOLE mutated document, write atomically.
+ *
+ * `unitId` must name the cursor unit — the contract is execute-the-cursor (driver parity),
+ * never pick-a-unit. Mutations: set the unit's status, advance `plan.cursor` to the first
+ * non-terminal unit in PLAN order (`depends_on` is ignored), shallow-merge `handoffPatch`
+ * into `handoff`, push `historyEntry` onto the 5-entry ring.
+ *
+ * VALIDATE BEFORE WRITING, AND WRITE NOTHING ON REFUSAL. The mutated document goes through
+ * the full schema before the first byte leaves; a failure returns `refused to write: …` and
+ * has touched neither the checkpoint nor the log — not even in the case where the log
+ * append would have succeeded, which is the one a reader assumes is safe because the log is
+ * append-only.
+ *
+ * Key ORDER survives the mutation because a `Map.set` on an existing key keeps its slot,
+ * exactly as CPython's dict does, and `json.dumps` here runs with `sort_keys=False`. A port
+ * that rebuilt the document from an object literal would reorder `handoff` on every merge.
+ */
+export declare function clockOut(checkpoint: string, unitId: string, status: string, handoffPatch: unknown, historyEntry: unknown, accounting?: unknown, options?: ClockOptions): PyValue;
+/**
+ * Read-only progress summary. Never mutates.
+ *
+ * `units` is a count per status in FIRST-SEEN order — a plain `dict` built by iteration, so
+ * its key order is the order the statuses appear in the plan and not an alphabetical one.
+ * The result is dumped without `sort_keys` on the wire, so that order is observable.
+ */
+export declare function status(checkpoint: string): PyValue;

package/dist/shiftwork.js

@@ -0,0 +1,324 @@
+/**
+ * Shift-work checkpoint operations — a port of `runtime-py/src/bantamkit/shiftwork.py`,
+ * statement for statement.
+ *
+ * The control flow is 78 executable statements and none of it is hard. The risk is
+ * entirely in how the two runtimes SERIALIZE, and the checkpoint bantamkit's own jobs are
+ * run from is one of the files at stake. Three artefacts leave this module and only one of
+ * them is ever read back:
+ *
+ *   * the rewritten checkpoint — `json.dumps(document, indent=2) + "\n"`, `.tmp` then
+ *     `replace()`;
+ *   * the `.log.jsonl` line — `json.dumps(record, sort_keys=True) + "\n"`, append mode,
+ *     **never read back**, so a wrong line is never noticed by the code that wrote it;
+ *   * the returned dict, which the MCP surface hands straight to the model.
+ *
+ * THE ensure_ascii RULING. `json.dumps` defaults to `ensure_ascii=True` and
+ * `JSON.stringify` has no such mode. Node must reproduce Python's escaping, not the other
+ * way round: the reference implementation is the one that has already written every
+ * checkpoint on disk (measured — `.shiftwork/job38-npx-public-install/checkpoint.json`
+ * carries 1 `เ` run and 16 `—`, and not one raw non-ASCII byte), and a Node
+ * clock_out that emitted raw UTF-8 would rewrite all 29 KB of it on its first successful
+ * call. Nothing would error: the file still parses to the same strings. It would just stop
+ * being diffable against the Python server's output, silently, from then on. So the escape
+ * is the contract, and `pyjson.dumpJson` is where it lives — with the other three rules
+ * (separators, codepoint `sort_keys`, `5.0` stays a float) that a `JSON.stringify` would
+ * also have got wrong.
+ *
+ * WHY THE DOCUMENT IS A `PyValue` AND NOT A PLAIN OBJECT. `1` and `1.0` are one type in JS.
+ * A checkpoint or an accounting record that came off the wire holding `5.0` has to leave
+ * holding `5.0`, and an integer past 2^53 has to survive; both need the tagged model
+ * `pyjson.ts` already carries. The three entry points therefore return `PyValue`, and the
+ * MCP layer converts with `pyjson.toJs` at the last moment.
+ *
+ * WHAT IS NOT PORTED, DELIBERATELY. The `depends_on` field is ignored on cursor advance
+ * (v1-linear, the Python module's own ruling), there is no lock (the MCP topology has one
+ * orchestrator by construction), and log-then-commit ordering is preserved exactly: the
+ * accounting line is appended BEFORE the atomic rename, so a partial failure can lose the
+ * commit but never the accounting.
+ */
+import { loadSchema } from './assets.js';
+import { schemaError } from './contract.js';
+import { pyAppendText, pyJoin, PyOSError, pyReplace, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, pyReadText, } from './memory/pyfs.js';
+import { dumpJson, fromJs, parseJson, PyJSONDecodeError } from './pyjson.js';
+export const SCHEMA_NAME = 'shiftwork-checkpoint';
+/** The driver's SUCCESS test. */
+export const TERMINAL_UNIT_STATUS = new Set(['done', 'dropped']);
+/** The schema's `maxItems` — older entries fall off the ring. */
+export const HISTORY_RING_SIZE = 5;
+// ------------------------------------------------------------------- tagged-value sugar
+const str = (v) => ({ t: 'str', v });
+const int = (v) => ({ t: 'int', v: BigInt(v) });
+const dict = (entries) => ({ t: 'dict', v: new Map(entries) });
+/** The document is schema-valid before any of these run, so the shapes are guaranteed. */
+const field = (d, key) => d.v.get(key);
+const subDict = (d, key) => field(d, key);
+const subList = (d, key) => field(d, key);
+const text = (v) => v.v;
+/**
+ * Whatever the caller handed over, as a `PyValue`.
+ *
+ * A value that is already tagged passes through EXACTLY — that is the route that keeps
+ * `5.0` a float, and the MCP layer should take it wherever it still holds the wire bytes
+ * (`pyjson.parseJson` over the raw arguments). A plain JS value goes through `fromJs` and
+ * takes its one documented loss: an integral JS number cannot remember that its JSON text
+ * said `5.0`, so a `{"tokens": 5.0}` that has already been through an SDK's `JSON.parse`
+ * logs as `5` where Python logs `5.0`. Ruled and pinned in
+ * `tools/conformance/suites/shiftwork.mjs`; the loss is upstream of this module, not in it.
+ */
+function asPyValue(value) {
+    return isPyValue(value) ? value : fromJs(value);
+}
+function isPyValue(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        't' in value &&
+        typeof value.t === 'string' &&
+        ['null', 'bool', 'int', 'float', 'str', 'list', 'dict'].includes(value.t));
+}
+/** `dict(x) if x else {}` — `None` and `{}` are both the empty patch. */
+function asPatch(value) {
+    if (value === null || value === undefined)
+        return new Map();
+    const lifted = asPyValue(value);
+    return lifted.t === 'dict' ? lifted.v : new Map();
+}
+// ------------------------------------------------------------------------------- shared
+function errorResult(reason) {
+    return dict([
+        ['result', str('error')],
+        ['reason', str(reason)],
+    ]);
+}
+/**
+ * Read and full-schema-validate. Returns `{document}` or `{refusal}`.
+ *
+ * Three refusals in Python's order, and the exceptions that are NOT caught matter as much
+ * as the ones that are: `read_text` raises `UnicodeDecodeError` on invalid UTF-8 and that
+ * is a `ValueError`, not an `OSError`, so it escapes to the caller in both runtimes.
+ *
+ * `schema_error` is handed the raw TEXT rather than the parsed document, exactly as Python
+ * does, so the checkpoint goes through `extract_json` + the decoder a second time and any
+ * disagreement between the two parses would show up here rather than at write time.
+ */
+function readValid(path) {
+    let raw;
+    try {
+        raw = pyReadText(path);
+    }
+    catch (e) {
+        if (e instanceof PyOSError)
+            return { document: null, refusal: errorResult(`checkpoint unreadable: ${e.message}`) };
+        throw e;
+    }
+    let document;
+    try {
+        document = parseJson(raw);
+    }
+    catch (e) {
+        if (e instanceof PyJSONDecodeError) {
+            return { document: null, refusal: errorResult(`checkpoint is not parseable as JSON: ${e.message}`) };
+        }
+        throw e;
+    }
+    const problem = schemaError(raw, loadSchema(SCHEMA_NAME));
+    if (problem !== null)
+        return { document: null, refusal: errorResult(`checkpoint invalid: ${problem}`) };
+    return { document: document, refusal: null };
+}
+function findUnit(document, unitId) {
+    for (const unit of subList(subDict(document, 'plan'), 'units').v) {
+        if (unit.v.get('id') !== undefined && text(unit.v.get('id')) === unitId) {
+            return unit;
+        }
+    }
+    return null;
+}
+/**
+ * `time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now))` — UTC, SECOND precision.
+ *
+ * `Date.prototype.toISOString` would write `2025-08-23T06:20:00.000Z`: three digits and a
+ * dot that no line Python ever appended to a `.log.jsonl` contains. `gmtime` also FLOORS
+ * its float argument rather than rounding it, which is visible for every `.999`.
+ */
+export function timestamp(now) {
+    const when = new Date(Math.floor(now) * 1000);
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    return (`${pad(when.getUTCFullYear(), 4)}-${pad(when.getUTCMonth() + 1)}-${pad(when.getUTCDate())}` +
+        `T${pad(when.getUTCHours())}:${pad(when.getUTCMinutes())}:${pad(when.getUTCSeconds())}Z`);
+}
+// ----------------------------------------------------------------------------- clock_in
+/**
+ * Validate the checkpoint and return the cursor unit's brief, or a refusal.
+ *
+ * `invariants` IS SYNTHESIZED HERE. It is not a key of the checkpoint — it is
+ * `document["job"]["constraints"]` under a different name — which is precisely why a brief
+ * has to be handed to a subagent verbatim and not as a path: the file at that path does not
+ * contain the array. Same for `do_not`, which is `handoff.do_not`, and `files`, which is
+ * `state.artifacts`.
+ *
+ * Order is load-bearing: open questions are checked BEFORE the all-terminal test, and the
+ * all-terminal test before the cursor lookup — so an empty plan reports success rather than
+ * escalating on its dangling cursor, because `all([])` is true.
+ */
+export function clockIn(checkpoint) {
+    const { document, refusal } = readValid(pyJoin(checkpoint));
+    if (refusal !== null)
+        return refusal;
+    const doc = document;
+    const handoff = subDict(doc, 'handoff');
+    const openQuestions = subList(handoff, 'open_questions');
+    if (openQuestions.v.length > 0) {
+        return dict([
+            ['result', str('escalate')],
+            ['reason', str(`open question: ${text(openQuestions.v[0])}`)],
+            ['open_questions', openQuestions],
+        ]);
+    }
+    const units = subList(subDict(doc, 'plan'), 'units');
+    if (units.v.every((u) => TERMINAL_UNIT_STATUS.has(text(u.v.get('status'))))) {
+        return dict([
+            ['result', str('success')],
+            ['reason', str('all units done or dropped')],
+        ]);
+    }
+    const cursor = text(field(subDict(doc, 'plan'), 'cursor'));
+    const unit = findUnit(doc, cursor);
+    if (unit === null) {
+        return dict([
+            ['result', str('escalate')],
+            ['reason', str(`cursor ${cursor} names no unit`)],
+        ]);
+    }
+    return dict([
+        ['result', str('brief')],
+        ['unit', unit],
+        ['role', field(unit, 'role')],
+        ['invariants', field(subDict(doc, 'job'), 'constraints')],
+        ['handoff', handoff],
+        ['do_not', field(handoff, 'do_not')],
+        ['files', field(subDict(doc, 'state'), 'artifacts')],
+    ]);
+}
+// ---------------------------------------------------------------------------- clock_out
+/**
+ * Apply the cursor unit's result, validate the WHOLE mutated document, write atomically.
+ *
+ * `unitId` must name the cursor unit — the contract is execute-the-cursor (driver parity),
+ * never pick-a-unit. Mutations: set the unit's status, advance `plan.cursor` to the first
+ * non-terminal unit in PLAN order (`depends_on` is ignored), shallow-merge `handoffPatch`
+ * into `handoff`, push `historyEntry` onto the 5-entry ring.
+ *
+ * VALIDATE BEFORE WRITING, AND WRITE NOTHING ON REFUSAL. The mutated document goes through
+ * the full schema before the first byte leaves; a failure returns `refused to write: …` and
+ * has touched neither the checkpoint nor the log — not even in the case where the log
+ * append would have succeeded, which is the one a reader assumes is safe because the log is
+ * append-only.
+ *
+ * Key ORDER survives the mutation because a `Map.set` on an existing key keeps its slot,
+ * exactly as CPython's dict does, and `json.dumps` here runs with `sort_keys=False`. A port
+ * that rebuilt the document from an object literal would reorder `handoff` on every merge.
+ */
+export function clockOut(checkpoint, unitId, status, handoffPatch, historyEntry, accounting = null, options = {}) {
+    const path = pyJoin(checkpoint);
+    const { document, refusal } = readValid(path);
+    if (refusal !== null)
+        return refusal;
+    const doc = document;
+    const unit = findUnit(doc, unitId);
+    if (unit === null)
+        return errorResult(`unit ${unitId} is not in the plan`);
+    const plan = subDict(doc, 'plan');
+    const cursor = text(field(plan, 'cursor'));
+    if (unitId !== cursor)
+        return errorResult(`unit ${unitId} is not the cursor unit ${cursor}`);
+    unit.v.set('status', str(status));
+    const remaining = subList(plan, 'units').v.filter((u) => !TERMINAL_UNIT_STATUS.has(text(u.v.get('status'))));
+    plan.v.set('cursor', remaining.length > 0 ? field(remaining[0], 'id') : str(unitId));
+    const handoff = subDict(doc, 'handoff');
+    for (const [key, value] of asPatch(handoffPatch))
+        handoff.v.set(key, value);
+    const history = subList(doc, 'history');
+    doc.v.set('history', {
+        t: 'list',
+        v: [...history.v, asPyValue(historyEntry)].slice(-HISTORY_RING_SIZE),
+    });
+    const problem = schemaError(dumpJson(doc), loadSchema(SCHEMA_NAME));
+    if (problem !== null)
+        return errorResult(`refused to write: ${problem}`);
+    // `record.update(accounting or {})`: the four keys the record starts with are OVERRIDABLE
+    // by the orchestrator's accounting, and `sort_keys=True` means the merge order never
+    // reaches the file anyway.
+    const record = new Map([
+        ['ts', str(timestamp(options.now ?? Date.now() / 1000))],
+        ['unit', str(unitId)],
+        ['role', field(unit, 'role')],
+        ['status', str(status)],
+    ]);
+    for (const [key, value] of asPatch(accounting))
+        record.set(key, value);
+    // `Path(str(path) + ".log.jsonl")` — string concatenation on the NORMALIZED path, not
+    // `with_suffix`, so `cp.json` gets `cp.json.log.jsonl` and not `cp.log.jsonl`.
+    const logPath = `${path}.log.jsonl`;
+    try {
+        pyAppendText(logPath, `${dumpJson({ t: 'dict', v: record }, { sortKeys: true })}\n`);
+    }
+    catch (e) {
+        if (!(e instanceof PyOSError))
+            throw e;
+        return errorResult(`accounting log unwritable, checkpoint untouched: ${e.message}`);
+    }
+    const tmp = pyWithSuffix(path, `${pySuffix(path)}.tmp`);
+    try {
+        pyWriteText(tmp, `${dumpJson(doc, { indent: 2 })}\n`);
+        pyReplace(tmp, path);
+    }
+    catch (e) {
+        if (!(e instanceof PyOSError))
+            throw e;
+        // `contextlib.suppress(OSError)` — the cleanup's own failure is not the story.
+        try {
+            pyUnlink(tmp);
+        }
+        catch (cleanup) {
+            if (!(cleanup instanceof PyOSError))
+                throw cleanup;
+        }
+        return errorResult(`checkpoint unwritable, last log line uncommitted: ${e.message}`);
+    }
+    return dict([
+        ['result', str('ok')],
+        ['unit', str(unitId)],
+        ['status', str(status)],
+        ['cursor', field(plan, 'cursor')],
+        ['log', str(logPath)],
+    ]);
+}
+// ------------------------------------------------------------------------------- status
+/**
+ * Read-only progress summary. Never mutates.
+ *
+ * `units` is a count per status in FIRST-SEEN order — a plain `dict` built by iteration, so
+ * its key order is the order the statuses appear in the plan and not an alphabetical one.
+ * The result is dumped without `sort_keys` on the wire, so that order is observable.
+ */
+export function status(checkpoint) {
+    const { document, refusal } = readValid(pyJoin(checkpoint));
+    if (refusal !== null)
+        return refusal;
+    const doc = document;
+    const counts = new Map();
+    for (const unit of subList(subDict(doc, 'plan'), 'units').v) {
+        const key = text(unit.v.get('status'));
+        const seen = counts.get(key);
+        counts.set(key, int(seen === undefined ? 1 : Number(seen.v) + 1));
+    }
+    const history = subList(doc, 'history');
+    return dict([
+        ['result', str('status')],
+        ['cursor', field(subDict(doc, 'plan'), 'cursor')],
+        ['units', { t: 'dict', v: counts }],
+        ['open_questions', int(subList(subDict(doc, 'handoff'), 'open_questions').v.length)],
+        ['last_history', history.v.length > 0 ? history.v[history.v.length - 1] : { t: 'null' }],
+    ]);
+}

package/dist/skillaudit.d.ts

@@ -0,0 +1,172 @@
+import { BantamError } from './errors.js';
+export declare const SKILL_FILE = "SKILL.md";
+export declare const OMIT_NOT_ENABLED = "plugin-not-enabled";
+export declare const OMIT_DUPLICATE = "duplicate-skill";
+export declare const OMIT_STALE_VERSION = "stale-version";
+export declare const OMIT_UNREADABLE = "unreadable-file";
+export declare const OMIT_UNPARSED = "unparsed-frontmatter";
+/**
+ * Reporting order for omissions. Fixed, so two runtimes emit the same document. The two
+ * version subjects are adjacent because they are the two halves of one rule.
+ */
+export declare const OMISSION_ORDER: readonly ["plugin-not-enabled", "duplicate-skill", "stale-version", "unreadable-file", "unparsed-frontmatter"];
+export declare const KIND_SHARED_PHRASE = "shared-trigger-phrase";
+export declare const KIND_OVER_BUDGET = "catalogue-over-budget";
+export declare const KIND_NEVER_INVOKED = "never-invoked";
+export declare const KIND_FRONTMATTER = "frontmatter-malformed";
+export declare const KIND_NAME_MISMATCH = "name-mismatch";
+export declare const SEVERITY: Readonly<Record<string, string>>;
+/** Reporting order for findings, and the order the contract lists them in. */
+export declare const FINDING_ORDER: readonly ["shared-trigger-phrase", "catalogue-over-budget", "never-invoked", "frontmatter-malformed", "name-mismatch"];
+/**
+ * `check` selects a FAMILY, not a kind: an operator asking about the bill wants both the
+ * overage and the skills nobody ever called, and one asking about frontmatter wants both the
+ * block that will not parse and the name that does not match its directory.
+ */
+export declare const CHECK_FAMILIES: Readonly<Record<string, readonly string[]>>;
+export declare const BAD_NO_BLOCK = "no-frontmatter";
+export declare const BAD_UNTERMINATED = "unterminated-frontmatter";
+export declare const BAD_NO_DESCRIPTION = "no-description";
+/**
+ * The audit could not be run at all: the message names what was seen at `root`.
+ *
+ * Reserved for a failure of the SCAN. A file that will not decode, a block that will not
+ * parse and a plugin that is switched off are all recorded as omissions and counted, never
+ * raised: an audit that refuses because one of twenty-six files is malformed has told the
+ * operator nothing about the other twenty-five.
+ */
+export declare class SkillAuditError extends BantamError {
+}
+export interface OmissionDict {
+    readonly subject: string;
+    readonly count: number;
+    readonly size: number;
+    readonly what: string;
+}
+/**
+ * A `SKILL.md` that was found and not counted, as a COUNT and the fact behind it.
+ *
+ * `size` is the UTF-8 description bytes those files would have added to the catalogue, `0`
+ * where that is not knowable — exactly the two cases where the description could not be read
+ * at all. `what` is the paths, relative to the root, in scan order.
+ */
+export declare class Omission {
+    readonly subject: string;
+    readonly count: number;
+    readonly size: number;
+    readonly what: string;
+    constructor(subject: string, count: number, size?: number, what?: string);
+    asDict(): OmissionDict;
+}
+export interface FindingDict {
+    readonly kind: string;
+    readonly severity: string;
+    readonly skills: string[];
+    readonly detail: string;
+}
+/**
+ * One thing wrong with the catalogue.
+ *
+ * `severity` is not stored independently — it is `SEVERITY[kind]`, fixed per kind. `detail`
+ * is a machine fact and not a sentence. Wording for a person is Layer 2's job.
+ */
+export declare class Finding {
+    readonly kind: string;
+    readonly skills: readonly string[];
+    readonly detail: string;
+    constructor(kind: string, skills: readonly string[], detail: string);
+    get severity(): string;
+    asDict(): FindingDict;
+}
+export interface AuditDict {
+    readonly roots: string[];
+    readonly skills: number;
+    readonly catalogue_bytes: number;
+    readonly findings: FindingDict[];
+    readonly omissions: OmissionDict[];
+}
+/** The whole answer. `skills` plus every omission's `count` is every `SKILL.md` found. */
+export declare class Audit {
+    readonly roots: readonly string[];
+    readonly skills: number;
+    readonly catalogueBytes: number;
+    readonly findings: readonly Finding[];
+    readonly omissions: readonly Omission[];
+    constructor(roots: readonly string[], skills: number, catalogueBytes: number, findings?: readonly Finding[], omissions?: readonly Omission[]);
+    asDict(): AuditDict;
+    /**
+     * Two-space indent and no ASCII escaping, so the reference's
+     * `json.dumps(..., indent=2, ensure_ascii=False)` produces the same bytes.
+     */
+    asJson(): string;
+}
+/**
+ * A whole-value quoted YAML scalar without its quotes; every other value unchanged.
+ *
+ * `"Use when a test is \"flaky in prod\""` is one scalar and unwraps. `"a" and "b"` opens and
+ * ends with `"` and is NOT one — its first quote closes at index 2 — so it is left alone and
+ * both of its phrases survive. `"never closed` never closes and is left alone too.
+ */
+export declare function unwrapScalar(value: string): string;
+/**
+ * Every literal quoted phrase in `text`, in order, deduplicated.
+ *
+ * Delimiters are paired sequentially — first with second, third with fourth — per quote
+ * character, and an unpaired trailing delimiter opens nothing.
+ */
+export declare function phrases(text: string): string[];
+export interface AuditOptions {
+    /** Plugin ids that are switched on, `<plugin>@<marketplace>`. `null` counts everything. */
+    readonly enabled?: readonly string[] | null;
+    /** The caller's own call counts, keyed by skill id. `null` is NO measurement. */
+    readonly usage?: ReadonlyMap<string, number | bigint> | null;
+    /** Which family of findings to report; `all` by default. */
+    readonly check?: string;
+    /** The catalogue byte budget. `null` means the budget finding cannot fire. */
+    readonly budget?: number | bigint | null;
+    /**
+     * The version directory the host actually serves, per `<plugin>@<marketplace>`. Host truth
+     * the caller supplies, the same class of argument `enabled` is; a plugin absent from it
+     * falls back to the byte order. `null` is every plugin absent.
+     */
+    readonly versions?: ReadonlyMap<string, string> | null;
+}
+/**
+ * Walk `root` and answer the whole audit.
+ *
+ * `usage` omitted is not the same as `usage` empty. An empty map is a measurement saying
+ * nothing was called; an absent map is no measurement at all, and reporting every skill as
+ * `never-invoked` on the strength of it would be an assertion about data this tool was never
+ * given. So `never-invoked` fires only when `usage` is supplied — the same discipline
+ * `catalogue-over-budget` follows for `budget`.
+ *
+ * An empty `root` is refused rather than resolved: `Path("")` is `Path(".")` on the reference
+ * and `statSync('')` throws here, so the two answered a CWD-relative audit and a refusal for
+ * the same input, and the reference's half contradicts the determinism the contract claims.
+ *
+ * `versions` is the same kind of argument `enabled` is: host truth the caller supplies rather
+ * than a fact this tool can read off `root`. It names, per `<plugin>@<marketplace>`, the
+ * version directory the host actually serves; a plugin absent from it falls back to the byte
+ * order, which is deterministic and — among names that are not versions — arbitrary.
+ *
+ * `skills`, `catalogueBytes` and `omissions` are reported whatever `check` says: they are the
+ * measurement, and `check` selects which family of FINDINGS is worth reporting on top of it.
+ */
+/** One `SKILL.md` as `scan` hands it back: the record `audit` then counts or omits. */
+export interface ScannedSkill {
+    readonly id: string;
+    readonly relpath: string;
+    readonly directory: string;
+    readonly marketplace: string;
+    readonly plugin: string;
+    readonly version: string;
+    readonly description: string;
+    readonly name: string;
+    readonly router: boolean;
+    readonly omitted: string | null;
+    readonly malformed: string | null;
+    readonly phrases: readonly string[];
+    readonly bytes: number;
+}
+export declare function scan(root: string, enabled?: readonly string[] | null, versions?: ReadonlyMap<string, string> | null): ScannedSkill[];
+export declare function audit(root: string, options?: AuditOptions): Audit;