@skill-map/cli 0.7.0 → 0.9.0

package/dist/kernel/index.d.ts

@@ -0,0 +1,2531 @@
+/**
+ * Domain types — byte-aligned with `spec/schemas/{node,link,issue,scan-result}.schema.json`.
+ *
+ * The kernel is the reference consumer of the spec; these types are therefore
+ * derived from the schemas, not invented. When a schema changes, this file
+ * follows. Until automatic AJV-driven derivation lands, the mapping is
+ * hand-maintained and the release gate is the conformance suite.
+ *
+ * --- Naming convention (kernel-wide) -------------------------------------
+ *
+ * Four categories with distinct prefix rules; the rules are deliberate
+ * even though they look mixed at first read:
+ *
+ *   1. **Domain types** — every shape that mirrors a `spec/schemas/*.json`
+ *      file: `Node`, `Link`, `Issue`, `ScanResult`, `ScanStats`,
+ *      `ExecutionRecord`, `HistoryStats`, …. **No prefix.** Names track
+ *      the spec verbatim because the spec is the source of truth.
+ *      Renaming any of these is a spec change.
+ *
+ *   2. **Hexagonal ports** — the abstract boundaries the kernel calls
+ *      out to (`StoragePort`, `RunnerPort`, `ProgressEmitterPort`,
+ *      `FilesystemPort`, `PluginLoaderPort`). **`Port` suffix.** The
+ *      suffix calls out the architectural role and avoids name clashes
+ *      with the concrete adapter classes (`SqliteStorageAdapter`
+ *      implements `StoragePort`).
+ *
+ *   3. **Runtime extension contracts** — what a plugin author
+ *      implements: `IProvider`, `IExtractor`, `IRule`, `IFormatter`,
+ *      `IExtensionBase`. **`I` prefix.** The prefix flags "this is a
+ *      contract you supply, not a value the kernel hands you" — same
+ *      reading as the rest of TypeScript's plugin ecosystems where a
+ *      shape is implementable.
+ *
+ *   4. **Internal shapes** — option bags, result records, config
+ *      slices, anything passed across function boundaries inside the
+ *      kernel / CLI but not part of the spec: `IRunScanOptions` (well,
+ *      `RunScanOptions` — see below), `IPluginRuntimeBundle`,
+ *      `IPruneResult`, `IMigrationFile`, `IDbLocationOptions`. **`I`
+ *      prefix.** The prefix matches category 3 because both are
+ *      "shapes that live in TypeScript only, never in JSON".
+ *
+ * Edge cases worth knowing:
+ *   - The following category-4 names lack the `I` prefix because
+ *     they are part of the public kernel surface and renaming is a
+ *     breaking change for downstream consumers. The list is closed:
+ *       option bags / records: `RunScanOptions`, `RenameOp`;
+ *       TS-only exports from `kernel/index.ts` / `kernel/ports/*`:
+ *         `Kernel`, `ProgressEvent`, `LogRecord`, `NodeStat`.
+ *     New public option bags and TS-only exports MUST still use
+ *     `I*`; removing a name from this list is a breaking change.
+ *   - `IDatabase` (SQLite schema) is category 4 but lives in
+ *     `adapters/sqlite/schema.ts`, not here. Same rule applies.
+ *
+ * If you find yourself wanting to add a new type and aren't sure which
+ * bucket it falls in: ask "does this shape exist in the spec?". If
+ * yes, no prefix and align the name with the schema. If no, `I`
+ * prefix.
+ */
+/**
+ * The five node kinds the **built-in Claude Provider** declares — `skill`,
+ * `agent`, `command`, `hook`, `note`. **NOT** the kernel-wide kind type.
+ *
+ * `Node.kind` is `string`. An external Provider (Cursor, Obsidian, …)
+ * MAY classify into its own kinds (e.g. `'cursorRule'`, `'daily'`); the
+ * orchestrator, persistence layer, and AJV `node.schema.json` accept any
+ * non-empty string. Per `spec/db-schema.md` § scan_nodes and
+ * `node.schema.json#/properties/kind`, the contract is open-by-design
+ * (matches `IProvider.kinds` "open by design" docstring).
+ *
+ * This alias survives because:
+ *   - claude-specific code legitimately wants to switch on the five
+ *     hard-coded values (filter widgets, kind-aware UI cards, the
+ *     `validate-all` built-in rule that maps each kind to its
+ *     frontmatter schema);
+ *   - sorting helpers want a stable `KIND_ORDER` for the canonical
+ *     catalog;
+ *   - tests expect to enumerate the five kinds when seeding fixtures.
+ *
+ * For "any kind a Provider could declare", use plain `string`. Only use
+ * `NodeKind` when the code is intentionally claude-catalog-specific.
+ */
+type NodeKind = 'skill' | 'agent' | 'command' | 'hook' | 'note';
+type LinkKind = 'invokes' | 'references' | 'mentions' | 'supersedes';
+type Confidence = 'high' | 'medium' | 'low';
+type Severity = 'error' | 'warn' | 'info';
+type Stability = 'experimental' | 'stable' | 'deprecated';
+/**
+ * Execution mode of an analytical extension. Mirrors the per-kind capability
+ * matrix in `spec/architecture.md` §Execution modes:
+ *
+ *   - `deterministic` — pure code, runs synchronously inside `sm scan` /
+ *     `sm check`. Same input → same output, every run.
+ *   - `probabilistic` — calls an LLM through `RunnerPort`, dispatches only
+ *     as a queued job (`sm job submit <kind>:<id>`); never participates in
+ *     scan-time pipelines.
+ *
+ * Extractor / Rule / Action declare it directly (default `deterministic` when
+ * omitted in the manifest). Provider / Formatter are deterministic-only and
+ * MUST NOT carry the field.
+ */
+type TExecutionMode = 'deterministic' | 'probabilistic';
+interface TripleSplit {
+    frontmatter: number;
+    body: number;
+    total: number;
+}
+interface LinkTrigger {
+    originalTrigger: string;
+    normalizedTrigger: string;
+}
+interface LinkLocation {
+    line: number;
+    column?: number;
+    offset?: number;
+}
+interface Node {
+    path: string;
+    /**
+     * Provider-declared category. Open string (matches
+     * `node.schema.json#/properties/kind`): the built-in Claude Provider
+     * emits one of `NodeKind`'s values, but external Providers MAY emit
+     * their own. Code that intentionally switches on the claude catalog
+     * narrows via `if (kind === 'skill' \| ... )`; everything else
+     * accepts the open string and treats unknown values as opaque labels.
+     */
+    kind: string;
+    provider: string;
+    bodyHash: string;
+    frontmatterHash: string;
+    bytes: TripleSplit;
+    linksOutCount: number;
+    linksInCount: number;
+    externalRefsCount: number;
+    title?: string | null;
+    description?: string | null;
+    stability?: Stability | null;
+    version?: string | null;
+    author?: string | null;
+    frontmatter?: Record<string, unknown>;
+    tokens?: TripleSplit;
+}
+interface Link {
+    /** The originating node — the path of the file the extractor was reading
+     *  when it emitted this link. Singular, NOT to be confused with
+     *  `sources` (plural) below. */
+    source: string;
+    target: string;
+    kind: LinkKind;
+    confidence: Confidence;
+    /** Identifiers of the extractors / extensions that contributed evidence
+     *  for this link (one link can be confirmed by multiple extractors).
+     *  Plural; NOT the same as `source` (singular) above, which is the
+     *  originating node path. Naming is unfortunate but spec-frozen. */
+    sources: string[];
+    trigger?: LinkTrigger | null;
+    location?: LinkLocation | null;
+    raw?: string | null;
+}
+interface IssueFix {
+    summary?: string;
+    autofixable?: boolean;
+}
+interface Issue {
+    ruleId: string;
+    severity: Severity;
+    nodeIds: string[];
+    message: string;
+    linkIndices?: number[];
+    detail?: string | null;
+    fix?: IssueFix | null;
+    data?: Record<string, unknown>;
+}
+interface ScanStats {
+    /**
+     * Files visited by the Provider walkers. With a single Provider this
+     * matches `nodesCount`; with multiple Providers running on overlapping
+     * roots it can diverge (each yielded `IRawNode` is one walked file).
+     */
+    filesWalked: number;
+    /**
+     * Files walked but not classified by any Provider. Today every walked
+     * file is classified by its Provider (the `claude` Provider falls back to
+     * `'note'`), so this is always 0; the field will matter once multiple
+     * Providers can claim the same file.
+     */
+    filesSkipped: number;
+    nodesCount: number;
+    linksCount: number;
+    issuesCount: number;
+    durationMs: number;
+}
+interface ScanScannedBy {
+    name: string;
+    version: string;
+    specVersion: string;
+}
+type ExecutionKind = 'action';
+type ExecutionStatus = 'completed' | 'failed' | 'cancelled';
+type ExecutionFailureReason = 'runner-error' | 'report-invalid' | 'timeout' | 'abandoned' | 'job-file-missing' | 'user-cancelled';
+type ExecutionRunner = 'cli' | 'skill' | 'in-process';
+/**
+ * One row of execution history (`state_executions`). Matches
+ * `spec/schemas/execution-record.schema.json`. `nodeIds` is the camelCased
+ * domain field name; storage flattens it to `node_ids_json`.
+ */
+interface ExecutionRecord {
+    id: string;
+    kind: ExecutionKind;
+    extensionId: string;
+    extensionVersion: string;
+    nodeIds?: string[];
+    contentHash?: string | null;
+    status: ExecutionStatus;
+    failureReason?: ExecutionFailureReason | null;
+    exitCode?: number | null;
+    runner?: ExecutionRunner | null;
+    startedAt: number;
+    finishedAt: number;
+    durationMs?: number | null;
+    tokensIn?: number | null;
+    tokensOut?: number | null;
+    reportPath?: string | null;
+    jobId?: string | null;
+}
+interface HistoryStatsTotals {
+    executionsCount: number;
+    completedCount: number;
+    failedCount: number;
+    tokensIn: number;
+    tokensOut: number;
+    durationMsTotal: number;
+}
+interface HistoryStatsTokensPerAction {
+    actionId: string;
+    actionVersion: string;
+    executionsCount: number;
+    tokensIn: number;
+    tokensOut: number;
+    durationMsMean: number | null;
+    durationMsMedian: number | null;
+}
+interface HistoryStatsExecutionsPerPeriod {
+    periodStart: string;
+    periodUnit: 'day' | 'week' | 'month';
+    executionsCount: number;
+    tokensIn: number;
+    tokensOut: number;
+}
+interface HistoryStatsTopNode {
+    nodePath: string;
+    executionsCount: number;
+    lastExecutedAt: number;
+}
+interface HistoryStatsPerActionRate {
+    actionId: string;
+    rate: number;
+    executionsCount: number;
+    failedCount: number;
+}
+interface HistoryStatsErrorRates {
+    global: number;
+    perAction: HistoryStatsPerActionRate[];
+    perFailureReason: Record<ExecutionFailureReason, number>;
+}
+/**
+ * `sm history stats --json` payload, conforming to
+ * `spec/schemas/history-stats.schema.json`. `elapsedMs` is the command's
+ * own wall-clock per `cli-contract.md` §Elapsed time.
+ */
+interface HistoryStats {
+    schemaVersion: 1;
+    range: {
+        since: string | null;
+        until: string;
+    };
+    totals: HistoryStatsTotals;
+    tokensPerAction: HistoryStatsTokensPerAction[];
+    executionsPerPeriod: HistoryStatsExecutionsPerPeriod[];
+    topNodes: HistoryStatsTopNode[];
+    errorRates: HistoryStatsErrorRates;
+    elapsedMs: number;
+}
+interface ScanResult {
+    schemaVersion: 1;
+    /** Unix milliseconds when the scan started. */
+    scannedAt: number;
+    /** Scan scope. `project` walks the cwd repo; `global` walks user-level skill dirs. */
+    scope: 'project' | 'global';
+    /**
+     * Filesystem roots that were walked during this scan. Spec requires
+     * `minItems: 1` — `runScan` throws if `roots: []` is supplied.
+     */
+    roots: string[];
+    /** Provider ids that participated in classification. Empty if no Provider matched. */
+    providers: string[];
+    /** Implementation metadata. Populated by `runScan` for self-describing output. */
+    scannedBy?: ScanScannedBy;
+    nodes: Node[];
+    links: Link[];
+    issues: Issue[];
+    stats: ScanStats;
+}
+
+/**
+ * Extension registry — six kinds, first-class, loaded through a single API.
+ *
+ * The `Extension` shape is aligned with `spec/schemas/extensions/base.schema.json`.
+ * Kind-specific manifests (provider / extractor / rule / action / formatter /
+ * hook) extend this base structurally; the registry stores the base view
+ * and each kind's code carries its own fuller type where needed.
+ *
+ * **Spec § A.6 — qualified ids.** Every extension is keyed in the registry
+ * by `<pluginId>/<id>` (e.g. `core/frontmatter`, `claude/slash`,
+ * `hello-world/greet`). `Extension.id` carries the **short** id as authored;
+ * `Extension.pluginId` carries the namespace; the registry composes the
+ * qualifier internally and exposes lookup APIs that operate on either form
+ * (qualified for direct lookup, kind-scoped listing for enumeration).
+ *
+ * Boot invariant: `new Registry()` is empty. `registry.totalCount() === 0`
+ * when the kernel boots with zero extensions. This is the data side of the
+ * `kernel-empty-boot` conformance contract.
+ */
+
+type ExtensionKind = 'provider' | 'extractor' | 'rule' | 'action' | 'formatter' | 'hook';
+declare const EXTENSION_KINDS: readonly ExtensionKind[];
+interface Extension {
+    /** Short (unqualified) extension id as declared in the manifest. */
+    id: string;
+    /** Owning plugin namespace. Composed with `id` to form the qualified key. */
+    pluginId: string;
+    kind: ExtensionKind;
+    version: string;
+    description?: string;
+    stability?: Stability;
+    preconditions?: string[];
+    entry?: string;
+}
+/**
+ * Compose the qualified registry key for an extension. Single source of
+ * truth so callers don't reinvent the format and a future change (e.g. a
+ * different separator) lands in one place.
+ */
+declare function qualifiedExtensionId(pluginId: string, id: string): string;
+declare class DuplicateExtensionError extends Error {
+    constructor(kind: ExtensionKind, qualifiedId: string);
+}
+declare class Registry {
+    #private;
+    constructor();
+    register(ext: Extension): void;
+    /**
+     * Lookup by qualified id (`<pluginId>/<id>`). Returns `undefined` when
+     * no extension of that kind is registered under the qualifier.
+     */
+    get(kind: ExtensionKind, qualifiedId: string): Extension | undefined;
+    /**
+     * Convenience wrapper that composes the qualified id for the caller.
+     * Equivalent to `get(kind, qualifiedExtensionId(pluginId, id))`.
+     */
+    find(kind: ExtensionKind, pluginId: string, id: string): Extension | undefined;
+    all(kind: ExtensionKind): Extension[];
+    count(kind: ExtensionKind): number;
+    totalCount(): number;
+}
+
+/**
+ * `.skill-mapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
+ * with the project-local layering: bundled defaults → `config.ignore`
+ * (from `.skill-map/settings.json`) → `.skill-mapignore` file content.
+ *
+ * Why a wrapper instead of exposing `ignore` directly:
+ *
+ * 1. Single-source defaults — `src/config/defaults/skill-mapignore` is
+ *    the canonical default list, loaded once at module init (or at
+ *    explicit build time, depending on bundling). The runtime never
+ *    re-reads it per scan.
+ * 2. Stable interface — Providers and the orchestrator depend on a
+ *    minimal `IIgnoreFilter` shape, so the underlying library can be
+ *    swapped without touching every consumer.
+ * 3. Path normalization — every consumer passes the path RELATIVE to
+ *    the scan root (POSIX separators); the wrapper guarantees that
+ *    contract before delegating to `ignore`.
+ */
+interface IIgnoreFilter {
+    /**
+     * Returns `true` when `relativePath` should be skipped. The caller
+     * MUST pass paths relative to the scan root, with POSIX separators
+     * (forward slashes), no leading `/`. Directories MAY be passed with
+     * or without trailing `/`; the wrapper does not require it.
+     */
+    ignores(relativePath: string): boolean;
+}
+
+/**
+ * `ProgressEmitterPort` — emits progress events during long operations.
+ *
+ * Shape-only today. The full event catalog (`run.started`,
+ * `job.claimed`, `model.delta`, etc.) is normative in
+ * `spec/job-events.md`; this port carries an open `data` payload so
+ * adapters can emit any documented event without type churn.
+ */
+interface ProgressEvent {
+    type: string;
+    timestamp: string;
+    runId?: string;
+    jobId?: string;
+    data?: unknown;
+}
+type ProgressListener = (event: ProgressEvent) => void;
+interface ProgressEmitterPort {
+    emit(event: ProgressEvent): void;
+    subscribe(listener: ProgressListener): () => void;
+}
+
+/**
+ * Plugin-surface types, hand-written to mirror
+ * `spec/schemas/plugins-registry.schema.json#/$defs/PluginManifest` and the
+ * extension-kind manifests under `spec/schemas/extensions/`.
+ *
+ * Per ROADMAP §DTO gap (review-pass decision): the proper emission of
+ * typed DTOs from `@skill-map/spec` is deferred to a future iteration when a
+ * third consumer (real providers / extractors / rules) forces a single
+ * source of truth. Until then, both `ui/src/models/` and `src/kernel/types/`
+ * hand-curate their own local mirror — the risk of drift is accepted at
+ * this scale (17 schemas) and flagged in the roadmap.
+ */
+
+/**
+ * Plugin storage mode. Matches the `oneOf` in the plugin manifest schema:
+ * either shared `state_plugin_kvs` (mode `kv`) or dedicated plugin-owned
+ * tables with explicit migrations (mode `dedicated`). Absent = the plugin
+ * does not persist state at all.
+ *
+ * Optional output-schema declarations (spec § A.12 — opt-in correctness
+ * for plugin custom storage):
+ *   - Mode `kv` → `schema` (single relative path). Validates the value
+ *     written by `ctx.store.set(key, value)`.
+ *   - Mode `dedicated` → `schemas` (per-table relative paths). Validates
+ *     each row written by `ctx.store.write(table, row)` whose table has
+ *     a declared schema; tables absent from the map accept any shape.
+ *
+ * Absent in both cases = permissive (status quo, no validation). Schema
+ * load failures surface as `load-error`. `emitLink` and `enrichNode`
+ * keep their universal kernel validation regardless of these fields.
+ */
+type TPluginStorage = {
+    mode: 'kv';
+    schema?: string;
+} | {
+    mode: 'dedicated';
+    tables: string[];
+    migrations: string[];
+    schemas?: Record<string, string>;
+};
+/**
+ * Toggle granularity for a plugin / built-in bundle.
+ *
+ * - `'bundle'`  — the plugin id is the only enable/disable key. The whole
+ *                 bundle of extensions follows the toggle; the user cannot
+ *                 enable some extensions of the bundle and disable others.
+ *                 Default for plugins (and for the built-in `claude`
+ *                 bundle, where the provider and its kind-aware extractors
+ *                 form a coherent provider).
+ * - `'extension'` — each extension is independently toggle-able under its
+ *                   qualified id `<plugin-id>/<extension-id>`. Used for
+ *                   the built-in `core` bundle (every kernel built-in
+ *                   rule / formatter is removable per spec
+ *                   "no extension is privileged"). Plugin authors opt in
+ *                   only when the plugin ships several orthogonal
+ *                   capabilities a user might reasonably want piecemeal.
+ */
+type TGranularity = 'bundle' | 'extension';
+/** Raw `plugin.json` shape after successful AJV validation. */
+interface IPluginManifest {
+    id: string;
+    version: string;
+    specCompat: string;
+    extensions: string[];
+    description?: string;
+    storage?: TPluginStorage;
+    /**
+     * Toggle granularity for this plugin. Default `'bundle'`. See
+     * `TGranularity` for the trade-off; in practice 95% of plugins want
+     * the default.
+     */
+    granularity?: TGranularity;
+    author?: string;
+    license?: string;
+    homepage?: string;
+    repository?: string;
+}
+/**
+ * Failure mode produced by the loader when a plugin cannot be loaded.
+ * Matches the three states named in spec §Plugin discovery / load.
+ *
+ * - `incompatible-spec`: manifest parsed fine but `semver.satisfies` failed
+ *   against the installed `@skill-map/spec` version.
+ * - `invalid-manifest`: `plugin.json` missing, unparseable, or failing AJV.
+ * - `load-error`: manifest passed but an extension module failed to import
+ *   or the imported manifest failed its extension-kind schema.
+ */
+/**
+ * Possible outcomes after the loader sees a plugin.json. Mirrors the
+ * `status` enum in `spec/schemas/plugins-registry.schema.json`.
+ *
+ * - `enabled`             — manifest valid, specCompat satisfied, every
+ *                           extension imported and validated.
+ * - `disabled`            — user-toggled off via `sm plugins disable` or
+ *                           `settings.json#/plugins/<id>/enabled`. Manifest
+ *                           is parsed and surfaced (so `sm plugins list`
+ *                           shows it), but extensions are not imported.
+ * - `incompatible-spec`   — manifest parsed but `semver.satisfies` failed.
+ * - `invalid-manifest`    — `plugin.json` missing, unparseable, AJV-fails,
+ *                           OR the directory name does not equal the
+ *                           manifest id (a cheap structural rule that
+ *                           rules out same-root collisions by construction:
+ *                           a filesystem cannot contain two siblings with
+ *                           the same name).
+ * - `load-error`          — manifest passed, an extension module failed.
+ * - `id-collision`        — two plugins reachable from different roots
+ *                           (project + global, or any `--plugin-dir`
+ *                           combination) declared the same `id`. Both
+ *                           collided plugins receive this status; no
+ *                           precedence rule applies. The user resolves
+ *                           by renaming one of them and rerunning.
+ */
+type TPluginLoadStatus = 'enabled' | 'disabled' | 'incompatible-spec' | 'invalid-manifest' | 'load-error' | 'id-collision';
+interface ILoadedExtension {
+    kind: ExtensionKind;
+    id: string;
+    /**
+     * Owning plugin namespace — `manifest.id` of the `plugin.json` that
+     * declared this extension. Composed with `id` to form the qualified
+     * registry key `<pluginId>/<id>`. Per spec § A.6 the loader injects
+     * this from the manifest; an extension that hand-declares a
+     * mismatching `pluginId` is rejected as `invalid-manifest`.
+     */
+    pluginId: string;
+    version: string;
+    entryPath: string;
+    /** Raw module namespace as returned by the dynamic `import()`. */
+    module: unknown;
+    /**
+     * Runtime extension instance ready for the registry / orchestrator —
+     * the `default` export of `module` (or the module itself when no
+     * default), shallow-cloned with `pluginId` injected per spec § A.6.
+     *
+     * The clone is essential: ESM caches the imported module, so two
+     * plugins importing the same file would otherwise share a single
+     * mutable instance and overwrite each other's `pluginId`. The loader
+     * owns the clone so consumers (CLI, tests) never need to mutate.
+     */
+    instance: unknown;
+}
+interface IDiscoveredPlugin {
+    /** Absolute path to the plugin directory. */
+    path: string;
+    /** Plugin id — populated from the manifest if it parsed, else a path hint. */
+    id: string;
+    status: TPluginLoadStatus;
+    /** Only present when status === 'enabled' or 'incompatible-spec'. */
+    manifest?: IPluginManifest;
+    /** Only present when status === 'enabled'. */
+    extensions?: ILoadedExtension[];
+    /**
+     * Resolved granularity for this plugin. Always populated from
+     * `manifest.granularity` (default `'bundle'`) when the manifest parsed;
+     * absent for `invalid-manifest` paths where the manifest never validated.
+     */
+    granularity?: TGranularity;
+    /**
+     * Runtime-only — never persisted, never spec-modeled.
+     *
+     * Spec § A.12 — opt-in JSON Schema validation for plugin custom storage.
+     * Populated by the loader when `manifest.storage.schemas` (Mode B) or
+     * `manifest.storage.schema` (Mode A) declares schema paths the loader
+     * successfully read and AJV-compiled. Consumed by the runtime store
+     * wrapper to validate `ctx.store.write(table, row)` (Mode B) and
+     * `ctx.store.set(key, value)` (Mode A) before persisting.
+     *
+     * Mode B layout — keyed by logical table name (without the
+     * `plugin_<normalizedId>_` prefix), matching the manifest's `schemas`
+     * map. Tables not present in the map accept any shape (permissive).
+     *
+     * Mode A layout — uses the sentinel key `__kv__` for the single
+     * value-shape schema. The sentinel survives the runtime contract change
+     * if Mode A ever grows multiple namespaces.
+     *
+     * Absent (`undefined`) when no schemas were declared OR when the load
+     * surfaced a `load-error` (the discovered plugin keeps its failure
+     * status; consumers must check `status === 'enabled'`).
+     */
+    storageSchemas?: Record<string, IPluginStorageSchema>;
+    /** Human-readable diagnostic shown by `sm plugins list/show`. */
+    reason?: string;
+}
+/**
+ * Runtime-only — a single AJV-compiled storage schema attached to a
+ * loaded plugin. The schema path (relative to the plugin directory) is
+ * preserved so error messages can name the offending file. `validate`
+ * is the AJV `ValidateFunction` itself: it returns `true` on shape
+ * match, otherwise `false` with `validate.errors` populated. Typed
+ * loosely here (no `ajv/dist/2020.js` import) to keep the shared type
+ * module free of Ajv at compile time; the runtime adapter narrows.
+ */
+interface IPluginStorageSchema {
+    /** Plugin-relative path to the schema file (`storage.schemas[<table>]` or `storage.schema`). */
+    schemaPath: string;
+    /** AJV-compiled validator. `errors` is populated after a failed call. */
+    validate: ((row: unknown) => boolean) & {
+        errors?: {
+            instancePath: string;
+            message?: string;
+            keyword: string;
+        }[] | null;
+    };
+}
+
+/**
+ * Plugin store wrappers — runtime injection for `ctx.store` per spec
+ * § A.12 (opt-in `outputSchema` for plugin custom storage).
+ *
+ * Two shapes, mirroring the manifest's storage modes documented in
+ * `spec/plugin-kv-api.md`:
+ *
+ *   - Mode A — `KvStore.set(key, value)`. AJV-validates `value` against
+ *     the schema declared by `manifest.storage.schema` (single
+ *     value-shape) when present. Absent = permissive.
+ *   - Mode B — `DedicatedStore.write(table, row)`. AJV-validates `row`
+ *     against the per-table schema declared in `manifest.storage.schemas`
+ *     when present. Tables absent from the map accept any shape.
+ *
+ * Both wrappers are storage-engine agnostic — they accept a `persist`
+ * callback the caller supplies. The persistence side (SQLite, in-memory,
+ * mock) is the caller's concern; this wrapper's only job is the
+ * AJV gate. That separation lets the test suite exercise the validator
+ * without spinning up a real DB and lets the kernel adapter (future
+ * `state_plugin_kvs` writer / dedicated-table writer) plug in
+ * unchanged.
+ *
+ * Universal validation (`emitLink` against `link.schema.json`,
+ * `enrichNode` against `node.schema.json`) is unaffected — it lives on
+ * the orchestrator side and runs regardless of the plugin's
+ * `outputSchema` opt-in.
+ */
+
+/**
+ * Sentinel key under which Mode A stores its single value-shape schema
+ * inside `IDiscoveredPlugin.storageSchemas`. The sentinel keeps the
+ * shared `Record<string, IPluginStorageSchema>` map a single-typed
+ * surface across both modes; consumers look up by sentinel for KV and
+ * by table name for dedicated.
+ */
+declare const KV_SCHEMA_KEY = "__kv__";
+interface IKvStorePersist {
+    (key: string, value: unknown): void | Promise<void>;
+}
+interface IDedicatedStorePersist {
+    (table: string, row: unknown): void | Promise<void>;
+}
+/**
+ * Mode A wrapper. `set(key, value)` AJV-validates `value` against the
+ * Mode A schema (sentinel key `__kv__`) when declared, then forwards
+ * to `persist`. Validation failure throws with a message naming the
+ * schema path and AJV errors; persistence is skipped on failure.
+ *
+ * `pluginId` is captured for diagnostics (the throw message names the
+ * plugin). The wrapper does NOT itself scope by plugin id — that is
+ * the persistence layer's job (the spec's `state_plugin_kvs` PK includes
+ * `pluginId` and the kernel-side adapter prepends it before write).
+ */
+interface IKvStoreWrapper {
+    set(key: string, value: unknown): Promise<void>;
+}
+/**
+ * Union shape exposed to extractors via `ctx.store`. Spec § A.12 — Mode A
+ * (`kv`) returns a `set(key, value)` surface; Mode B (`dedicated`) returns
+ * `write(table, row)`. Plugin authors narrow at the call site based on
+ * the storage mode declared in their `plugin.json`.
+ */
+type IPluginStore = IKvStoreWrapper | IDedicatedStoreWrapper;
+declare function makeKvStoreWrapper(opts: {
+    pluginId: string;
+    schema: IPluginStorageSchema | undefined;
+    persist: IKvStorePersist;
+}): IKvStoreWrapper;
+/**
+ * Mode B wrapper. `write(table, row)` AJV-validates `row` against
+ * `storageSchemas[table]` when declared, then forwards to `persist`.
+ * Tables absent from the map are permissive — the wrapper forwards
+ * straight to `persist` without validation.
+ *
+ * The wrapper accepts the full `storageSchemas` map (rather than a
+ * single schema) so a plugin author can declare schemas for some
+ * tables and leave others permissive in the same map without the
+ * caller having to lookup-then-narrow.
+ */
+interface IDedicatedStoreWrapper {
+    write(table: string, row: unknown): Promise<void>;
+}
+declare function makeDedicatedStoreWrapper(opts: {
+    pluginId: string;
+    schemas: Record<string, IPluginStorageSchema> | undefined;
+    persist: IDedicatedStorePersist;
+}): IDedicatedStoreWrapper;
+/**
+ * Convenience entry point: build whichever wrapper matches the
+ * discovered plugin's storage mode. Returns `undefined` when the
+ * plugin declared no storage at all (the orchestrator omits
+ * `ctx.store` in that case, per the existing contract). Mode A
+ * extracts the sentinel-keyed schema; Mode B forwards the full map.
+ */
+declare function makePluginStore(opts: {
+    plugin: IDiscoveredPlugin;
+    persistKv?: IKvStorePersist;
+    persistDedicated?: IDedicatedStorePersist;
+}): IPluginStore | undefined;
+
+/**
+ * Base manifest shape shared by every extension kind. Mirrors
+ * `spec/schemas/extensions/base.schema.json` at the TypeScript level.
+ *
+ * Spec § A.6 — every extension is identified in the registry by the
+ * qualified id `<pluginId>/<id>`. The `pluginId` field is required at the
+ * runtime / TS level: built-ins declare it directly in
+ * `src/extensions/built-ins.ts`; user plugins have it injected by the
+ * `PluginLoader` from `plugin.json#/id` before the extension reaches the
+ * registry. A plugin author who hand-codes a `pluginId` that disagrees
+ * with the manifest's `id` is rejected as `invalid-manifest`.
+ *
+ * The JSON Schema deliberately does NOT model `pluginId` — the qualifier
+ * is a runtime concern composed by the loader, not a manifest field
+ * authors are expected to set. Stripping it before AJV validation in
+ * the loader keeps the spec contract clean ("authors declare only the
+ * short id").
+ */
+
+interface IExtensionBase {
+    id: string;
+    /**
+     * Owning plugin namespace. Composed with `id` to produce the
+     * qualified registry key `<pluginId>/<id>`. Built-ins declare this
+     * directly; user plugins have it injected by the `PluginLoader`
+     * from `plugin.json#/id`.
+     */
+    pluginId: string;
+    version: string;
+    description?: string;
+    stability?: Stability;
+    preconditions?: string[];
+    entry?: string;
+}
+
+/**
+ * Provider runtime contract. Walks filesystem roots and emits raw node
+ * records; classification maps path conventions to a node kind.
+ *
+ * Distinct from the **hexagonal-architecture** 'adapter' (`RunnerPort.adapter`,
+ * `StoragePort.adapter`, etc.). A `Provider` is an extension kind authored
+ * by plugins to declare a platform's universe (the catalog of kinds it
+ * emits, the per-kind frontmatter schema, the filesystem directory it
+ * owns); a hexagonal adapter is an internal implementation of a port.
+ * Both can coexist without confusion because they live in different
+ * namespaces.
+ *
+ * `walk()` is an async iterator so large scopes don't buffer in memory.
+ * Each yielded `IRawNode` carries the full parsed frontmatter + body plus
+ * the path relative to the scan root; the kernel computes hashes, bytes,
+ * and tokens on top.
+ *
+ * **Spec 0.8.0**. Per-kind frontmatter schemas relocated from the spec
+ * to the Provider that owns them. The flat
+ * `defaultRefreshAction` map collapsed into the new `kinds` map: every
+ * kind the Provider emits gets one entry that declares both its schema
+ * and its refresh action. Spec keeps only `frontmatter/base.schema.json`
+ * (universal); per-kind schemas live with the Provider.
+ */
+
+interface IRawNode {
+    /** Path relative to the scan root that produced this node. */
+    path: string;
+    /** Raw markdown body (everything after the frontmatter fence). */
+    body: string;
+    /** Raw frontmatter text (between `---` fences). Empty string when absent. */
+    frontmatterRaw: string;
+    /** Parsed frontmatter, or `{}` when absent / unparseable. */
+    frontmatter: Record<string, unknown>;
+}
+/**
+ * One entry in a Provider's `kinds` map. Declares both the per-kind
+ * frontmatter schema (path relative to the Provider's package dir, plus
+ * the loaded JSON object the kernel passes to AJV) and the qualified
+ * default refresh action id the UI dispatches for nodes of this kind.
+ *
+ * The split between `schema` (manifest-level path) and `schemaJson`
+ * (runtime-loaded JSON) keeps the manifest shape spec-conformant while
+ * letting the runtime instance carry the parsed schema without a second
+ * filesystem read at scan time. Built-in Providers populate `schemaJson`
+ * via `import schema from './schemas/skill.schema.json' with { type: 'json' }`;
+ * user-plugin Providers loaded by `PluginLoader` will have it filled in
+ * by the loader after manifest validation.
+ */
+interface IProviderKind {
+    /**
+     * Path to the kind's frontmatter JSON Schema, relative to the
+     * Provider's package directory. Mirrors the spec field of the same
+     * name in `extensions/provider.schema.json#/properties/kinds/.../schema`.
+     */
+    schema: string;
+    /**
+     * Loaded JSON Schema document for the kind. The kernel registers this
+     * with AJV at scan boot and validates each node's frontmatter against
+     * it. The schema MUST extend the spec's
+     * `frontmatter/base.schema.json` via `allOf` + `$ref` to base's
+     * `$id`; the loader registers base into the same AJV instance so
+     * cross-package `$ref`-by-`$id` resolves transparently.
+     *
+     * `unknown` rather than a stronger type because AJV consumes any JSON
+     * Schema object; tightening to a concrete shape would require mirroring
+     * the JSON Schema vocabulary in TypeScript.
+     */
+    schemaJson: unknown;
+    /**
+     * Qualified action id (`<plugin-id>/<action-id>`) the probabilistic-
+     * refresh UI dispatches for nodes of this kind. The kernel resolves
+     * the id against its qualified action registry; a dangling reference
+     * disables the Provider with status `invalid-manifest`.
+     */
+    defaultRefreshAction: string;
+}
+interface IProvider extends IExtensionBase {
+    kind: 'provider';
+    /**
+     * Filesystem directory (relative to user home or project root) where this
+     * Provider's content lives. Required. Examples: `'~/.claude'` for the
+     * Claude Provider, `'~/.cursor'` for a hypothetical Cursor Provider.
+     * The kernel walks this directory during boot/scan to discover nodes;
+     * `sm doctor` validates the directory exists and emits a non-blocking
+     * warning when it does not.
+     */
+    explorationDir: string;
+    /**
+     * Catalog of node kinds this Provider emits. Keyed by kind name. Every
+     * kind the Provider can `classify()` MUST have an entry; an entry is
+     * the union of the kind's frontmatter schema and its default refresh
+     * action.
+     *
+     * The string keys are typed loosely (`string`) rather than `NodeKind`
+     * because the value space is open by design: a future Cursor Provider
+     * could declare `rule`, an Obsidian Provider could declare `daily`.
+     * The kernel's hard-coded `NodeKind` union represents the kinds the
+     * built-in Claude Provider emits; it is NOT the kernel-wide kind type
+     * (see `kernel/types.ts:NodeKind` docstring). `Node.kind`, the AJV
+     * `node.schema.json` validator, and the SQLite `scan_nodes.kind`
+     * column all accept any non-empty string an enabled Provider returns.
+     */
+    kinds: Record<string, IProviderKind>;
+    /**
+     * Walk the given roots and yield every node the Provider recognises.
+     * Non-matching files are silently skipped. Unreadable files produce
+     * a diagnostic via the emitter but do not abort the walk.
+     *
+     * `options.ignoreFilter` — when supplied, the Provider MUST
+     * skip every directory and file whose path-relative-to-root the
+     * filter reports as ignored. Providers MAY also keep their own
+     * hard-coded skip list (e.g. `.git`) as a defensive measure, but the
+     * filter is the canonical source of user intent.
+     */
+    walk(roots: string[], options?: {
+        ignoreFilter?: IIgnoreFilter;
+    }): AsyncIterable<IRawNode>;
+    /**
+     * Given a path and its parsed frontmatter, decide the node kind. The
+     * classifier is called after walk() yields — Providers MAY embed the
+     * logic inside walk itself, but exposing it lets the kernel rebuild
+     * classification during partial scans without re-walking.
+     *
+     * Returns an open `string`. The returned value MUST be a key of the
+     * Provider's own `kinds` catalog; the orchestrator does not validate
+     * the kind against `NodeKind`. External Providers (Cursor, Obsidian,
+     * …) freely return their own kinds (e.g. `'cursorRule'`, `'daily'`).
+     */
+    classify(path: string, frontmatter: Record<string, unknown>): string;
+}
+
+/**
+ * Extractor runtime contract. Consumes a single node (frontmatter + body)
+ * and emits its output through three context-supplied callbacks rather than
+ * a return value. Extractors run in isolation: they MUST NOT read other
+ * nodes, the graph, or the DB. Cross-node reasoning lives in rules.
+ *
+ * Output channels (all on the context):
+ *
+ *   - `ctx.emitLink(link)` — persist a link in the kernel's `links` table.
+ *     Validated against `emitsLinkKinds` before insertion; an off-contract
+ *     kind drops the link and surfaces an `extension.error` event.
+ *   - `ctx.enrichNode(partial)` — merge canonical, kernel-curated properties
+ *     onto the node. Strictly separate from the author-supplied frontmatter
+ *     (the latter remains immutable and survives verbatim). Persistence and
+ *     stale-tracking are spec'd in § A.8.
+ *   - `ctx.store` — plugin-scoped persistence. Present only when the
+ *     plugin declares `storage.mode` in `plugin.json`; shape depends on the
+ *     mode (`KvStore` for mode A, scoped `Database` for mode B). See
+ *     `plugin-kv-api.md` for the contract.
+ *   - `ctx.runner` — `RunnerPort` injection for `probabilistic` extractors.
+ *     `undefined` for the default `deterministic` mode.
+ *
+ * The manifest's `scope` field tells the orchestrator which parts to feed:
+ * `frontmatter` extractors receive an empty string for body and vice versa.
+ *
+ * Renamed from `Detector` in spec 0.8.x. The previous `detect(ctx) → Link[]`
+ * signature is gone; everything now flows through `extract(ctx) → void`
+ * and the callbacks above.
+ */
+
+/**
+ * Output callbacks supplied by the kernel on the extractor context.
+ * Split out so plugin authors can name the callback shape if they
+ * want to mock it in unit tests without depending on the wider
+ * `IExtractorContext`.
+ */
+interface IExtractorCallbacks {
+    /**
+     * Emit a single Link. The orchestrator validates the link against the
+     * extractor's declared `emitsLinkKinds` before inserting it; off-contract
+     * links are silently dropped with an `extension.error` event.
+     */
+    emitLink(link: Link): void;
+    /**
+     * Merge canonical, kernel-curated properties onto the current node's
+     * enrichment layer. The author-supplied frontmatter stays untouched
+     * (Decision #109 in `ROADMAP.md`). Persistence and stale-tracking
+     * semantics live in spec § A.8; the orchestrator already buffers the
+     * partials and `persistScanResult` upserts them.
+     */
+    enrichNode(partial: Partial<Node>): void;
+}
+interface IExtractorContext extends IExtractorCallbacks {
+    node: Node;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    /**
+     * Plugin-scoped persistence. Optional because not every plugin declares
+     * a `storage.mode` in `plugin.json`. Shape: `KvStoreWrapper` for mode A
+     * (`set(key, value)`), `DedicatedStoreWrapper` for mode B
+     * (`write(table, row)`). See `spec/plugin-kv-api.md`.
+     *
+     * Typed as `unknown` so this contract module stays free of any
+     * adapter-side imports — the concrete `IPluginStore` lives in
+     * `kernel/adapters/plugin-store.js`. Plugin authors narrow at the
+     * call site based on the storage mode declared in their manifest.
+     * The orchestrator looks up the wrapper per-extractor in
+     * `RunScanOptions.pluginStores` (keyed by `pluginId`) and attaches
+     * it here.
+     */
+    store?: unknown;
+    /**
+     * `RunnerPort` injection for `probabilistic` extractors. `undefined`
+     * for `deterministic` mode (the default). The kernel rejects
+     * probabilistic extractors that try to register scan-time hooks at
+     * load time.
+     */
+    runner?: unknown;
+}
+interface IExtractor extends IExtensionBase {
+    kind: 'extractor';
+    /**
+     * Execution mode. Optional in the manifest with a default of
+     * `deterministic` per `spec/schemas/extensions/extractor.schema.json`.
+     * `probabilistic` extractors invoke an LLM through the kernel's
+     * `RunnerPort` and never participate in scan-time pipelines —
+     * they dispatch only as queued jobs.
+     */
+    mode?: TExecutionMode;
+    emitsLinkKinds: LinkKind[];
+    defaultConfidence: Confidence;
+    scope: 'frontmatter' | 'body' | 'both';
+    /**
+     * Optional opt-in filter on `node.kind`. When declared, the orchestrator
+     * skips invocation of `extract()` for any node whose `kind` is NOT in
+     * this list — fail-fast, before context construction, so a
+     * probabilistic extractor wastes zero LLM cost on inapplicable nodes
+     * and a deterministic extractor wastes zero CPU.
+     *
+     * Absent (`undefined`) is the default: the extractor applies to every
+     * kind. There are no wildcards — the absence of the field already
+     * encodes "every kind". An empty array (`[]`) is rejected at load
+     * time by AJV (`minItems: 1` in the schema).
+     *
+     * Unknown kinds (no installed Provider declares them) do NOT block
+     * the load: the extractor keeps `loaded` status and `sm plugins doctor`
+     * surfaces a warning. The Provider that declares the kind may arrive
+     * later (e.g. a user installs the corresponding plugin).
+     *
+     * Spec: `spec/schemas/extensions/extractor.schema.json#/properties/applicableKinds`.
+     */
+    applicableKinds?: string[];
+    /**
+     * Extractor entry point. Returns nothing; output flows through
+     * `ctx.emitLink`, `ctx.enrichNode`, and `ctx.store`.
+     */
+    extract(ctx: IExtractorContext): void | Promise<void>;
+}
+
+/**
+ * Rule runtime contract. Runs against the whole graph after every Provider
+ * and extractor has completed; emits issues. Deterministic rules are pure
+ * (same graph in → same issues out) and run synchronously inside `sm scan`
+ * / `sm check`. Probabilistic rules invoke an LLM through the kernel's
+ * `RunnerPort` and dispatch only as queued jobs — they never participate
+ * in scan-time pipelines. Mode is declared in the manifest (default
+ * `deterministic`).
+ */
+
+interface IRuleContext {
+    nodes: Node[];
+    links: Link[];
+}
+interface IRule extends IExtensionBase {
+    kind: 'rule';
+    /**
+     * Execution mode. Optional in the manifest with a default of
+     * `deterministic` per `spec/schemas/extensions/rule.schema.json`.
+     */
+    mode?: TExecutionMode;
+    evaluate(ctx: IRuleContext): Issue[] | Promise<Issue[]>;
+}
+
+/**
+ * Action runtime contract. The fourth plugin kind (spec § A.4 +
+ * `spec/schemas/extensions/action.schema.json`).
+ *
+ * Actions operate on one or more nodes in one of two execution modes:
+ *
+ *   - `deterministic` — code runs in-process; the action computes the
+ *     report synchronously and returns it. No job file, no runner.
+ *   - `probabilistic` — the kernel renders a prompt + preamble into a
+ *     job file; a runner executes it via `RunnerPort` against an LLM;
+ *     `sm record` closes the job and validates the report against
+ *     `reportSchemaRef`.
+ *
+ * **Deferred runtime invocation.** The dispatcher (`Action.run(ctx)` for
+ * deterministic; the `RunnerPort` + `sm record` round-trip for
+ * probabilistic) lands with the job subsystem (Decision #114 in
+ * `ROADMAP.md`). Today the loader still validates `kind: 'action'`
+ * manifests against `extension-action.schema.json` and the registry
+ * holds them — `sm actions show` and the precondition gating UI consume
+ * the manifest data. The runtime entry point is intentionally absent
+ * from `IAction` so plugin authors don't ship a method the kernel will
+ * not call until the job subsystem is in place; when it ships, the
+ * method shape will land here without breaking the manifest contract.
+ *
+ * Mirrors `extensions/action.schema.json`:
+ *
+ *   - `mode` (required) — discriminator between the two modes.
+ *   - `reportSchemaRef` (required) — JSON Schema reference the report
+ *     MUST validate against. MUST extend `report-base.schema.json`.
+ *   - `promptTemplateRef` — REQUIRED when `mode: 'probabilistic'`,
+ *     FORBIDDEN when `mode: 'deterministic'`. The schema's conditional
+ *     `allOf` enforces both directions; the runtime contract simply
+ *     surfaces the field as optional and lets the loader catch shape
+ *     violations at AJV time.
+ *   - `expectedDurationSeconds` — REQUIRED for probabilistic (drives
+ *     TTL); advisory for deterministic.
+ *   - `precondition` — declarative filter consumed by `--all` fan-out,
+ *     UI button gating, `sm actions show`.
+ *   - `expectedTools` — hint to Skill / CLI runners about expected
+ *     tools (no normative enforcement in v0).
+ *   - `fanOutPolicy` — `'per-node'` (default) vs `'batch'`.
+ */
+
+/**
+ * Declarative filter applied by `--all` fan-out, UI button gating, and
+ * `sm actions show`. All fields optional — an empty precondition matches
+ * every node.
+ */
+interface IActionPrecondition {
+    /**
+     * Node kinds this action accepts. Open-by-design (matches
+     * `node.schema.json#/properties/kind`): an action declared with
+     * `kind: ['cursorRule']` is valid as long as some Provider classifies
+     * into `cursorRule`. Omitted → any kind.
+     */
+    kind?: string[];
+    /** Provider ids whose nodes this action accepts. Omitted → any Provider. */
+    provider?: string[];
+    /** Node stability filter. */
+    stability?: Array<'experimental' | 'stable' | 'deprecated'>;
+    /**
+     * Free-form precondition strings the kernel forwards to the action for
+     * runtime evaluation (example: `frontmatter.metadata.source != null`).
+     */
+    custom?: string[];
+}
+interface IAction extends IExtensionBase {
+    kind: 'action';
+    /**
+     * Execution mode discriminator. Required per
+     * `extensions/action.schema.json`.
+     */
+    mode: TExecutionMode;
+    /**
+     * Reference to the JSON Schema the report MUST validate against. MUST
+     * extend `report-base.schema.json` (directly or transitively).
+     * Validation failure → job transitions to `failed` with reason
+     * `report-invalid`.
+     */
+    reportSchemaRef: string;
+    /**
+     * Best-effort estimate of wall-clock duration in seconds. Drives TTL
+     * (`ttl = max(expectedDurationSeconds × graceMultiplier,
+     * minimumTtlSeconds)`). Required for `probabilistic`; advisory for
+     * `deterministic`.
+     */
+    expectedDurationSeconds?: number;
+    /**
+     * Path (relative to the extension file) to the prompt template the
+     * kernel renders at `sm job submit`. REQUIRED when `mode:
+     * 'probabilistic'`; FORBIDDEN when `mode: 'deterministic'`. The
+     * conditional shape is enforced by AJV at load time; the runtime
+     * contract carries the field as optional so both modes share one
+     * interface.
+     */
+    promptTemplateRef?: string;
+    /**
+     * Optional declarative filter; absent → applies to every node.
+     */
+    precondition?: IActionPrecondition;
+    /**
+     * Hint to Skill / CLI runners about what tools the rendered prompt
+     * expects access to (`Bash`, `Read`, `WebSearch`, …). No normative
+     * enforcement in v0.
+     */
+    expectedTools?: string[];
+    /**
+     * `'per-node'` (default): `sm job submit --all` produces one job per
+     * matching node. `'batch'`: one job whose prompt template receives the
+     * full list. Batch actions tend to hit context limits; use sparingly.
+     */
+    fanOutPolicy?: 'per-node' | 'batch';
+}
+
+/**
+ * Formatter runtime contract. Turns the (nodes, links, issues) graph into
+ * a textual representation for `sm graph --format <name>`.
+ *
+ * Two adjacent names live on the same instance:
+ *
+ *   - `formatId: string` — the manifest field consumed by the
+ *     `--format <name>` CLI flag. The kernel's lookup is
+ *     `formatters.find((f) => f.formatId === flag)`.
+ *   - `format(ctx) → string` — the runtime method. Receives the full
+ *     graph and returns the serialized output. Output MUST be
+ *     byte-deterministic for the same input (the snapshot-test suite
+ *     relies on this).
+ *
+ * The split (`formatId` vs `format`) is deliberate: it keeps the method
+ * named after the kind (`Formatter.format()` reads naturally) while the
+ * field carries the identifier the user types on the command line.
+ */
+
+interface IFormatterContext {
+    nodes: Node[];
+    links: Link[];
+    issues: Issue[];
+}
+interface IFormatter extends IExtensionBase {
+    kind: 'formatter';
+    /** Format identifier consumed by `sm graph --format <name>`. */
+    formatId: string;
+    /** Serialize the graph into a string. Deterministic-only. */
+    format(ctx: IFormatterContext): string;
+}
+
+/**
+ * Hook runtime contract. The sixth plugin kind (spec § A.11).
+ *
+ * Hooks subscribe declaratively to a curated set of kernel lifecycle
+ * events and react to them. Reaction-only by design: a hook cannot
+ * mutate the pipeline, block emission, or alter outputs. Use cases
+ * are notification (Slack on `job.completed`), integration glue (CI
+ * webhook on `job.failed`), and bookkeeping (per-extractor metrics).
+ *
+ * The hookable trigger set is INTENTIONALLY SMALL — eight events. The
+ * full `ProgressEmitterPort` catalog (per-node `scan.progress`,
+ * `model.delta`, `run.*`, internal job lifecycle) is deliberately not
+ * hookable: too verbose for a reactive surface, internal to the runner,
+ * or covered elsewhere. Declaring a trigger outside the curated set
+ * yields `invalid-manifest` at load time.
+ *
+ * Dual-mode (declared in manifest):
+ *
+ *   - `deterministic` (default): `on(ctx)` runs in-process during the
+ *     dispatch of the matching event, synchronously between the
+ *     event's emission and the next pipeline step. Errors are caught
+ *     by the dispatcher, logged via `extension.error`, and never
+ *     block the main flow.
+ *   - `probabilistic`: the hook is enqueued as a job. Until the job
+ *     subsystem ships, probabilistic hooks load but skip dispatch
+ *     with a stderr advisory (Decision #114 in `ROADMAP.md`).
+ *
+ * Curated trigger set (per spec § A.11):
+ *
+ *   1. `scan.started`         — pre-scan setup (one per scan).
+ *   2. `scan.completed`       — post-scan reaction (one per scan).
+ *   3. `extractor.completed`  — aggregated per-Extractor outputs.
+ *   4. `rule.completed`       — aggregated per-Rule outputs.
+ *   5. `action.completed`     — Action executed on a node.
+ *   6. `job.spawning`         — pre-spawn of runner subprocess.
+ *   7. `job.completed`        — most common trigger.
+ *   8. `job.failed`           — alerts, retry triggers.
+ */
+
+/**
+ * The eight hookable lifecycle events. Mirrors the `triggers[]` enum in
+ * `spec/schemas/extensions/hook.schema.json`. Anything outside this set
+ * is rejected at load time as `invalid-manifest`.
+ */
+type THookTrigger = 'scan.started' | 'scan.completed' | 'extractor.completed' | 'rule.completed' | 'action.completed' | 'job.spawning' | 'job.completed' | 'job.failed';
+/**
+ * Frozen list mirror of `THookTrigger` for runtime introspection. The
+ * loader validates `manifest.triggers[]` against this set; the
+ * orchestrator's dispatcher iterates it in order when fanning an event
+ * out to subscribed hooks.
+ */
+declare const HOOK_TRIGGERS: readonly THookTrigger[];
+/**
+ * Context the dispatcher hands to `Hook.on()`. The shape is intentionally
+ * narrow: a hook reacts to an event, it does not steer the pipeline.
+ *
+ * The `event` carries the raw `ProgressEvent` envelope (type, timestamp,
+ * runId/jobId when applicable, data). Optional `node` / `extractorId`
+ * / `ruleId` / `actionId` are extracted from the event payload by the
+ * dispatcher when present so authors don't have to walk `event.data`.
+ *
+ * Probabilistic hooks additionally receive `runner` for LLM dispatch.
+ * Deterministic hooks SHOULD ignore the field.
+ */
+interface IHookContext {
+    /** The raw event the dispatcher matched. */
+    event: {
+        type: THookTrigger;
+        timestamp: string;
+        runId?: string;
+        jobId?: string;
+        data?: unknown;
+    };
+    /**
+     * Convenience extraction of the node payload when the event is
+     * node-scoped (`action.completed`). Undefined for run-scoped or
+     * scan-scoped events.
+     */
+    node?: Node;
+    /**
+     * Set on `extractor.completed` events. Qualified extension id of the
+     * Extractor whose work the event aggregates.
+     */
+    extractorId?: string;
+    /**
+     * Set on `rule.completed` events. Qualified extension id of the Rule.
+     */
+    ruleId?: string;
+    /**
+     * Set on `action.completed` events. Qualified extension id of the
+     * Action that just ran.
+     */
+    actionId?: string;
+    /**
+     * Set on `job.*` events once the job subsystem lands. Carries the
+     * report payload for `job.completed`, the failure record for
+     * `job.failed`, and the spawn metadata for `job.spawning`.
+     */
+    jobResult?: unknown;
+    /**
+     * `RunnerPort` injection for `probabilistic` hooks. `undefined` for
+     * `deterministic` mode (the default). Probabilistic hooks land with
+     * the job subsystem; the field is reserved here so the runtime
+     * contract is forward-compatible without a major bump.
+     */
+    runner?: unknown;
+}
+/**
+ * Optional declarative filter applied by the dispatcher BEFORE
+ * invoking `on(ctx)`. Keys are payload field paths (top-level only in
+ * v0.x); values are the literal expected match. The dispatcher walks
+ * `event.data` for the field and short-circuits the invocation if the
+ * value disagrees.
+ *
+ * Cross-field validation against declared `triggers` is best-effort
+ * at load time: when none of the declared triggers carries a given
+ * filter field, the loader surfaces `invalid-manifest`. The current
+ * impl performs the basic enum check but defers full payload-shape
+ * cross-validation to a follow-up — the dispatcher is permissive at
+ * runtime (an unknown field never matches → the hook simply never
+ * fires for that event, which is a correct interpretation of "filter
+ * by a field that doesn't exist").
+ */
+type THookFilter = Record<string, string | number | boolean>;
+interface IHook extends IExtensionBase {
+    kind: 'hook';
+    /**
+     * Execution mode. Optional in the manifest with a default of
+     * `deterministic` per `spec/schemas/extensions/hook.schema.json`.
+     * Probabilistic hooks load but skip dispatch with a stderr advisory
+     * until the job subsystem ships (Decision #114).
+     */
+    mode?: TExecutionMode;
+    /**
+     * Subset of the curated lifecycle trigger set this hook subscribes
+     * to. MUST be non-empty; every entry MUST be a member of
+     * `HOOK_TRIGGERS`. The loader validates both invariants and surfaces
+     * `invalid-manifest` on violation.
+     */
+    triggers: THookTrigger[];
+    /**
+     * Optional declarative filter. Absent → invoke on every dispatched
+     * event of every declared trigger.
+     */
+    filter?: THookFilter;
+    /**
+     * Hook entry point. Returns nothing; reactions are side effects.
+     * Errors are caught by the dispatcher (logged as `extension.error`,
+     * surfaced via `hook.failed` meta-event) and NEVER block the main
+     * pipeline — a buggy hook degrades gracefully.
+     */
+    on(ctx: IHookContext): void | Promise<void>;
+}
+
+/**
+ * Scan orchestrator — runs the Provider → extractor → rule pipeline across
+ * every registered extension and emits `ProgressEmitterPort` events in
+ * canonical order. The callable extension set is injected via
+ * `RunScanOptions.extensions` — the Registry holds manifest metadata, the
+ * callable set holds the runtime instances the orchestrator actually
+ * invokes. Separating the two lets `sm plugins` and `sm help` introspect
+ * the graph without loading code.
+ *
+ * With zero registered extensions (or a callable set that carries none)
+ * the pipeline still produces a valid zero-filled `ScanResult` — the
+ * kernel-empty-boot invariant.
+ *
+ * Roots are validated up front: each entry of `RunScanOptions.roots`
+ * must exist on disk as a directory. The first failure throws a clear
+ * `Error` naming the offending path. This guards every caller (CLI,
+ * server, skill-agent) against silently producing a zero-filled
+ * `ScanResult` when a Provider walks a non-existent path — the bug
+ * that wiped a populated DB via `sm scan -- --dry-run` (clipanion's
+ * `--` made `--dry-run` a positional root that did not exist).
+ *
+ * Incremental scans: when `priorSnapshot` is supplied, the
+ * orchestrator walks the filesystem, hashes each file, and reuses the
+ * prior node + its prior-extracted internal links whenever both
+ * `bodyHash` and `frontmatterHash` match. New / modified files run
+ * through the full extractor pipeline (including the external-url-counter
+ * which produces ephemeral pseudo-links). Rules ALWAYS run over the
+ * fully merged graph — issue state can change even for an unchanged node
+ * (e.g. a previously broken `references` link now resolves because a new
+ * node was added). For unchanged nodes the prior `externalRefsCount` is
+ * preserved as-is (the external pseudo-links were never persisted, so
+ * they cannot be reconstructed; the count survived in the node row).
+ *
+ * Extractor output model (B.1, post-rename from Detector): extractors
+ * return `void` and emit through three callbacks injected on the context:
+ *   - `ctx.emitLink(link)` → orchestrator validates against
+ *     `emitsLinkKinds` then partitions into internal / external buckets.
+ *   - `ctx.enrichNode(partial)` → orchestrator records ONE enrichment
+ *     entry per `(node, extractor)` so attribution survives into the DB.
+ *     Persisted into `node_enrichments` (A.8). The author-supplied
+ *     frontmatter on `node.frontmatter` stays immutable from any Extractor
+ *     — the enrichment layer is the only writable surface, and rules /
+ *     formatters consume it via `mergeNodeWithEnrichments`.
+ *   - `ctx.store` → plugin's own KV / dedicated tables (spec § A.12).
+ *     Wired by the driving adapter via `RunScanOptions.pluginStores`,
+ *     which the orchestrator looks up per-extractor by `pluginId` and
+ *     attaches to the context. The orchestrator never inspects what
+ *     plugins write through it; the wrapper handles AJV validation
+ *     when the manifest declared an output schema.
+ */
+
+interface IScanExtensions {
+    providers: IProvider[];
+    extractors: IExtractor[];
+    rules: IRule[];
+    /**
+     * Optional hooks (spec § A.11). When supplied, the orchestrator's
+     * lifecycle dispatcher invokes deterministic hooks subscribed to one
+     * of the eight hookable triggers in canonical order with the matching
+     * event payload. Absent → no hooks fire (the scan still emits its
+     * lifecycle events to `ProgressEmitterPort` for observability).
+     * Probabilistic hooks are loaded but skipped here with a stderr
+     * advisory until the job subsystem ships once the job subsystem ships.
+     */
+    hooks?: IHook[];
+}
+/**
+ * Confidence-tagged plan to repoint `state_*` references from one node
+ * path to another. Emitted by the rename heuristic during `runScan` and
+ * consumed by `persistScanResult` so the FK migration runs inside the
+ * same transaction as the scan zone replace-all.
+ */
+interface RenameOp {
+    from: string;
+    to: string;
+    confidence: 'high' | 'medium';
+}
+interface RunScanOptions {
+    /**
+     * Filesystem roots to walk. Spec requires `minItems: 1`; passing an
+     * empty array makes `runScan` throw before any work happens.
+     */
+    roots: string[];
+    emitter?: ProgressEmitterPort;
+    /** Runtime extension instances. Absent → empty pipeline. */
+    extensions?: IScanExtensions;
+    /**
+     * Scan scope. Defaults to `'project'`. The CLI flag wiring lands in
+     * the config layer wiring; `runScan` already accepts the override
+     * so plugins / tests can opt into `'global'` today.
+     */
+    scope?: 'project' | 'global';
+    /**
+     * Compute per-node token counts (frontmatter / body / total) using the
+     * cl100k_base BPE (the modern OpenAI tokenizer used by GPT-4 / GPT-3.5).
+     * Defaults to true. Set false to skip tokenization; `node.tokens` is
+     * left undefined (spec-valid: the field is optional).
+     */
+    tokenize?: boolean;
+    /**
+     * Prior snapshot for two purposes (decoupled by design):
+     *
+     *   1. **Rename heuristic** (`spec/db-schema.md` §Rename detection):
+     *      always evaluated when `priorSnapshot` is supplied. The
+     *      heuristic compares prior vs current node paths and emits
+     *      high / medium / ambiguous / orphan classifications. This
+     *      runs on EVERY `sm scan` (with or without `--changed`) so
+     *      reorganising files always preserves history, never silently.
+     *
+     *   2. **Cache reuse** (`sm scan --changed`): only kicks in when
+     *      `enableCache: true` is also passed. With the flag set, nodes
+     *      whose `path` exists in the prior with both `bodyHash` and
+     *      `frontmatterHash` matching the freshly-computed hashes are
+     *      reused as-is (their internal links and `externalRefsCount`
+     *      survive); only new / modified nodes run through extractors.
+     *      Rules always re-run over the merged graph.
+     *
+     * Pass `null` (or omit) for a fresh scan with no rename detection.
+     */
+    priorSnapshot?: ScanResult | null;
+    /**
+     * Reuse unchanged nodes from `priorSnapshot` instead of re-running
+     * extractors over them. Defaults to `false` so a plain `sm scan`
+     * always re-walks deterministically. `sm scan --changed` flips this
+     * to `true` for the perf win on unchanged files.
+     *
+     * Has no effect without `priorSnapshot`; setting it to `true` with
+     * a null prior is a no-op (every file is "new").
+     */
+    enableCache?: boolean;
+    /**
+     * Filter that decides which paths the Providers skip. Composed by the
+     * caller (typically the CLI) from bundled defaults + `config.ignore`
+     * + `.skill-mapignore`. Providers that omit this option fall back to
+     * their own defensive defaults (just enough to keep `.git` /
+     * `node_modules` out).
+     */
+    ignoreFilter?: IIgnoreFilter;
+    /**
+     * Promote frontmatter-validation findings from `warn` to `error`.
+     * Defaults to false. The CLI surfaces this via `--strict` on `sm scan`
+     * and the `scan.strict` config key. When false, the orchestrator
+     * still emits a `frontmatter-invalid` issue per malformed file but
+     * leaves the severity at `warn` so a clean scan exits 0; when true,
+     * the same finding becomes `error` and the scan exits 1.
+     */
+    strict?: boolean;
+    /**
+     * Spec § A.9 — fine-grained Extractor cache breadcrumbs from the
+     * prior scan. Shape: `Map<nodePath, Map<qualifiedExtractorId, bodyHashAtRun>>`.
+     * Loaded from the `scan_extractor_runs` table by the CLI before
+     * invoking `runScan`; absent / empty for a fresh DB or an out-of-band
+     * caller that does not maintain a cache. Decoupled from `priorSnapshot`
+     * because the runs live in a sibling table and are useful only when
+     * `enableCache` is also set.
+     *
+     * Cache decision per `(node, extractor)`:
+     *   - body+frontmatter hashes match the prior node AND every currently-
+     *     registered extractor that applies to this kind has a matching
+     *     row → full skip, all prior outbound links reused.
+     *   - some applicable extractor lacks a matching row (newly registered,
+     *     or its prior run targeted a different body hash) → run only the
+     *     missing extractors, drop prior links whose `sources` map to any
+     *     missing extractor or to an extractor that is no longer registered.
+     */
+    priorExtractorRuns?: Map<string, Map<string, string>>;
+    /**
+     * Spec § A.12 — per-plugin storage wrappers exposed to extractors via
+     * `ctx.store`. Keyed by `pluginId`; absent / missing entry leaves
+     * `ctx.store` undefined for that extractor (the existing contract).
+     *
+     * The kernel does not construct these — the driving adapter (CLI,
+     * future server) builds them with `makePluginStore` from
+     * `kernel/adapters/plugin-store.js` and threads them through. This
+     * keeps the orchestrator persistence-agnostic (the wrapper supplies
+     * its own persist callback) and lets tests inject a captured-call
+     * mock without spinning up a DB.
+     */
+    pluginStores?: ReadonlyMap<string, IPluginStore>;
+}
+/**
+ * Spec § A.9 — runs to persist into `scan_extractor_runs`. One entry
+ * per `(nodePath, qualifiedExtractorId)` pair the orchestrator decided
+ * "this extractor is current for this body". Includes both freshly-run
+ * pairs (extractor invoked this scan) and reused pairs (cached node, the
+ * extractor's prior run still applies to the same body hash). Excludes
+ * obsolete pairs — extractors that ran in the prior but are no longer
+ * registered — so a replace-all persist drops them automatically.
+ */
+interface IExtractorRunRecord {
+    nodePath: string;
+    extractorId: string;
+    bodyHashAtRun: string;
+    ranAt: number;
+}
+/**
+ * Spec § A.8 — universal enrichment layer.
+ *
+ * One entry per `(nodePath, qualifiedExtractorId)` pair an Extractor
+ * produced via `ctx.enrichNode(...)` during the walk. Attribution is
+ * preserved per-Extractor (rather than merged client-side as B.1 did)
+ * so the persistence layer can:
+ *
+ *   - upsert a single row per pair (stable PRIMARY KEY conflict on
+ *     re-extract);
+ *   - flag probabilistic rows `stale = 1` when the body changes between
+ *     scans (preserving the prior LLM cost);
+ *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
+ *     for last-write-wins per field at read time.
+ *
+ * `value` is the cumulative merge across every `enrichNode` call that
+ * Extractor made for this node within this scan — multiple
+ * `ctx.enrichNode({...})` calls inside one `extract(ctx)` invocation
+ * fold into a single row, but two different Extractors hitting the
+ * same node yield two distinct rows.
+ *
+ * `isProbabilistic` is denormalised so the persistence layer's stale
+ * flag query stays a single-table read; recomputing from the live
+ * registry would force every read-path to thread the runtime extension
+ * set through.
+ */
+interface IEnrichmentRecord {
+    nodePath: string;
+    extractorId: string;
+    bodyHashAtEnrichment: string;
+    value: Partial<Node>;
+    enrichedAt: number;
+    isProbabilistic: boolean;
+}
+/**
+ * Same as `runScan` but also returns the rename heuristic's `RenameOp[]`
+ * — the high- and medium-confidence renames the persistence layer must
+ * apply to `state_*` rows inside the same tx as the scan zone replace-
+ * all (per `spec/db-schema.md` §Rename detection). Most callers want
+ * `runScan` (which returns just `ScanResult`); the CLI's `sm scan`
+ * uses this variant so it can hand the ops off to `persistScanResult`.
+ *
+ * Also returns `extractorRuns` — the Spec § A.9 fine-grained cache
+ * breadcrumbs the CLI persists into `scan_extractor_runs` so the next
+ * incremental scan can decide per-(node, extractor) whether re-running
+ * is required.
+ */
+declare function runScanWithRenames(_kernel: Kernel, options: RunScanOptions): Promise<{
+    result: ScanResult;
+    renameOps: RenameOp[];
+    extractorRuns: IExtractorRunRecord[];
+    enrichments: IEnrichmentRecord[];
+}>;
+declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
+/**
+ * Run a set of extractors against a single node, collecting their link
+ * emissions and node-enrichment partials. Each extractor is invoked
+ * exactly once with a fresh `IExtractorContext`. Caller decides what
+ * to do with the returned arrays (push into per-scan buffers, write to
+ * a focused refresh result, etc.).
+ *
+ * Exported so `cli/commands/refresh.ts` can reuse the same wiring it
+ * needs for re-running a single extractor against a single node — the
+ * pre-extraction code in `refresh.ts` was hand-duplicating this loop
+ * (audit item V4).
+ *
+ * Within this call, multiple `enrichNode(partial)` calls from the same
+ * extractor against the same node fold into one record (last-write-wins
+ * per field) — same contract as the in-scan path.
+ */
+declare function runExtractorsForNode(opts: {
+    extractors: IExtractor[];
+    node: Node;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    bodyHash: string;
+    emitter: ProgressEmitterPort;
+    /**
+     * Spec § A.12 — per-plugin `ctx.store` wrappers keyed by `pluginId`.
+     * The map's lookup is per-extractor inside the loop, so callers that
+     * don't track plugin storage can omit it; the resulting `ctx.store`
+     * stays `undefined` (the existing contract).
+     */
+    pluginStores?: ReadonlyMap<string, IPluginStore>;
+}): Promise<{
+    internalLinks: Link[];
+    externalLinks: Link[];
+    enrichments: IEnrichmentRecord[];
+}>;
+/**
+ * Pure rename / orphan classification per `spec/db-schema.md` §Rename
+ * detection. Mutates `issues` in place — caller passes the in-progress
+ * issue list; returns the `RenameOp[]` for the persistence layer to
+ * apply inside its tx.
+ *
+ * Pipeline (1-to-1: a `newPath` claimed by one stage cannot be reused
+ * by another):
+ *
+ *   1. **High-confidence**: pair each `deletedPath` with a `newPath`
+ *      that has the same `bodyHash`. No issue, no prompt.
+ *   2. **Medium-confidence (1:1)**: of the remaining deletions, pair
+ *      each with the *unique* unclaimed `newPath` that shares its
+ *      `frontmatterHash`. Emits `auto-rename-medium` (severity warn)
+ *      with `data: { from, to, confidence: 'medium' }`.
+ *   3. **Ambiguous (N:1)**: when a single `newPath` has more than one
+ *      remaining frontmatter-matching candidate, emit ONE
+ *      `auto-rename-ambiguous` issue per `newPath`, listing all
+ *      candidates in `data.candidates`. NO migration.
+ *   4. **Orphan**: every `deletedPath` left after steps 1-3 yields one
+ *      `orphan` issue (severity info) with `data: { path: <deletedPath> }`.
+ *
+ * Determinism: `deletedPaths` and `newPaths` are iterated in lex-asc
+ * order so the same input always produces the same matches —
+ * required for reproducible tests and conformance fixtures (the spec
+ * does not prescribe an order, but stability is the obvious contract).
+ */
+declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
+/**
+ * Spec § A.8 — produce the merged read-time view of a Node.
+ *
+ * Rules / `sm check` / `sm export` consume `node.frontmatter` directly
+ * (deterministic CI-safe baseline — author intent, byte-stable). UI / future
+ * rules that opt into enrichment context call this helper to merge the
+ * author frontmatter with the live enrichment layer.
+ *
+ * Algorithm:
+ *
+ *   1. Filter `enrichments` down to rows targeting this node AND not
+ *      flagged `stale`. Stale rows (probabilistic enrichments whose
+ *      body changed since their last run) are excluded by default —
+ *      stale visibility belongs to the UI layer where the marker is
+ *      shown next to the value.
+ *   2. Sort the survivors by `enrichedAt` ASC so iteration order is
+ *      "oldest first". This makes the spread merge below
+ *      last-write-wins per field — the freshest Extractor's value
+ *      pisar the older one for any conflicting key.
+ *   3. Spread-merge each row's `value` over `node.frontmatter`. The
+ *      author's keys are the base; enrichment keys overlay them.
+ *
+ * The returned object is a fresh shallow copy — mutating it does not
+ * touch the caller's node. The original `node.frontmatter` reference
+ * remains accessible via `node.frontmatter` for callers that want the
+ * pristine author baseline.
+ *
+ * @param node          Node to merge against; `node.frontmatter` is the base.
+ * @param enrichments   Per-(node, extractor) enrichment records — typically
+ *                      loaded via `loadNodeEnrichments(db, node.path)` or
+ *                      pre-filtered to this node by the caller.
+ * @param opts.includeStale  When true, include rows flagged stale. Defaults
+ *                            to false (the safe, CI-deterministic default).
+ *                            UIs that want to display "stale (last value: …)"
+ *                            pass `true` and consult `enrichment.stale`
+ *                            on the source rows.
+ */
+declare function mergeNodeWithEnrichments(node: Node, enrichments: IPersistedEnrichment[], opts?: {
+    includeStale?: boolean;
+}): Record<string, unknown>;
+/**
+ * A persisted enrichment row, post-load. Mirrors the DB row shape
+ * but with `value` already deserialised from JSON and `stale` /
+ * `isProbabilistic` already decoded from `0 | 1`. Surfaced via
+ * `loadNodeEnrichments` (driven adapter) and consumed by
+ * `mergeNodeWithEnrichments` and the `sm refresh` command.
+ */
+interface IPersistedEnrichment {
+    nodePath: string;
+    extractorId: string;
+    bodyHashAtEnrichment: string;
+    value: Partial<Node>;
+    stale: boolean;
+    enrichedAt: number;
+    isProbabilistic: boolean;
+}
+
+/**
+ * In-memory `ProgressEmitterPort` adapter. No network, no DB — just a
+ * synchronous fan-out to registered listeners. Used by the default scan
+ * orchestrator; the WebSocket-backed emitter that streams to
+ * the Web UI lands.
+ */
+
+declare class InMemoryProgressEmitter implements ProgressEmitterPort {
+    #private;
+    emit(event: ProgressEvent): void;
+    subscribe(listener: ProgressListener): () => void;
+}
+
+/**
+ * File watcher for `sm watch` / `sm scan --watch`.
+ *
+ * Wraps `chokidar` behind a small `IFsWatcher` interface so:
+ *
+ *   1. The CLI command is impl-agnostic — swapping chokidar for a
+ *      different watcher later (Java? Rust port? a future `WatchPort`?)
+ *      doesn't ripple into the command.
+ *   2. Debouncing, batching, and ignore-filter integration live in one
+ *      place. The CLI just gets `onBatch(paths)` callbacks and decides
+ *      whether to re-scan.
+ *
+ * The watcher does NOT call into the orchestrator itself. That decision
+ * is deliberate: the CLI owns the scan-and-persist pipeline (`runScan`,
+ * `persistScanResult`, optional rebuild of the ignore filter when
+ * `.skill-mapignore` itself changes). Pulling that into the watcher
+ * would couple the kernel module to `SqliteStorageAdapter`, which the
+ * Server wouldn't want. Keep this module side-effect free
+ * apart from filesystem subscription.
+ *
+ * Ignore filter integration: the supplied `IIgnoreFilter` is consulted
+ * via chokidar's `ignored` predicate, which receives an absolute path.
+ * We re-derive the path RELATIVE to the closest matching root before
+ * passing it through `IIgnoreFilter.ignores`. This mirrors what the
+ * scan walker does (`extensions/providers/claude/index.ts`) so both code
+ * paths agree on what "ignored" means.
+ */
+
+type TWatchEventKind = 'add' | 'change' | 'unlink';
+interface IWatchEvent {
+    kind: TWatchEventKind;
+    /** Absolute path. */
+    absolutePath: string;
+}
+interface IWatchBatch {
+    /** Events that arrived inside the debounce window, in arrival order. */
+    events: IWatchEvent[];
+    /** Convenience: deduplicated absolute paths across the batch. */
+    paths: string[];
+}
+interface IFsWatcher {
+    /** Resolves once chokidar has finished its initial directory scan and is ready to emit. */
+    ready: Promise<void>;
+    /** Tear down the watcher. Resolves after chokidar releases handles. */
+    close: () => Promise<void>;
+}
+interface ICreateFsWatcherOptions {
+    /** Roots to watch. Resolved relative to `cwd` if relative paths are passed. */
+    roots: string[];
+    /** Working directory used to resolve relative roots and the ignore-filter root. */
+    cwd: string;
+    /** Debounce window in milliseconds. `0` triggers `onBatch` synchronously per event. */
+    debounceMs: number;
+    /** Optional ignore filter — same instance the scan walker uses. */
+    ignoreFilter?: IIgnoreFilter | undefined;
+    /** Called once per debounced batch. Awaited; concurrent batches are serialised. */
+    onBatch: (batch: IWatchBatch) => void | Promise<void>;
+    /**
+     * Called when the underlying watcher surfaces an error. The watcher
+     * stays open — callers decide whether to log, keep going, or close.
+     */
+    onError?: (err: Error) => void;
+}
+/**
+ * Construct a chokidar-backed watcher. Subscribes immediately; the
+ * returned `ready` promise resolves once chokidar's initial directory
+ * walk completes, at which point only NEW events fire `onBatch`.
+ *
+ * The initial directory walk is deliberately silent — we set
+ * `ignoreInitial: true`. The CLI runs a one-shot scan before flipping
+ * the watcher on, so re-emitting an `add` for every existing file
+ * would be redundant churn.
+ */
+declare function createChokidarWatcher(opts: ICreateFsWatcherOptions): IFsWatcher;
+
+/**
+ * Scan delta — pure comparison of two `ScanResult` snapshots. Drives
+ * `sm scan --compare-with <path>` and is the single place the kernel
+ * knows how to identify "the same" entity across two scans.
+ *
+ * **Identity contract** (mirrors decisions made at earlier sub-steps):
+ *
+ *   - **Node**: `node.path`. The path is the only field stable across
+ *     edits — every other Node field is content-derived (hashes, counts,
+ *     denormalised frontmatter). Two nodes with the same path are the
+ *     "same" node; differences are reported as a `changed` entry with
+ *     a reason narrowing what diverged.
+ *
+ *   - **Link**: `(source, target, kind, normalizedTrigger ?? '')`. This
+ *     mirrors the link-conflict rule and `sm show` aggregation —
+ *     two links with identical endpoints, kind, and (optional) trigger
+ *     are the same link, even if emitted by different extractors. The
+ *     `sources[]` union and confidence are NOT part of identity; they
+ *     are presentation facets that can churn without making the link
+ *     "different" for delta purposes.
+ *
+ *   - **Issue**: `(ruleId, sorted nodeIds, message)`. Mirrors
+ *     `spec/job-events.md` §issue.* — same key → same issue, even when
+ *     `data` / `severity` / `linkIndices` shift. A meaningful change in
+ *     `message` (or a different set of node ids) is a different issue.
+ *     This is the same key future job events will use; keep it aligned
+ *     so consumers can reuse logic.
+ *
+ * No "changed" bucket for links / issues — identity already captures
+ * everything that matters there. Nodes get a "changed" bucket because
+ * the path stays stable while the body / frontmatter rewrite, and that
+ * change is meaningful (formatters, summarisers, downstream consumers
+ * all care about it).
+ *
+ * Pure: no IO, no DB, no FS. Safe to run in-memory inside `sm scan`
+ * without polluting the persisted snapshot.
+ */
+
+type TNodeChangeReason = 'body' | 'frontmatter' | 'both';
+interface INodeChange {
+    before: Node;
+    after: Node;
+    /**
+     * Which hash diverged. `'body'` means body rewritten, frontmatter
+     * untouched; `'frontmatter'` means metadata rewritten, body
+     * untouched; `'both'` means both rewritten in the same edit.
+     */
+    reason: TNodeChangeReason;
+}
+interface IScanDelta {
+    /** Path the current scan was compared against (echoed for the report header). */
+    comparedWith: string;
+    nodes: {
+        added: Node[];
+        removed: Node[];
+        changed: INodeChange[];
+    };
+    links: {
+        added: Link[];
+        removed: Link[];
+    };
+    issues: {
+        added: Issue[];
+        removed: Issue[];
+    };
+}
+declare function computeScanDelta(prior: ScanResult, current: ScanResult, comparedWith: string): IScanDelta;
+/**
+ * `true` iff every bucket is empty. Callers use this to decide the
+ * exit code (`0` clean, `1` non-empty delta).
+ */
+declare function isEmptyDelta(delta: IScanDelta): boolean;
+
+/**
+ * Export query — minimal filter language for `sm export <query>` (Step 8.3).
+ *
+ * Spec contract: `spec/cli-contract.md` line 190 says "Query syntax is
+ * implementation-defined pre-1.0". This module defines the v0.5.0 syntax.
+ *
+ * **Grammar** (BNF-ish, intentionally tiny):
+ *
+ *   query     := token (WS+ token)*
+ *   token     := key "=" value-list
+ *   key       := "kind" | "has" | "path"
+ *   value-list := value ("," value)*
+ *   value     := non-comma, non-whitespace string
+ *
+ * Tokens AND together; values within one token OR. An empty / whitespace-only
+ * query is valid and matches every node ("export everything").
+ *
+ * **Filters**:
+ *
+ *   - `kind=skill` / `kind=skill,agent` — node kind whitelist.
+ *   - `has=issues` — node must appear in some issue's `nodeIds`. (Future
+ *     expansion: `has=findings` / `has=summary` once Step 10 / 11 land.
+ *     Unknown values are a parse error today; we'll ratchet up the
+ *     accepted set additively.)
+ *   - `path=foo/*` / `path=.claude/agents/**` — POSIX glob over `node.path`.
+ *     Supports `*` (any chars except `/`) and `**` (any chars including `/`).
+ *
+ * **Subset semantics** (`applyExportQuery`):
+ *
+ *   - Nodes pass when every specified filter matches (AND across keys,
+ *     OR within values).
+ *   - Links survive only when BOTH endpoints (`source` + `target`) belong
+ *     to the filtered node set. A subset that includes "edges out to
+ *     unfiltered nodes" would be confusing — the user asked for a focused
+ *     subgraph, not its boundary. External-URL pseudo-links are already
+ *     stripped by the orchestrator and never reach this layer.
+ *   - Issues survive when ANY of the issue's `nodeIds` is in the filtered
+ *     set. Issues span multiple nodes (e.g. `trigger-collision` over two
+ *     advertisers); dropping an issue when one of its nodes is outside
+ *     would hide cross-cutting problems the user is investigating.
+ *
+ * Pure: no IO, no DB, no FS.
+ */
+
+interface IExportQuery {
+    /** Original query string echoed back so consumers can render the header. */
+    raw: string;
+    /**
+     * Whitelist of node kinds (`node.kind` is open string — built-in
+     * Claude catalog `skill` / `agent` / `command` / `hook` / `note`,
+     * plus whatever external Providers declare). The query parser does
+     * not validate values against a closed enum; an unknown kind simply
+     * yields zero matches at filter time.
+     */
+    kinds?: string[];
+    hasIssues?: boolean;
+    pathGlobs?: string[];
+}
+interface IExportSubset {
+    query: IExportQuery;
+    nodes: Node[];
+    links: Link[];
+    issues: Issue[];
+}
+declare class ExportQueryError extends Error {
+    constructor(message: string);
+}
+declare function parseExportQuery(raw: string): IExportQuery;
+declare function applyExportQuery(scan: {
+    nodes: Node[];
+    links: Link[];
+    issues: Issue[];
+}, query: IExportQuery): IExportSubset;
+
+/**
+ * `PluginLoaderPort` — discovers plugin directories and loads their
+ * extensions. The shape mirrors what the concrete loader actually
+ * exposes (see `kernel/adapters/plugin-loader.ts`); the port exists so
+ * the CLI consumes the abstract contract via `createPluginLoader(...)`
+ * instead of `new PluginLoader(...)` and so the concrete adapter is
+ * structurally pinned to the port (`implements PluginLoaderPort` makes
+ * any drift a compile error).
+ *
+ * Domain types (`IPluginManifest`, `ILoadedExtension`, `IDiscoveredPlugin`,
+ * `TPluginStorage`, `TPluginLoadStatus`, `TGranularity`) live in
+ * `kernel/types/plugin.ts` because they are spec-mirroring DTOs, not
+ * port-shape types. The port re-exports them for callers that import
+ * from the ports barrel.
+ */
+
+interface PluginLoaderPort {
+    /**
+     * Synchronously enumerate every directory containing a `plugin.json`
+     * across the configured search paths. Non-existent paths are skipped.
+     */
+    discoverPaths(): string[];
+    /**
+     * Discover every plugin, attempt to load each, then apply the
+     * cross-root id-collision pass. Never throws — failures are reported
+     * via `IDiscoveredPlugin.status`.
+     */
+    discoverAndLoadAll(): Promise<IDiscoveredPlugin[]>;
+    /**
+     * Load a single plugin from its directory. Never throws — failure is
+     * reported via the returned `status`.
+     */
+    loadOne(pluginPath: string): Promise<IDiscoveredPlugin>;
+}
+
+/**
+ * Row-level filter for `port.scans.findNodes(...)` (driven by
+ * `sm list`'s flags). All fields are optional — an empty filter
+ * returns every node sorted by `path` asc.
+ */
+interface INodeFilter {
+    /** Restrict to a single node kind. Open string (matches `Node.kind`). */
+    kind?: string;
+    /**
+     * When `true`, keep only nodes whose path is referenced by at least
+     * one `scan_issues.nodeIds` array.
+     */
+    hasIssues?: boolean;
+    /**
+     * Sort column. The adapter validates against its own whitelist and
+     * rejects anything else with an Error (the CLI's own usage-error
+     * exit is the right place to surface a bad `--sort-by`; the port
+     * defends in depth).
+     */
+    sortBy?: string;
+    /** `'asc'` or `'desc'`. Defaults to the adapter's per-column convention. */
+    sortDirection?: 'asc' | 'desc';
+    /** Cap the result. Positive integer; absent → no limit. */
+    limit?: number;
+}
+/**
+ * Bundled fetch for `port.scans.findNode(path)` — one node and
+ * everything `sm show <path>` displays alongside it. Every field is
+ * computed from `scan_*` zone reads only; per-domain data (history,
+ * jobs, plugin enrichments) ships through other namespaces.
+ */
+interface INodeBundle {
+    node: Node;
+    linksOut: Link[];
+    linksIn: Link[];
+    issues: Issue[];
+}
+/**
+ * Output of `port.scans.countRows()`. Used by `sm scan` to decide
+ * whether the persist would wipe a populated DB (the "refusing to
+ * wipe" guard) and by `sm db status` for the human summary.
+ */
+interface INodeCounts {
+    nodes: number;
+    links: number;
+    issues: number;
+}
+/**
+ * Lightweight option bag for `port.scans.persist`. Mirrors the trailing
+ * arguments of the legacy `persistScanResult(db, result, renameOps,
+ * extractorRuns, enrichments)` free function so the adapter
+ * implementation is a one-line delegation today; the named-bag shape
+ * tomorrow lets new optional inputs land without breaking callers.
+ */
+interface IPersistOptions {
+    renameOps?: RenameOp[];
+    extractorRuns?: IExtractorRunRecord[];
+    enrichments?: IEnrichmentRecord[];
+}
+/**
+ * Issue row as the storage layer sees it — paired with its DB-assigned
+ * id so `port.issues.deleteById(id)` can target it inside a
+ * transaction. The runtime `Issue` shape (per `issue.schema.json`) does
+ * not carry `id` because the spec models issues as ephemeral findings
+ * scoped to a scan; the DB does need the synthetic id to update / delete
+ * a single row.
+ */
+interface IIssueRow {
+    id: number;
+    issue: Issue;
+}
+/** Output of `port.jobs.pruneTerminal` / `listTerminalCandidates`. */
+interface IPruneResult {
+    /** How many `state_jobs` rows were deleted (or would be, in dry-run). */
+    deletedCount: number;
+    /** Job-file paths from the affected rows; the CLI unlinks these from disk. `null` `filePath` rows contribute nothing here. */
+    filePaths: string[];
+}
+/** Filter shape for `port.history.list`. All fields optional. */
+interface IListExecutionsFilter {
+    /** Restrict to executions whose `nodeIds` array contains this path. */
+    nodePath?: string;
+    /** Exact match on `extension_id`. */
+    actionId?: string;
+    /** Subset of {`completed`,`failed`,`cancelled`}. */
+    statuses?: ExecutionStatus[];
+    /** Lower bound (inclusive) on `started_at`. Unix ms. */
+    sinceMs?: number;
+    /** Upper bound (exclusive) on `started_at`. Unix ms. */
+    untilMs?: number;
+    /** Cap result count. No default. */
+    limit?: number;
+}
+/** Window shape for `port.history.aggregateStats`. */
+interface IHistoryStatsRange {
+    /** Inclusive lower bound. `null` = all-time. */
+    sinceMs: number | null;
+    /** Exclusive upper bound. */
+    untilMs: number;
+}
+/** Period bucket granularity for `port.history.aggregateStats`. */
+type THistoryStatsPeriod = 'day' | 'week' | 'month';
+/**
+ * Output of `port.transaction(tx => tx.history.migrateNodeFks(from, to))`.
+ * Lists how many rows in each `state_*` table were repointed plus any
+ * composite-PK collisions that forced a drop instead of an update.
+ */
+interface IMigrateNodeFksReport {
+    jobs: number;
+    executions: number;
+    summaries: number;
+    enrichments: number;
+    pluginKvs: number;
+    /**
+     * Composite-PK collisions encountered when migrating
+     * `state_summaries` / `state_enrichments` / `state_plugin_kvs` because
+     * a row already existed at the destination PK. The pre-existing rows
+     * are preserved — the migrating rows are dropped (deleted from
+     * `fromPath` without a corresponding INSERT). One entry per dropped
+     * row, with the affected PK fields included for diagnostic output.
+     */
+    collisions: Array<{
+        table: 'state_summaries' | 'state_enrichments' | 'state_plugin_kvs';
+        fromPath: string;
+        toPath: string;
+        keys: Record<string, string>;
+    }>;
+}
+/** A single `config_plugins` override row as the kernel sees it. */
+interface IPluginConfigRow {
+    pluginId: string;
+    enabled: boolean;
+    configJson: string | null;
+    updatedAt: number;
+}
+/** Discovered kernel migration file (one of `NNN_snake_case.sql`). */
+interface IMigrationFile {
+    version: number;
+    description: string;
+    filePath: string;
+}
+/** A row from the `config_schema_versions` ledger for the kernel scope. */
+interface IMigrationRecord {
+    scope: string;
+    ownerId: string;
+    version: number;
+    description: string;
+    appliedAt: number;
+}
+/** `port.migrations.plan` output: applied vs pending. */
+interface IMigrationPlan {
+    applied: IMigrationRecord[];
+    pending: IMigrationFile[];
+}
+/** Apply-time options for `port.migrations.apply`. */
+interface IApplyOptions {
+    backup?: boolean;
+    dryRun?: boolean;
+    to?: number;
+}
+/** Result of `port.migrations.apply`. */
+interface IApplyResult {
+    applied: IMigrationFile[];
+    backupPath: string | null;
+}
+/** Discovered plugin migration file. Same `NNN_snake_case.sql` convention. */
+interface IPluginMigrationFile {
+    version: number;
+    description: string;
+    filePath: string;
+}
+/** A row from the `config_schema_versions` ledger for a single plugin. */
+interface IPluginMigrationRecord {
+    version: number;
+    description: string;
+    appliedAt: number;
+}
+/** `port.pluginMigrations.plan` output for a single plugin. */
+interface IPluginMigrationPlan {
+    pluginId: string;
+    applied: IPluginMigrationRecord[];
+    pending: IPluginMigrationFile[];
+}
+/** Apply-time options for `port.pluginMigrations.apply`. */
+interface IPluginApplyOptions {
+    /** No actual writes; surfaces what would run. Default false. */
+    dryRun?: boolean;
+}
+/** Result of `port.pluginMigrations.apply`. */
+interface IPluginApplyResult {
+    pluginId: string;
+    applied: IPluginMigrationFile[];
+    /** Catalog intrusions caught by Layer 3 (post-apply sweep). Empty when clean. */
+    intrusions: string[];
+}
+
+/**
+ * `StoragePort` — the kernel's persistence boundary. Driving adapters
+ * (CLI, future server, in-memory test harness) consume this surface
+ * exclusively; nothing in `cli/**` should reach into the SQLite
+ * adapter's internal helpers (free functions on
+ * `kernel/adapters/sqlite/*`) directly. Phase F of the
+ * storage-port-promotion refactor finishes that hardening; A-E grow
+ * the port enough that the CLI has somewhere to land.
+ *
+ * The port is namespaced by domain (`scans`, `issues`, `enrichments`,
+ * etc.) — explicitly NOT a generic `port.query<T>(sql)`. Each
+ * namespace's methods name an operation the kernel cares about; the
+ * adapter translates to its persistence engine's idioms.
+ *
+ * Phase A lands the **scans / issues / enrichments / transaction**
+ * namespaces — the core scan pipeline. The remaining namespaces
+ * (history / jobs / pluginConfig / migrations / pluginMigrations)
+ * arrive in subsequent phases. The port shape declared here is the
+ * Phase A subset; later phases extend it without reshaping what
+ * lands today.
+ */
+
+/**
+ * Subset of `StoragePort` exposed inside a `transaction(fn)` callback.
+ * Lifecycle methods are intentionally omitted — a transaction that
+ * tries to `init()` the adapter mid-flight is a category error.
+ *
+ * Every callable in the subset MUST run on the same underlying
+ * transaction handle the adapter opened for the callback. Adapters
+ * are responsible for that wiring; consumers only see the namespace
+ * surfaces.
+ */
+interface ITransactionalStorage {
+    scans: {
+        persist(result: ScanResult, opts?: IPersistOptions): Promise<void>;
+    };
+    issues: {
+        deleteById(id: number): Promise<void>;
+        insert(issue: Issue): Promise<void>;
+    };
+    enrichments: {
+        /**
+         * Upsert a batch of fresh enrichment records produced by an
+         * extractor pass. Composite PK is `(nodePath, extractorId)`;
+         * conflict → replace. Every row lands with `stale = 0` (the
+         * caller just refreshed it; ROADMAP §B.10 — staleness is
+         * computed downstream when the body hash changes again).
+         */
+        upsertMany(records: IEnrichmentRecord[]): Promise<void>;
+    };
+    history: {
+        /**
+         * Repoint every `state_*` reference from `fromPath` to `toPath`.
+         * Atomic across the four state tables; the report flags any
+         * composite-PK collisions so callers can diagnose them.
+         * `sm orphans reconcile` / `undo-rename` and the scan-time
+         * rename heuristic are the canonical consumers.
+         */
+        migrateNodeFks(from: string, to: string): Promise<IMigrateNodeFksReport>;
+    };
+}
+interface StoragePort {
+    init(): Promise<void>;
+    close(): Promise<void>;
+    scans: {
+        /**
+         * Persist a fresh `ScanResult` (replace-all on the scan zone).
+         * Called by `sm scan` after the orchestrator returns. The renames /
+         * extractor-runs / enrichments side bags ride along inside the
+         * same transaction — the call is atomic from the caller's view.
+         */
+        persist(result: ScanResult, opts?: IPersistOptions): Promise<void>;
+        /**
+         * Hydrate the persisted `ScanResult`. Returns the snapshot the
+         * scan zone holds today (including external-Provider kinds —
+         * `node.kind` is open string per `node.schema.json`).
+         */
+        load(): Promise<ScanResult>;
+        /**
+         * Spec § A.9 — fine-grained extractor-runs cache breadcrumbs.
+         * Returns `Map<nodePath, Map<qualifiedExtractorId, bodyHashAtRun>>`.
+         */
+        loadExtractorRuns(): Promise<Map<string, Map<string, string>>>;
+        /** Universal enrichment layer — every persisted `(node, extractor)` pair. */
+        loadNodeEnrichments(): Promise<IPersistedEnrichment[]>;
+        /**
+         * Row counts for `scan_nodes` / `scan_links` / `scan_issues`.
+         * Used by `sm scan`'s "refusing to wipe a populated DB" guard.
+         */
+        countRows(): Promise<INodeCounts>;
+        /** Row-level filter for `sm list`. Open `kind` (matches `Node.kind`). */
+        findNodes(filter: INodeFilter): Promise<Node[]>;
+        /**
+         * Bundled fetch for `sm show <path>`. Returns `null` if the node
+         * is not in the persisted scan.
+         */
+        findNode(path: string): Promise<INodeBundle | null>;
+    };
+    issues: {
+        /** Every issue from the latest scan, in insertion order. */
+        listAll(): Promise<Issue[]>;
+        /**
+         * Issue rows whose runtime `Issue` shape passes `predicate`.
+         * `port.issues.findActive((i) => i.ruleId === 'orphan')` is the
+         * canonical use; `sm orphans` consumes this. The returned shape
+         * carries the DB-assigned `id` so a follow-up
+         * `transaction(tx => tx.issues.deleteById(row.id))` can target
+         * a specific row.
+         */
+        findActive(predicate: (issue: Issue) => boolean): Promise<IIssueRow[]>;
+    };
+    pluginConfig: {
+        /**
+         * Upsert the per-plugin enabled override into `config_plugins`.
+         * Caller is `sm plugins enable / disable`.
+         */
+        set(pluginId: string, enabled: boolean): Promise<void>;
+        /** Read a single override; `undefined` when no row exists. */
+        get(pluginId: string): Promise<boolean | undefined>;
+        /** Every override row, sorted by `pluginId` for stable rendering. */
+        list(): Promise<IPluginConfigRow[]>;
+        /** Drop a single override row (no-op when absent). */
+        delete(pluginId: string): Promise<void>;
+        /**
+         * Load every override into a map for quick lookup by id. Used by
+         * `loadPluginRuntime` to layer the DB overrides over the
+         * `settings.json` defaults at scan boot.
+         */
+        loadOverrideMap(): Promise<Map<string, boolean>>;
+    };
+    jobs: {
+        /**
+         * Delete `state_jobs` rows in terminal `status` whose `finishedAt`
+         * is older than `cutoffMs` (Unix ms). Returns the deleted count
+         * plus every non-null `filePath` from the deleted rows so the
+         * caller can unlink the on-disk MD files. Caller computes
+         * `cutoffMs` from the configured retention.
+         */
+        pruneTerminal(status: 'completed' | 'failed', cutoffMs: number): Promise<IPruneResult>;
+        /**
+         * Same SELECT side as `pruneTerminal` but without the DELETE.
+         * Powers `sm job prune --dry-run` previews so the dry-run output
+         * names exactly the rows the live mode would delete.
+         */
+        listTerminalCandidates(status: 'completed' | 'failed', cutoffMs: number): Promise<IPruneResult>;
+        /**
+         * Read every `state_jobs.filePath` currently set, normalized through
+         * `path.resolve()`. The CLI's `sm job prune --orphan-files` flow
+         * pairs this set with `kernel/jobs/orphan-files.ts:findOrphanJobFiles`
+         * (which walks the directory) to compute the MD files on disk that
+         * no row references — keeps the storage layer FS-free.
+         */
+        listReferencedFilePaths(): Promise<Set<string>>;
+    };
+    history: {
+        /** List `state_executions` rows (paginated by filter). */
+        list(filter: IListExecutionsFilter): Promise<ExecutionRecord[]>;
+        /**
+         * Aggregate counters / period buckets / top-nodes / error rates
+         * over `state_executions`. Body matches the spec
+         * `history-stats.schema.json` shape minus `range`/`elapsedMs`
+         * (the verb fills those in around the call).
+         */
+        aggregateStats(range: IHistoryStatsRange, period: THistoryStatsPeriod, topN: number): Promise<Omit<HistoryStats, 'elapsedMs' | 'range'> & {
+            rangeMs: {
+                sinceMs: number | null;
+                untilMs: number;
+            };
+        }>;
+    };
+    migrations: {
+        /** Enumerate kernel migration files bundled with this build. */
+        discover(): IMigrationFile[];
+        /**
+         * Compute the apply / pending plan against the current `config_
+         * schema_versions` ledger. Read-only; safe under `--dry-run`.
+         */
+        plan(files?: IMigrationFile[]): IMigrationPlan;
+        /**
+         * Apply pending migrations in order. Each runs inside its own
+         * `BEGIN/COMMIT` (per `kernel/adapters/sqlite/migrations.ts`); a
+         * partial failure rolls back to the prior state. Returns the
+         * applied list + backup path (when `backup: true`).
+         */
+        apply(options?: IApplyOptions, files?: IMigrationFile[]): IApplyResult;
+        /**
+         * WAL-checkpoint + atomic file copy of the DB to `destPath`.
+         * Caller composes the path. Returns the destination on success,
+         * or `null` for in-memory DBs (no file to copy).
+         */
+        writeBackup(destPath: string): string | null;
+        /**
+         * Read `PRAGMA user_version` from the underlying DB. The migrations
+         * runner keeps that pragma in sync with the latest applied kernel
+         * migration, so this is the canonical "current schema version"
+         * read for `sm version --json`'s `dbSchema` field. Returns `null`
+         * on engine quirks (non-numeric / null pragma).
+         */
+        currentSchemaVersion(): number | null;
+    };
+    pluginMigrations: {
+        /** Path to the plugin's `migrations/` directory, or `null` when absent. */
+        resolveDir(plugin: IDiscoveredPlugin): string | null;
+        /** Discover the plugin's migration files. */
+        discover(plugin: IDiscoveredPlugin): IPluginMigrationFile[];
+        /**
+         * Plan against `config_schema_versions` for the plugin's
+         * `(scope='plugin', ownerId=plugin.id)`.
+         */
+        plan(plugin: IDiscoveredPlugin, files?: IPluginMigrationFile[]): IPluginMigrationPlan;
+        /** Apply pending plugin migrations. Same per-file BEGIN/COMMIT pattern. */
+        apply(plugin: IDiscoveredPlugin, options?: IPluginApplyOptions, files?: IPluginMigrationFile[]): IPluginApplyResult;
+    };
+    /**
+     * Open a transaction. The callback receives a transactional subset
+     * of the port; the adapter commits on resolution and rolls back on
+     * rejection. `sm orphans reconcile / undo-rename` and `sm refresh`
+     * are the canonical consumers.
+     */
+    transaction<T>(fn: (tx: ITransactionalStorage) => Promise<T>): Promise<T>;
+}
+
+/**
+ * `FilesystemPort` — walks roots, reads nodes, writes job files.
+ *
+ * Shape-only. The real adapter ships with the scan end-to-end pipeline.
+ */
+interface NodeStat {
+    path: string;
+    sizeBytes: number;
+    mtimeMs: number;
+}
+interface IWalkOptions {
+    ignore?: string[];
+}
+interface FilesystemPort {
+    walk(roots: string[], options?: IWalkOptions): AsyncIterable<NodeStat>;
+    readNode(path: string): Promise<string>;
+    stat(path: string): Promise<NodeStat>;
+    writeJobFile(path: string, content: string): Promise<void>;
+    ensureDir(path: string): Promise<void>;
+}
+
+/**
+ * `RunnerPort` — executes an action against a rendered job file.
+ *
+ * Shape-only. `ClaudeCliRunner` + `MockRunner` land with the job subsystem
+ * (job subsystem + first summarizer).
+ */
+interface IRunOptions {
+    timeoutMs?: number;
+    model?: string;
+}
+interface IRunResult {
+    reportPath: string;
+    tokensIn: number;
+    tokensOut: number;
+    durationMs: number;
+    exitCode: number;
+}
+interface RunnerPort {
+    run(jobFilePath: string, options?: IRunOptions): Promise<IRunResult>;
+}
+
+/**
+ * `LoggerPort` — structured logging port for the kernel.
+ *
+ * The kernel must NOT write to stdout/stderr directly. Anything that
+ * would historically have been a `console.log` / `console.error` goes
+ * through this port; the adapter (CLI, server, test harness) decides
+ * format, level filter, and destination.
+ *
+ * Levels follow the conventional ordering, lowest = most verbose:
+ *
+ *   trace < debug < info < warn < error < silent
+ *
+ * `silent` is a sentinel for filtering only — it never appears as a
+ * `LogRecord.level`. Setting an adapter to `silent` disables every
+ * method.
+ */
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+type LogMethodLevel = Exclude<LogLevel, 'silent'>;
+declare const LOG_LEVELS: readonly LogLevel[];
+declare function logLevelRank(level: LogLevel): number;
+declare function isLogLevel(value: unknown): value is LogLevel;
+/**
+ * Parse a string into a `LogLevel`. Returns `null` for invalid input
+ * (incl. `undefined` / `null` / empty). Case-insensitive; trims
+ * whitespace.
+ */
+declare function parseLogLevel(value: string | undefined | null): LogLevel | null;
+interface LogRecord {
+    level: LogMethodLevel;
+    /** ISO 8601 timestamp produced at the moment the log call was made. */
+    timestamp: string;
+    message: string;
+    /** Optional structured context. Caller-owned; serialization is up to the formatter. */
+    context?: Record<string, unknown>;
+}
+interface LoggerPort {
+    trace(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+
+/**
+ * No-op `LoggerPort`. Default when the kernel is invoked without a
+ * logger (tests, embedded usage). Equivalent in spirit to
+ * `InMemoryProgressEmitter`: callers that don't care get a working
+ * implementation that does nothing.
+ *
+ * Every method is intentionally empty — that IS the contract of this
+ * class. We disable `no-empty-function` for the whole file because
+ * adding `// eslint-disable-next-line` to each method would be noise.
+ */
+
+declare class SilentLogger implements LoggerPort {
+    trace(): void;
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+
+/**
+ * Module-level singleton `LoggerPort`. The kernel emits warnings /
+ * info / debug through `log.*`; the active implementation defaults to
+ * `SilentLogger` (no output) and is swapped by the driving adapter at
+ * boot time via `configureLogger(...)`.
+ *
+ * Why a singleton (vs. per-call injection):
+ *   - Logging crosses every layer; threading a `logger` argument
+ *     through every kernel function costs a lot of plumbing for a
+ *     side-channel concern.
+ *   - The active impl is a pointer; the exported `log` is a stable
+ *     proxy. Imports made before `configureLogger` runs still see the
+ *     new impl on every call — no "captured stale logger" bugs.
+ *
+ * Tradeoffs accepted:
+ *   - Tests must call `resetLogger()` (or replace the active impl) in
+ *     teardown to avoid cross-test bleed.
+ *   - Concurrent scans share the same logger; per-scan logging requires
+ *     reintroducing an explicit `logger` argument on the call path.
+ */
+
+/** Stable proxy. Methods always delegate to the current `active` impl. */
+declare const log: LoggerPort;
+/** Install a logger as the active implementation. Idempotent. */
+declare function configureLogger(impl: LoggerPort): void;
+/** Restore the default `SilentLogger`. Call from test teardown. */
+declare function resetLogger(): void;
+/** Inspect the active logger. Test-only — production code uses `log`. */
+declare function getActiveLogger(): LoggerPort;
+
+/**
+ * Kernel entry point. `createKernel()` returns a shell with an empty registry
+ * and no bound ports. Driving adapters (CLI, Server, Skill) are expected to
+ * wire adapters before invoking use cases.
+ */
+
+interface Kernel {
+    registry: Registry;
+}
+declare function createKernel(): Kernel;
+
+export { type Confidence, DuplicateExtensionError, EXTENSION_KINDS, type ExecutionFailureReason, type ExecutionKind, type ExecutionRecord, type ExecutionRunner, type ExecutionStatus, ExportQueryError, type Extension, type ExtensionKind, type FilesystemPort, HOOK_TRIGGERS, type HistoryStats, type HistoryStatsErrorRates, type HistoryStatsExecutionsPerPeriod, type HistoryStatsPerActionRate, type HistoryStatsTokensPerAction, type HistoryStatsTopNode, type HistoryStatsTotals, type IAction, type IActionPrecondition, type ICreateFsWatcherOptions, type IDedicatedStorePersist, type IDedicatedStoreWrapper, type IDiscoveredPlugin, type IEnrichmentRecord, type IExportQuery, type IExportSubset, type IExtensionBase, type IExtractor, type IExtractorCallbacks, type IExtractorContext, type IExtractorRunRecord, type IFormatter, type IFormatterContext, type IFsWatcher, type IHook, type IHookContext, type IIssueRow, type IKvStorePersist, type IKvStoreWrapper, type ILoadedExtension, type INodeBundle, type INodeChange, type INodeCounts, type INodeFilter, type IPersistOptions, type IPersistedEnrichment, type IPluginManifest, type IPluginStorageSchema, type IPluginStore, type IProvider, type IRawNode, type IRule, type IRuleContext, type IRunOptions, type IRunResult, type IScanDelta, type ITransactionalStorage, type IWalkOptions, type IWatchBatch, type IWatchEvent, InMemoryProgressEmitter, type Issue, type IssueFix, KV_SCHEMA_KEY, type Kernel, LOG_LEVELS, type Link, type LinkKind, type LinkLocation, type LinkTrigger, type LogLevel, type LogMethodLevel, type LogRecord, type LoggerPort, type Node, type NodeKind, type NodeStat, type PluginLoaderPort, type ProgressEmitterPort, type ProgressEvent, type ProgressListener, Registry, type RenameOp, type RunScanOptions, type RunnerPort, type ScanResult, type ScanScannedBy, type ScanStats, type Severity, SilentLogger, type Stability, type StoragePort, type TExecutionMode, type TGranularity, type THookFilter, type THookTrigger, type TNodeChangeReason, type TPluginLoadStatus, type TPluginStorage, type TWatchEventKind, type TripleSplit, applyExportQuery, computeScanDelta, configureLogger, createChokidarWatcher, createKernel, detectRenamesAndOrphans, getActiveLogger, isEmptyDelta, isLogLevel, log, logLevelRank, makeDedicatedStoreWrapper, makeKvStoreWrapper, makePluginStore, mergeNodeWithEnrichments, parseExportQuery, parseLogLevel, qualifiedExtensionId, resetLogger, runExtractorsForNode, runScan, runScanWithRenames };