@skill-map/cli 0.20.1 → 0.21.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`.
@@ -1191,6 +1191,67 @@ 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;
+}
+
 /**
  * Provider runtime contract. Walks filesystem roots and emits raw node
  * records; classification maps path conventions to a node kind.
@@ -2266,7 +2327,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 +2339,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
@@ -2345,6 +2407,14 @@ interface IExtractorRunRecord {
     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.
@@ -3170,9 +3240,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 +3262,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 +3281,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