@skill-map/cli 0.17.0 → 0.19.0

package/dist/kernel/index.d.ts

@@ -8,7 +8,7 @@
  *
  * --- Naming convention (kernel-wide) -------------------------------------
  *
- * Four categories with distinct prefix rules; the rules are deliberate
+ * Five categories with distinct prefix rules; the rules are deliberate
  * even though they look mixed at first read:
  *
  *   1. **Domain types** — every shape that mirrors a `spec/schemas/*.json`
@@ -31,13 +31,22 @@
  *      reading as the rest of TypeScript's plugin ecosystems where a
  *      shape is implementable.
  *
- *   4. **Internal shapes** — option bags, result records, config
- *      slices, anything passed across function boundaries inside the
- *      kernel / CLI but not part of the spec: `IRunScanOptions` (well,
- *      `RunScanOptions` — see below), `IPluginRuntimeBundle`,
- *      `IPruneResult`, `IMigrationFile`, `IDbLocationOptions`. **`I`
- *      prefix.** The prefix matches category 3 because both are
- *      "shapes that live in TypeScript only, never in JSON".
+ *   4. **Internal interfaces** — option bags, result records, config
+ *      slices, anything declared as `interface` and passed across
+ *      function boundaries inside the kernel / CLI but not part of the
+ *      spec: `IPluginRuntimeBundle`, `IPruneResult`, `IMigrationFile`,
+ *      `IDbLocationOptions`. **`I` prefix.** The prefix matches
+ *      category 3 because both are "shapes that live in TypeScript
+ *      only, never in JSON".
+ *
+ *   5. **Internal type aliases** — anything declared as `type` (string-
+ *      literal unions, function types, mapped/derived types) that lives
+ *      only in TS: `TLogLevel`, `TLogMethodLevel`, `TProgressListener`,
+ *      `TLogFormatter`, `TActionWrite`, `TExecutionMode`, `TGranularity`,
+ *      `THookFilter`, `THookTrigger`, `TNodeChangeReason`,
+ *      `TPluginLoadStatus`, `TPluginStorage`, `TWatchEventKind`. **`T`
+ *      prefix.** Use this bucket when `interface` is the wrong shape
+ *      (a union, a callback signature, an `Exclude<…>` derivation).
  *
  * Edge cases worth knowing:
  *   - The following category-4 names lack the `I` prefix because
@@ -46,15 +55,16 @@
  *       option bags / records: `RunScanOptions`, `RenameOp`;
  *       TS-only exports from `kernel/index.ts` / `kernel/ports/*`:
  *         `Kernel`, `ProgressEvent`, `LogRecord`, `NodeStat`.
- *     New public option bags and TS-only exports MUST still use
- *     `I*`; removing a name from this list is a breaking change.
+ *     New public option bags MUST still use `I*`; new public type
+ *     aliases MUST still use `T*`. Removing a name from this list is a
+ *     breaking change.
  *   - `IDatabase` (SQLite schema) is category 4 but lives in
  *     `adapters/sqlite/schema.ts`, not here. Same rule applies.
  *
  * If you find yourself wanting to add a new type and aren't sure which
  * bucket it falls in: ask "does this shape exist in the spec?". If
- * yes, no prefix and align the name with the schema. If no, `I`
- * prefix.
+ * yes, no prefix and align the name with the schema. If no, `I` prefix
+ * for `interface`, `T` prefix for `type` aliases.
  */
 /**
  * The four node kinds the **built-in Claude Provider** declares — `skill`,
@@ -70,8 +80,12 @@
  * Step 9.5 dropped `hook` from the catalog: `.claude/hooks/*.md` is NOT
  * an Anthropic-defined node type — hooks live in `settings.json` or as
  * sub-objects of agent / skill frontmatter (see
- * https://code.claude.com/docs/en/hooks.md). Files at the old path now
- * classify as `note` via the Provider's fallback.
+ * https://code.claude.com/docs/en/hooks.md). Files at the old path
+ * classify as `markdown` via the Provider's fallback. The fallback is
+ * named after the *format* because the file is generic markdown with
+ * no specific role; format-named kinds apply only as the generic
+ * fallback — a file that matches a specific role (agent / command /
+ * skill) classifies under that role, not under `markdown`.
  *
  * This alias survives because:
  *   - claude-specific code legitimately wants to switch on the four
@@ -85,7 +99,7 @@
  * For "any kind a Provider could declare", use plain `string`. Only use
  * `NodeKind` when the code is intentionally claude-catalog-specific.
  */
-type NodeKind = 'skill' | 'agent' | 'command' | 'note';
+type NodeKind = 'skill' | 'agent' | 'command' | 'markdown';
 type LinkKind = 'invokes' | 'references' | 'mentions' | 'supersedes';
 type Confidence = 'high' | 'medium' | 'low';
 type Severity = 'error' | 'warn' | 'info';
@@ -137,13 +151,58 @@ interface Node {
     linksOutCount: number;
     linksInCount: number;
     externalRefsCount: number;
-    title?: string | null;
-    description?: string | null;
-    stability?: Stability | null;
-    version?: string | null;
-    author?: string | null;
     frontmatter?: Record<string, unknown>;
     tokens?: TripleSplit;
+    /**
+     * Step 9.6.2 — sidecar denormalisation surface. Populated by the
+     * orchestrator at scan time; absent when the orchestrator did not
+     * inspect sidecars (legacy code paths) or when no sidecar accompanies
+     * the node. Read by `annotation-stale` rule and the persistence layer.
+     */
+    sidecar?: ISidecarOverlay | null;
+    /**
+     * Per-user "favorite" flag, decorated by the BFF on `/api/nodes` and
+     * `/api/nodes/:pathB64` responses via in-memory `Set` lookup against
+     * `state_node_favorites`. Absent on emissions that don't carry per-user
+     * state (e.g. `sm export --json`); consumers that don't recognise the
+     * field MUST treat the absence as "unknown" rather than "false" — a
+     * truthy `isFavorite` only ever lands when the BFF set it.
+     */
+    isFavorite?: boolean;
+}
+/**
+ * Drift status of a co-located `.sm` sidecar relative to the live
+ * node hashes. Mirrors `TSidecarStatus` on the SQLite schema.
+ */
+type SidecarStatus = 'fresh' | 'stale-body' | 'stale-frontmatter' | 'stale-both';
+/**
+ * Sidecar overlay attached to a `Node` after the orchestrator parses
+ * `<basename>.sm`. `present === false` is the empty overlay (no
+ * sidecar accompanies the node); the other fields are absent or null
+ * in that case. When `present === true` and parse + validation
+ * succeeded, `status` carries the drift state and `annotations` carries
+ * the parsed (typed) `annotations:` block.
+ */
+interface ISidecarOverlay {
+    present: boolean;
+    status?: SidecarStatus | null;
+    /**
+     * Parsed `annotations:` block. Untyped object — schema lives in
+     * `spec/schemas/annotations.schema.json`. Null when no sidecar or
+     * the block is empty/absent.
+     */
+    annotations?: Record<string, unknown> | null;
+    /**
+     * R15 closure (2026-05-07) — full parsed YAML root of the sidecar
+     * (the entire `.sm` payload, mirroring `sidecar.schema.json`). Surfaced
+     * so the UI inspector can render `for:`, `audit:`, `settings:`, and
+     * `<plugin-id>:` namespace blocks without re-reading the file. NULL
+     * when no sidecar is present, or when the sidecar exists but failed
+     * to parse / validate. The `annotations` field above stays — it
+     * duplicates `root.annotations` intentionally so existing consumers
+     * keep working unchanged.
+     */
+    root?: Record<string, unknown> | null;
 }
 interface Link {
     /** The originating node — the path of the file the extractor was reading
@@ -186,8 +245,8 @@ interface ScanStats {
     /**
      * Files walked but not classified by any Provider. Today every walked
      * file is classified by its Provider (the `claude` Provider falls back to
-     * `'note'`), so this is always 0; the field will matter once multiple
-     * Providers can claim the same file.
+     * `'markdown'`), so this is always 0; the field will matter once
+     * multiple Providers can claim the same file.
      */
     filesSkipped: number;
     nodesCount: number;
@@ -316,7 +375,7 @@ interface ScanResult {
  * and each kind's code carries its own fuller type where needed.
  *
  * **Spec § A.6 — qualified ids.** Every extension is keyed in the registry
- * by `<pluginId>/<id>` (e.g. `core/frontmatter`, `claude/slash`,
+ * by `<pluginId>/<id>` (e.g. `core/annotations`, `core/slash`,
  * `hello-world/greet`). `Extension.id` carries the **short** id as authored;
  * `Extension.pluginId` carries the namespace; the registry composes the
  * qualifier internally and exposes lookup APIs that operate on either form
@@ -369,6 +428,333 @@ declare class Registry {
     totalCount(): number;
 }
 
+/**
+ * Step 9.6.6 — runtime annotation-contribution catalog types.
+ *
+ * Lives in its own module (rather than `kernel/index.ts`) so consumers
+ * deep inside the kernel — `IRuleContext`, the BFF route factories,
+ * future Action contexts — can depend on the catalog shape without
+ * dragging the whole kernel barrel and risking a cycle.
+ */
+/**
+ * Single row of the runtime annotation-contribution catalog surfaced by
+ * `kernel.getRegisteredAnnotationKeys()`. One row per (plugin × key)
+ * tuple. Built-in catalog keys from `annotations.schema.json` are NOT
+ * included — this catalog is plugin-only; the UI knows the built-in
+ * catalog via the schema bundle.
+ */
+interface IRegisteredAnnotationKey {
+    pluginId: string;
+    key: string;
+    location: 'namespaced' | 'root';
+    ownership: 'exclusive' | 'shared';
+    /** Inline JSON Schema as declared in the manifest (not the AJV compiled validator). */
+    schema: Record<string, unknown>;
+}
+
+/**
+ * Step 11.x — runtime view-contribution catalog types.
+ *
+ * Lives in its own module (rather than `kernel/index.ts`) so consumers
+ * deep inside the kernel — `IRuleContext`, the BFF route factories,
+ * future Action contexts — can depend on the catalog shape without
+ * dragging the whole kernel barrel and risking a cycle.
+ *
+ * Mirrors `annotation-catalog.ts` for the annotation contribution side
+ * (Step 9.6.6). The two systems share the "plugin contributes data,
+ * kernel exposes catalog, UI renders" pattern but never overlap in
+ * storage or routing — see `architecture.md` §View contribution system
+ * for the comparison table.
+ *
+ * **Closed catalog by design.** Both `TContractName` and `TInputTypeName`
+ * mirror the closed enums in `spec/schemas/view-contracts.schema.json`
+ * and `spec/schemas/input-types.schema.json`. Adding a member is a
+ * coordinated kernel + spec + UI + scaffolder change. The closed-enum
+ * shape lets TypeScript surface unknown contracts at author time
+ * (in plugin authors' editors when their plugin imports `@skill-map/cli`)
+ * AND lets the runtime exhaustively dispatch contract → renderer in the
+ * UI without `default:` fallbacks.
+ */
+/**
+ * Closed enum of view contract names. Mirror of
+ * `spec/schemas/view-contracts.schema.json#/$defs/ContractName`.
+ *
+ * Plugins pick one of these by name in their extension manifest's
+ * `viewContributions[<contributionId>].contract` field. The kernel
+ * validates each pick at load time (`invalid-manifest` on miss); the
+ * UI maps each contract to one or more slots and a renderer.
+ */
+type TContractName = 'node-counter' | 'node-tag' | 'node-breakdown' | 'node-records' | 'node-tree' | 'node-key-values' | 'node-link-list' | 'node-markdown' | 'node-alert' | 'scope-stat';
+/**
+ * Closed enum of input-type names for plugin settings. Mirror of
+ * `spec/schemas/input-types.schema.json#/$defs/InputTypeName`.
+ *
+ * Plugins pick one of these by name in their plugin manifest's
+ * `settings[<settingId>].type` field. The kernel exposes the resolved
+ * value via `ctx.settings.<settingId>` typed per the input-type's
+ * value-type promise.
+ */
+type TInputTypeName = 'string-list' | 'single-string' | 'boolean-flag' | 'integer' | 'enum-pick' | 'enum-multipick' | 'path-glob' | 'regex' | 'secret' | 'key-value-list';
+/** Closed severity palette aligned with PrimeNG `<p-tag>` / `<p-message>`. */
+type TSeverity = 'info' | 'warn' | 'success' | 'danger';
+/**
+ * Manifest-side declaration of a single view contribution. The plugin
+ * author writes one of these per Record key in
+ * `IExtensionBase.viewContributions[<contributionId>]`.
+ *
+ * Mirror of `view-contracts.schema.json#/$defs/IViewContribution`.
+ */
+interface IViewContribution {
+    /**
+     * Required. Closed-catalog contract name. Unknown name rejects the
+     * extension as `invalid-manifest` at load.
+     */
+    contract: TContractName;
+    /**
+     * Optional human-readable label. English-only per `AGENTS.md`
+     * (`Externalized texts, not internationalized`).
+     */
+    label?: string;
+    /** Optional hover tooltip. English-only. */
+    tooltip?: string;
+    /**
+     * Optional emoji codepoint OR PrimeIcons class id (without the
+     * `pi-` prefix). The UI discriminates: matches Unicode
+     * `\p{Extended_Pictographic}` → emoji text, otherwise → PrimeIcon.
+     */
+    icon?: string;
+    /**
+     * Optional empty placeholder text shown when the payload is empty
+     * AND `emitWhenEmpty` is true. Falls back to a UI-supplied generic
+     * 'No data.' string. English-only.
+     */
+    emptyText?: string;
+    /**
+     * When false (default), the kernel drops emissions whose payload is
+     * structurally empty so the slot stays silent. When true, the
+     * renderer surfaces an empty placeholder. Per-contract definition
+     * of "empty" lives in the contract's payload schema.
+     */
+    emitWhenEmpty?: boolean;
+    /**
+     * Optional ordering hint (default 100). Slots configured with
+     * `order: 'priority'` sort contributions ASC by this value, with
+     * alphabetical tie-break by qualified id. The plugin uses this to
+     * suggest where its contribution belongs relative to others sharing
+     * the same slot — the slot has the final say.
+     */
+    priority?: number;
+}
+/**
+ * Single row of the runtime view-contribution catalog surfaced by
+ * `kernel.getRegisteredViewContributions()`. One row per
+ * `(pluginId × extensionId × contributionId)` tuple. Composed at boot
+ * by `loadPluginRuntime` from every loaded extension's
+ * `viewContributions` map.
+ *
+ * The qualified id is `<pluginId>/<extensionId>/<contributionId>` —
+ * matches the qualified id pattern used elsewhere in the kernel
+ * (`<pluginId>/<extensionId>` for extensions; this adds the third
+ * segment for per-contribution identity).
+ */
+interface IRegisteredViewContribution {
+    pluginId: string;
+    extensionId: string;
+    contributionId: string;
+    contract: TContractName;
+    /** Optional manifest-declared label (English-only). */
+    label?: string;
+    tooltip?: string;
+    icon?: string;
+    emptyText?: string;
+    emitWhenEmpty: boolean;
+    /** Manifest-declared ordering hint (default 100). See `IViewContribution.priority`. */
+    priority?: number;
+}
+/**
+ * Common fields on every setting declaration. The discriminated union
+ * `ISettingDeclaration` extends one of these per `type` value.
+ */
+interface ISettingCommon {
+    /** Required. Short human-readable label. English-only. */
+    label: string;
+    /** Optional helper text shown below the control. English-only. */
+    description?: string;
+}
+interface ISetting_StringList extends ISettingCommon {
+    type: 'string-list';
+    default?: string[];
+    min?: number;
+    max?: number;
+    itemMaxLength?: number;
+}
+interface ISetting_SingleString extends ISettingCommon {
+    type: 'single-string';
+    default?: string;
+    minLength?: number;
+    maxLength?: number;
+    /** Optional ECMAScript regex pattern (no flags). */
+    pattern?: string;
+}
+interface ISetting_BooleanFlag extends ISettingCommon {
+    type: 'boolean-flag';
+    default?: boolean;
+}
+interface ISetting_Integer extends ISettingCommon {
+    type: 'integer';
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+interface ISetting_EnumOption {
+    value: string;
+    label: string;
+}
+interface ISetting_EnumPick extends ISettingCommon {
+    type: 'enum-pick';
+    options: ISetting_EnumOption[];
+    default?: string;
+}
+interface ISetting_EnumMultipick extends ISettingCommon {
+    type: 'enum-multipick';
+    options: ISetting_EnumOption[];
+    default?: string[];
+    min?: number;
+    max?: number;
+}
+interface ISetting_PathGlob extends ISettingCommon {
+    type: 'path-glob';
+    default?: string;
+    /** When true, accepts string[]; when false (default), single string. */
+    multiple?: boolean;
+}
+interface ISetting_Regex extends ISettingCommon {
+    type: 'regex';
+    default?: string;
+    /** Subset of `gimsuy`. Default `''`. */
+    flags?: string;
+}
+interface ISetting_Secret extends ISettingCommon {
+    type: 'secret';
+    /**
+     * Optional uppercase-ASCII identifier. When set in the process
+     * environment, that value wins over any stored value (lets CI
+     * inject without writing to disk).
+     */
+    envVar?: string;
+}
+interface ISetting_KeyValueListEntry {
+    key: string;
+    value: string;
+}
+interface ISetting_KeyValueList extends ISettingCommon {
+    type: 'key-value-list';
+    keyLabel?: string;
+    valueLabel?: string;
+    default?: ISetting_KeyValueListEntry[];
+    min?: number;
+    max?: number;
+}
+/**
+ * Discriminated union of every setting declaration shape. The plugin
+ * author NEVER writes JSON Schema for settings — they pick one of
+ * these `type` values and supply per-type parameters.
+ *
+ * Mirror of `input-types.schema.json#/$defs/ISettingDeclaration`.
+ */
+type ISettingDeclaration = ISetting_StringList | ISetting_SingleString | ISetting_BooleanFlag | ISetting_Integer | ISetting_EnumPick | ISetting_EnumMultipick | ISetting_PathGlob | ISetting_Regex | ISetting_Secret | ISetting_KeyValueList;
+/**
+ * Runtime value type for a setting, derived from its declaration. The
+ * kernel exposes settings to extractors as `Record<string, TSettingValue>`
+ * via `ctx.settings.<settingId>`; consumers that want narrow typing
+ * narrow at the call site by reading `manifest.settings[id].type`.
+ */
+type TSettingValue = string | string[] | boolean | number | ISetting_KeyValueListEntry[];
+
+/**
+ * Base manifest shape shared by every extension kind. Mirrors
+ * `spec/schemas/extensions/base.schema.json` at the TypeScript level.
+ *
+ * Spec § A.6 — every extension is identified in the registry by the
+ * qualified id `<pluginId>/<id>`. The `pluginId` field is required at the
+ * runtime / TS level: built-ins declare it directly in
+ * `src/extensions/built-ins.ts`; user plugins have it injected by the
+ * `PluginLoader` from `plugin.json#/id` before the extension reaches the
+ * registry. A plugin author who hand-codes a `pluginId` that disagrees
+ * with the manifest's `id` is rejected as `invalid-manifest`.
+ *
+ * The JSON Schema deliberately does NOT model `pluginId` — the qualifier
+ * is a runtime concern composed by the loader, not a manifest field
+ * authors are expected to set. Stripping it before AJV validation in
+ * the loader keeps the spec contract clean ("authors declare only the
+ * short id").
+ */
+
+/**
+ * Step 9.6.6 — single entry of an extension's `annotationContributions`
+ * map. Mirrors `spec/schemas/extensions/base.schema.json#/properties/annotationContributions/additionalProperties`.
+ *
+ * `schema` is an INLINE JSON Schema (object literal in the manifest),
+ * not a `$ref` to a file. The kernel compiles it at load time; an
+ * invalid schema rejects the extension as `invalid-manifest`.
+ */
+interface IAnnotationContribution {
+    /** Inline JSON Schema describing the value written under this key. */
+    schema: Record<string, unknown>;
+    /**
+     * Conflict policy. `shared` (default) — multiple plugins MAY write
+     * the key; `exclusive` — only this plugin may. REQUIRED to be
+     * `'exclusive'` when `location: 'root'`.
+     */
+    ownership?: 'exclusive' | 'shared';
+    /**
+     * Where the key lands. `namespaced` (default) — under the plugin's
+     * `<plugin-id>:` block; `root` — top-level, alongside `for` /
+     * `annotations` / `settings` / `audit`. Cross-plugin root-key
+     * collisions on `exclusive` are a fatal startup error.
+     */
+    location?: 'namespaced' | 'root';
+}
+interface IExtensionBase {
+    id: string;
+    /**
+     * Owning plugin namespace. Composed with `id` to produce the
+     * qualified registry key `<pluginId>/<id>`. Built-ins declare this
+     * directly; user plugins have it injected by the `PluginLoader`
+     * from `plugin.json#/id`.
+     */
+    pluginId: string;
+    version: string;
+    description?: string;
+    stability?: Stability;
+    preconditions?: string[];
+    entry?: string;
+    /**
+     * Step 9.6.6 — plugin-contributed annotation keys. Each entry maps a
+     * key name to an inline JSON Schema + ownership + location triple.
+     * The kernel surfaces the aggregate via `kernel.getRegisteredAnnotationKeys()`.
+     * See `IAnnotationContribution` for the field semantics and
+     * `plugin-author-guide.md` §Annotation contributions for examples.
+     */
+    annotationContributions?: Record<string, IAnnotationContribution>;
+    /**
+     * Plugin-contributed view contributions. Each entry maps a local
+     * contribution id (kebab-case, unique within the extension) to a
+     * `IViewContribution` declaration that picks a view contract by name
+     * from the closed kernel catalog (`view-catalog.ts#TContractName`).
+     * The kernel validates each `contract` pick at load time
+     * (`invalid-manifest` on miss); the plugin emits per-node payloads
+     * via `ctx.emitContribution(<contributionId>, payload)` during scan;
+     * the runtime validates payloads against the contract's payload
+     * schema. The aggregate runtime catalog is exposed via
+     * `kernel.getRegisteredViewContributions()`. The plugin author
+     * NEVER picks a UI slot — slot mapping is owned by the UI driving
+     * adapter. See `architecture.md` §View contribution system.
+     */
+    viewContributions?: Record<string, IViewContribution>;
+}
+
 /**
  * `.skillmapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
  * with the project-local layering: bundled defaults → `config.ignore`
@@ -412,10 +798,10 @@ interface ProgressEvent {
     jobId?: string;
     data?: unknown;
 }
-type ProgressListener = (event: ProgressEvent) => void;
+type TProgressListener = (event: ProgressEvent) => void;
 interface ProgressEmitterPort {
     emit(event: ProgressEvent): void;
-    subscribe(listener: ProgressListener): () => void;
+    subscribe(listener: TProgressListener): () => void;
 }
 
 /**
@@ -481,6 +867,16 @@ interface IPluginManifest {
     id: string;
     version: string;
     specCompat: string;
+    /**
+     * Optional semver range against the kernel's view-contracts +
+     * input-types catalog version. Independent from `specCompat` because
+     * the catalog evolves on its own cadence (see `architecture.md`
+     * §View contribution system → Catalog versioning). Mismatch surfaces
+     * as `incompatible-catalog`. Absent = the plugin opts out of catalog
+     * checking; `sm plugins doctor` warns if such a plugin actually
+     * declares `viewContributions` or `settings`.
+     */
+    catalogCompat?: string;
     extensions: string[];
     description?: string;
     storage?: TPluginStorage;
@@ -490,6 +886,18 @@ interface IPluginManifest {
      * the default.
      */
     granularity?: TGranularity;
+    /**
+     * Plugin user-configurable settings. Each entry picks an `input-type`
+     * from the closed catalog at
+     * `spec/schemas/input-types.schema.json#/$defs/InputTypeName`.
+     * The plugin author NEVER writes JSON Schema — they pick `type` by
+     * name and supply per-type parameters. The kernel exposes resolved
+     * settings to extractors via `ctx.settings.<settingId>`; settings
+     * are read once at extractor invocation; changing a setting requires
+     * `sm scan` to re-emit. See `architecture.md` §View contribution
+     * system → Settings.
+     */
+    settings?: Record<string, ISettingDeclaration>;
     author?: string;
     license?: string;
     homepage?: string;
@@ -530,7 +938,7 @@ interface IPluginManifest {
  *                           precedence rule applies. The user resolves
  *                           by renaming one of them and rerunning.
  */
-type TPluginLoadStatus = 'enabled' | 'disabled' | 'incompatible-spec' | 'invalid-manifest' | 'load-error' | 'id-collision';
+type TPluginLoadStatus = 'enabled' | 'disabled' | 'incompatible-spec' | 'incompatible-catalog' | 'invalid-manifest' | 'load-error' | 'id-collision';
 interface ILoadedExtension {
     kind: ExtensionKind;
     id: string;
@@ -723,38 +1131,60 @@ declare function makePluginStore(opts: {
 }): IPluginStore | undefined;
 
 /**
- * Base manifest shape shared by every extension kind. Mirrors
- * `spec/schemas/extensions/base.schema.json` at the TypeScript level.
+ * `scan_contributions` adapter — replace-all writer used by
+ * `persistScanResult`, plus read helpers consumed by the BFF
+ * (`/api/contributions/...`) and rules (`core/contribution-orphan`).
  *
- * Spec § A.6 — every extension is identified in the registry by the
- * qualified id `<pluginId>/<id>`. The `pluginId` field is required at the
- * runtime / TS level: built-ins declare it directly in
- * `src/extensions/built-ins.ts`; user plugins have it injected by the
- * `PluginLoader` from `plugin.json#/id` before the extension reaches the
- * registry. A plugin author who hand-codes a `pluginId` that disagrees
- * with the manifest's `id` is rejected as `invalid-manifest`.
+ * 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 JSON Schema deliberately does NOT model `pluginId` — the qualifier
- * is a runtime concern composed by the loader, not a manifest field
- * authors are expected to set. Stripping it before AJV validation in
- * the loader keeps the spec contract clean ("authors declare only the
- * short id").
+ * 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).
  */
 
-interface IExtensionBase {
-    id: string;
+/**
+ * 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 contract's payload schema happens at emit time (orchestrator);
+ * by the time records reach this adapter they are wire-shape clean.
+ */
+interface IContributionRecord {
+    pluginId: string;
+    extensionId: string;
+    nodePath: string;
+    contributionId: string;
     /**
-     * Owning plugin namespace. Composed with `id` to produce the
-     * qualified registry key `<pluginId>/<id>`. Built-ins declare this
-     * directly; user plugins have it injected by the `PluginLoader`
-     * from `plugin.json#/id`.
+     * Closed enum value mirroring `view-contracts.schema.json#/$defs/ContractName`.
+     * Persisted as TEXT (no SQL CHECK by design — see migration comment).
      */
+    contract: string;
+    /** Already-validated payload. Serialised via `JSON.stringify` at write. */
+    payload: unknown;
+    emittedAt: number;
+}
+/**
+ * Single contribution row as returned to callers. The payload is
+ * `unknown` because the contract space is open at the type layer
+ * (catalog evolution is a kernel + spec concern); narrow at the call
+ * site by reading `contract`.
+ */
+interface IPersistedContribution {
     pluginId: string;
-    version: string;
-    description?: string;
-    stability?: Stability;
-    preconditions?: string[];
-    entry?: string;
+    extensionId: string;
+    nodePath: string;
+    contributionId: string;
+    contract: string;
+    payload: unknown;
+    emittedAt: number;
 }
 
 /**
@@ -882,7 +1312,7 @@ interface IProviderKindUi {
      * `emoji`; when both are absent, the UI falls back to the first
      * letter of `label` colored with `color`.
      */
-    icon?: IProviderKindIcon;
+    icon?: TProviderKindIcon;
 }
 /**
  * Discriminated icon contract. `pi` references a PrimeIcons identifier
@@ -891,7 +1321,7 @@ interface IProviderKindUi {
  * `currentColor`. The discriminator (`kind`) keeps the UI dispatch
  * exhaustive without string-sniffing the payload.
  */
-type IProviderKindIcon = {
+type TProviderKindIcon = {
     kind: 'pi';
     id: string;
 } | {
@@ -942,6 +1372,30 @@ interface IProvider extends IExtensionBase {
      * concern of how the runtime composes those.
      */
     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
@@ -952,22 +1406,52 @@ interface IProvider extends IExtensionBase {
      * 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?: {
+    walk?(roots: string[], options?: {
         ignoreFilter?: IIgnoreFilter;
     }): AsyncIterable<IRawNode>;
     /**
-     * Given a path and its parsed frontmatter, decide the node kind. The
-     * classifier is called after walk() yields — Providers MAY embed the
-     * logic inside walk itself, but exposing it lets the kernel rebuild
-     * classification during partial scans without re-walking.
+     * 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.
      *
-     * Returns an open `string`. The returned value MUST be a key of the
-     * Provider's own `kinds` catalog; the orchestrator does not validate
-     * the kind against `NodeKind`. External Providers (Cursor, Obsidian,
-     * …) freely return their own kinds (e.g. `'cursorRule'`, `'daily'`).
+     * 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;
+}
+/**
+ * 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 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`.
      */
-    classify(path: string, frontmatter: Record<string, unknown>): string;
+    parser: string;
 }
 
 /**
@@ -976,6 +1460,11 @@ interface IProvider extends IExtensionBase {
  * 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):
  *
  *   - `ctx.emitLink(link)` — persist a link in the kernel's `links` table.
@@ -983,14 +1472,12 @@ interface IProvider extends IExtensionBase {
  *     kind drops the link and surfaces an `extension.error` event.
  *   - `ctx.enrichNode(partial)` — merge canonical, kernel-curated properties
  *     onto the node. Strictly separate from the author-supplied frontmatter
- *     (the latter remains immutable and survives verbatim). Persistence and
- *     stale-tracking are spec'd in § A.8.
+ *     (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.
- *   - `ctx.runner` — `RunnerPort` injection for `probabilistic` extractors.
- *     `undefined` for the default `deterministic` mode.
  *
  * The manifest's `scope` field tells the orchestrator which parts to feed:
  * `frontmatter` extractors receive an empty string for body and vice versa.
@@ -1021,6 +1508,21 @@ interface IExtractorCallbacks {
      * 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 contract's payload schema in
+     * `spec/schemas/view-contracts.schema.json#/$defs/payloads/<contract>`.
+     * The orchestrator validates the payload against the contract schema
+     * before persisting to `scan_contributions`; off-contract 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;
@@ -1041,33 +1543,17 @@ interface IExtractorContext extends IExtractorCallbacks {
      * it here.
      */
     store?: unknown;
-    /**
-     * `RunnerPort` injection for `probabilistic` extractors. `undefined`
-     * for `deterministic` mode (the default). The kernel rejects
-     * probabilistic extractors that try to register scan-time hooks at
-     * load time.
-     */
-    runner?: unknown;
 }
 interface IExtractor extends IExtensionBase {
     kind: 'extractor';
-    /**
-     * Execution mode. Optional in the manifest with a default of
-     * `deterministic` per `spec/schemas/extensions/extractor.schema.json`.
-     * `probabilistic` extractors invoke an LLM through the kernel's
-     * `RunnerPort` and never participate in scan-time pipelines —
-     * they dispatch only as queued jobs.
-     */
-    mode?: TExecutionMode;
     emitsLinkKinds: LinkKind[];
     defaultConfidence: Confidence;
     scope: 'frontmatter' | 'body' | 'both';
     /**
      * Optional opt-in filter on `node.kind`. When declared, the orchestrator
      * skips invocation of `extract()` for any node whose `kind` is NOT in
-     * this list — fail-fast, before context construction, so a
-     * probabilistic extractor wastes zero LLM cost on inapplicable nodes
-     * and a deterministic extractor wastes zero CPU.
+     * 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
@@ -1099,9 +1585,76 @@ interface IExtractor extends IExtensionBase {
  * `deterministic`).
  */
 
+/**
+ * Step 9.6.2 — orphan sidecar entry surfaced to rules. A `.sm` file
+ * whose sibling `.md` does not exist on disk; the `annotation-orphan`
+ * built-in rule emits one warning per entry. Other rules that care
+ * about orphan sidecars MAY consume the list too.
+ */
+interface IRuleOrphanSidecar {
+    /** Relative path (POSIX-separated) of the orphan `.sm`. */
+    relativePath: string;
+    /** Absolute path of the missing `.md` the sidecar was anchored to. */
+    expectedMdPath: string;
+}
 interface IRuleContext {
     nodes: Node[];
     links: Link[];
+    /**
+     * 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.
+     */
+    orphanSidecars?: IRuleOrphanSidecar[];
+    /**
+     * Step 9.6.6 — raw parsed sidecar root keyed by `node.path`. Populated
+     * by the orchestrator alongside the public `Node.sidecar` overlay so
+     * rules that inspect plugin namespaces (e.g. the built-in
+     * `core/unknown-field` Rule) 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.
+     */
+    sidecarRoots?: ReadonlyMap<string, Record<string, unknown>>;
+    /**
+     * Step 9.6.6 — runtime catalog of plugin-contributed annotation keys,
+     * as exposed by `kernel.getRegisteredAnnotationKeys()`. Threaded
+     * through so rules 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).
+     */
+    annotationContributions?: readonly IRegisteredAnnotationKey[];
+    /**
+     * Step 11.x — runtime catalog of plugin-contributed view contributions,
+     * as exposed by `kernel.getRegisteredViewContributions()`. Threaded
+     * through so rules can reason about emissions without reaching back
+     * into the kernel: built-in `core/unknown-contract` walks this list to
+     * detect deprecated contracts in use, and `core/contribution-orphan`
+     * joins it with the live node set to flag dangling emissions. Empty
+     * array when no extension declares view contributions; absent for
+     * legacy callers (older runScan sites that never wired the catalog
+     * through).
+     */
+    viewContributions?: readonly IRegisteredViewContribution[];
+    /**
+     * Emit a per-node view contribution declared in this rule's manifest
+     * `viewContributions` map. Sync, void return; the orchestrator
+     * validates the payload against the contract 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), Rule's `evaluate()`
+     * sees the full graph at once. The rule 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 IRule extends IExtensionBase {
     kind: 'rule';
@@ -1156,6 +1709,58 @@ interface IRule extends IExtensionBase {
  *   - `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;
+}
 /**
  * Declarative filter applied by `--all` fan-out, UI button gating, and
  * `sm actions show`. All fields optional — an empty precondition matches
@@ -1225,6 +1830,26 @@ interface IAction extends IExtensionBase {
      * full list. Batch actions tend to hit context limits; use sparingly.
      */
     fanOutPolicy?: 'per-node' | 'batch';
+    /**
+     * 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`.
+     *
+     * 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.
+     *
+     * `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.
+     */
+    invoke?: <TInput, TReport>(input: TInput, ctx: IActionContext) => IActionResult<TReport>;
 }
 
 /**
@@ -1499,6 +2124,31 @@ interface RunScanOptions {
     emitter?: ProgressEmitterPort;
     /** Runtime extension instances. Absent → empty pipeline. */
     extensions?: IScanExtensions;
+    /**
+     * 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.
+     */
+    annotationContributions?: readonly IRegisteredAnnotationKey[];
+    /**
+     * Runtime catalog of plugin-contributed view contributions (the same
+     * shape `kernel.getRegisteredViewContributions()` returns). Threaded
+     * into the rule pass so:
+     *   - `core/unknown-contract` and `core/contribution-orphan` can
+     *     introspect the catalog (read-only).
+     *   - The orchestrator's per-rule emit closure can look up each
+     *     declared `(contributionId → contract)` 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.
+     */
+    viewContributions?: readonly IRegisteredViewContribution[];
     /**
      * Scan scope. Defaults to `'project'`. The CLI flag wiring lands in
      * the config layer wiring; `runScan` already accepts the override
@@ -1618,8 +2268,6 @@ interface IExtractorRunRecord {
  *
  *   - upsert a single row per pair (stable PRIMARY KEY conflict on
  *     re-extract);
- *   - flag probabilistic rows `stale = 1` when the body changes between
- *     scans (preserving the prior LLM cost);
  *   - feed `mergeNodeWithEnrichments` with `enrichedAt`-sorted partials
  *     for last-write-wins per field at read time.
  *
@@ -1629,10 +2277,12 @@ interface IExtractorRunRecord {
  * fold into a single row, but two different Extractors hitting the
  * same node yield two distinct rows.
  *
- * `isProbabilistic` is denormalised so the persistence layer's stale
- * flag query stays a single-table read; recomputing from the live
- * registry would force every read-path to thread the runtime extension
- * set through.
+ * `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;
@@ -1660,6 +2310,7 @@ declare function runScanWithRenames(_kernel: Kernel, options: RunScanOptions): P
     renameOps: RenameOp[];
     extractorRuns: IExtractorRunRecord[];
     enrichments: IEnrichmentRecord[];
+    contributions: IContributionRecord[];
 }>;
 declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
 /**
@@ -1696,6 +2347,7 @@ declare function runExtractorsForNode(opts: {
     internalLinks: Link[];
     externalLinks: Link[];
     enrichments: IEnrichmentRecord[];
+    contributions: IContributionRecord[];
 }>;
 /**
  * Pure rename / orphan classification per `spec/db-schema.md` §Rename
@@ -1736,10 +2388,11 @@ declare function detectRenamesAndOrphans(prior: ScanResult, current: Node[], iss
  * Algorithm:
  *
  *   1. Filter `enrichments` down to rows targeting this node AND not
- *      flagged `stale`. Stale rows (probabilistic enrichments whose
- *      body changed since their last run) are excluded by default —
- *      stale visibility belongs to the UI layer where the marker is
- *      shown next to the value.
+ *      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
@@ -1792,7 +2445,7 @@ interface IPersistedEnrichment {
 declare class InMemoryProgressEmitter implements ProgressEmitterPort {
     #private;
     emit(event: ProgressEvent): void;
-    subscribe(listener: ProgressListener): () => void;
+    subscribe(listener: TProgressListener): () => void;
 }
 
 /**
@@ -2033,6 +2686,72 @@ declare function applyExportQuery(scan: {
     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';
+}
+
+/**
+ * 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;
+}
+
 /**
  * `PluginLoaderPort` — discovers plugin directories and loads their
  * extensions. The shape mirrors what the concrete loader actually
@@ -2126,6 +2845,19 @@ interface IPersistOptions {
     renameOps?: RenameOp[];
     extractorRuns?: IExtractorRunRecord[];
     enrichments?: IEnrichmentRecord[];
+    contributions?: IContributionRecord[];
+    /**
+     * 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).
+     */
+    registeredContributionKeys?: ReadonlySet<string>;
 }
 /**
  * Issue row as the storage layer sees it — paired with its DB-assigned
@@ -2181,16 +2913,18 @@ interface IMigrateNodeFksReport {
     summaries: number;
     enrichments: number;
     pluginKvs: number;
+    nodeFavorites: number;
     /**
-     * Composite-PK collisions encountered when migrating
-     * `state_summaries` / `state_enrichments` / `state_plugin_kvs` because
-     * a row already existed at the destination PK. The pre-existing rows
-     * are preserved — the migrating rows are dropped (deleted from
-     * `fromPath` without a corresponding INSERT). One entry per dropped
-     * row, with the affected PK fields included for diagnostic output.
+     * Collisions 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.
      */
     collisions: Array<{
-        table: 'state_summaries' | 'state_enrichments' | 'state_plugin_kvs';
+        table: 'state_summaries' | 'state_enrichments' | 'state_plugin_kvs' | 'state_node_favorites';
         fromPath: string;
         toPath: string;
         keys: Record<string, string>;
@@ -2264,28 +2998,6 @@ interface IPluginApplyResult {
     intrusions: string[];
 }
 
-/**
- * `StoragePort` — the kernel's persistence boundary. Driving adapters
- * (CLI, future server, in-memory test harness) consume this surface
- * exclusively; nothing in `cli/**` should reach into the SQLite
- * adapter's internal helpers (free functions on
- * `kernel/adapters/sqlite/*`) directly. Phase F of the
- * storage-port-promotion refactor finishes that hardening; A-E grow
- * the port enough that the CLI has somewhere to land.
- *
- * The port is namespaced by domain (`scans`, `issues`, `enrichments`,
- * etc.) — explicitly NOT a generic `port.query<T>(sql)`. Each
- * namespace's methods name an operation the kernel cares about; the
- * adapter translates to its persistence engine's idioms.
- *
- * Phase A lands the **scans / issues / enrichments / transaction**
- * namespaces — the core scan pipeline. The remaining namespaces
- * (history / jobs / pluginConfig / migrations / pluginMigrations)
- * arrive in subsequent phases. The port shape declared here is the
- * Phase A subset; later phases extend it without reshaping what
- * lands today.
- */
-
 /**
  * Subset of `StoragePort` exposed inside a `transaction(fn)` callback.
  * Lifecycle methods are intentionally omitted — a transaction that
@@ -2362,6 +3074,50 @@ interface StoragePort {
          */
         findNode(path: string): Promise<INodeBundle | null>;
     };
+    /**
+     * 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.
+     */
+    contributions: {
+        /** Every contribution row for a single node. Stable order. */
+        listForNode(nodePath: string): Promise<IPersistedContribution[]>;
+        /**
+         * Bulk variant for the BFF nodes-list route. Returns rows for
+         * every path in `paths`, sorted `nodePath` ASC, then qualified-id
+         * ASC. Empty `paths` returns `[]` without a query.
+         */
+        listForPaths(paths: readonly string[]): Promise<IPersistedContribution[]>;
+        /**
+         * Lookup by qualified id + path. Used by
+         * `GET /api/contributions/:pluginId/:contributionId?path=...`.
+         */
+        lookup(pluginId: string, contributionId: string, nodePath: string, extensionId?: string): Promise<IPersistedContribution[]>;
+    };
+    /**
+     * Read-only access to `scan_node_tags`. Writes happen exclusively
+     * via `scans.persist({...})` (the persistence layer projects from
+     * `node.frontmatter.tags` and `node.sidecar.annotations.tags`); this
+     * namespace is read-only.
+     */
+    tags: {
+        /** Every tag row for a single node. Author entries first, then user. */
+        listForNode(nodePath: string): Promise<ITagRecord[]>;
+        /**
+         * Bulk variant for the BFF nodes-list route. Returns rows for every
+         * path in `paths`, sorted `nodePath` ASC, then `source` ASC, then
+         * `tag` ASC. Empty `paths` returns `[]` without a query.
+         */
+        listForPaths(paths: readonly string[]): Promise<ITagRecord[]>;
+        /**
+         * Find every node carrying `tag`. Optional `source` narrows to one
+         * side of the dual surface (matches `sm list --tag <name>
+         * --tag-source author|user`); absent matches the union (default
+         * `sm list --tag`).
+         */
+        findNodes(tag: string, source?: 'author' | 'user'): Promise<string[]>;
+    };
     issues: {
         /** Every issue from the latest scan, in insertion order. */
         listAll(): Promise<Issue[]>;
@@ -2418,6 +3174,53 @@ interface StoragePort {
          */
         listReferencedFilePaths(): Promise<Set<string>>;
     };
+    /**
+     * Generic key/value preferences keyed by a stable string. Backs the
+     * `config_preferences` table — one row per `key`, `value_json` is a
+     * single JSON blob the caller serialises. Keys with the `_kernel.`
+     * prefix are reserved for kernel-managed entries (today: the
+     * update-check cache); user-set preferences land under unprefixed
+     * keys when those ship.
+     *
+     * Read-only by design at the port level — the only writer is the
+     * CLI's post-run hook (`cli/util/update-check-banner.ts`), which
+     * reaches the persistence helpers directly. The port surfaces the
+     * read so the BFF's `GET /api/update-status` projection can stay
+     * inside the abstract contract.
+     */
+    preferences: {
+        /**
+         * Load the update-check cache row. Returns `null` when the row
+         * is absent, malformed JSON, or fails the shape guard. Never
+         * throws — read failures degrade silently because the banner is
+         * a non-essential surface.
+         */
+        loadUpdateCheckCache(): Promise<IUpdateCheckCache | null>;
+        /**
+         * Upsert the update-check cache row. Always overwrites the
+         * existing JSON blob in place. `updated_at` tracks wall-clock
+         * now — separate from the embedded `checkedAt` field, which
+         * the caller controls.
+         */
+        saveUpdateCheckCache(cache: IUpdateCheckCache): Promise<void>;
+    };
+    favorites: {
+        /**
+         * Mark `path` as favorited. Idempotent — a second call refreshes
+         * `favoritedAt` but does not error. The path is FK-semantic to
+         * `scan_nodes.path`; the route layer is responsible for confirming
+         * the path exists in the live scan before calling.
+         */
+        set(path: string): Promise<void>;
+        /** Drop the favorite row for `path`. Idempotent — no-op when absent. */
+        unset(path: string): Promise<void>;
+        /**
+         * Load every favorited path as a `Set<string>` ready for `O(1)`
+         * membership checks. Used by the BFF's `/api/nodes` decorator —
+         * one query per request, no SQL JOIN against `scan_nodes`.
+         */
+        listPaths(): Promise<Set<string>>;
+    };
     history: {
         /** List `state_executions` rows (paginated by filter). */
         list(filter: IListExecutionsFilter): Promise<ExecutionRecord[]>;
@@ -2544,19 +3347,19 @@ interface RunnerPort {
  * `LogRecord.level`. Setting an adapter to `silent` disables every
  * method.
  */
-type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
-type LogMethodLevel = Exclude<LogLevel, 'silent'>;
-declare const LOG_LEVELS: readonly LogLevel[];
-declare function logLevelRank(level: LogLevel): number;
-declare function isLogLevel(value: unknown): value is LogLevel;
+type TLogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+type TLogMethodLevel = Exclude<TLogLevel, 'silent'>;
+declare const LOG_LEVELS: readonly TLogLevel[];
+declare function logLevelRank(level: TLogLevel): number;
+declare function isLogLevel(value: unknown): value is TLogLevel;
 /**
- * Parse a string into a `LogLevel`. Returns `null` for invalid input
+ * Parse a string into a `TLogLevel`. Returns `null` for invalid input
  * (incl. `undefined` / `null` / empty). Case-insensitive; trims
  * whitespace.
  */
-declare function parseLogLevel(value: string | undefined | null): LogLevel | null;
+declare function parseLogLevel(value: string | undefined | null): TLogLevel | null;
 interface LogRecord {
-    level: LogMethodLevel;
+    level: TLogMethodLevel;
     /** ISO 8601 timestamp produced at the moment the log call was made. */
     timestamp: string;
     message: string;
@@ -2628,7 +3431,35 @@ declare function getActiveLogger(): LoggerPort;
 
 interface Kernel {
     registry: Registry;
+    /**
+     * Step 9.6.6 — read-only catalog of plugin-contributed annotation
+     * keys, keyed by `(pluginId, key)`. Populated at plugin-load time;
+     * pure read with no side effects. Built-in catalog (from
+     * `annotations.schema.json`) is NOT included here.
+     */
+    getRegisteredAnnotationKeys: () => readonly IRegisteredAnnotationKey[];
+    /**
+     * Internal — replace the frozen catalog. Called once by the
+     * plugin runtime composer after every plugin has loaded; consumers
+     * MUST treat the resulting array as immutable.
+     */
+    setRegisteredAnnotationKeys: (entries: readonly IRegisteredAnnotationKey[]) => void;
+    /**
+     * Step 11.x — read-only catalog of plugin-contributed view
+     * contributions, keyed by `(pluginId, extensionId, contributionId)`.
+     * Populated at plugin-load time; pure read with no side effects.
+     * Mirror of `getRegisteredAnnotationKeys` for the view contribution
+     * surface (see `architecture.md` §View contribution system →
+     * Runtime catalog).
+     */
+    getRegisteredViewContributions: () => readonly IRegisteredViewContribution[];
+    /**
+     * Internal — replace the frozen view-contribution catalog. Called
+     * once by the plugin runtime composer after every plugin has loaded;
+     * consumers MUST treat the resulting array as immutable.
+     */
+    setRegisteredViewContributions: (entries: readonly IRegisteredViewContribution[]) => void;
 }
 declare function createKernel(): Kernel;
 
-export { type Confidence, DuplicateExtensionError, EXTENSION_KINDS, type ExecutionFailureReason, type ExecutionKind, type ExecutionRecord, type ExecutionRunner, type ExecutionStatus, ExportQueryError, type Extension, type ExtensionKind, type FilesystemPort, HOOK_TRIGGERS, type HistoryStats, type HistoryStatsErrorRates, type HistoryStatsExecutionsPerPeriod, type HistoryStatsPerActionRate, type HistoryStatsTokensPerAction, type HistoryStatsTopNode, type HistoryStatsTotals, type IAction, type IActionPrecondition, type ICreateFsWatcherOptions, type IDedicatedStorePersist, type IDedicatedStoreWrapper, type IDiscoveredPlugin, type IEnrichmentRecord, type IExportQuery, type IExportSubset, type IExtensionBase, type IExtractor, type IExtractorCallbacks, type IExtractorContext, type IExtractorRunRecord, type IFormatter, type IFormatterContext, type IFsWatcher, type IHook, type IHookContext, type IIssueRow, type IKvStorePersist, type IKvStoreWrapper, type ILoadedExtension, type INodeBundle, type INodeChange, type INodeCounts, type INodeFilter, type IPersistOptions, type IPersistedEnrichment, type IPluginManifest, type IPluginStorageSchema, type IPluginStore, type IProvider, type IRawNode, type IRule, type IRuleContext, type IRunOptions, type IRunResult, type IScanDelta, type ITransactionalStorage, type IWalkOptions, type IWatchBatch, type IWatchEvent, InMemoryProgressEmitter, type Issue, type IssueFix, KV_SCHEMA_KEY, type Kernel, LOG_LEVELS, type Link, type LinkKind, type LinkLocation, type LinkTrigger, type LogLevel, type LogMethodLevel, type LogRecord, type LoggerPort, type Node, type NodeKind, type NodeStat, type PluginLoaderPort, type ProgressEmitterPort, type ProgressEvent, type ProgressListener, Registry, type RenameOp, type RunScanOptions, type RunnerPort, type ScanResult, type ScanScannedBy, type ScanStats, type Severity, SilentLogger, type Stability, type StoragePort, type TExecutionMode, type TGranularity, type THookFilter, type THookTrigger, type TNodeChangeReason, type TPluginLoadStatus, type TPluginStorage, type TWatchEventKind, type TripleSplit, applyExportQuery, computeScanDelta, configureLogger, createChokidarWatcher, createKernel, detectRenamesAndOrphans, getActiveLogger, isEmptyDelta, isLogLevel, log, logLevelRank, makeDedicatedStoreWrapper, makeKvStoreWrapper, makePluginStore, mergeNodeWithEnrichments, parseExportQuery, parseLogLevel, qualifiedExtensionId, resetLogger, runExtractorsForNode, runScan, runScanWithRenames };
+export { type Confidence, DuplicateExtensionError, EXTENSION_KINDS, type ExecutionFailureReason, type ExecutionKind, type ExecutionRecord, type ExecutionRunner, type ExecutionStatus, ExportQueryError, type Extension, type ExtensionKind, type FilesystemPort, HOOK_TRIGGERS, type HistoryStats, type HistoryStatsErrorRates, type HistoryStatsExecutionsPerPeriod, type HistoryStatsPerActionRate, type HistoryStatsTokensPerAction, type HistoryStatsTopNode, type HistoryStatsTotals, type IAction, type IActionContext, type IActionPrecondition, type IActionResult, type IAnnotationContribution, type ICreateFsWatcherOptions, type IDedicatedStorePersist, type IDedicatedStoreWrapper, type IDiscoveredPlugin, type IEnrichmentRecord, type IExportQuery, type IExportSubset, type IExtensionBase, type IExtractor, type IExtractorCallbacks, type IExtractorContext, type IExtractorRunRecord, type IFormatter, type IFormatterContext, type IFsWatcher, type IHook, type IHookContext, type IIssueRow, type IKvStorePersist, type IKvStoreWrapper, type ILoadedExtension, type INodeBundle, type INodeChange, type INodeCounts, type INodeFilter, type IPersistOptions, type IPersistedEnrichment, type IPluginManifest, type IPluginStorageSchema, type IPluginStore, type IProvider, type IRawNode, type IRegisteredAnnotationKey, type IRegisteredViewContribution, type IRule, type IRuleContext, type IRunOptions, type IRunResult, type IScanDelta, type ISettingDeclaration, type ITransactionalStorage, type IViewContribution, type IWalkOptions, type IWatchBatch, type IWatchEvent, InMemoryProgressEmitter, type Issue, type IssueFix, KV_SCHEMA_KEY, type Kernel, LOG_LEVELS, type Link, type LinkKind, type LinkLocation, type LinkTrigger, type LogRecord, type LoggerPort, type Node, type NodeKind, type NodeStat, type PluginLoaderPort, type ProgressEmitterPort, type ProgressEvent, Registry, type RenameOp, type RunScanOptions, type RunnerPort, type ScanResult, type ScanScannedBy, type ScanStats, type Severity, SilentLogger, type Stability, type StoragePort, type TActionWrite, type TContractName, type TExecutionMode, type TGranularity, type THookFilter, type THookTrigger, type TInputTypeName, type TLogLevel, type TLogMethodLevel, type TNodeChangeReason, type TPluginLoadStatus, type TPluginStorage, type TProgressListener, type TSettingValue, type TSeverity, type TWatchEventKind, type TripleSplit, applyExportQuery, computeScanDelta, configureLogger, createChokidarWatcher, createKernel, detectRenamesAndOrphans, getActiveLogger, isEmptyDelta, isLogLevel, log, logLevelRank, makeDedicatedStoreWrapper, makeKvStoreWrapper, makePluginStore, mergeNodeWithEnrichments, parseExportQuery, parseLogLevel, qualifiedExtensionId, resetLogger, runExtractorsForNode, runScan, runScanWithRenames };