@skill-map/cli 0.16.6 → 0.18.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,19 +55,20 @@
  *       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 five node kinds the **built-in Claude Provider** declares — `skill`,
- * `agent`, `command`, `hook`, `note`. **NOT** the kernel-wide kind type.
+ * The four node kinds the **built-in Claude Provider** declares — `skill`,
+ * `agent`, `command`, `note`. **NOT** the kernel-wide kind type.
  *
  * `Node.kind` is `string`. An external Provider (Cursor, Obsidian, …)
  * MAY classify into its own kinds (e.g. `'cursorRule'`, `'daily'`); the
@@ -67,19 +77,29 @@
  * `node.schema.json#/properties/kind`, the contract is open-by-design
  * (matches `IProvider.kinds` "open by design" docstring).
  *
+ * 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
+ * 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 five
+ *   - claude-specific code legitimately wants to switch on the four
  *     hard-coded values (filter widgets, kind-aware UI cards, the
  *     `validate-all` built-in rule that maps each kind to its
  *     frontmatter schema);
  *   - sorting helpers want a stable `KIND_ORDER` for the canonical
  *     catalog;
- *   - tests expect to enumerate the five kinds when seeding fixtures.
+ *   - tests expect to enumerate the four kinds when seeding fixtures.
  *
  * For "any kind a Provider could declare", use plain `string`. Only use
  * `NodeKind` when the code is intentionally claude-catalog-specific.
  */
-type NodeKind = 'skill' | 'agent' | 'command' | 'hook' | 'note';
+type NodeKind = 'skill' | 'agent' | 'command' | 'markdown';
 type LinkKind = 'invokes' | 'references' | 'mentions' | 'supersedes';
 type Confidence = 'high' | 'medium' | 'low';
 type Severity = 'error' | 'warn' | 'info';
@@ -134,10 +154,66 @@ interface Node {
     title?: string | null;
     description?: string | null;
     stability?: Stability | null;
-    version?: string | null;
-    author?: string | null;
+    /**
+     * Monotonic version counter sourced from the sidecar's
+     * `annotations.version` (Step 9.6.2). `null` when no sidecar accompanies
+     * the node, or when the sidecar omits `version`. Pre-9.6.2 the field
+     * was a semver string sourced from `frontmatter.metadata.version`;
+     * see migration `002_sidecar_columns.sql` and Decision #125.
+     */
+    version?: number | 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
@@ -180,8 +256,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;
@@ -363,6 +439,98 @@ 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>;
+}
+
+/**
+ * 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>;
+}
+
 /**
  * `.skillmapignore` parser + filter facade. Wraps `ignore` (kaelzhang)
  * with the project-local layering: bundled defaults → `config.ignore`
@@ -406,10 +574,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;
 }
 
 /**
@@ -716,41 +884,6 @@ declare function makePluginStore(opts: {
     persistDedicated?: IDedicatedStorePersist;
 }): IPluginStore | undefined;
 
-/**
- * Base manifest shape shared by every extension kind. Mirrors
- * `spec/schemas/extensions/base.schema.json` at the TypeScript level.
- *
- * Spec § A.6 — every extension is identified in the registry by the
- * qualified id `<pluginId>/<id>`. The `pluginId` field is required at the
- * runtime / TS level: built-ins declare it directly in
- * `src/extensions/built-ins.ts`; user plugins have it injected by the
- * `PluginLoader` from `plugin.json#/id` before the extension reaches the
- * registry. A plugin author who hand-codes a `pluginId` that disagrees
- * with the manifest's `id` is rejected as `invalid-manifest`.
- *
- * The JSON Schema deliberately does NOT model `pluginId` — the qualifier
- * is a runtime concern composed by the loader, not a manifest field
- * authors are expected to set. Stripping it before AJV validation in
- * the loader keeps the spec contract clean ("authors declare only the
- * short id").
- */
-
-interface IExtensionBase {
-    id: string;
-    /**
-     * Owning plugin namespace. Composed with `id` to produce the
-     * qualified registry key `<pluginId>/<id>`. Built-ins declare this
-     * directly; user plugins have it injected by the `PluginLoader`
-     * from `plugin.json#/id`.
-     */
-    pluginId: string;
-    version: string;
-    description?: string;
-    stability?: Stability;
-    preconditions?: string[];
-    entry?: string;
-}
-
 /**
  * Provider runtime contract. Walks filesystem roots and emits raw node
  * records; classification maps path conventions to a node kind.
@@ -876,7 +1009,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
@@ -885,7 +1018,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;
 } | {
@@ -919,6 +1052,47 @@ interface IProvider extends IExtensionBase {
      * column all accept any non-empty string an enabled Provider returns.
      */
     kinds: Record<string, IProviderKind>;
+    /**
+     * Optional auxiliary JSON Schemas this Provider's per-kind schemas
+     * `$ref` by `$id`. Registered with AJV via `addSchema` BEFORE the
+     * per-kind schemas compile, so cross-file `$ref` resolution succeeds.
+     *
+     * Use case: when several kinds share a common base (e.g. Anthropic's
+     * merged skill / command frontmatter — both extend a shared
+     * `skill-base.schema.json`), the Provider declares the base here so
+     * `skill.schema.json` and `command.schema.json` can `$ref` it without
+     * duplicating fields.
+     *
+     * Runtime-only — does NOT appear in the spec's `provider.schema.json`
+     * manifest. Manifest-validated schemas remain the per-kind ones in
+     * `kinds[<kind>].schema`; auxiliary schemas are an implementation
+     * concern of how the runtime composes those.
+     */
+    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
@@ -929,22 +1103,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;
 }
 
 /**
@@ -1076,9 +1280,46 @@ 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[];
 }
 interface IRule extends IExtensionBase {
     kind: 'rule';
@@ -1133,6 +1374,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
@@ -1202,6 +1495,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>;
 }
 
 /**
@@ -1476,6 +1789,17 @@ 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[];
     /**
      * Scan scope. Defaults to `'project'`. The CLI flag wiring lands in
      * the config layer wiring; `runScan` already accepts the override
@@ -1769,7 +2093,7 @@ interface IPersistedEnrichment {
 declare class InMemoryProgressEmitter implements ProgressEmitterPort {
     #private;
     emit(event: ProgressEvent): void;
-    subscribe(listener: ProgressListener): () => void;
+    subscribe(listener: TProgressListener): () => void;
 }
 
 /**
@@ -2158,16 +2482,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>;
@@ -2395,6 +2721,23 @@ interface StoragePort {
          */
         listReferencedFilePaths(): Promise<Set<string>>;
     };
+    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[]>;
@@ -2521,19 +2864,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;
@@ -2605,7 +2948,20 @@ 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;
 }
 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 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 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 TExecutionMode, type TGranularity, type THookFilter, type THookTrigger, type TLogLevel, type TLogMethodLevel, type TNodeChangeReason, type TPluginLoadStatus, type TPluginStorage, type TProgressListener, 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 };