@skill-map/cli 0.23.1 → 0.24.1

package/dist/kernel/index.d.ts

@@ -1088,2244 +1088,2252 @@ declare function makePluginStore(opts: {
 }): IPluginStore | undefined;
 
 /**
- * `scan_contributions` adapter, replace-all writer used by
- * `persistScanResult`, plus read helpers consumed by the BFF
- * (`/api/contributions/...`) and rules (`core/contribution-orphan`).
- *
- * One row per `(plugin_id, extension_id, node_path, contribution_id)`
- * tuple. See `spec/architecture.md` § View contribution system →
- * Persistence and `migrations/001_initial.sql` § View contribution
- * layer for the normative shape.
- *
- * Replace-all semantics mirror the rest of the `scan_*` zone: every
- * scan is a fresh snapshot, so prior rows are deleted before insert.
- * Wrapped in the same transaction `persistScanResult` opens.
- *
- * The rename heuristic does NOT need to migrate `node_path` here,
- * because of replace-all, every contribution is re-emitted on the new
- * path automatically. Keeping the rename path lighter than `state_*`
- * (which IS rename-migrated because state survives across scans).
- */
-
-/**
- * In-memory contribution record buffered during scan and flushed to
- * `scan_contributions` by `persistScanResult`. One entry per accepted
- * `ctx.emitContribution(id, payload)` call. Payload validation against
- * the slot's payload schema happens at emit time (orchestrator);
- * by the time records reach this adapter they are wire-shape clean.
+ * 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 IContributionRecord {
-    pluginId: string;
-    extensionId: string;
-    nodePath: string;
-    contributionId: string;
+interface INodeFilter {
+    /** Restrict to a single node kind. Open string (matches `Node.kind`). */
+    kind?: string;
     /**
-     * Closed enum value mirroring `view-slots.schema.json#/$defs/SlotName`.
-     * Persisted as TEXT (no SQL CHECK by design, see migration comment).
+     * When `true`, keep only nodes whose path is referenced by at least
+     * one `scan_issues.nodeIds` array.
      */
-    slot: string;
-    /** Already-validated payload. Serialised via `JSON.stringify` at write. */
-    payload: unknown;
-    emittedAt: number;
+    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;
 }
 /**
- * Single contribution row as returned to callers. The payload is
- * `unknown` because the slot space is open at the type layer (catalog
- * evolution is a kernel + spec concern); narrow at the call site by
- * reading `slot`.
+ * 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 IPersistedContribution {
-    pluginId: string;
-    extensionId: string;
-    nodePath: string;
-    contributionId: string;
-    slot: string;
-    payload: unknown;
-    emittedAt: number;
+interface INodeBundle {
+    node: Node;
+    linksOut: Link[];
+    linksIn: Link[];
+    issues: Issue[];
 }
-
-/**
- * `loadScanResult`, driving inverse of `persistScanResult`. Reads the
- * `scan_*` tables and reconstructs a `ScanResult` shape so the
- * orchestrator can run an incremental scan (`sm scan --changed`) on
- * top of a prior snapshot.
- *
- * The reconstruction is faithful for everything that was actually
- * persisted: nodes (with triple-split bytes / tokens, denormalised
- * counts, JSON frontmatter), internal links (with regrouped
- * `trigger` / `location`, parsed `sources[]`), and issues
- * (with parsed `nodeIds` / `linkIndices` / `fix` / `data`).
- *
- * **Documented omission**: external pseudo-links (those whose target is
- * an `http://` / `https://` URL emitted by the external-url-counter
- * extractor) are NEVER persisted to `scan_links`, only their per-node
- * count survives in `scan_nodes.external_refs_count`. Therefore the
- * `result.links` returned by `loadScanResult` contains only internal
- * graph links, and `node.externalRefsCount` is the authoritative count
- * carried over from the prior scan. The orchestrator's incremental path
- * preserves that count for "unchanged" nodes and re-derives it for
- * new / modified nodes from a fresh extractor pass.
- *
- * Meta envelope: the `scan_meta` table persists `scope` / `roots` /
- * `scannedAt` / `scannedBy` / `providers` / `stats.filesWalked` /
- * `stats.filesSkipped` / `stats.durationMs`. When the row exists,
- * those fields come back authoritatively. When it does not (DB
- * freshly migrated but never scanned, or a legacy DB never
- * re-persisted), the loader degrades to a synthetic envelope:
- *
- *   - `scannedAt` ← max(`scan_nodes.scanned_at`); falls back to `Date.now()`
- *     for empty snapshots so the field stays a positive integer.
- *   - `scope`     ← `'project'`.
- *   - `roots`     ← `['.']` to satisfy spec's `minItems: 1`. NOT
- *     load-bearing: the orchestrator's incremental path only reads
- *     `nodes` / `links` / `issues` from the prior; it never reuses the
- *     prior `roots`.
- *   - `providers` ← `[]`.
- *   - `stats`     ← zeros for `filesWalked` / `filesSkipped` /
- *     `durationMs`; the three count fields derive from row counts.
- *
- * Both branches keep `nodesCount` / `linksCount` / `issuesCount` derived
- * from `COUNT(*)` of the loaded rows, never persisted, always recomputed.
- */
-
 /**
- * Spec § A.9, load the fine-grained Extractor cache as a per-node map
- * from qualified extractor id (`<pluginId>/<id>`) to the run-time
- * hashes the extractor recorded on its last run. Empty map is the
- * default when the table is empty (fresh DB, never-scanned scope, or
- * every extractor has been uninstalled since the last scan).
- *
- * Returned shape: `Map<nodePath, Map<extractorId, IPriorExtractorRun>>`.
- * The inner value carries the body hash AND the sidecar-annotations
- * hash so the orchestrator can apply the widened cache key (both must
- * match for a cache hit).
+ * 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 IPriorExtractorRun {
-    bodyHash: string;
-    sidecarAnnotationsHash: string;
+interface INodeCounts {
+    nodes: number;
+    links: number;
+    issues: number;
 }
-
 /**
- * `.skillmapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
- * with the project-local layering: bundled defaults → `config.ignore`
- * (from `.skill-map/settings.json`) → `.skillmapignore` file content.
- *
- * Why a wrapper instead of exposing `ignore` directly:
- *
- * 1. Single-source defaults, `src/config/defaults/skillmapignore` 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`.
+ * 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 IIgnoreFilter {
+interface IPersistOptions {
+    renameOps?: RenameOp[];
+    extractorRuns?: IExtractorRunRecord[];
+    enrichments?: IEnrichmentRecord[];
+    contributions?: IContributionRecord[];
     /**
-     * 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.
+     * Phase 3 / View contribution system, active runtime catalog of
+     * registered view contributions, keyed by qualified id
+     * `<pluginId>/<extensionId>/<contributionId>`. Passed to the
+     * `scan_contributions` upsert so the catalog sweep can drop rows
+     * belonging to plugins / extensions that are no longer in the
+     * catalog (uninstalled plugins, disabled bundles, removed
+     * contributions). Empty / absent set = no catalog sweep (legacy
+     * behaviour, leaves disabled-plugin rows stale per design F24
+     * pre-fix).
      */
-    ignores(relativePath: string): boolean;
+    registeredContributionKeys?: ReadonlySet<string>;
+    /**
+     * Phase 3 / View contribution system, set of `(plugin, extension,
+     * node)` tuples where the extension actually RAN against that node
+     * in this scan. Format: `<pluginId>/<extensionId>/<nodePath>` (no
+     * contribution-id segment, the sweep operates at the (plugin,
+     * extension, node) level and inspects the buffer to decide which
+     * contribution-ids survive).
+     *
+     * Membership rules:
+     *   - Extractor + cache miss: tuple INCLUDED (extract() ran).
+     *   - Extractor + cache hit: tuple OMITTED (extract() skipped, prior
+     *     rows must be preserved).
+     *   - Rule, every node in `ctx.nodes`: tuple INCLUDED (rules always
+     *     run and see the full graph).
+     *
+     * Drives the per-tuple sweep documented in `spec/architecture.md`
+     * §View contribution system → Persistence (sweep #3): rows whose
+     * `(plugin_id, extension_id, node_path)` is in this set but whose
+     * `(plugin_id, extension_id, node_path, contribution_id)` is NOT in
+     * the buffer get DELETEd before the upsert. Catches the "extractor
+     * used to emit, now does not" case (e.g. body change removes the
+     * trigger). Empty / absent set = no per-tuple sweep (legacy
+     * callers preserve the pre-fix behaviour where stale rows linger).
+     */
+    freshlyRunTuples?: ReadonlySet<string>;
 }
-
 /**
- * Diagnostic surfaced by a parser when the raw input was structurally
- * malformed (e.g. YAML parse error). The parser MUST still return a
- * usable `{ frontmatter, frontmatterRaw, body }` triple (defaults are
- * fine) so the scan keeps making progress; this carries the message
- * the orchestrator translates into a kernel `Issue` with severity
- * `warn` (and `error` under `--strict`).
- *
- * Pure data: parsers never log or throw; they describe the failure
- * here and let the orchestrator decide how to surface it.
+ * 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 IParseIssue {
-    /**
-     * Stable tag describing the failure class. The only emitter today
-     * is `frontmatter-yaml` reporting a YAML parse error
-     * (`'frontmatter-parse-error'`); the set may grow as new parsers
-     * land.
-     */
-    code: string;
-    /**
-     * Human-readable message, sanitised. Never includes the raw input
-     * (a hostile YAML could embed multi-line garbage); only the
-     * parser-error string is interpolated.
-     */
-    message: string;
+interface IIssueRow {
+    id: number;
+    issue: Issue;
 }
-
 /**
- * Provider runtime contract. Walks filesystem roots and emits raw node
- * records; classification maps path conventions to a node kind.
+ * Filter + pagination shape for `port.issues.list(...)`, driven by the
+ * BFF's `/api/issues` route. Every field is optional, an empty filter
+ * returns every issue ordered by `id` ASC (insertion order, stable
+ * across pages so `offset` / `limit` paging is deterministic).
  *
- * 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.
+ * The three semantic filters mirror `/api/issues`'s query params:
  *
- * `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.
+ *   - `severities`, narrowed list of `Severity` values. Empty / absent
+ *     matches every severity.
+ *   - `analyzerIds`, accepts qualified (`<plugin>/<id>`) AND short
+ *     (`<id>`) forms; the suffix-match semantics live in
+ *     `matchesAnalyzerFilter`. Each entry generates two SQL clauses
+ *     (`= ?` and `LIKE '%/' || ?`) ORed together so the filter remains
+ *     a single SQL pass with parameterised values, no string
+ *     interpolation. Empty / absent matches every analyzer id.
+ *   - `nodePath`, keeps issues whose `nodeIds` JSON array contains the
+ *     given path (correlated EXISTS over `json_each`). Absent / null
+ *     skips the filter.
  *
- * **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.
+ * Pagination is mandatory; the route layer fills the defaults via
+ * `parsePagination`. `total` in `IIssueListResult` reports the total
+ * MATCHING the filters (not just the page slice) so the SPA can
+ * surface a correct page-count without a second round-trip.
  */
-
-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>;
+interface IIssueListFilter {
     /**
-     * Parser diagnostics (audit L1). Populated by the walker when the
-     * parser surfaced `IParseIssue` entries (e.g. malformed YAML).
-     * Carried through `processRawNode` and converted into warn-level
-     * kernel `Issue` rows inside `buildFreshNodeAndValidateFrontmatter`.
-     * Empty / undefined on the happy path.
+     * Severity tokens to match. Typed as open `string` (not the
+     * `Severity` union) so an unknown value from a URL query string
+     * surfaces as a zero-match SQL query, not a kernel validation
+     * error. The adapter parameterises each entry into the `IN(...)`
+     * clause; unrecognised severities simply match no rows.
      */
-    parseIssues?: readonly IParseIssue[];
+    severities?: readonly string[];
+    analyzerIds?: readonly string[];
+    nodePath?: string | null;
+    offset: number;
+    limit: number;
 }
 /**
- * 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.
+ * Output of `port.issues.list(...)`. `items` is the page slice (length
+ * ≤ `filter.limit`); `total` is the count of rows matching the filters
+ * before pagination was applied.
  */
-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;
-    /**
-     * Presentation metadata the UI consumes to render nodes of this kind
-     * (palette swatches, list tags, graph nodes, filter chips). Required
-     * so the UI never has to invent visuals for a Provider-declared kind.
-     * Mirrors `extensions/provider.schema.json#/properties/kinds/.../ui`.
-     */
-    ui: IProviderKindUi;
+interface IIssueListResult {
+    items: Issue[];
+    total: number;
 }
-/**
- * Presentation contract for one Provider kind. The Provider declares
- * intent (label + base color, optional dark variant + emoji + icon);
- * the UI derives `bg`/`fg` tints per theme via a deterministic helper
- * and reads the registry from the `kindRegistry` field embedded in REST
- * envelopes. Single source of truth for what a kind looks like, the
- * UI never hardcodes presentation for a built-in kind.
- */
-interface IProviderKindUi {
-    /**
-     * Plural human-readable label for groups of this kind (e.g. `'Skills'`,
-     * `'Agents'`, `'Cursor Rules'`). Used in filter dropdowns, palette
-     * tooltips, and any list grouping.
-     */
-    label: string;
-    /**
-     * Base hex color (`#RRGGBB`) for the light theme. The UI derives `bg`
-     * and `fg` tints from this value at runtime via a deterministic
-     * helper. Declaring one base value (instead of three) keeps the
-     * manifest small and centralises accessibility-driven contrast in the
-     * UI.
-     */
-    color: string;
-    /**
-     * Optional dark-theme variant of `color`. When absent, the UI falls
-     * back to `color`. Declared explicitly because a luminosity flip
-     * rarely matches the brand intent for kinds that should stand out in
-     * dark mode.
-     */
-    colorDark?: string;
-    /**
-     * Optional decorative emoji used as a fallback when `icon` is absent
-     * or fails to render. Length-bound so the UI can lay it out
-     * predictably alongside text.
-     */
-    emoji?: string;
-    /**
-     * Optional discriminated icon descriptor. The UI prefers `icon` over
-     * `emoji`; when both are absent, the UI falls back to the first
-     * letter of `label` colored with `color`.
-     */
-    icon?: TProviderKindIcon;
+/** 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';
 /**
- * Discriminated icon contract. `pi` references a PrimeIcons identifier
- * (e.g. `'pi-cog'`); `svg` carries raw SVG path data the UI wraps in a
- * `<svg viewBox="0 0 24 24"><path d="…"/></svg>` element tinted with
- * `currentColor`. The discriminator (`kind`) keeps the UI dispatch
- * exhaustive without string-sniffing the payload.
+ * 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.
  */
-type TProviderKindIcon = {
-    kind: 'pi';
-    id: string;
-} | {
-    kind: 'svg';
-    path: string;
-};
-interface IProvider extends IExtensionBase {
-    kind: 'provider';
-    /**
-     * 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>;
+interface IMigrateNodeFksReport {
+    jobs: number;
+    executions: number;
+    summaries: number;
+    enrichments: number;
+    pluginKvs: number;
+    nodeFavorites: number;
     /**
-     * Optional auxiliary JSON Schemas this Provider's per-kind schemas
-     * `$ref` by `$id`. Registered with AJV via `addSchema` BEFORE the
-     * per-kind schemas compile, so cross-file `$ref` resolution succeeds.
-     *
-     * Use case: when several kinds share a common base (e.g. Anthropic's
-     * merged skill / command frontmatter, both extend a shared
-     * `skill-base.schema.json`), the Provider declares the base here so
-     * `skill.schema.json` and `command.schema.json` can `$ref` it without
-     * duplicating fields.
-     *
-     * Runtime-only, does NOT appear in the spec's `provider.schema.json`
-     * manifest. Manifest-validated schemas remain the per-kind ones in
-     * `kinds[<kind>].schema`; auxiliary schemas are an implementation
-     * concern of how the runtime composes those.
+     * Collisions encountered when migrating any of the keyed-by-node
+     * `state_*` tables 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. `state_node_favorites` has no composite key
+     * so its `keys` is the empty object.
      */
-    schemas?: unknown[];
-    /**
-     * Declarative file-discovery config consumed by the kernel walker.
-     * When present, the kernel walks every root, includes files whose
-     * extension matches `extensions`, parses each with the parser id
-     * registered in the kernel-internal registry, and yields `IRawNode`
-     * records the same shape `walk()` would.
-     *
-     * When neither `read` nor `walk` is declared, `resolveProviderWalk`
-     * applies the default `{ extensions: ['.md'], parser: 'frontmatter-yaml' }`
-     * so the most common Provider shape needs zero configuration.
-     *
-     * Precedence: when both `walk()` (runtime field) and `read` are
-     * declared, `walk()` wins, `read` is ignored. The escape-hatch
-     * relationship is intentional: most Providers should use `read`;
-     * Providers with non-standard discovery requirements (custom file
-     * naming, multi-pass walks, dynamic ignore logic) implement `walk()`
-     * directly and accept the duplication of audit-cleared defences.
-     *
-     * Built-in parsers: `'frontmatter-yaml'` (markdown with `--- … ---`
-     * YAML frontmatter; pollution-strip + JSON_SCHEMA-pinned), `'plain'`
-     * (entire body, empty frontmatter). The set is closed; user plugins
-     * cannot register their own.
-     */
-    read?: IProviderReadConfig;
-    /**
-     * 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.
-     *
-     * Optional. When omitted, the Provider MUST declare `read` (or rely
-     * on the default config). The orchestrator never calls `walk()`
-     * directly, it goes through `resolveProviderWalk(provider)` which
-     * picks `walk` over `read`.
-     */
-    walk?(roots: string[], options?: {
-        ignoreFilter?: IIgnoreFilter;
-    }): AsyncIterable<IRawNode>;
-    /**
-     * Given a path and its parsed frontmatter, decide the node kind, or
-     * `null` to disclaim the file. The classifier is called after walk()
-     * yields; with multiple Providers active, every Provider walks every
-     * file matching its `read.extensions`, so each Provider MUST disclaim
-     * paths it does not recognise. Returning the same path's kind from
-     * two Providers fires the spec's `provider-ambiguous` issue and the
-     * orchestrator drops the duplicate.
-     *
-     * Convention: a Provider's classify returns one of its own `kinds`
-     * map keys for paths in its territory (`.claude/`, `.gemini/`,
-     * `.agents/skills/`, etc.) and `null` elsewhere. External Providers
-     * (Cursor, Obsidian, …) follow the same rule: claim what's yours,
-     * disclaim everything else. The orchestrator does not validate the
-     * kind against `NodeKind`.
-     */
-    classify(path: string, frontmatter: Record<string, unknown>): string | null;
+    collisions: Array<{
+        table: 'state_summaries' | 'state_enrichments' | 'state_plugin_kvs' | 'state_node_favorites';
+        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[];
 }
 /**
- * Declarative read config a Provider declares via `IProvider.read`.
- * Mirrors `extensions/provider.schema.json#/properties/read` at the
- * TypeScript level. Built-in parser ids: `'frontmatter-yaml'`, `'plain'`.
+ * Single contribution row as returned to callers of the
+ * `contributions` namespace on `StoragePort`. The payload is
+ * `unknown` because the slot space is open at the type layer (catalog
+ * evolution is a kernel + spec concern); narrow at the call site by
+ * reading `slot`.
+ *
+ * Lives next to the port (not under `adapters/sqlite/`) so non-SQLite
+ * implementations of `StoragePort` (in-memory test harness, future
+ * Postgres adapter) can satisfy the port contract without importing
+ * from the SQLite adapter. The SQLite adapter re-exports this type
+ * for backwards compatibility with callers that still import from
+ * the adapter path.
  */
-interface IProviderReadConfig {
-    /**
-     * File extensions the walker yields. Strings include the leading dot
-     * (e.g. `'.md'`, `'.mdc'`, `'.toml'`). Match is suffix-based; the
-     * comparison is case-sensitive.
-     */
-    extensions: string[];
-    /**
-     * Parser id from the kernel-internal registry. Built-ins:
-     * `'frontmatter-yaml'`, `'plain'`. Unknown ids surface as
-     * `UnknownParserError` from the walker; the orchestrator translates
-     * the error into a Provider issue with status `invalid-manifest`.
-     */
-    parser: string;
+interface IPersistedContribution {
+    pluginId: string;
+    extensionId: string;
+    nodePath: string;
+    contributionId: string;
+    slot: string;
+    payload: unknown;
+    emittedAt: number;
 }
 
 /**
- * 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.
- *
- * Extractors are deterministic-only. They run synchronously inside the
- * scan loop; LLM-driven enrichment of a node is an Action concern, not
- * an Extractor concern. The Extractor context therefore exposes no
- * `RunnerPort`, see spec `architecture.md` §Execution modes.
- *
- * Output channels (all on the context):
+ * `scan_contributions` adapter, replace-all writer used by
+ * `persistScanResult`, plus read helpers consumed by the BFF
+ * (`/api/contributions/...`) and rules (`core/contribution-orphan`).
  *
- *   - `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
- *     is 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.
+ * One row per `(plugin_id, extension_id, node_path, contribution_id)`
+ * tuple. See `spec/architecture.md` § View contribution system →
+ * Persistence and `migrations/001_initial.sql` § View contribution
+ * layer for the normative shape.
  *
- * The manifest's `scope` field tells the orchestrator which parts to feed:
- * `frontmatter` extractors receive an empty string for body and vice versa.
+ * Replace-all semantics mirror the rest of the `scan_*` zone: every
+ * scan is a fresh snapshot, so prior rows are deleted before insert.
+ * Wrapped in the same transaction `persistScanResult` opens.
  *
- * 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.
+ * The rename heuristic does NOT need to migrate `node_path` here,
+ * because of replace-all, every contribution is re-emitted on the new
+ * path automatically. Keeping the rename path lighter than `state_*`
+ * (which IS rename-migrated because state survives across scans).
  */
 
 /**
- * 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`.
+ * In-memory contribution record buffered during scan and flushed to
+ * `scan_contributions` by `persistScanResult`. One entry per accepted
+ * `ctx.emitContribution(id, payload)` call. Payload validation against
+ * the slot's payload schema happens at emit time (orchestrator);
+ * by the time records reach this adapter they are wire-shape clean.
  */
-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;
-    /**
-     * Emit a per-node view contribution. The first argument is the
-     * extension-local Record key declared under
-     * `extension.viewContributions[<contributionId>]`; the second is a
-     * payload that conforms to the slot's payload schema in
-     * `spec/schemas/view-slots.schema.json#/$defs/payloads/<slot>`,
-     * where `<slot>` is the slot the manifest declared for this
-     * contribution. The orchestrator validates the payload against the
-     * slot's schema before persisting to `scan_contributions`; off-shape
-     * payloads are silently dropped with an `extension.error` event
-     * (mirror of `emitLink` rejecting off-`emitsLinkKinds` links).
-     * Calling `emitContribution` with a `contributionId` that is not
-     * declared in the manifest is also dropped with an `extension.error`.
-     * See `architecture.md` §View contribution system → Emit path.
-     */
-    emitContribution(contributionId: string, payload: unknown): void;
-}
-interface IExtractorContext extends IExtractorCallbacks {
-    node: Node;
-    body: string;
-    frontmatter: Record<string, unknown>;
+interface IContributionRecord {
+    pluginId: string;
+    extensionId: string;
+    nodePath: string;
+    contributionId: string;
     /**
-     * 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.
+     * Closed enum value mirroring `view-slots.schema.json#/$defs/SlotName`.
+     * Persisted as TEXT (no SQL CHECK by design, see migration comment).
      */
-    store?: unknown;
-}
-interface IExtractor extends IExtensionBase {
-    kind: 'extractor';
-    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 the extractor
-     * wastes zero CPU on inapplicable nodes.
-     *
-     * 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>;
+    slot: string;
+    /** Already-validated payload. Serialised via `JSON.stringify` at write. */
+    payload: unknown;
+    emittedAt: number;
 }
 
 /**
- * Analyzer runtime contract. Runs against the whole graph after every
- * Provider and extractor has completed; emits issues and MAY project
- * findings into the UI via view contributions. Deterministic analyzers
- * are pure (same graph in → same issues out) and run synchronously
- * inside `sm scan` / `sm check`. Probabilistic analyzers 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`).
+ * `loadScanResult`, driving inverse of `persistScanResult`. Reads the
+ * `scan_*` tables and reconstructs a `ScanResult` shape so the
+ * orchestrator can run an incremental scan (`sm scan --changed`) on
+ * top of a prior snapshot.
+ *
+ * The reconstruction is faithful for everything that was actually
+ * persisted: nodes (with triple-split bytes / tokens, denormalised
+ * counts, JSON frontmatter), internal links (with regrouped
+ * `trigger` / `location`, parsed `sources[]`), and issues
+ * (with parsed `nodeIds` / `linkIndices` / `fix` / `data`).
+ *
+ * **Documented omission**: external pseudo-links (those whose target is
+ * an `http://` / `https://` URL emitted by the external-url-counter
+ * extractor) are NEVER persisted to `scan_links`, only their per-node
+ * count survives in `scan_nodes.external_refs_count`. Therefore the
+ * `result.links` returned by `loadScanResult` contains only internal
+ * graph links, and `node.externalRefsCount` is the authoritative count
+ * carried over from the prior scan. The orchestrator's incremental path
+ * preserves that count for "unchanged" nodes and re-derives it for
+ * new / modified nodes from a fresh extractor pass.
+ *
+ * Meta envelope: the `scan_meta` table persists `scope` / `roots` /
+ * `scannedAt` / `scannedBy` / `providers` / `stats.filesWalked` /
+ * `stats.filesSkipped` / `stats.durationMs`. When the row exists,
+ * those fields come back authoritatively. When it does not (DB
+ * freshly migrated but never scanned, or a legacy DB never
+ * re-persisted), the loader degrades to a synthetic envelope:
+ *
+ *   - `scannedAt` ← max(`scan_nodes.scanned_at`); falls back to `Date.now()`
+ *     for empty snapshots so the field stays a positive integer.
+ *   - `scope`     ← `'project'`.
+ *   - `roots`     ← `['.']` to satisfy spec's `minItems: 1`. NOT
+ *     load-bearing: the orchestrator's incremental path only reads
+ *     `nodes` / `links` / `issues` from the prior; it never reuses the
+ *     prior `roots`.
+ *   - `providers` ← `[]`.
+ *   - `stats`     ← zeros for `filesWalked` / `filesSkipped` /
+ *     `durationMs`; the three count fields derive from row counts.
+ *
+ * Both branches keep `nodesCount` / `linksCount` / `issuesCount` derived
+ * from `COUNT(*)` of the loaded rows, never persisted, always recomputed.
  */
 
 /**
- * Step 9.6.2, orphan sidecar entry surfaced to analyzers. A `.sm` file
- * whose sibling `.md` does not exist on disk; the `annotation-orphan`
- * built-in analyzer emits one warning per entry. Other analyzers that
- * care about orphan sidecars MAY consume the list too.
+ * Spec § A.9, load the fine-grained Extractor cache as a per-node map
+ * from qualified extractor id (`<pluginId>/<id>`) to the run-time
+ * hashes the extractor recorded on its last run. Empty map is the
+ * default when the table is empty (fresh DB, never-scanned scope, or
+ * every extractor has been uninstalled since the last scan).
+ *
+ * Returned shape: `Map<nodePath, Map<extractorId, IPriorExtractorRun>>`.
+ * The inner value carries the body hash AND the sidecar-annotations
+ * hash so the orchestrator can apply the widened cache key (both must
+ * match for a cache hit).
  */
-interface IAnalyzerOrphanSidecar {
-    /** Relative path (POSIX-separated) of the orphan `.sm`. */
-    relativePath: string;
-    /** Absolute path of the missing `.md` the sidecar was anchored to. */
-    expectedMdPath: string;
+interface IPriorExtractorRun {
+    bodyHash: string;
+    sidecarAnnotationsHash: string;
 }
-interface IAnalyzerContext {
-    nodes: Node[];
-    links: Link[];
+
+/**
+ * `.skillmapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
+ * with the project-local layering: bundled defaults → `config.ignore`
+ * (from `.skill-map/settings.json`) → `.skillmapignore` file content.
+ *
+ * Why a wrapper instead of exposing `ignore` directly:
+ *
+ * 1. Single-source defaults, `src/config/defaults/skillmapignore` 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 {
     /**
-     * Step 9.6.2, orphaned sidecars discovered during the scan walk.
-     * Empty when sidecar discovery did not run (legacy callers) or
-     * when no orphans exist.
+     * 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.
      */
-    orphanSidecars?: IAnalyzerOrphanSidecar[];
+    ignores(relativePath: string): boolean;
+}
+
+/**
+ * Diagnostic surfaced by a parser when the raw input was structurally
+ * malformed (e.g. YAML parse error). The parser MUST still return a
+ * usable `{ frontmatter, frontmatterRaw, body }` triple (defaults are
+ * fine) so the scan keeps making progress; this carries the message
+ * the orchestrator translates into a kernel `Issue` with severity
+ * `warn` (and `error` under `--strict`).
+ *
+ * Pure data: parsers never log or throw; they describe the failure
+ * here and let the orchestrator decide how to surface it.
+ */
+interface IParseIssue {
     /**
-     * Step 9.6.6, raw parsed sidecar root keyed by `node.path`. Populated
-     * by the orchestrator alongside the public `Node.sidecar` overlay so
-     * analyzers that inspect plugin namespaces (e.g. the built-in
-     * `core/unknown-field` Analyzer) can walk the full tree without
-     * re-reading the file from disk. Absent (or `undefined` per node)
-     * when no sidecar accompanies the node, or when the sidecar failed
-     * to parse. Treat as read-only.
+     * Stable tag describing the failure class. The only emitter today
+     * is `frontmatter-yaml` reporting a YAML parse error
+     * (`'frontmatter-parse-error'`); the set may grow as new parsers
+     * land.
      */
-    sidecarRoots?: ReadonlyMap<string, Record<string, unknown>>;
+    code: string;
     /**
-     * Step 9.6.6, runtime catalog of plugin-contributed annotation keys,
-     * as exposed by `kernel.getRegisteredAnnotationKeys()`. Threaded
-     * through so analyzers can reason about the registered-vs-unknown
-     * split without reaching back into the kernel. Empty array when no
-     * plugin declares contributions; absent for legacy callers (older
-     * runScan sites that never wired the catalog through).
+     * Human-readable message, sanitised. Never includes the raw input
+     * (a hostile YAML could embed multi-line garbage); only the
+     * parser-error string is interpolated.
      */
-    annotationContributions?: readonly IRegisteredAnnotationKey[];
+    message: 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>;
     /**
-     * Step 11.x, runtime catalog of plugin-contributed view contributions,
-     * as exposed by `kernel.getRegisteredViewContributions()`. Threaded
-     * through so analyzers can reason about emissions without reaching
-     * back into the kernel (built-in `core/contribution-orphan` joins it
-     * with the live node set to flag dangling emissions). Slot catalog
-     * drift detection is NOT a scan concern, it lives at load time and
-     * surfaces via `sm plugins doctor`. Empty array when no extension
-     * declares view contributions; absent for legacy callers (older
-     * runScan sites that never wired the catalog through).
+     * Parser diagnostics (audit L1). Populated by the walker when the
+     * parser surfaced `IParseIssue` entries (e.g. malformed YAML).
+     * Carried through `processRawNode` and converted into warn-level
+     * kernel `Issue` rows inside `buildFreshNodeAndValidateFrontmatter`.
+     * Empty / undefined on the happy path.
      */
-    viewContributions?: readonly IRegisteredViewContribution[];
+    parseIssues?: readonly IParseIssue[];
+}
+/**
+ * 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 {
     /**
-     * Absolute paths of `*.md` files under the project's
-     * `.skill-map/jobs/` that no `state_jobs.filePath` references, the
-     * built-in `core/job-orphan-file` analyzer projects each as a `warn`
-     * issue. Pre-computed by the driving adapter (CLI / BFF) inside its
-     * already-open storage transaction (mirrors the `orphanSidecars`
-     * pattern: detection lives outside the analyzer, the analyzer only
-     * projects). Absent (or empty) when the caller does not maintain a
-     * jobs directory, when the storage path is unavailable, or when no
-     * orphan files exist. Treat as read-only.
+     * 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`.
      */
-    orphanJobFiles?: readonly string[];
+    schema: string;
     /**
-     * Set of absolute file paths the operator has opted into for
-     * link-validation purposes via `scan.referencePaths`. The driving
-     * adapter walks each configured path before the scan and collects
-     * every existing file's absolute path here. Files in this set are
-     * NOT indexed as graph nodes, the only consumer is
-     * `core/broken-ref`, which suppresses its `warn` issue when a
-     * path-style link target falls into the set. Absent / empty when
-     * the operator left `scan.referencePaths` empty or when the
-     * adapter does not maintain the side index. Treat as read-only.
-     */
-    referenceablePaths?: ReadonlySet<string>;
-    /**
-     * Absolute path of the scan's project root (cwd of the invocation).
-     * Threaded into the analyzer pass so an analyzer that needs to
-     * resolve a relative `link.target` to an absolute filesystem path
-     * (today only `core/broken-ref`, when consulting
-     * `referenceablePaths`) does not have to derive it from
-     * `nodes[0].path` heuristics. Absent for legacy callers (older
-     * `runScan` sites that never wired the field through). Always an
-     * absolute path when present.
-     */
-    cwd?: string;
-    /**
-     * Emit a per-node view contribution declared in this analyzer's
-     * manifest `viewContributions` map. Sync, void return; the
-     * orchestrator validates the payload against the slot's schema at
-     * call time and silently drops invalid emissions with a logged
-     * `extension.error` event (parallel to
-     * `IExtractorCallbacks.emitContribution`).
-     *
-     * Unlike Extractor's emit (which binds `nodePath` from `ctx.node.path`
-     * implicitly because Extractors run per-node), Analyzer's `evaluate()`
-     * sees the full graph at once. The analyzer walks `ctx.nodes` itself
-     * and MUST supply the target node path explicitly per emission.
+     * 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.
      *
-     * Calling `emitContribution` with a `contributionId` that is not
-     * declared in the manifest is dropped with an `extension.error`. The
-     * kernel routes emitted contributions to the same persistence
-     * pipeline as Extractor emissions (`scan_contributions`).
+     * `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.
      */
-    emitContribution(nodePath: string, contributionId: string, payload: unknown): void;
-}
-interface IAnalyzer extends IExtensionBase {
-    kind: 'analyzer';
+    schemaJson: unknown;
     /**
-     * Execution mode. Optional in the manifest with a default of
-     * `deterministic` per `spec/schemas/extensions/analyzer.schema.json`.
+     * 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`.
      */
-    mode?: TExecutionMode;
+    defaultRefreshAction: string;
     /**
-     * Qualified `<pluginId>/<id>` Action ids the analyzer recommends to
-     * resolve its findings. Distinct from `Action.precondition` (which
-     * declares which nodes an Action applies to from the Action side);
-     * this field declares which Actions are relevant when this
-     * Analyzer fires from the Analyzer side. Actions are per-node by
-     * design (project-level cleanup verbs like orphan file prune or
-     * contribution relink are CLI verbs, not Actions) and are NOT
-     * surfaced through this field. The UI consumes it in the node
-     * inspector under "Recommended for issues". Optional; omit when no
-     * Action resolves the finding (e.g. `core/superseded` surfaces
-     * deliberate user declarations, not problems).
+     * Presentation metadata the UI consumes to render nodes of this kind
+     * (palette swatches, list tags, graph nodes, filter chips). Required
+     * so the UI never has to invent visuals for a Provider-declared kind.
+     * Mirrors `extensions/provider.schema.json#/properties/kinds/.../ui`.
      */
-    recommendedActions?: readonly string[];
-    evaluate(ctx: IAnalyzerContext): 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'`.
- */
-
-/**
- * Single sidecar write payload an Action can return. Discriminated union so
- * future write kinds (storage rows, plugin KV, etc.) can land additively
- * without breaking consumers that only handle `kind: 'sidecar'`.
- *
- *   - `path`, absolute path to the `.sm` file the kernel must materialise
- *     the change into. Resolved by the Action from the node's absolute
- *     path via `sidecarPathFor()`.
- *   - `changes`, partial sidecar root used as a deep-merge patch (NOT a
- *     full replacement). Arrays REPLACE; objects RECURSE. Reason:
- *     sidecars are shared-write between skill-map core and plugins;
- *     a full replace would clobber `<plugin-id>:` namespaced blocks.
- */
-type TActionWrite = {
-    kind: 'sidecar';
-    path: string;
-    changes: Record<string, unknown>;
-};
-/**
- * Result envelope returned by deterministic Actions. The `report` field
- * carries the typed report payload (each Action declares its shape via
- * `reportSchemaRef`); `writes` is opt-in, Actions that do not mutate
- * persistent state simply omit it.
- */
-interface IActionResult<TReport = unknown> {
-    report: TReport;
-    writes?: TActionWrite[];
-}
-/**
- * Runtime context passed to a deterministic Action's `invoke()` method.
- * Minimal surface, Actions stay pure (no IO inside `invoke`); the kernel
- * materialises any returned `writes` after the call.
- *
- *   - `node`, the target `Node` the Action operates on. Open-by-design;
- *     batch / fan-out flows pick the matching nodes upstream.
- *   - `nodeAbsolutePath`, absolute path to the node's `.md` file on
- *     disk. The Action uses this to compute the sidecar path it returns
- *     in a `TActionWrite`. Surfaced separately from `node.path` (which is
- *     the relative scope-root form) so Actions never compose absolute
- *     paths from `node.path` themselves.
- *   - `invoker`, identity of the caller; written into the sidecar's
- *     `audit.lastBumpedBy` when the Action chooses to. CLI invocations
- *     pass `'cli'`; plugin-driven invocations pass `'plugin:<plugin-id>'`.
- *   - `now`, clock function; tests inject a deterministic source.
- *     Defaults to `() => new Date()` at the composition root.
- */
-interface IActionContext {
-    node: Node;
-    nodeAbsolutePath: string;
-    invoker: string;
-    now: () => Date;
+    ui: IProviderKindUi;
 }
 /**
- * Declarative filter applied by `--all` fan-out, UI button gating, and
- * `sm actions show`. All fields optional, an empty precondition matches
- * every node.
+ * Presentation contract for one Provider kind. The Provider declares
+ * intent (label + base color, optional dark variant + emoji + icon);
+ * the UI derives `bg`/`fg` tints per theme via a deterministic helper
+ * and reads the registry from the `kindRegistry` field embedded in REST
+ * envelopes. Single source of truth for what a kind looks like, the
+ * UI never hardcodes presentation for a built-in kind.
  */
-interface IActionPrecondition {
+interface IProviderKindUi {
     /**
-     * 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.
+     * Plural human-readable label for groups of this kind (e.g. `'Skills'`,
+     * `'Agents'`, `'Cursor Rules'`). Used in filter dropdowns, palette
+     * tooltips, and any list grouping.
      */
-    kind?: string[];
-    /** Provider ids whose nodes this action accepts. Omitted → any Provider. */
-    provider?: string[];
-    /** Node stability filter. */
-    stability?: Array<'experimental' | 'stable' | 'deprecated'>;
+    label: string;
     /**
-     * Free-form precondition strings the kernel forwards to the action for
-     * runtime evaluation (example: `frontmatter.metadata.source != null`).
+     * Base hex color (`#RRGGBB`) for the light theme. The UI derives `bg`
+     * and `fg` tints from this value at runtime via a deterministic
+     * helper. Declaring one base value (instead of three) keeps the
+     * manifest small and centralises accessibility-driven contrast in the
+     * UI.
      */
-    custom?: string[];
-}
-interface IAction extends IExtensionBase {
-    kind: 'action';
+    color: string;
     /**
-     * Execution mode discriminator. Required per
-     * `extensions/action.schema.json`.
+     * Optional dark-theme variant of `color`. When absent, the UI falls
+     * back to `color`. Declared explicitly because a luminosity flip
+     * rarely matches the brand intent for kinds that should stand out in
+     * dark mode.
      */
-    mode: TExecutionMode;
+    colorDark?: string;
     /**
-     * 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`.
+     * Optional decorative emoji used as a fallback when `icon` is absent
+     * or fails to render. Length-bound so the UI can lay it out
+     * predictably alongside text.
      */
-    reportSchemaRef: string;
+    emoji?: string;
     /**
-     * Best-effort estimate of wall-clock duration in seconds. Drives TTL
-     * (`ttl = max(expectedDurationSeconds × graceMultiplier,
-     * minimumTtlSeconds)`). Required for `probabilistic`; advisory for
-     * `deterministic`.
+     * Optional discriminated icon descriptor. The UI prefers `icon` over
+     * `emoji`; when both are absent, the UI falls back to the first
+     * letter of `label` colored with `color`.
      */
-    expectedDurationSeconds?: number;
+    icon?: TProviderKindIcon;
+}
+/**
+ * Discriminated icon contract. `pi` references a PrimeIcons identifier
+ * (e.g. `'pi-cog'`); `svg` carries raw SVG path data the UI wraps in a
+ * `<svg viewBox="0 0 24 24"><path d="…"/></svg>` element tinted with
+ * `currentColor`. The discriminator (`kind`) keeps the UI dispatch
+ * exhaustive without string-sniffing the payload.
+ */
+type TProviderKindIcon = {
+    kind: 'pi';
+    id: string;
+} | {
+    kind: 'svg';
+    path: string;
+};
+interface IProvider extends IExtensionBase {
+    kind: 'provider';
     /**
-     * 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.
+     * 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.
      */
-    precondition?: IActionPrecondition;
+    kinds: Record<string, IProviderKind>;
     /**
-     * Hint to Skill / CLI runners about what tools the rendered prompt
-     * expects access to (`Bash`, `Read`, `WebSearch`, …). No normative
-     * enforcement in v0.
+     * Optional auxiliary JSON Schemas this Provider's per-kind schemas
+     * `$ref` by `$id`. Registered with AJV via `addSchema` BEFORE the
+     * per-kind schemas compile, so cross-file `$ref` resolution succeeds.
+     *
+     * Use case: when several kinds share a common base (e.g. Anthropic's
+     * merged skill / command frontmatter, both extend a shared
+     * `skill-base.schema.json`), the Provider declares the base here so
+     * `skill.schema.json` and `command.schema.json` can `$ref` it without
+     * duplicating fields.
+     *
+     * Runtime-only, does NOT appear in the spec's `provider.schema.json`
+     * manifest. Manifest-validated schemas remain the per-kind ones in
+     * `kinds[<kind>].schema`; auxiliary schemas are an implementation
+     * concern of how the runtime composes those.
      */
-    expectedTools?: string[];
+    schemas?: unknown[];
     /**
-     * `'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.
+     * Declarative file-discovery config consumed by the kernel walker.
+     * When present, the kernel walks every root, includes files whose
+     * extension matches `extensions`, parses each with the parser id
+     * registered in the kernel-internal registry, and yields `IRawNode`
+     * records the same shape `walk()` would.
+     *
+     * When neither `read` nor `walk` is declared, `resolveProviderWalk`
+     * applies the default `{ extensions: ['.md'], parser: 'frontmatter-yaml' }`
+     * so the most common Provider shape needs zero configuration.
+     *
+     * Precedence: when both `walk()` (runtime field) and `read` are
+     * declared, `walk()` wins, `read` is ignored. The escape-hatch
+     * relationship is intentional: most Providers should use `read`;
+     * Providers with non-standard discovery requirements (custom file
+     * naming, multi-pass walks, dynamic ignore logic) implement `walk()`
+     * directly and accept the duplication of audit-cleared defences.
+     *
+     * Built-in parsers: `'frontmatter-yaml'` (markdown with `--- … ---`
+     * YAML frontmatter; pollution-strip + JSON_SCHEMA-pinned), `'plain'`
+     * (entire body, empty frontmatter). The set is closed; user plugins
+     * cannot register their own.
      */
-    fanOutPolicy?: 'per-node' | 'batch';
+    read?: IProviderReadConfig;
     /**
-     * Deterministic invocation entry point. OPTIONAL on the runtime
-     * contract for backward compatibility with the manifest-only era
-     * (Decision #114), actions that ship for the future probabilistic
-     * runner / record path leave it absent and the kernel never calls it.
-     * Step 9.6.3 (Decision #125) introduces the first concrete consumer:
-     * the built-in `bump` Action implements `invoke()` and returns a
-     * `writes: [{ kind: 'sidecar', ... }]` payload that the kernel
-     * materialises through `ISidecarStore`.
+     * 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.
      *
-     * Implementations MUST stay pure, no IO inside `invoke()`. The Action
-     * computes the patch and returns it; the kernel reads the on-disk
-     * sidecar, deep-merges, validates, and writes back inside its critical
-     * section.
+     * `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.
      *
-     * `TInput` is action-specific; the built-in `bump` Action declares
-     * `{ force?: boolean; reason?: string }`. The signature stays generic
-     * so each Action narrows it locally without forcing a common base.
+     * Optional. When omitted, the Provider MUST declare `read` (or rely
+     * on the default config). The orchestrator never calls `walk()`
+     * directly, it goes through `resolveProviderWalk(provider)` which
+     * picks `walk` over `read`.
      */
-    invoke?: <TInput, TReport>(input: TInput, ctx: IActionContext) => IActionResult<TReport>;
+    walk?(roots: string[], options?: {
+        ignoreFilter?: IIgnoreFilter;
+    }): AsyncIterable<IRawNode>;
+    /**
+     * Given a path and its parsed frontmatter, decide the node kind, or
+     * `null` to disclaim the file. The classifier is called after walk()
+     * yields; with multiple Providers active, every Provider walks every
+     * file matching its `read.extensions`, so each Provider MUST disclaim
+     * paths it does not recognise. Returning the same path's kind from
+     * two Providers fires the spec's `provider-ambiguous` issue and the
+     * orchestrator drops the duplicate.
+     *
+     * Convention: a Provider's classify returns one of its own `kinds`
+     * map keys for paths in its territory (`.claude/`, `.gemini/`,
+     * `.agents/skills/`, etc.) and `null` elsewhere. External Providers
+     * (Cursor, Obsidian, …) follow the same rule: claim what's yours,
+     * disclaim everything else. The orchestrator does not validate the
+     * kind against `NodeKind`.
+     */
+    classify(path: string, frontmatter: Record<string, unknown>): string | null;
 }
-
 /**
- * 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.
+ * Declarative read config a Provider declares via `IProvider.read`.
+ * Mirrors `extensions/provider.schema.json#/properties/read` at the
+ * TypeScript level. Built-in parser ids: `'frontmatter-yaml'`, `'plain'`.
  */
-
-interface IFormatterContext {
-    nodes: Node[];
-    links: Link[];
-    issues: Issue[];
+interface IProviderReadConfig {
     /**
-     * Full persisted scan, when the caller has it on hand. Optional so
-     * existing formatters that only consume (nodes, links, issues) keep
-     * working unchanged; formatters whose output mirrors a `ScanResult`
-     * envelope (today: the built-in `json` formatter under
-     * `built-in-plugins/formatters/json/`) read this to project the
-     * canonical document verbatim. `undefined` when the caller has only
-     * the three primary arrays (back-compat with older drivers).
+     * File extensions the walker yields. Strings include the leading dot
+     * (e.g. `'.md'`, `'.mdc'`, `'.toml'`). Match is suffix-based; the
+     * comparison is case-sensitive.
      */
-    scanResult?: ScanResult;
-}
-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;
+    extensions: string[];
+    /**
+     * Parser id from the kernel-internal registry. Built-ins:
+     * `'frontmatter-yaml'`, `'plain'`. Unknown ids surface as
+     * `UnknownParserError` from the walker; the orchestrator translates
+     * the error into a Provider issue with status `invalid-manifest`.
+     */
+    parser: 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).
+ * 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.
  *
- * The hookable trigger set is INTENTIONALLY SMALL, ten events. Eight
- * are pipeline-driven (emitted from inside `runScan`); two
- * (`boot`, `shutdown`) are CLI-process-driven (emitted by the driving
- * binary before / after the verb runs, fire-and-forget so
- * `process.exit` is never blocked). 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.
+ * Extractors are deterministic-only. They run synchronously inside the
+ * scan loop; LLM-driven enrichment of a node is an Action concern, not
+ * an Extractor concern. The Extractor context therefore exposes no
+ * `RunnerPort`, see spec `architecture.md` §Execution modes.
  *
- * Dual-mode (declared in manifest):
+ * Output channels (all on the context):
  *
- *   - `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`).
+ *   - `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
+ *     is 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.
  *
- * Curated trigger set (per spec § A.11):
+ * The manifest's `scope` field tells the orchestrator which parts to feed:
+ * `frontmatter` extractors receive an empty string for body and vice versa.
  *
- *   0. `boot`                , once per CLI process, before verb routing.
- *   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. `analyzer.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.
- *   9. `shutdown`            , once per CLI process, after the verb's
- *                                exit code resolves and before
- *                                `process.exit`.
+ * 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.
  */
 
 /**
- * The ten hookable lifecycle events. Mirrors the `triggers[]` enum in
- * `spec/schemas/extensions/hook.schema.json`. Eight are pipeline-driven
- * (emitted from inside `runScan`); two (`boot`, `shutdown`) are
- * CLI-process-driven (emitted by the driving binary before / after the
- * verb runs). Anything outside this set is rejected at load time as
- * `invalid-manifest`.
- */
-type THookTrigger = 'boot' | 'scan.started' | 'scan.completed' | 'extractor.completed' | 'analyzer.completed' | 'action.completed' | 'job.spawning' | 'job.completed' | 'job.failed' | 'shutdown';
-/**
- * Frozen list mirror of `THookTrigger` for runtime introspection. The
- * loader validates `manifest.triggers[]` against this set; the
- * dispatcher iterates it in order when fanning an event out to
- * subscribed hooks. `boot` first / `shutdown` last so a debug log of
- * the array reads in lifecycle order.
+ * 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`.
  */
-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`
- * / `analyzerId` / `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;
-    };
+interface IExtractorCallbacks {
     /**
-     * Convenience extraction of the node payload when the event is
-     * node-scoped (`action.completed`). Undefined for run-scoped or
-     * scan-scoped events.
+     * 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.
      */
-    node?: Node;
+    emitLink(link: Link): void;
     /**
-     * Set on `extractor.completed` events. Qualified extension id of the
-     * Extractor whose work the event aggregates.
+     * 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.
      */
-    extractorId?: string;
+    enrichNode(partial: Partial<Node>): void;
     /**
-     * Set on `analyzer.completed` events. Qualified extension id of the Rule.
+     * Emit a per-node view contribution. The first argument is the
+     * extension-local Record key declared under
+     * `extension.viewContributions[<contributionId>]`; the second is a
+     * payload that conforms to the slot's payload schema in
+     * `spec/schemas/view-slots.schema.json#/$defs/payloads/<slot>`,
+     * where `<slot>` is the slot the manifest declared for this
+     * contribution. The orchestrator validates the payload against the
+     * slot's schema before persisting to `scan_contributions`; off-shape
+     * payloads are silently dropped with an `extension.error` event
+     * (mirror of `emitLink` rejecting off-`emitsLinkKinds` links).
+     * Calling `emitContribution` with a `contributionId` that is not
+     * declared in the manifest is also dropped with an `extension.error`.
+     * See `architecture.md` §View contribution system → Emit path.
      */
-    analyzerId?: string;
+    emitContribution(contributionId: string, payload: unknown): void;
+}
+interface IExtractorContext extends IExtractorCallbacks {
+    node: Node;
+    body: string;
+    frontmatter: Record<string, unknown>;
     /**
-     * Set on `action.completed` events. Qualified extension id of the
-     * Action that just ran.
+     * 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.
      */
-    actionId?: string;
+    store?: unknown;
+}
+interface IExtractor extends IExtensionBase {
+    kind: 'extractor';
+    emitsLinkKinds: LinkKind[];
+    defaultConfidence: Confidence;
+    scope: 'frontmatter' | 'body' | 'both';
     /**
-     * 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`.
+     * 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 the extractor
+     * wastes zero CPU on inapplicable nodes.
+     *
+     * 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`.
      */
-    jobResult?: unknown;
+    applicableKinds?: string[];
     /**
-     * `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.
+     * Extractor entry point. Returns nothing; output flows through
+     * `ctx.emitLink`, `ctx.enrichNode`, and `ctx.store`.
      */
-    runner?: unknown;
+    extract(ctx: IExtractorContext): void | Promise<void>;
 }
+
 /**
- * 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").
+ * Analyzer runtime contract. Runs against the whole graph after every
+ * Provider and extractor has completed; emits issues and MAY project
+ * findings into the UI via view contributions. Deterministic analyzers
+ * are pure (same graph in → same issues out) and run synchronously
+ * inside `sm scan` / `sm check`. Probabilistic analyzers 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`).
  */
-type THookFilter = Record<string, string | number | boolean>;
-interface IHook extends IExtensionBase {
-    kind: 'hook';
+
+/**
+ * Step 9.6.2, orphan sidecar entry surfaced to analyzers. A `.sm` file
+ * whose sibling `.md` does not exist on disk; the `annotation-orphan`
+ * built-in analyzer emits one warning per entry. Other analyzers that
+ * care about orphan sidecars MAY consume the list too.
+ */
+interface IAnalyzerOrphanSidecar {
+    /** Relative path (POSIX-separated) of the orphan `.sm`. */
+    relativePath: string;
+    /** Absolute path of the missing `.md` the sidecar was anchored to. */
+    expectedMdPath: string;
+}
+interface IAnalyzerContext {
+    nodes: Node[];
+    links: Link[];
     /**
-     * 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).
+     * Step 9.6.2, orphaned sidecars discovered during the scan walk.
+     * Empty when sidecar discovery did not run (legacy callers) or
+     * when no orphans exist.
      */
-    mode?: TExecutionMode;
+    orphanSidecars?: IAnalyzerOrphanSidecar[];
     /**
-     * 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.
+     * Step 9.6.6, raw parsed sidecar root keyed by `node.path`. Populated
+     * by the orchestrator alongside the public `Node.sidecar` overlay so
+     * analyzers that inspect plugin namespaces (e.g. the built-in
+     * `core/unknown-field` Analyzer) can walk the full tree without
+     * re-reading the file from disk. Absent (or `undefined` per node)
+     * when no sidecar accompanies the node, or when the sidecar failed
+     * to parse. Treat as read-only.
      */
-    triggers: THookTrigger[];
+    sidecarRoots?: ReadonlyMap<string, Record<string, unknown>>;
     /**
-     * Optional declarative filter. Absent → invoke on every dispatched
-     * event of every declared trigger.
+     * Step 9.6.6, runtime catalog of plugin-contributed annotation keys,
+     * as exposed by `kernel.getRegisteredAnnotationKeys()`. Threaded
+     * through so analyzers can reason about the registered-vs-unknown
+     * split without reaching back into the kernel. Empty array when no
+     * plugin declares contributions; absent for legacy callers (older
+     * runScan sites that never wired the catalog through).
      */
-    filter?: THookFilter;
+    annotationContributions?: readonly IRegisteredAnnotationKey[];
     /**
-     * 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.
+     * Step 11.x, runtime catalog of plugin-contributed view contributions,
+     * as exposed by `kernel.getRegisteredViewContributions()`. Threaded
+     * through so analyzers can reason about emissions without reaching
+     * back into the kernel (built-in `core/contribution-orphan` joins it
+     * with the live node set to flag dangling emissions). Slot catalog
+     * drift detection is NOT a scan concern, it lives at load time and
+     * surfaces via `sm plugins doctor`. Empty array when no extension
+     * declares view contributions; absent for legacy callers (older
+     * runScan sites that never wired the catalog through).
      */
-    on(ctx: IHookContext): void | Promise<void>;
-}
-
-/**
- * `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 TProgressListener = (event: ProgressEvent) => void;
-interface ProgressEmitterPort {
-    emit(event: ProgressEvent): void;
-    subscribe(listener: TProgressListener): () => void;
-}
-
-/**
- * Per-node extractor invocation: build a fresh `IExtractorContext` for
- * each extractor, validate every emitted link / contribution against
- * the declared catalog, fold enrichment partials into per-`(node,
- * extractor)` records, and surface emit-time drops as
- * `extension.error` events.
- *
- * Also hosts the post-walk recompute helpers that re-derive
- * `linksOutCount` / `linksInCount` / `externalRefsCount` on every node
- * from the final merged link buffer, plus the `IExtractorRunRecord`
- * and `IEnrichmentRecord` types those records eventually persist as.
- */
-
-/**
- * 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;
+    viewContributions?: readonly IRegisteredViewContribution[];
     /**
-     * sha256 of the canonical-form sidecar annotations the Extractor saw
-     * at run time. Always populated (an absent sidecar canonicalises to
-     * `{}` so the hash is stable). Used unconditionally by the cache
-     * decision alongside `bodyHashAtRun`: a sidecar-only edit invalidates
-     * the cached run for every applicable Extractor on that node.
+     * Absolute paths of `*.md` files under the project's
+     * `.skill-map/jobs/` that no `state_jobs.filePath` references, the
+     * built-in `core/job-orphan-file` analyzer projects each as a `warn`
+     * issue. Pre-computed by the driving adapter (CLI / BFF) inside its
+     * already-open storage transaction (mirrors the `orphanSidecars`
+     * pattern: detection lives outside the analyzer, the analyzer only
+     * projects). Absent (or empty) when the caller does not maintain a
+     * jobs directory, when the storage path is unavailable, or when no
+     * orphan files exist. Treat as read-only.
      */
-    sidecarAnnotationsHashAtRun: string;
-}
+    orphanJobFiles?: readonly string[];
+    /**
+     * Set of absolute file paths the operator has opted into for
+     * link-validation purposes via `scan.referencePaths`. The driving
+     * adapter walks each configured path before the scan and collects
+     * every existing file's absolute path here. Files in this set are
+     * NOT indexed as graph nodes, the only consumer is
+     * `core/broken-ref`, which suppresses its `warn` issue when a
+     * path-style link target falls into the set. Absent / empty when
+     * the operator left `scan.referencePaths` empty or when the
+     * adapter does not maintain the side index. Treat as read-only.
+     */
+    referenceablePaths?: ReadonlySet<string>;
+    /**
+     * Absolute path of the scan's project root (cwd of the invocation).
+     * Threaded into the analyzer pass so an analyzer that needs to
+     * resolve a relative `link.target` to an absolute filesystem path
+     * (today only `core/broken-ref`, when consulting
+     * `referenceablePaths`) does not have to derive it from
+     * `nodes[0].path` heuristics. Absent for legacy callers (older
+     * `runScan` sites that never wired the field through). Always an
+     * absolute path when present.
+     */
+    cwd?: string;
+    /**
+     * Emit a per-node view contribution declared in this analyzer's
+     * manifest `viewContributions` map. Sync, void return; the
+     * orchestrator validates the payload against the slot's schema at
+     * call time and silently drops invalid emissions with a logged
+     * `extension.error` event (parallel to
+     * `IExtractorCallbacks.emitContribution`).
+     *
+     * Unlike Extractor's emit (which binds `nodePath` from `ctx.node.path`
+     * implicitly because Extractors run per-node), Analyzer's `evaluate()`
+     * sees the full graph at once. The analyzer walks `ctx.nodes` itself
+     * and MUST supply the target node path explicitly per emission.
+     *
+     * Calling `emitContribution` with a `contributionId` that is not
+     * declared in the manifest is dropped with an `extension.error`. The
+     * kernel routes emitted contributions to the same persistence
+     * pipeline as Extractor emissions (`scan_contributions`).
+     */
+    emitContribution(nodePath: string, contributionId: string, payload: unknown): void;
+}
+interface IAnalyzer extends IExtensionBase {
+    kind: 'analyzer';
+    /**
+     * Execution mode. Optional in the manifest with a default of
+     * `deterministic` per `spec/schemas/extensions/analyzer.schema.json`.
+     */
+    mode?: TExecutionMode;
+    /**
+     * Qualified `<pluginId>/<id>` Action ids the analyzer recommends to
+     * resolve its findings. Distinct from `Action.precondition` (which
+     * declares which nodes an Action applies to from the Action side);
+     * this field declares which Actions are relevant when this
+     * Analyzer fires from the Analyzer side. Actions are per-node by
+     * design (project-level cleanup verbs like orphan file prune or
+     * contribution relink are CLI verbs, not Actions) and are NOT
+     * surfaced through this field. The UI consumes it in the node
+     * inspector under "Recommended for issues". Optional; omit when no
+     * Action resolves the finding (e.g. `core/superseded` surfaces
+     * deliberate user declarations, not problems).
+     */
+    recommendedActions?: readonly string[];
+    evaluate(ctx: IAnalyzerContext): Issue[] | Promise<Issue[]>;
+}
+
 /**
- * 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:
+ * Action runtime contract. The fourth plugin kind (spec § A.4 +
+ * `spec/schemas/extensions/action.schema.json`).
  *
- *   - upsert a single row per pair (stable PRIMARY KEY conflict on
- *     re-extract);
- *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
- *     for last-write-wins per field at read time.
+ * Actions operate on one or more nodes in one of two execution modes:
  *
- * `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.
+ *   - `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`.
  *
- * `isProbabilistic` is reserved: Extractors are deterministic-only, so
- * every record produced by the orchestrator sets it to `false`. The
- * field is kept on the record (and the row in `node_enrichments`) so a
- * future Action-issued enrichment can populate it without reshaping
- * the persistence contract, see spec `architecture.md`
- * §Extractor · enrichment layer.
- */
-interface IEnrichmentRecord {
-    nodePath: string;
-    extractorId: string;
-    bodyHashAtEnrichment: string;
-    value: Partial<Node>;
-    enrichedAt: number;
-    isProbabilistic: boolean;
-}
-/**
- * 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.).
+ * **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.
  *
- * 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).
+ * Mirrors `extensions/action.schema.json`:
  *
- * 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.
+ *   - `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'`.
  */
-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[];
-    contributions: IContributionRecord[];
-}>;
 
 /**
- * Rename + orphan classification per `spec/db-schema.md` §Rename
- * detection. Pure: takes the prior `ScanResult` and the current node
- * set, mutates the supplied `issues` array in place, and returns the
- * `RenameOp[]` the persistence layer must apply inside the same tx as
- * the scan zone replace-all.
+ * Single sidecar write payload an Action can return. Discriminated union so
+ * future write kinds (storage rows, plugin KV, etc.) can land additively
+ * without breaking consumers that only handle `kind: 'sidecar'`.
+ *
+ *   - `path`, absolute path to the `.sm` file the kernel must materialise
+ *     the change into. Resolved by the Action from the node's absolute
+ *     path via `sidecarPathFor()`.
+ *   - `changes`, partial sidecar root used as a deep-merge patch (NOT a
+ *     full replacement). Arrays REPLACE; objects RECURSE. Reason:
+ *     sidecars are shared-write between skill-map core and plugins;
+ *     a full replace would clobber `<plugin-id>:` namespaced blocks.
  */
-
+type TActionWrite = {
+    kind: 'sidecar';
+    path: string;
+    changes: Record<string, unknown>;
+};
 /**
- * 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.
+ * Result envelope returned by deterministic Actions. The `report` field
+ * carries the typed report payload (each Action declares its shape via
+ * `reportSchemaRef`); `writes` is opt-in, Actions that do not mutate
+ * persistent state simply omit it.
  */
-interface RenameOp {
-    from: string;
-    to: string;
-    confidence: 'high' | 'medium';
+interface IActionResult<TReport = unknown> {
+    report: TReport;
+    writes?: TActionWrite[];
 }
 /**
- * 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> }`.
+ * Runtime context passed to a deterministic Action's `invoke()` method.
+ * Minimal surface, Actions stay pure (no IO inside `invoke`); the kernel
+ * materialises any returned `writes` after the call.
  *
- * 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).
+ *   - `node`, the target `Node` the Action operates on. Open-by-design;
+ *     batch / fan-out flows pick the matching nodes upstream.
+ *   - `nodeAbsolutePath`, absolute path to the node's `.md` file on
+ *     disk. The Action uses this to compute the sidecar path it returns
+ *     in a `TActionWrite`. Surfaced separately from `node.path` (which is
+ *     the relative scope-root form) so Actions never compose absolute
+ *     paths from `node.path` themselves.
+ *   - `invoker`, identity of the caller; written into the sidecar's
+ *     `audit.lastBumpedBy` when the Action chooses to. CLI invocations
+ *     pass `'cli'`; plugin-driven invocations pass `'plugin:<plugin-id>'`.
+ *   - `now`, clock function; tests inject a deterministic source.
+ *     Defaults to `() => new Date()` at the composition root.
  */
-declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
-
+interface IActionContext {
+    node: Node;
+    nodeAbsolutePath: string;
+    invoker: string;
+    now: () => Date;
+}
 /**
- * Scan orchestrator, runs the Provider → extractor → analyzer 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.
+ * Declarative filter applied by `--all` fan-out, UI button gating, and
+ * `sm actions show`. All fields optional, an empty precondition matches
+ * every node.
  */
-
-interface IScanExtensions {
-    providers: IProvider[];
-    extractors: IExtractor[];
-    analyzers: IAnalyzer[];
-    /**
-     * 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[];
-}
-interface RunScanOptions {
+interface IActionPrecondition {
     /**
-     * Filesystem roots to walk. Spec requires `minItems: 1`; passing an
-     * empty array makes `runScan` throw before any work happens.
+     * 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.
      */
-    roots: string[];
-    emitter?: ProgressEmitterPort;
-    /** Runtime extension instances. Absent → empty pipeline. */
-    extensions?: IScanExtensions;
+    kind?: string[];
+    /** Provider ids whose nodes this action accepts. Omitted → any Provider. */
+    provider?: string[];
+    /** Node stability filter. */
+    stability?: Array<'experimental' | 'stable' | 'deprecated'>;
     /**
-     * Step 9.6.6, runtime catalog of plugin-contributed annotation keys
-     * (the same shape `kernel.getRegisteredAnnotationKeys()` returns).
-     * Threaded into the rule pass so `core/unknown-field` can
-     * legitimise registered plugin namespaces / root keys without
-     * re-walking the manifests. Absent → empty catalog (every plugin
-     * key is treated as unknown). Built-in catalog from
-     * `annotations.schema.json` is NOT included, that is hard-coded
-     * inside the rule.
+     * Free-form precondition strings the kernel forwards to the action for
+     * runtime evaluation (example: `frontmatter.metadata.source != null`).
      */
-    annotationContributions?: readonly IRegisteredAnnotationKey[];
+    custom?: string[];
+}
+interface IAction extends IExtensionBase {
+    kind: 'action';
     /**
-     * Runtime catalog of plugin-contributed view contributions (the same
-     * shape `kernel.getRegisteredViewContributions()` returns). Threaded
-     * into the rule pass so:
-     *   - `core/contribution-orphan` can introspect the catalog
-     *     (read-only) and join it with the live node set to flag
-     *     dangling emissions. Slot catalog drift is NOT a scan concern,
-     *     it lives at load time and surfaces via `sm plugins doctor`
-     *     (the kernel rejects unknown slots as `invalid-manifest` first,
-     *     doctor catches the catalog-version-skew tail).
-     *   - The orchestrator's per-rule emit closure can look up each
-     *     declared `(contributionId → slot)` pairing for AJV
-     *     payload validation.
-     * Absent → empty catalog. Rules that emit contributions silently
-     * drop emissions when the catalog has no entry for the rule's
-     * declared contributionId.
+     * Execution mode discriminator. Required per
+     * `extensions/action.schema.json`.
      */
-    viewContributions?: readonly IRegisteredViewContribution[];
+    mode: TExecutionMode;
     /**
-     * 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.
+     * 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`.
      */
-    scope?: 'project' | 'global';
+    reportSchemaRef: string;
     /**
-     * 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).
+     * Best-effort estimate of wall-clock duration in seconds. Drives TTL
+     * (`ttl = max(expectedDurationSeconds × graceMultiplier,
+     * minimumTtlSeconds)`). Required for `probabilistic`; advisory for
+     * `deterministic`.
      */
-    tokenize?: boolean;
+    expectedDurationSeconds?: number;
     /**
-     * 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.
+     * 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.
      */
-    priorSnapshot?: ScanResult | null;
+    promptTemplateRef?: string;
     /**
-     * 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").
+     * Optional declarative filter; absent → applies to every node.
      */
-    enableCache?: boolean;
+    precondition?: IActionPrecondition;
     /**
-     * Filter that decides which paths the Providers skip. Composed by the
-     * caller (typically the CLI) from bundled defaults + `config.ignore`
-     * + `.skillmapignore`. Providers that omit this option fall back to
-     * their own defensive defaults (just enough to keep `.git` /
-     * `node_modules` out).
+     * Hint to Skill / CLI runners about what tools the rendered prompt
+     * expects access to (`Bash`, `Read`, `WebSearch`, …). No normative
+     * enforcement in v0.
      */
-    ignoreFilter?: IIgnoreFilter;
+    expectedTools?: string[];
     /**
-     * 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.
+     * `'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.
      */
-    strict?: boolean;
+    fanOutPolicy?: 'per-node' | 'batch';
     /**
-     * Spec § A.9, fine-grained Extractor cache breadcrumbs from the
-     * prior scan. Shape: `Map<nodePath, Map<qualifiedExtractorId, IPriorExtractorRun>>`.
-     * 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.
+     * Deterministic invocation entry point. OPTIONAL on the runtime
+     * contract for backward compatibility with the manifest-only era
+     * (Decision #114), actions that ship for the future probabilistic
+     * runner / record path leave it absent and the kernel never calls it.
+     * Step 9.6.3 (Decision #125) introduces the first concrete consumer:
+     * the built-in `bump` Action implements `invoke()` and returns a
+     * `writes: [{ kind: 'sidecar', ... }]` payload that the kernel
+     * materialises through `ISidecarStore`.
      *
-     * 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 or sidecar
-     *     annotations 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, IPriorExtractorRun>>;
-    /**
-     * 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).
+     * Implementations MUST stay pure, no IO inside `invoke()`. The Action
+     * computes the patch and returns it; the kernel reads the on-disk
+     * sidecar, deep-merges, validates, and writes back inside its critical
+     * section.
      *
-     * 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>;
-    /**
-     * Pre-computed absolute paths of orphan job MD files (files under
-     * `.skill-map/jobs/` whose absolute path appears nowhere in
-     * `state_jobs.filePath`). Threaded into the rule pass so the
-     * built-in `core/job-orphan-file` rule can project each as a `warn`
-     * issue without the kernel reaching for the storage port or doing
-     * its own FS walk. The driving adapter (CLI, BFF) computes this
-     * inside its already-open storage transaction via
-     * `findOrphanJobFiles(jobsDir, await port.jobs.listReferencedFilePaths())`
-     * mirrors the `orphanSidecars` model where detection lives
-     * outside the rule and the rule only projects. Absent / empty when
-     * the caller has no jobs context (out-of-band tests, fresh DB,
-     * `--no-built-ins`).
+     * `TInput` is action-specific; the built-in `bump` Action declares
+     * `{ force?: boolean; reason?: string }`. The signature stays generic
+     * so each Action narrows it locally without forcing a common base.
      */
-    orphanJobFiles?: readonly string[];
-    /**
-     * Side set of absolute file paths the operator opted into for
-     * link-validation purposes via `scan.referencePaths`. Threaded
-     * through to `IAnalyzerContext.referenceablePaths` so the built-in
-     * `core/broken-ref` rule can suppress its `warn` for path-style
-     * links whose target lands in the set. Files are NOT walked by
-     * the kernel, the driving adapter populates the set before
-     * calling `runScan`. Absent / empty when the operator left
-     * `scan.referencePaths` unconfigured.
-     */
-    referenceablePaths?: ReadonlySet<string>;
-    /**
-     * Absolute path of the scan's cwd / project root. Threaded onto
-     * `IAnalyzerContext.cwd` so rules that need to resolve a relative
-     * `link.target` to an absolute filesystem path can do so without
-     * heuristics. Absent for callers that don't track a cwd
-     * concept (out-of-band tests, embedders).
-     */
-    cwd?: string;
+    invoke?: <TInput, TReport>(input: TInput, ctx: IActionContext) => IActionResult<TReport>;
 }
+
 /**
- * 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`.
+ * Formatter runtime contract. Turns the (nodes, links, issues) graph into
+ * a textual representation for `sm graph --format <name>`.
  *
- * 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.
+ * 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.
  */
-declare function runScanWithRenames(_kernel: Kernel, options: RunScanOptions): Promise<{
-    result: ScanResult;
-    renameOps: RenameOp[];
-    extractorRuns: IExtractorRunRecord[];
-    enrichments: IEnrichmentRecord[];
-    contributions: IContributionRecord[];
-    freshlyRunTuples: ReadonlySet<string>;
-}>;
-declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
 
-/**
- * Node-construction helpers: hash a body, canonicalise frontmatter /
- * sidecar annotations, resolve the sidecar overlay for a given relative
- * path, and produce a fresh `Node` (validating its frontmatter on the
- * way out). Also hosts `mergeNodeWithEnrichments` + `IPersistedEnrichment`
- * the read-time merge of author frontmatter with the A.8 enrichment
- * layer.
- */
+interface IFormatterContext {
+    nodes: Node[];
+    links: Link[];
+    issues: Issue[];
+    /**
+     * Full persisted scan, when the caller has it on hand. Optional so
+     * existing formatters that only consume (nodes, links, issues) keep
+     * working unchanged; formatters whose output mirrors a `ScanResult`
+     * envelope (today: the built-in `json` formatter under
+     * `built-in-plugins/formatters/json/`) read this to project the
+     * canonical document verbatim. `undefined` when the caller has only
+     * the three primary arrays (back-compat with older drivers).
+     */
+    scanResult?: ScanResult;
+}
+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;
+}
 
 /**
- * Spec § A.8, produce the merged read-time view of a Node.
+ * Hook runtime contract. The sixth plugin kind (spec § A.11).
  *
- * 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.
+ * 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).
  *
- * Algorithm:
+ * The hookable trigger set is INTENTIONALLY SMALL, ten events. Eight
+ * are pipeline-driven (emitted from inside `runScan`); two
+ * (`boot`, `shutdown`) are CLI-process-driven (emitted by the driving
+ * binary before / after the verb runs, fire-and-forget so
+ * `process.exit` is never blocked). 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.
  *
- *   1. Filter `enrichments` down to rows targeting this node AND not
- *      flagged `stale`. With Extractors deterministic-only no row is
- *      stale-flagged in this revision; the filter is preserved for the
- *      future Action-issued enrichment revision (queued LLM jobs whose
- *      output must survive body changes), where stale visibility
- *      belongs to the UI layer 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.
+ * Dual-mode (declared in manifest):
  *
- * 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.
+ *   - `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`).
  *
- * @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.
+ * Curated trigger set (per spec § A.11):
+ *
+ *   0. `boot`                , once per CLI process, before verb routing.
+ *   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. `analyzer.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.
+ *   9. `shutdown`            , once per CLI process, after the verb's
+ *                                exit code resolves and before
+ *                                `process.exit`.
  */
-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.
+ * The ten hookable lifecycle events. Mirrors the `triggers[]` enum in
+ * `spec/schemas/extensions/hook.schema.json`. Eight are pipeline-driven
+ * (emitted from inside `runScan`); two (`boot`, `shutdown`) are
+ * CLI-process-driven (emitted by the driving binary before / after the
+ * verb runs). Anything outside this set is rejected at load time as
+ * `invalid-manifest`.
  */
-interface IPersistedEnrichment {
-    nodePath: string;
-    extractorId: string;
-    bodyHashAtEnrichment: string;
-    value: Partial<Node>;
-    stale: boolean;
-    enrichedAt: number;
-    isProbabilistic: boolean;
-}
-
+type THookTrigger = 'boot' | 'scan.started' | 'scan.completed' | 'extractor.completed' | 'analyzer.completed' | 'action.completed' | 'job.spawning' | 'job.completed' | 'job.failed' | 'shutdown';
 /**
- * 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.
+ * Frozen list mirror of `THookTrigger` for runtime introspection. The
+ * loader validates `manifest.triggers[]` against this set; the
+ * dispatcher iterates it in order when fanning an event out to
+ * subscribed hooks. `boot` first / `shutdown` last so a debug log of
+ * the array reads in lifecycle order.
  */
-
-declare class InMemoryProgressEmitter implements ProgressEmitterPort {
-    #private;
-    emit(event: ProgressEvent): void;
-    subscribe(listener: TProgressListener): () => void;
-}
-
+declare const HOOK_TRIGGERS: readonly THookTrigger[];
 /**
- * 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.
+ * 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 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
- * `.skillmapignore` 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.
+ * The `event` carries the raw `ProgressEvent` envelope (type, timestamp,
+ * runId/jobId when applicable, data). Optional `node` / `extractorId`
+ * / `analyzerId` / `actionId` are extracted from the event payload by the
+ * dispatcher when present so authors don't have to walk `event.data`.
  *
- * 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.
+ * Probabilistic hooks additionally receive `runner` for LLM dispatch.
+ * Deterministic hooks SHOULD ignore the field.
  */
-
-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;
+interface IHookContext {
+    /** The raw event the dispatcher matched. */
+    event: {
+        type: THookTrigger;
+        timestamp: string;
+        runId?: string;
+        jobId?: string;
+        data?: unknown;
+    };
     /**
-     * Optional ignore filter, same instance the scan walker uses.
-     *
-     * Two shapes are accepted:
-     *
-     *   - **`IIgnoreFilter`** (the static one), captured by reference at
-     *     construction. Use this when the filter never changes for the
-     *     lifetime of the watcher (the typical CLI `sm watch` flow).
-     *
-     *   - **`() => IIgnoreFilter | undefined`** (a getter), re-evaluated
-     *     on EVERY chokidar `ignored` predicate call. Use this when the
-     *     filter can change at runtime, e.g. the BFF rebuilds it after
-     *     a `.skillmapignore` or `.skill-map/settings.json` edit and
-     *     wants chokidar to immediately respect the new patterns without
-     *     tearing down and rebuilding the watcher. A getter that returns
-     *     `undefined` disables ignore filtering for that call.
+     * Convenience extraction of the node payload when the event is
+     * node-scoped (`action.completed`). Undefined for run-scoped or
+     * scan-scoped events.
      */
-    ignoreFilter?: IIgnoreFilter | (() => IIgnoreFilter | undefined) | undefined;
+    node?: Node;
     /**
-     * Maximum directory traversal depth. `undefined` (default) walks the
-     * tree recursively without bound; `0` limits the watch to the
-     * literal `roots` entries (no descent), which is the right setting
-     * when watching a directory only to catch changes to specific
-     * top-level files (see `subscribeMeta` in `core/watcher/runtime.ts`).
-     * Forwarded verbatim to chokidar's `depth` option.
+     * Set on `extractor.completed` events. Qualified extension id of the
+     * Extractor whose work the event aggregates.
      */
-    depth?: number;
-    /** Called once per debounced batch. Awaited; concurrent batches are serialised. */
-    onBatch: (batch: IWatchBatch) => void | Promise<void>;
+    extractorId?: string;
     /**
-     * Called when the underlying watcher surfaces an error. The watcher
-     * stays open, callers decide whether to log, keep going, or close.
+     * Set on `analyzer.completed` events. Qualified extension id of the Rule.
      */
-    onError?: (err: Error) => void;
+    analyzerId?: 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;
 }
 /**
- * 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`.
+ * 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.
  *
- * 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.
+ * 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").
  */
-declare function createChokidarWatcher(opts: ICreateFsWatcherOptions): IFsWatcher;
+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 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**: `(analyzerId, 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).
+ * `ProgressEmitterPort`, emits progress events during long operations.
  *
- * Pure: no IO, no DB, no FS. Safe to run in-memory inside `sm scan`
- * without polluting the persisted snapshot.
+ * 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.
  */
-
-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 ProgressEvent {
+    type: string;
+    timestamp: string;
+    runId?: string;
+    jobId?: string;
+    data?: unknown;
 }
-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[];
-    };
+type TProgressListener = (event: ProgressEvent) => void;
+interface ProgressEmitterPort {
+    emit(event: ProgressEvent): void;
+    subscribe(listener: TProgressListener): () => void;
 }
-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).
+ * Per-node extractor invocation: build a fresh `IExtractorContext` for
+ * each extractor, validate every emitted link / contribution against
+ * the declared catalog, fold enrichment partials into per-`(node,
+ * extractor)` records, and surface emit-time drops as
+ * `extension.error` events.
+ *
+ * Also hosts the post-walk recompute helpers that re-derive
+ * `linksOutCount` / `linksInCount` / `externalRefsCount` on every node
+ * from the final merged link buffer, plus the `IExtractorRunRecord`
+ * and `IEnrichmentRecord` types those records eventually persist as.
  */
-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
+ * 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;
+    /**
+     * sha256 of the canonical-form sidecar annotations the Extractor saw
+     * at run time. Always populated (an absent sidecar canonicalises to
+     * `{}` so the hash is stable). Used unconditionally by the cache
+     * decision alongside `bodyHashAtRun`: a sidecar-only edit invalidates
+     * the cached run for every applicable Extractor on that node.
+     */
+    sidecarAnnotationsHashAtRun: string;
+}
+/**
+ * Spec § A.8, universal enrichment layer.
  *
- * Tokens AND together; values within one token OR. An empty / whitespace-only
- * query is valid and matches every node ("export everything").
+ * 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:
  *
- * **Filters**:
+ *   - upsert a single row per pair (stable PRIMARY KEY conflict on
+ *     re-extract);
+ *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
+ *     for last-write-wins per field at read time.
  *
- *   - `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 `/`).
+ * `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.
  *
- * **Subset semantics** (`applyExportQuery`):
+ * `isProbabilistic` is reserved: Extractors are deterministic-only, so
+ * every record produced by the orchestrator sets it to `false`. The
+ * field is kept on the record (and the row in `node_enrichments`) so a
+ * future Action-issued enrichment can populate it without reshaping
+ * the persistence contract, see spec `architecture.md`
+ * §Extractor · enrichment layer.
+ */
+interface IEnrichmentRecord {
+    nodePath: string;
+    extractorId: string;
+    bodyHashAtEnrichment: string;
+    value: Partial<Node>;
+    enrichedAt: number;
+    isProbabilistic: boolean;
+}
+/**
+ * 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.).
  *
- *   - 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.
+ * 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).
  *
- * Pure: no IO, no DB, no FS.
+ * 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.
  */
-
-interface IExportQuery {
-    /** Original query string echoed back so consumers can render the header. */
-    raw: string;
+declare function runExtractorsForNode(opts: {
+    extractors: IExtractor[];
+    node: Node;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    bodyHash: string;
+    emitter: ProgressEmitterPort;
     /**
-     * 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.
+     * 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).
      */
-    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;
+    pluginStores?: ReadonlyMap<string, IPluginStore>;
+}): Promise<{
+    internalLinks: Link[];
+    externalLinks: Link[];
+    enrichments: IEnrichmentRecord[];
+    contributions: IContributionRecord[];
+}>;
 
 /**
- * `scan_node_tags` adapter, tags · dual-source persistence layer.
- *
- * One row per `(node_path, tag, source)` triple. Projected at persist
- * time from BOTH `frontmatter.tags` (with `source='author'`) and
- * `sidecar.annotations.tags` (with `source='user'`). The same tag
- * string MAY appear under both sources for the same node, the PK
- * accepts the pair; search returns the node once via DISTINCT, the
- * UI renders both chips with their attribution.
- *
- * Belongs to the `scan_*` family, replaced wholesale per scan.
- * Cached nodes' tag rows are projected from the cached
- * `node.frontmatter.tags` / `node.sidecar.annotations.tags` (both
- * already in memory at persist time), so the rebuild is cheap
- * regardless of cache hit / miss. See `spec/db-schema.md`
- * § scan_node_tags for the normative shape and replace-all semantics.
+ * Rename + orphan classification per `spec/db-schema.md` §Rename
+ * detection. Pure: takes the prior `ScanResult` and the current node
+ * set, mutates the supplied `issues` array in place, and returns the
+ * `RenameOp[]` the persistence layer must apply inside the same tx as
+ * the scan zone replace-all.
  */
 
 /**
- * In-memory tag record buffered during scan and flushed to
- * `scan_node_tags` by `persistScanResult`. One entry per
- * `(node_path, tag, source)` projected from a node's frontmatter tags
- * (`source: 'author'`) or sidecar annotations tags
- * (`source: 'user'`).
+ * 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 ITagRecord {
-    nodePath: string;
-    tag: string;
-    source: 'author' | 'user';
+interface RenameOp {
+    from: string;
+    to: string;
+    confidence: 'high' | 'medium';
 }
-
 /**
- * Pure helpers for the "update available" notification feature.
+ * 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.
  *
- * Three responsibilities:
- *   - `fetchLatestVersion` , query `https://registry.npmjs.org/<pkg>/latest`
- *                             with `AbortController` + timeout. Throws on
- *                             non-200 / parse failure / abort.
- *   - `compareVersions`    , semver compare (-1 / 0 / 1). Pre-1.0 aware:
- *                             treats prereleases via the standard rules
- *                             (release > prerelease at the same triple).
- *   - `isOutdated`         , sugar over `compareVersions` for the common
- *                             "is `latest` strictly greater than `current`"
- *                             check the banner runs against.
+ * Pipeline (1-to-1: a `newPath` claimed by one stage cannot be reused
+ * by another):
  *
- * Pure kernel module, NO `process.env` reads, NO Node globals beyond the
- * built-in `fetch` / `AbortController` (Node 22+). Every env / settings
- * lookup happens in `src/cli/util/update-check-banner.ts`, the CLI-side
- * adapter that owns side effects.
+ *   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> }`.
  *
- * The shared cache type (`IUpdateCheckCache`) is used by the storage
- * helpers under `kernel/storage/update-check.ts` and by the BFF's
- * `GET /api/update-status` projection. A second type
- * (`IUpdateStatus`) shapes the BFF response, it merges `current`
- * (from `VERSION`) into the cache so the UI can render without a
- * second lookup. Both stay flat, no nested objects, so JSON
- * serialization is trivial.
+ * 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).
  */
-interface IUpdateCheckCache {
-    latestVersion: string;
-    /** Epoch ms, when the registry was last successfully probed. */
-    checkedAt: number;
-    /** Epoch ms, when the banner was last printed; null = never shown yet. */
-    shownAt: number | null;
-}
+declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
 
 /**
- * `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).
+ * Scan orchestrator, runs the Provider → extractor → analyzer 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.
  *
- * 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.
+ * 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 PluginLoaderPort {
+interface IScanExtensions {
+    providers: IProvider[];
+    extractors: IExtractor[];
+    analyzers: IAnalyzer[];
     /**
-     * Synchronously enumerate every directory containing a `plugin.json`
-     * across the configured search paths. Non-existent paths are skipped.
+     * 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.
      */
-    discoverPaths(): string[];
+    hooks?: IHook[];
+}
+interface RunScanOptions {
     /**
-     * Discover every plugin, attempt to load each, then apply the
-     * cross-root id-collision pass. Never throws, failures are reported
-     * via `IDiscoveredPlugin.status`.
+     * Filesystem roots to walk. Spec requires `minItems: 1`; passing an
+     * empty array makes `runScan` throw before any work happens.
      */
-    discoverAndLoadAll(): Promise<IDiscoveredPlugin[]>;
+    roots: string[];
+    emitter?: ProgressEmitterPort;
+    /** Runtime extension instances. Absent → empty pipeline. */
+    extensions?: IScanExtensions;
     /**
-     * Load a single plugin from its directory. Never throws, failure is
-     * reported via the returned `status`.
+     * Step 9.6.6, runtime catalog of plugin-contributed annotation keys
+     * (the same shape `kernel.getRegisteredAnnotationKeys()` returns).
+     * Threaded into the rule pass so `core/unknown-field` can
+     * legitimise registered plugin namespaces / root keys without
+     * re-walking the manifests. Absent → empty catalog (every plugin
+     * key is treated as unknown). Built-in catalog from
+     * `annotations.schema.json` is NOT included, that is hard-coded
+     * inside the rule.
      */
-    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;
+    annotationContributions?: readonly IRegisteredAnnotationKey[];
     /**
-     * When `true`, keep only nodes whose path is referenced by at least
-     * one `scan_issues.nodeIds` array.
+     * Runtime catalog of plugin-contributed view contributions (the same
+     * shape `kernel.getRegisteredViewContributions()` returns). Threaded
+     * into the rule pass so:
+     *   - `core/contribution-orphan` can introspect the catalog
+     *     (read-only) and join it with the live node set to flag
+     *     dangling emissions. Slot catalog drift is NOT a scan concern,
+     *     it lives at load time and surfaces via `sm plugins doctor`
+     *     (the kernel rejects unknown slots as `invalid-manifest` first,
+     *     doctor catches the catalog-version-skew tail).
+     *   - The orchestrator's per-rule emit closure can look up each
+     *     declared `(contributionId → slot)` pairing for AJV
+     *     payload validation.
+     * Absent → empty catalog. Rules that emit contributions silently
+     * drop emissions when the catalog has no entry for the rule's
+     * declared contributionId.
      */
-    hasIssues?: boolean;
+    viewContributions?: readonly IRegisteredViewContribution[];
     /**
-     * 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).
+     * 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.
      */
-    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[];
-    contributions?: IContributionRecord[];
+    scope?: 'project' | 'global';
     /**
-     * Phase 3 / View contribution system, active runtime catalog of
-     * registered view contributions, keyed by qualified id
-     * `<pluginId>/<extensionId>/<contributionId>`. Passed to the
-     * `scan_contributions` upsert so the catalog sweep can drop rows
-     * belonging to plugins / extensions that are no longer in the
-     * catalog (uninstalled plugins, disabled bundles, removed
-     * contributions). Empty / absent set = no catalog sweep (legacy
-     * behaviour, leaves disabled-plugin rows stale per design F24
-     * pre-fix).
+     * 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).
      */
-    registeredContributionKeys?: ReadonlySet<string>;
+    tokenize?: boolean;
     /**
-     * Phase 3 / View contribution system, set of `(plugin, extension,
-     * node)` tuples where the extension actually RAN against that node
-     * in this scan. Format: `<pluginId>/<extensionId>/<nodePath>` (no
-     * contribution-id segment, the sweep operates at the (plugin,
-     * extension, node) level and inspects the buffer to decide which
-     * contribution-ids survive).
+     * Prior snapshot for two purposes (decoupled by design):
      *
-     * Membership rules:
-     *   - Extractor + cache miss: tuple INCLUDED (extract() ran).
-     *   - Extractor + cache hit: tuple OMITTED (extract() skipped, prior
-     *     rows must be preserved).
-     *   - Rule, every node in `ctx.nodes`: tuple INCLUDED (rules always
-     *     run and see the full graph).
+     *   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.
      *
-     * Drives the per-tuple sweep documented in `spec/architecture.md`
-     * §View contribution system → Persistence (sweep #3): rows whose
-     * `(plugin_id, extension_id, node_path)` is in this set but whose
-     * `(plugin_id, extension_id, node_path, contribution_id)` is NOT in
-     * the buffer get DELETEd before the upsert. Catches the "extractor
-     * used to emit, now does not" case (e.g. body change removes the
-     * trigger). Empty / absent set = no per-tuple sweep (legacy
-     * callers preserve the pre-fix behaviour where stale rows linger).
+     *   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.
      */
-    freshlyRunTuples?: ReadonlySet<string>;
-}
-/**
- * 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;
-}
-/**
- * Filter + pagination shape for `port.issues.list(...)`, driven by the
- * BFF's `/api/issues` route. Every field is optional, an empty filter
- * returns every issue ordered by `id` ASC (insertion order, stable
- * across pages so `offset` / `limit` paging is deterministic).
- *
- * The three semantic filters mirror `/api/issues`'s query params:
- *
- *   - `severities`, narrowed list of `Severity` values. Empty / absent
- *     matches every severity.
- *   - `analyzerIds`, accepts qualified (`<plugin>/<id>`) AND short
- *     (`<id>`) forms; the suffix-match semantics live in
- *     `matchesAnalyzerFilter`. Each entry generates two SQL clauses
- *     (`= ?` and `LIKE '%/' || ?`) ORed together so the filter remains
- *     a single SQL pass with parameterised values, no string
- *     interpolation. Empty / absent matches every analyzer id.
- *   - `nodePath`, keeps issues whose `nodeIds` JSON array contains the
- *     given path (correlated EXISTS over `json_each`). Absent / null
- *     skips the filter.
- *
- * Pagination is mandatory; the route layer fills the defaults via
- * `parsePagination`. `total` in `IIssueListResult` reports the total
- * MATCHING the filters (not just the page slice) so the SPA can
- * surface a correct page-count without a second round-trip.
- */
-interface IIssueListFilter {
+    priorSnapshot?: ScanResult | null;
     /**
-     * Severity tokens to match. Typed as open `string` (not the
-     * `Severity` union) so an unknown value from a URL query string
-     * surfaces as a zero-match SQL query, not a kernel validation
-     * error. The adapter parameterises each entry into the `IN(...)`
-     * clause; unrecognised severities simply match no rows.
+     * 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").
      */
-    severities?: readonly string[];
-    analyzerIds?: readonly string[];
-    nodePath?: string | null;
-    offset: number;
-    limit: number;
-}
-/**
- * Output of `port.issues.list(...)`. `items` is the page slice (length
- * ≤ `filter.limit`); `total` is the count of rows matching the filters
- * before pagination was applied.
- */
-interface IIssueListResult {
-    items: Issue[];
-    total: number;
-}
-/** 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;
-    nodeFavorites: number;
+    enableCache?: boolean;
     /**
-     * Collisions encountered when migrating any of the keyed-by-node
-     * `state_*` tables 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. `state_node_favorites` has no composite key
-     * so its `keys` is the empty object.
+     * Filter that decides which paths the Providers skip. Composed by the
+     * caller (typically the CLI) from bundled defaults + `config.ignore`
+     * + `.skillmapignore`. Providers that omit this option fall back to
+     * their own defensive defaults (just enough to keep `.git` /
+     * `node_modules` out).
      */
-    collisions: Array<{
-        table: 'state_summaries' | 'state_enrichments' | 'state_plugin_kvs' | 'state_node_favorites';
-        fromPath: string;
-        toPath: string;
-        keys: Record<string, string>;
-    }>;
+    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, IPriorExtractorRun>>`.
+     * 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 or sidecar
+     *     annotations 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, IPriorExtractorRun>>;
+    /**
+     * 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>;
+    /**
+     * Pre-computed absolute paths of orphan job MD files (files under
+     * `.skill-map/jobs/` whose absolute path appears nowhere in
+     * `state_jobs.filePath`). Threaded into the rule pass so the
+     * built-in `core/job-orphan-file` rule can project each as a `warn`
+     * issue without the kernel reaching for the storage port or doing
+     * its own FS walk. The driving adapter (CLI, BFF) computes this
+     * inside its already-open storage transaction via
+     * `findOrphanJobFiles(jobsDir, await port.jobs.listReferencedFilePaths())`
+     * mirrors the `orphanSidecars` model where detection lives
+     * outside the rule and the rule only projects. Absent / empty when
+     * the caller has no jobs context (out-of-band tests, fresh DB,
+     * `--no-built-ins`).
+     */
+    orphanJobFiles?: readonly string[];
+    /**
+     * Side set of absolute file paths the operator opted into for
+     * link-validation purposes via `scan.referencePaths`. Threaded
+     * through to `IAnalyzerContext.referenceablePaths` so the built-in
+     * `core/broken-ref` rule can suppress its `warn` for path-style
+     * links whose target lands in the set. Files are NOT walked by
+     * the kernel, the driving adapter populates the set before
+     * calling `runScan`. Absent / empty when the operator left
+     * `scan.referencePaths` unconfigured.
+     */
+    referenceablePaths?: ReadonlySet<string>;
+    /**
+     * Absolute path of the scan's cwd / project root. Threaded onto
+     * `IAnalyzerContext.cwd` so rules that need to resolve a relative
+     * `link.target` to an absolute filesystem path can do so without
+     * heuristics. Absent for callers that don't track a cwd
+     * concept (out-of-band tests, embedders).
+     */
+    cwd?: string;
 }
-/** A single `config_plugins` override row as the kernel sees it. */
-interface IPluginConfigRow {
-    pluginId: string;
-    enabled: boolean;
-    configJson: string | null;
-    updatedAt: number;
+/**
+ * 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[];
+    contributions: IContributionRecord[];
+    freshlyRunTuples: ReadonlySet<string>;
+}>;
+declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
+
+/**
+ * Node-construction helpers: hash a body, canonicalise frontmatter /
+ * sidecar annotations, resolve the sidecar overlay for a given relative
+ * path, and produce a fresh `Node` (validating its frontmatter on the
+ * way out). Also hosts `mergeNodeWithEnrichments` + `IPersistedEnrichment`
+ * the read-time merge of author frontmatter with the A.8 enrichment
+ * layer.
+ */
+
+/**
+ * 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`. With Extractors deterministic-only no row is
+ *      stale-flagged in this revision; the filter is preserved for the
+ *      future Action-issued enrichment revision (queued LLM jobs whose
+ *      output must survive body changes), where stale visibility
+ *      belongs to the UI layer 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;
 }
-/** Discovered kernel migration file (one of `NNN_snake_case.sql`). */
-interface IMigrationFile {
-    version: number;
-    description: string;
-    filePath: string;
+
+/**
+ * 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: TProgressListener): () => void;
 }
-/** A row from the `config_schema_versions` ledger for the kernel scope. */
-interface IMigrationRecord {
-    scope: string;
-    ownerId: string;
-    version: number;
-    description: string;
-    appliedAt: number;
+
+/**
+ * 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
+ * `.skillmapignore` 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;
 }
-/** `port.migrations.plan` output: applied vs pending. */
-interface IMigrationPlan {
-    applied: IMigrationRecord[];
-    pending: IMigrationFile[];
+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.
+     *
+     * Two shapes are accepted:
+     *
+     *   - **`IIgnoreFilter`** (the static one), captured by reference at
+     *     construction. Use this when the filter never changes for the
+     *     lifetime of the watcher (the typical CLI `sm watch` flow).
+     *
+     *   - **`() => IIgnoreFilter | undefined`** (a getter), re-evaluated
+     *     on EVERY chokidar `ignored` predicate call. Use this when the
+     *     filter can change at runtime, e.g. the BFF rebuilds it after
+     *     a `.skillmapignore` or `.skill-map/settings.json` edit and
+     *     wants chokidar to immediately respect the new patterns without
+     *     tearing down and rebuilding the watcher. A getter that returns
+     *     `undefined` disables ignore filtering for that call.
+     */
+    ignoreFilter?: IIgnoreFilter | (() => IIgnoreFilter | undefined) | undefined;
+    /**
+     * Maximum directory traversal depth. `undefined` (default) walks the
+     * tree recursively without bound; `0` limits the watch to the
+     * literal `roots` entries (no descent), which is the right setting
+     * when watching a directory only to catch changes to specific
+     * top-level files (see `subscribeMeta` in `core/watcher/runtime.ts`).
+     * Forwarded verbatim to chokidar's `depth` option.
+     */
+    depth?: number;
+    /** 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**: `(analyzerId, 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;
 }
-/** Apply-time options for `port.migrations.apply`. */
-interface IApplyOptions {
-    backup?: boolean;
-    dryRun?: boolean;
-    to?: number;
+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[];
+    };
 }
-/** Result of `port.migrations.apply`. */
-interface IApplyResult {
-    applied: IMigrationFile[];
-    backupPath: string | null;
+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[];
 }
-/** Discovered plugin migration file. Same `NNN_snake_case.sql` convention. */
-interface IPluginMigrationFile {
-    version: number;
-    description: string;
-    filePath: string;
+interface IExportSubset {
+    query: IExportQuery;
+    nodes: Node[];
+    links: Link[];
+    issues: Issue[];
 }
-/** A row from the `config_schema_versions` ledger for a single plugin. */
-interface IPluginMigrationRecord {
-    version: number;
-    description: string;
-    appliedAt: number;
+declare class ExportQueryError extends Error {
+    constructor(message: string);
 }
-/** `port.pluginMigrations.plan` output for a single plugin. */
-interface IPluginMigrationPlan {
-    pluginId: string;
-    applied: IPluginMigrationRecord[];
-    pending: IPluginMigrationFile[];
+declare function parseExportQuery(raw: string): IExportQuery;
+declare function applyExportQuery(scan: {
+    nodes: Node[];
+    links: Link[];
+    issues: Issue[];
+}, query: IExportQuery): IExportSubset;
+
+/**
+ * `scan_node_tags` adapter, tags · dual-source persistence layer.
+ *
+ * One row per `(node_path, tag, source)` triple. Projected at persist
+ * time from BOTH `frontmatter.tags` (with `source='author'`) and
+ * `sidecar.annotations.tags` (with `source='user'`). The same tag
+ * string MAY appear under both sources for the same node, the PK
+ * accepts the pair; search returns the node once via DISTINCT, the
+ * UI renders both chips with their attribution.
+ *
+ * Belongs to the `scan_*` family, replaced wholesale per scan.
+ * Cached nodes' tag rows are projected from the cached
+ * `node.frontmatter.tags` / `node.sidecar.annotations.tags` (both
+ * already in memory at persist time), so the rebuild is cheap
+ * regardless of cache hit / miss. See `spec/db-schema.md`
+ * § scan_node_tags for the normative shape and replace-all semantics.
+ */
+
+/**
+ * In-memory tag record buffered during scan and flushed to
+ * `scan_node_tags` by `persistScanResult`. One entry per
+ * `(node_path, tag, source)` projected from a node's frontmatter tags
+ * (`source: 'author'`) or sidecar annotations tags
+ * (`source: 'user'`).
+ */
+interface ITagRecord {
+    nodePath: string;
+    tag: string;
+    source: 'author' | 'user';
 }
-/** Apply-time options for `port.pluginMigrations.apply`. */
-interface IPluginApplyOptions {
-    /** No actual writes; surfaces what would run. Default false. */
-    dryRun?: boolean;
+
+/**
+ * Pure helpers for the "update available" notification feature.
+ *
+ * Three responsibilities:
+ *   - `fetchLatestVersion` , query `https://registry.npmjs.org/<pkg>/latest`
+ *                             with `AbortController` + timeout. Throws on
+ *                             non-200 / parse failure / abort.
+ *   - `compareVersions`    , semver compare (-1 / 0 / 1). Pre-1.0 aware:
+ *                             treats prereleases via the standard rules
+ *                             (release > prerelease at the same triple).
+ *   - `isOutdated`         , sugar over `compareVersions` for the common
+ *                             "is `latest` strictly greater than `current`"
+ *                             check the banner runs against.
+ *
+ * Pure kernel module, NO `process.env` reads, NO Node globals beyond the
+ * built-in `fetch` / `AbortController` (Node 22+). Every env / settings
+ * lookup happens in `src/cli/util/update-check-banner.ts`, the CLI-side
+ * adapter that owns side effects.
+ *
+ * The shared cache type (`IUpdateCheckCache`) is used by the storage
+ * helpers under `kernel/storage/update-check.ts` and by the BFF's
+ * `GET /api/update-status` projection. A second type
+ * (`IUpdateStatus`) shapes the BFF response, it merges `current`
+ * (from `VERSION`) into the cache so the UI can render without a
+ * second lookup. Both stay flat, no nested objects, so JSON
+ * serialization is trivial.
+ */
+interface IUpdateCheckCache {
+    latestVersion: string;
+    /** Epoch ms, when the registry was last successfully probed. */
+    checkedAt: number;
+    /** Epoch ms, when the banner was last printed; null = never shown yet. */
+    shownAt: number | null;
 }
-/** 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[];
+
+/**
+ * `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>;
 }
 
 /**