@skill-map/cli 0.20.1 → 0.22.0

package/dist/kernel/index.d.ts

@@ -484,7 +484,7 @@ interface IRegisteredAnnotationKey {
  * validates each pick at load time (`invalid-manifest` on miss); the
  * slot fixes both the renderer and the payload shape.
  */
-type TSlotName = 'card.title.right' | 'card.subtitle.left' | 'card.footer.left.counter' | 'card.footer.right' | 'graph.node.alert' | 'inspector.header.badge.counter' | 'inspector.header.badge.tag' | 'inspector.body.panel.breakdown' | 'inspector.body.panel.records' | 'inspector.body.panel.tree' | 'inspector.body.panel.key-values' | 'inspector.body.panel.link-list' | 'inspector.body.panel.markdown' | 'topbar.actions.indicator';
+type TSlotName = 'card.title.right' | 'card.subtitle.left' | 'card.footer.left' | 'card.footer.right' | 'graph.node.alert' | 'inspector.header.badge.counter' | 'inspector.header.badge.tag' | 'inspector.body.panel.breakdown' | 'inspector.body.panel.records' | 'inspector.body.panel.tree' | 'inspector.body.panel.key-values' | 'inspector.body.panel.link-list' | 'inspector.body.panel.markdown' | 'topbar.nav.start';
 /**
  * Closed enum of input-type names for plugin settings. Mirror of
  * `spec/schemas/input-types.schema.json#/$defs/InputTypeName`.
@@ -759,55 +759,6 @@ interface IExtensionBase {
     viewContributions?: Record<string, IViewContribution>;
 }
 
-/**
- * `.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 {
-    /**
-     * Returns `true` when `relativePath` should be skipped. The caller
-     * MUST pass paths relative to the scan root, with POSIX separators
-     * (forward slashes), no leading `/`. Directories MAY be passed with
-     * or without trailing `/`; the wrapper does not require it.
-     */
-    ignores(relativePath: string): boolean;
-}
-
-/**
- * `ProgressEmitterPort` — emits progress events during long operations.
- *
- * Shape-only today. The full event catalog (`run.started`,
- * `job.claimed`, `model.delta`, etc.) is normative in
- * `spec/job-events.md`; this port carries an open `data` payload so
- * adapters can emit any documented event without type churn.
- */
-interface ProgressEvent {
-    type: string;
-    timestamp: string;
-    runId?: string;
-    jobId?: string;
-    data?: unknown;
-}
-type TProgressListener = (event: ProgressEvent) => void;
-interface ProgressEmitterPort {
-    emit(event: ProgressEvent): void;
-    subscribe(listener: TProgressListener): () => void;
-}
-
 /**
  * Plugin-surface types, hand-written to mirror
  * `spec/schemas/plugins-registry.schema.json#/$defs/PluginManifest` and the
@@ -913,9 +864,11 @@ interface IPluginManifest {
  *
  * - `incompatible-spec`: manifest parsed fine but `semver.satisfies` failed
  *   against the installed `@skill-map/spec` version.
- * - `invalid-manifest`: `plugin.json` missing, unparseable, or failing AJV.
- * - `load-error`: manifest passed but an extension module failed to import
- *   or the imported manifest failed its extension-kind schema.
+ * - `invalid-manifest`: `plugin.json` missing, unparseable, failing AJV on
+ *   the base manifest schema, OR the exported extension shape failed its
+ *   kind-specific schema (per spec/architecture.md §Plugin discovery —
+ *   "AJV rejects unknown `slot` names with `invalid-manifest`").
+ * - `load-error`: manifest parsed but an extension module failed to import.
  */
 /**
  * Possible outcomes after the loader sees a plugin.json. Mirrors the
@@ -1191,6 +1144,95 @@ interface IPersistedContribution {
     emittedAt: number;
 }
 
+/**
+ * `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).
+ */
+interface IPriorExtractorRun {
+    bodyHash: string;
+    sidecarAnnotationsHash: string;
+}
+
+/**
+ * `.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 {
+    /**
+     * Returns `true` when `relativePath` should be skipped. The caller
+     * MUST pass paths relative to the scan root, with POSIX separators
+     * (forward slashes), no leading `/`. Directories MAY be passed with
+     * or without trailing `/`; the wrapper does not require it.
+     */
+    ignores(relativePath: string): boolean;
+}
+
 /**
  * Provider runtime contract. Walks filesystem roots and emits raw node
  * records; classification maps path conventions to a node kind.
@@ -1334,15 +1376,6 @@ type TProviderKindIcon = {
 };
 interface IProvider extends IExtensionBase {
     kind: 'provider';
-    /**
-     * Filesystem directory (relative to user home or project root) where this
-     * Provider's content lives. Required. Examples: `'~/.claude'` for the
-     * Claude Provider, `'~/.cursor'` for a hypothetical Cursor Provider.
-     * The kernel walks this directory during boot/scan to discover nodes;
-     * `sm doctor` validates the directory exists and emits a non-blocking
-     * warning when it does not.
-     */
-    explorationDir: string;
     /**
      * Catalog of node kinds this Provider emits. Keyed by kind name. Every
      * kind the Provider can `classify()` MUST have an entry; an entry is
@@ -2092,6 +2125,182 @@ interface IHook extends IExtensionBase {
     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;
+    /**
+     * 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.
+ *
+ * One entry per `(nodePath, qualifiedExtractorId)` pair an Extractor
+ * produced via `ctx.enrichNode(...)` during the walk. Attribution is
+ * preserved per-Extractor (rather than merged client-side as B.1 did)
+ * so the persistence layer can:
+ *
+ *   - upsert a single row per pair (stable PRIMARY KEY conflict on
+ *     re-extract);
+ *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
+ *     for last-write-wins per field at read time.
+ *
+ * `value` is the cumulative merge across every `enrichNode` call that
+ * Extractor made for this node within this scan — multiple
+ * `ctx.enrichNode({...})` calls inside one `extract(ctx)` invocation
+ * fold into a single row, but two different Extractors hitting the
+ * same node yield two distinct rows.
+ *
+ * `isProbabilistic` is 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.).
+ *
+ * Exported so `cli/commands/refresh.ts` can reuse the same wiring it
+ * needs for re-running a single extractor against a single node — the
+ * pre-extraction code in `refresh.ts` was hand-duplicating this loop
+ * (audit item V4).
+ *
+ * Within this call, multiple `enrichNode(partial)` calls from the same
+ * extractor against the same node fold into one record (last-write-wins
+ * per field) — same contract as the in-scan path.
+ */
+declare function runExtractorsForNode(opts: {
+    extractors: IExtractor[];
+    node: Node;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    bodyHash: string;
+    emitter: ProgressEmitterPort;
+    /**
+     * Spec § A.12 — per-plugin `ctx.store` wrappers keyed by `pluginId`.
+     * The map's lookup is per-extractor inside the loop, so callers that
+     * don't track plugin storage can omit it; the resulting `ctx.store`
+     * stays `undefined` (the existing contract).
+     */
+    pluginStores?: ReadonlyMap<string, IPluginStore>;
+}): Promise<{
+    internalLinks: Link[];
+    externalLinks: Link[];
+    enrichments: IEnrichmentRecord[];
+    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.
+ */
+
+/**
+ * Confidence-tagged plan to repoint `state_*` references from one node
+ * path to another. Emitted by the rename heuristic during `runScan` and
+ * consumed by `persistScanResult` so the FK migration runs inside the
+ * same transaction as the scan zone replace-all.
+ */
+interface RenameOp {
+    from: string;
+    to: string;
+    confidence: 'high' | 'medium';
+}
+/**
+ * Pure rename / orphan classification per `spec/db-schema.md` §Rename
+ * detection. Mutates `issues` in place — caller passes the in-progress
+ * issue list; returns the `RenameOp[]` for the persistence layer to
+ * apply inside its tx.
+ *
+ * Pipeline (1-to-1: a `newPath` claimed by one stage cannot be reused
+ * by another):
+ *
+ *   1. **High-confidence**: pair each `deletedPath` with a `newPath`
+ *      that has the same `bodyHash`. No issue, no prompt.
+ *   2. **Medium-confidence (1:1)**: of the remaining deletions, pair
+ *      each with the *unique* unclaimed `newPath` that shares its
+ *      `frontmatterHash`. Emits `auto-rename-medium` (severity warn)
+ *      with `data: { from, to, confidence: 'medium' }`.
+ *   3. **Ambiguous (N:1)**: when a single `newPath` has more than one
+ *      remaining frontmatter-matching candidate, emit ONE
+ *      `auto-rename-ambiguous` issue per `newPath`, listing all
+ *      candidates in `data.candidates`. NO migration.
+ *   4. **Orphan**: every `deletedPath` left after steps 1-3 yields one
+ *      `orphan` issue (severity info) with `data: { path: <deletedPath> }`.
+ *
+ * Determinism: `deletedPaths` and `newPaths` are iterated in lex-asc
+ * order so the same input always produces the same matches —
+ * required for reproducible tests and conformance fixtures (the spec
+ * does not prescribe an order, but stability is the obvious contract).
+ */
+declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
+
 /**
  * Scan orchestrator — runs the Provider → extractor → analyzer pipeline across
  * every registered extension and emits `ProgressEmitterPort` events in
@@ -2158,17 +2367,6 @@ interface IScanExtensions {
      */
     hooks?: IHook[];
 }
-/**
- * Confidence-tagged plan to repoint `state_*` references from one node
- * path to another. Emitted by the rename heuristic during `runScan` and
- * consumed by `persistScanResult` so the FK migration runs inside the
- * same transaction as the scan zone replace-all.
- */
-interface RenameOp {
-    from: string;
-    to: string;
-    confidence: 'high' | 'medium';
-}
 interface RunScanOptions {
     /**
      * Filesystem roots to walk. Spec requires `minItems: 1`; passing an
@@ -2266,7 +2464,7 @@ interface RunScanOptions {
     strict?: boolean;
     /**
      * Spec § A.9 — fine-grained Extractor cache breadcrumbs from the
-     * prior scan. Shape: `Map<nodePath, Map<qualifiedExtractorId, bodyHashAtRun>>`.
+     * 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`
@@ -2278,11 +2476,12 @@ interface RunScanOptions {
      *     registered extractor that applies to this kind has a matching
      *     row → full skip, all prior outbound links reused.
      *   - some applicable extractor lacks a matching row (newly registered,
-     *     or its prior run targeted a different body hash) → run only the
-     *     missing extractors, drop prior links whose `sources` map to any
-     *     missing extractor or to an extractor that is no longer registered.
+     *     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, string>>;
+    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
@@ -2331,55 +2530,6 @@ interface RunScanOptions {
      */
     cwd?: 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;
-}
-/**
- * Spec § A.8 — universal enrichment layer.
- *
- * One entry per `(nodePath, qualifiedExtractorId)` pair an Extractor
- * produced via `ctx.enrichNode(...)` during the walk. Attribution is
- * preserved per-Extractor (rather than merged client-side as B.1 did)
- * so the persistence layer can:
- *
- *   - upsert a single row per pair (stable PRIMARY KEY conflict on
- *     re-extract);
- *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
- *     for last-write-wins per field at read time.
- *
- * `value` is the cumulative merge across every `enrichNode` call that
- * Extractor made for this node within this scan — multiple
- * `ctx.enrichNode({...})` calls inside one `extract(ctx)` invocation
- * fold into a single row, but two different Extractors hitting the
- * same node yield two distinct rows.
- *
- * `isProbabilistic` is 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;
-}
 /**
  * Same as `runScan` but also returns the rename heuristic's `RenameOp[]`
  * — the high- and medium-confidence renames the persistence layer must
@@ -2402,70 +2552,16 @@ declare function runScanWithRenames(_kernel: Kernel, options: RunScanOptions): P
     freshlyRunTuples: ReadonlySet<string>;
 }>;
 declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
+
 /**
- * Run a set of extractors against a single node, collecting their link
- * emissions and node-enrichment partials. Each extractor is invoked
- * exactly once with a fresh `IExtractorContext`. Caller decides what
- * to do with the returned arrays (push into per-scan buffers, write to
- * a focused refresh result, etc.).
- *
- * Exported so `cli/commands/refresh.ts` can reuse the same wiring it
- * needs for re-running a single extractor against a single node — the
- * pre-extraction code in `refresh.ts` was hand-duplicating this loop
- * (audit item V4).
- *
- * Within this call, multiple `enrichNode(partial)` calls from the same
- * extractor against the same node fold into one record (last-write-wins
- * per field) — same contract as the in-scan path.
- */
-declare function runExtractorsForNode(opts: {
-    extractors: IExtractor[];
-    node: Node;
-    body: string;
-    frontmatter: Record<string, unknown>;
-    bodyHash: string;
-    emitter: ProgressEmitterPort;
-    /**
-     * Spec § A.12 — per-plugin `ctx.store` wrappers keyed by `pluginId`.
-     * The map's lookup is per-extractor inside the loop, so callers that
-     * don't track plugin storage can omit it; the resulting `ctx.store`
-     * stays `undefined` (the existing contract).
-     */
-    pluginStores?: ReadonlyMap<string, IPluginStore>;
-}): Promise<{
-    internalLinks: Link[];
-    externalLinks: Link[];
-    enrichments: IEnrichmentRecord[];
-    contributions: IContributionRecord[];
-}>;
-/**
- * Pure rename / orphan classification per `spec/db-schema.md` §Rename
- * detection. Mutates `issues` in place — caller passes the in-progress
- * issue list; returns the `RenameOp[]` for the persistence layer to
- * apply inside its tx.
- *
- * Pipeline (1-to-1: a `newPath` claimed by one stage cannot be reused
- * by another):
- *
- *   1. **High-confidence**: pair each `deletedPath` with a `newPath`
- *      that has the same `bodyHash`. No issue, no prompt.
- *   2. **Medium-confidence (1:1)**: of the remaining deletions, pair
- *      each with the *unique* unclaimed `newPath` that shares its
- *      `frontmatterHash`. Emits `auto-rename-medium` (severity warn)
- *      with `data: { from, to, confidence: 'medium' }`.
- *   3. **Ambiguous (N:1)**: when a single `newPath` has more than one
- *      remaining frontmatter-matching candidate, emit ONE
- *      `auto-rename-ambiguous` issue per `newPath`, listing all
- *      candidates in `data.candidates`. NO migration.
- *   4. **Orphan**: every `deletedPath` left after steps 1-3 yields one
- *      `orphan` issue (severity info) with `data: { path: <deletedPath> }`.
- *
- * Determinism: `deletedPaths` and `newPaths` are iterated in lex-asc
- * order so the same input always produces the same matches —
- * required for reproducible tests and conformance fixtures (the spec
- * does not prescribe an order, but stability is the obvious contract).
+ * 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.
  */
-declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], issues: Issue[]): RenameOp[];
+
 /**
  * Spec § A.8 — produce the merged read-time view of a Node.
  *
@@ -3170,9 +3266,11 @@ interface StoragePort {
         load(): Promise<ScanResult>;
         /**
          * Spec § A.9 — fine-grained extractor-runs cache breadcrumbs.
-         * Returns `Map<nodePath, Map<qualifiedExtractorId, bodyHashAtRun>>`.
+         * Returns `Map<nodePath, Map<qualifiedExtractorId, IPriorExtractorRun>>`.
+         * Inner value carries `bodyHash` AND `sidecarAnnotationsHash`; both
+         * participate in the cache hit condition for every Extractor.
          */
-        loadExtractorRuns(): Promise<Map<string, Map<string, string>>>;
+        loadExtractorRuns(): Promise<Map<string, Map<string, IPriorExtractorRun>>>;
         /** Universal enrichment layer — every persisted `(node, extractor)` pair. */
         loadNodeEnrichments(): Promise<IPersistedEnrichment[]>;
         /**
@@ -3190,9 +3288,10 @@ interface StoragePort {
     };
     /**
      * Phase 3 / View contribution system — read access to
-     * `scan_contributions`. Writes happen exclusively via
-     * `scans.persist({ contributions })` to keep the replace-all
-     * semantics intact; this namespace is read-only.
+     * `scan_contributions`, plus the targeted purge used by
+     * `sm plugins disable` to clear stale rows immediately at toggle time.
+     * Bulk writes still happen exclusively via
+     * `scans.persist({ contributions })` (replace-all semantics).
      */
     contributions: {
         /** Every contribution row for a single node. Stable order. */
@@ -3208,6 +3307,13 @@ interface StoragePort {
          * `GET /api/contributions/:pluginId/:contributionId?path=...`.
          */
         lookup(pluginId: string, contributionId: string, nodePath: string, extensionId?: string): Promise<IPersistedContribution[]>;
+        /**
+         * Drop rows for a plugin (optionally narrowed to a single
+         * extension within the bundle). Returns the number of deleted
+         * rows. Called by `sm plugins disable` so the UI stops rendering
+         * the disabled plugin's chips before the next scan.
+         */
+        purgeByPlugin(pluginId: string, extensionId?: string): Promise<number>;
     };
     /**
      * Read-only access to `scan_node_tags`. Writes happen exclusively