@skill-map/cli 0.19.0 → 0.20.1

package/dist/kernel/index.d.ts

@@ -25,7 +25,7 @@
  *      implements `StoragePort`).
  *
  *   3. **Runtime extension contracts** — what a plugin author
- *      implements: `IProvider`, `IExtractor`, `IRule`, `IFormatter`,
+ *      implements: `IProvider`, `IExtractor`, `IAnalyzer`, `IFormatter`,
  *      `IExtensionBase`. **`I` prefix.** The prefix flags "this is a
  *      contract you supply, not a value the kernel hands you" — same
  *      reading as the rest of TypeScript's plugin ecosystems where a
@@ -226,7 +226,7 @@ interface IssueFix {
     autofixable?: boolean;
 }
 interface Issue {
-    ruleId: string;
+    analyzerId: string;
     severity: Severity;
     nodeIds: string[];
     message: string;
@@ -370,7 +370,7 @@ interface ScanResult {
  * Extension registry — six kinds, first-class, loaded through a single API.
  *
  * The `Extension` shape is aligned with `spec/schemas/extensions/base.schema.json`.
- * Kind-specific manifests (provider / extractor / rule / action / formatter /
+ * Kind-specific manifests (provider / extractor / analyzer / action / formatter /
  * hook) extend this base structurally; the registry stores the base view
  * and each kind's code carries its own fuller type where needed.
  *
@@ -386,7 +386,7 @@ interface ScanResult {
  * `kernel-empty-boot` conformance contract.
  */
 
-type ExtensionKind = 'provider' | 'extractor' | 'rule' | 'action' | 'formatter' | 'hook';
+type ExtensionKind = 'provider' | 'extractor' | 'analyzer' | 'action' | 'formatter' | 'hook';
 declare const EXTENSION_KINDS: readonly ExtensionKind[];
 interface Extension {
     /** Short (unqualified) extension id as declared in the manifest. */
@@ -432,7 +432,7 @@ declare class Registry {
  * 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,
+ * deep inside the kernel — `IAnalyzerContext`, the BFF route factories,
  * future Action contexts — can depend on the catalog shape without
  * dragging the whole kernel barrel and risking a cycle.
  */
@@ -456,7 +456,7 @@ interface IRegisteredAnnotationKey {
  * 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,
+ * deep inside the kernel — `IAnalyzerContext`, the BFF route factories,
  * future Action contexts — can depend on the catalog shape without
  * dragging the whole kernel barrel and risking a cycle.
  *
@@ -466,25 +466,25 @@ interface IRegisteredAnnotationKey {
  * 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`
+ * **Closed catalog by design.** Both `TSlotName` and `TInputTypeName`
+ * mirror the closed enums in `spec/schemas/view-slots.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
+ * shape lets TypeScript surface unknown slots at author time
  * (in plugin authors' editors when their plugin imports `@skill-map/cli`)
- * AND lets the runtime exhaustively dispatch contract → renderer in the
+ * AND lets the runtime exhaustively dispatch slot → renderer in the
  * UI without `default:` fallbacks.
  */
 /**
- * Closed enum of view contract names. Mirror of
- * `spec/schemas/view-contracts.schema.json#/$defs/ContractName`.
+ * Closed enum of view slot names. Mirror of
+ * `spec/schemas/view-slots.schema.json#/$defs/SlotName`.
  *
  * Plugins pick one of these by name in their extension manifest's
- * `viewContributions[<contributionId>].contract` field. The kernel
+ * `viewContributions[<contributionId>].slot` 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.
+ * slot fixes both the renderer and the payload shape.
  */
-type TContractName = 'node-counter' | 'node-tag' | 'node-breakdown' | 'node-records' | 'node-tree' | 'node-key-values' | 'node-link-list' | 'node-markdown' | 'node-alert' | 'scope-stat';
+type TSlotName = 'card.title.right' | 'card.subtitle.left' | 'card.footer.left.counter' | 'card.footer.right' | 'graph.node.alert' | 'inspector.header.badge.counter' | 'inspector.header.badge.tag' | 'inspector.body.panel.breakdown' | 'inspector.body.panel.records' | 'inspector.body.panel.tree' | 'inspector.body.panel.key-values' | 'inspector.body.panel.link-list' | 'inspector.body.panel.markdown' | 'topbar.actions.indicator';
 /**
  * Closed enum of input-type names for plugin settings. Mirror of
  * `spec/schemas/input-types.schema.json#/$defs/InputTypeName`.
@@ -502,14 +502,16 @@ type TSeverity = 'info' | 'warn' | 'success' | 'danger';
  * author writes one of these per Record key in
  * `IExtensionBase.viewContributions[<contributionId>]`.
  *
- * Mirror of `view-contracts.schema.json#/$defs/IViewContribution`.
+ * Mirror of `view-slots.schema.json#/$defs/IViewContribution`.
  */
 interface IViewContribution {
     /**
-     * Required. Closed-catalog contract name. Unknown name rejects the
-     * extension as `invalid-manifest` at load.
+     * Required. Closed-catalog slot name. Unknown name rejects the
+     * extension as `invalid-manifest` at load. The slot fixes both the
+     * renderer and the payload shape; there is no separate "contract"
+     * abstraction.
      */
-    contract: TContractName;
+    slot: TSlotName;
     /**
      * Optional human-readable label. English-only per `AGENTS.md`
      * (`Externalized texts, not internationalized`).
@@ -521,6 +523,8 @@ interface IViewContribution {
      * Optional emoji codepoint OR PrimeIcons class id (without the
      * `pi-` prefix). The UI discriminates: matches Unicode
      * `\p{Extended_Pictographic}` → emoji text, otherwise → PrimeIcon.
+     * Required for counter slots and `card.title.right` (enforced by
+     * the manifest-side conditional in `view-slots.schema.json`).
      */
     icon?: string;
     /**
@@ -532,8 +536,8 @@ interface IViewContribution {
     /**
      * 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.
+     * renderer surfaces an empty placeholder. Per-slot definition of
+     * "empty" lives in the slot's payload schema.
      */
     emitWhenEmpty?: boolean;
     /**
@@ -561,7 +565,7 @@ interface IRegisteredViewContribution {
     pluginId: string;
     extensionId: string;
     contributionId: string;
-    contract: TContractName;
+    slot: TSlotName;
     /** Optional manifest-declared label (English-only). */
     label?: string;
     tooltip?: string;
@@ -741,16 +745,16 @@ interface IExtensionBase {
     /**
      * 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.
+     * `IViewContribution` declaration that picks a view slot by name
+     * from the closed kernel catalog (`view-catalog.ts#TSlotName`).
+     * The slot fixes both the renderer and the payload shape — there
+     * is no separate "contract" abstraction. The kernel validates each
+     * `slot` 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 slot's payload schema. The aggregate runtime catalog is
+     * exposed via `kernel.getRegisteredViewContributions()`. See
+     * `architecture.md` §View contribution system.
      */
     viewContributions?: Record<string, IViewContribution>;
 }
@@ -868,7 +872,7 @@ interface IPluginManifest {
     version: string;
     specCompat: string;
     /**
-     * Optional semver range against the kernel's view-contracts +
+     * Optional semver range against the kernel's view-slots +
      * 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
@@ -1154,7 +1158,7 @@ declare function makePluginStore(opts: {
  * 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);
+ * the slot's payload schema happens at emit time (orchestrator);
  * by the time records reach this adapter they are wire-shape clean.
  */
 interface IContributionRecord {
@@ -1163,26 +1167,26 @@ interface IContributionRecord {
     nodePath: string;
     contributionId: string;
     /**
-     * Closed enum value mirroring `view-contracts.schema.json#/$defs/ContractName`.
+     * Closed enum value mirroring `view-slots.schema.json#/$defs/SlotName`.
      * Persisted as TEXT (no SQL CHECK by design — see migration comment).
      */
-    contract: string;
+    slot: 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`.
+ * `unknown` because the slot space is open at the type layer (catalog
+ * evolution is a kernel + spec concern); narrow at the call site by
+ * reading `slot`.
  */
 interface IPersistedContribution {
     pluginId: string;
     extensionId: string;
     nodePath: string;
     contributionId: string;
-    contract: string;
+    slot: string;
     payload: unknown;
     emittedAt: number;
 }
@@ -1512,15 +1516,16 @@ interface IExtractorCallbacks {
      * 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.
+     * payload that conforms to the slot's payload schema in
+     * `spec/schemas/view-slots.schema.json#/$defs/payloads/<slot>` —
+     * where `<slot>` is the slot the manifest declared for this
+     * contribution. The orchestrator validates the payload against the
+     * slot's schema before persisting to `scan_contributions`; off-shape
+     * payloads are silently dropped with an `extension.error` event
+     * (mirror of `emitLink` rejecting off-`emitsLinkKinds` links).
+     * Calling `emitContribution` with a `contributionId` that is not
+     * declared in the manifest is also dropped with an `extension.error`.
+     * See `architecture.md` §View contribution system → Emit path.
      */
     emitContribution(contributionId: string, payload: unknown): void;
 }
@@ -1576,28 +1581,29 @@ interface IExtractor extends IExtensionBase {
 }
 
 /**
- * Rule runtime contract. Runs against the whole graph after every Provider
- * and extractor has completed; emits issues. Deterministic rules are pure
- * (same graph in → same issues out) and run synchronously inside `sm scan`
- * / `sm check`. Probabilistic rules invoke an LLM through the kernel's
- * `RunnerPort` and dispatch only as queued jobs — they never participate
- * in scan-time pipelines. Mode is declared in the manifest (default
- * `deterministic`).
+ * Analyzer runtime contract. Runs against the whole graph after every
+ * Provider and extractor has completed; emits issues and MAY project
+ * findings into the UI via view contributions. Deterministic analyzers
+ * are pure (same graph in → same issues out) and run synchronously
+ * inside `sm scan` / `sm check`. Probabilistic analyzers invoke an LLM
+ * through the kernel's `RunnerPort` and dispatch only as queued jobs —
+ * they never participate in scan-time pipelines. Mode is declared in
+ * the manifest (default `deterministic`).
  */
 
 /**
- * Step 9.6.2 — orphan sidecar entry surfaced to rules. A `.sm` file
+ * Step 9.6.2 — orphan sidecar entry surfaced to analyzers. A `.sm` file
  * whose sibling `.md` does not exist on disk; the `annotation-orphan`
- * built-in rule emits one warning per entry. Other rules that care
- * about orphan sidecars MAY consume the list too.
+ * built-in analyzer emits one warning per entry. Other analyzers that
+ * care about orphan sidecars MAY consume the list too.
  */
-interface IRuleOrphanSidecar {
+interface IAnalyzerOrphanSidecar {
     /** Relative path (POSIX-separated) of the orphan `.sm`. */
     relativePath: string;
     /** Absolute path of the missing `.md` the sidecar was anchored to. */
     expectedMdPath: string;
 }
-interface IRuleContext {
+interface IAnalyzerContext {
     nodes: Node[];
     links: Link[];
     /**
@@ -1605,32 +1611,32 @@ interface IRuleContext {
      * Empty when sidecar discovery did not run (legacy callers) or
      * when no orphans exist.
      */
-    orphanSidecars?: IRuleOrphanSidecar[];
+    orphanSidecars?: IAnalyzerOrphanSidecar[];
     /**
      * 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.
+     * analyzers that inspect plugin namespaces (e.g. the built-in
+     * `core/unknown-field` Analyzer) can walk the full tree without
+     * re-reading the file from disk. Absent (or `undefined` per node)
+     * when no sidecar accompanies the node, or when the sidecar failed
+     * to parse. Treat as read-only.
      */
     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).
+     * through so analyzers can reason about the registered-vs-unknown
+     * split without reaching back into the kernel. Empty array when no
+     * plugin declares contributions; absent for legacy callers (older
+     * runScan sites that never wired the catalog through).
      */
     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`
+     * through so analyzers can reason about emissions without reaching
+     * back into the kernel: built-in `core/unknown-slot` walks this list
+     * to detect deprecated slots 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
@@ -1638,16 +1644,52 @@ interface IRuleContext {
      */
     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`).
+     * Absolute paths of `*.md` files under the project's
+     * `.skill-map/jobs/` that no `state_jobs.filePath` references — the
+     * built-in `core/job-orphan-file` analyzer projects each as a `warn`
+     * issue. Pre-computed by the driving adapter (CLI / BFF) inside its
+     * already-open storage transaction (mirrors the `orphanSidecars`
+     * pattern: detection lives outside the analyzer, the analyzer only
+     * projects). Absent (or empty) when the caller does not maintain a
+     * jobs directory, when the storage path is unavailable, or when no
+     * orphan files exist. Treat as read-only.
+     */
+    orphanJobFiles?: readonly string[];
+    /**
+     * Set of absolute file paths the operator has opted into for
+     * link-validation purposes via `scan.referencePaths`. The driving
+     * adapter walks each configured path before the scan and collects
+     * every existing file's absolute path here. Files in this set are
+     * NOT indexed as graph nodes — the only consumer is
+     * `core/broken-ref`, which suppresses its `warn` issue when a
+     * path-style link target falls into the set. Absent / empty when
+     * the operator left `scan.referencePaths` empty or when the
+     * adapter does not maintain the side index. Treat as read-only.
+     */
+    referenceablePaths?: ReadonlySet<string>;
+    /**
+     * Absolute path of the scan's project root (cwd of the invocation).
+     * Threaded into the analyzer pass so an analyzer that needs to
+     * resolve a relative `link.target` to an absolute filesystem path
+     * (today only `core/broken-ref`, when consulting
+     * `referenceablePaths`) does not have to derive it from
+     * `nodes[0].path` heuristics. Absent for legacy callers (older
+     * `runScan` sites that never wired the field through). Always an
+     * absolute path when present.
+     */
+    cwd?: string;
+    /**
+     * Emit a per-node view contribution declared in this analyzer's
+     * manifest `viewContributions` map. Sync, void return; the
+     * orchestrator validates the payload against the slot's schema at
+     * call time and silently drops invalid emissions with a logged
+     * `extension.error` event (parallel to
+     * `IExtractorCallbacks.emitContribution`).
      *
      * Unlike Extractor's emit (which binds `nodePath` from `ctx.node.path`
-     * implicitly because Extractors run per-node), 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.
+     * implicitly because Extractors run per-node), Analyzer's `evaluate()`
+     * sees the full graph at once. The analyzer walks `ctx.nodes` itself
+     * and MUST supply the target node path explicitly per emission.
      *
      * Calling `emitContribution` with a `contributionId` that is not
      * declared in the manifest is dropped with an `extension.error`. The
@@ -1656,14 +1698,14 @@ interface IRuleContext {
      */
     emitContribution(nodePath: string, contributionId: string, payload: unknown): void;
 }
-interface IRule extends IExtensionBase {
-    kind: 'rule';
+interface IAnalyzer extends IExtensionBase {
+    kind: 'analyzer';
     /**
      * Execution mode. Optional in the manifest with a default of
-     * `deterministic` per `spec/schemas/extensions/rule.schema.json`.
+     * `deterministic` per `spec/schemas/extensions/analyzer.schema.json`.
      */
     mode?: TExecutionMode;
-    evaluate(ctx: IRuleContext): Issue[] | Promise<Issue[]>;
+    evaluate(ctx: IAnalyzerContext): Issue[] | Promise<Issue[]>;
 }
 
 /**
@@ -1893,12 +1935,16 @@ interface IFormatter extends IExtensionBase {
  * are notification (Slack on `job.completed`), integration glue (CI
  * webhook on `job.failed`), and bookkeeping (per-extractor metrics).
  *
- * The hookable trigger set is INTENTIONALLY SMALL — eight events. The
- * full `ProgressEmitterPort` catalog (per-node `scan.progress`,
- * `model.delta`, `run.*`, internal job lifecycle) is deliberately not
- * hookable: too verbose for a reactive surface, internal to the runner,
- * or covered elsewhere. Declaring a trigger outside the curated set
- * yields `invalid-manifest` at load time.
+ * The hookable trigger set is INTENTIONALLY SMALL — ten events. Eight
+ * are pipeline-driven (emitted from inside `runScan`); two
+ * (`boot`, `shutdown`) are CLI-process-driven (emitted by the driving
+ * binary before / after the verb runs, fire-and-forget so
+ * `process.exit` is never blocked). The full `ProgressEmitterPort`
+ * catalog (per-node `scan.progress`, `model.delta`, `run.*`, internal
+ * job lifecycle) is deliberately not hookable: too verbose for a
+ * reactive surface, internal to the runner, or covered elsewhere.
+ * Declaring a trigger outside the curated set yields
+ * `invalid-manifest` at load time.
  *
  * Dual-mode (declared in manifest):
  *
@@ -1913,27 +1959,35 @@ interface IFormatter extends IExtensionBase {
  *
  * Curated trigger set (per spec § A.11):
  *
+ *   0. `boot`                 — once per CLI process, before verb routing.
  *   1. `scan.started`         — pre-scan setup (one per scan).
  *   2. `scan.completed`       — post-scan reaction (one per scan).
  *   3. `extractor.completed`  — aggregated per-Extractor outputs.
- *   4. `rule.completed`       — aggregated per-Rule outputs.
+ *   4. `analyzer.completed`       — aggregated per-Rule outputs.
  *   5. `action.completed`     — Action executed on a node.
  *   6. `job.spawning`         — pre-spawn of runner subprocess.
  *   7. `job.completed`        — most common trigger.
  *   8. `job.failed`           — alerts, retry triggers.
+ *   9. `shutdown`             — once per CLI process, after the verb's
+ *                                exit code resolves and before
+ *                                `process.exit`.
  */
 
 /**
- * The eight hookable lifecycle events. Mirrors the `triggers[]` enum in
- * `spec/schemas/extensions/hook.schema.json`. Anything outside this set
- * is rejected at load time as `invalid-manifest`.
+ * The ten hookable lifecycle events. Mirrors the `triggers[]` enum in
+ * `spec/schemas/extensions/hook.schema.json`. Eight are pipeline-driven
+ * (emitted from inside `runScan`); two (`boot`, `shutdown`) are
+ * CLI-process-driven (emitted by the driving binary before / after the
+ * verb runs). Anything outside this set is rejected at load time as
+ * `invalid-manifest`.
  */
-type THookTrigger = 'scan.started' | 'scan.completed' | 'extractor.completed' | 'rule.completed' | 'action.completed' | 'job.spawning' | 'job.completed' | 'job.failed';
+type THookTrigger = 'boot' | 'scan.started' | 'scan.completed' | 'extractor.completed' | 'analyzer.completed' | 'action.completed' | 'job.spawning' | 'job.completed' | 'job.failed' | 'shutdown';
 /**
  * Frozen list mirror of `THookTrigger` for runtime introspection. The
  * loader validates `manifest.triggers[]` against this set; the
- * orchestrator's dispatcher iterates it in order when fanning an event
- * out to subscribed hooks.
+ * dispatcher iterates it in order when fanning an event out to
+ * subscribed hooks. `boot` first / `shutdown` last so a debug log of
+ * the array reads in lifecycle order.
  */
 declare const HOOK_TRIGGERS: readonly THookTrigger[];
 /**
@@ -1942,7 +1996,7 @@ declare const HOOK_TRIGGERS: readonly THookTrigger[];
  *
  * The `event` carries the raw `ProgressEvent` envelope (type, timestamp,
  * runId/jobId when applicable, data). Optional `node` / `extractorId`
- * / `ruleId` / `actionId` are extracted from the event payload by the
+ * / `analyzerId` / `actionId` are extracted from the event payload by the
  * dispatcher when present so authors don't have to walk `event.data`.
  *
  * Probabilistic hooks additionally receive `runner` for LLM dispatch.
@@ -1969,9 +2023,9 @@ interface IHookContext {
      */
     extractorId?: string;
     /**
-     * Set on `rule.completed` events. Qualified extension id of the Rule.
+     * Set on `analyzer.completed` events. Qualified extension id of the Rule.
      */
-    ruleId?: string;
+    analyzerId?: string;
     /**
      * Set on `action.completed` events. Qualified extension id of the
      * Action that just ran.
@@ -2039,7 +2093,7 @@ interface IHook extends IExtensionBase {
 }
 
 /**
- * Scan orchestrator — runs the Provider → extractor → rule pipeline across
+ * Scan orchestrator — runs the Provider → extractor → analyzer pipeline across
  * every registered extension and emits `ProgressEmitterPort` events in
  * canonical order. The callable extension set is injected via
  * `RunScanOptions.extensions` — the Registry holds manifest metadata, the
@@ -2092,7 +2146,7 @@ interface IHook extends IExtensionBase {
 interface IScanExtensions {
     providers: IProvider[];
     extractors: IExtractor[];
-    rules: IRule[];
+    analyzers: IAnalyzer[];
     /**
      * Optional hooks (spec § A.11). When supplied, the orchestrator's
      * lifecycle dispatcher invokes deterministic hooks subscribed to one
@@ -2139,10 +2193,10 @@ interface RunScanOptions {
      * 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
+     *   - `core/unknown-slot` 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
+     *     declared `(contributionId → slot)` pairing for AJV
      *     payload validation.
      * Absent → empty catalog. Rules that emit contributions silently
      * drop emissions when the catalog has no entry for the rule's
@@ -2242,6 +2296,40 @@ interface RunScanOptions {
      * mock without spinning up a DB.
      */
     pluginStores?: ReadonlyMap<string, IPluginStore>;
+    /**
+     * Pre-computed absolute paths of orphan job MD files (files under
+     * `.skill-map/jobs/` whose absolute path appears nowhere in
+     * `state_jobs.filePath`). Threaded into the rule pass so the
+     * built-in `core/job-orphan-file` rule can project each as a `warn`
+     * issue without the kernel reaching for the storage port or doing
+     * its own FS walk. The driving adapter (CLI, BFF) computes this
+     * inside its already-open storage transaction via
+     * `findOrphanJobFiles(jobsDir, await port.jobs.listReferencedFilePaths())`
+     * — mirrors the `orphanSidecars` model where detection lives
+     * outside the rule and the rule only projects. Absent / empty when
+     * the caller has no jobs context (out-of-band tests, fresh DB,
+     * `--no-built-ins`).
+     */
+    orphanJobFiles?: readonly string[];
+    /**
+     * Side set of absolute file paths the operator opted into for
+     * link-validation purposes via `scan.referencePaths`. Threaded
+     * through to `IAnalyzerContext.referenceablePaths` so the built-in
+     * `core/broken-ref` rule can suppress its `warn` for path-style
+     * links whose target lands in the set. Files are NOT walked by
+     * the kernel — the driving adapter populates the set before
+     * calling `runScan`. Absent / empty when the operator left
+     * `scan.referencePaths` unconfigured.
+     */
+    referenceablePaths?: ReadonlySet<string>;
+    /**
+     * Absolute path of the scan's cwd / project root. Threaded onto
+     * `IAnalyzerContext.cwd` so rules that need to resolve a relative
+     * `link.target` to an absolute filesystem path can do so without
+     * heuristics. Absent for callers that don't track a cwd
+     * concept (out-of-band tests, embedders).
+     */
+    cwd?: string;
 }
 /**
  * Spec § A.9 — runs to persist into `scan_extractor_runs`. One entry
@@ -2311,6 +2399,7 @@ declare function runScanWithRenames(_kernel: Kernel, options: RunScanOptions): P
     extractorRuns: IExtractorRunRecord[];
     enrichments: IEnrichmentRecord[];
     contributions: IContributionRecord[];
+    freshlyRunTuples: ReadonlySet<string>;
 }>;
 declare function runScan(_kernel: Kernel, options: RunScanOptions): Promise<ScanResult>;
 /**
@@ -2560,7 +2649,7 @@ declare function createChokidarWatcher(opts: ICreateFsWatcherOptions): IFsWatche
  *     are presentation facets that can churn without making the link
  *     "different" for delta purposes.
  *
- *   - **Issue**: `(ruleId, sorted nodeIds, message)`. Mirrors
+ *   - **Issue**: `(analyzerId, sorted nodeIds, message)`. Mirrors
  *     `spec/job-events.md` §issue.* — same key → same issue, even when
  *     `data` / `severity` / `linkIndices` shift. A meaningful change in
  *     `message` (or a different set of node ids) is a different issue.
@@ -2858,6 +2947,31 @@ interface IPersistOptions {
      * pre-fix).
      */
     registeredContributionKeys?: ReadonlySet<string>;
+    /**
+     * Phase 3 / View contribution system — set of `(plugin, extension,
+     * node)` tuples where the extension actually RAN against that node
+     * in this scan. Format: `<pluginId>/<extensionId>/<nodePath>` (no
+     * contribution-id segment — the sweep operates at the (plugin,
+     * extension, node) level and inspects the buffer to decide which
+     * contribution-ids survive).
+     *
+     * Membership rules:
+     *   - Extractor + cache miss: tuple INCLUDED (extract() ran).
+     *   - Extractor + cache hit: tuple OMITTED (extract() skipped, prior
+     *     rows must be preserved).
+     *   - Rule, every node in `ctx.nodes`: tuple INCLUDED (rules always
+     *     run and see the full graph).
+     *
+     * Drives the per-tuple sweep documented in `spec/architecture.md`
+     * §View contribution system → Persistence (sweep #3): rows whose
+     * `(plugin_id, extension_id, node_path)` is in this set but whose
+     * `(plugin_id, extension_id, node_path, contribution_id)` is NOT in
+     * the buffer get DELETEd before the upsert. Catches the "extractor
+     * used to emit, now does not" case (e.g. body change removes the
+     * trigger). Empty / absent set = no per-tuple sweep (legacy
+     * callers preserve the pre-fix behaviour where stale rows linger).
+     */
+    freshlyRunTuples?: ReadonlySet<string>;
 }
 /**
  * Issue row as the storage layer sees it — paired with its DB-assigned
@@ -3123,7 +3237,7 @@ interface StoragePort {
         listAll(): Promise<Issue[]>;
         /**
          * Issue rows whose runtime `Issue` shape passes `predicate`.
-         * `port.issues.findActive((i) => i.ruleId === 'orphan')` is the
+         * `port.issues.findActive((i) => i.analyzerId === 'orphan')` is the
          * canonical use; `sm orphans` consumes this. The returned shape
          * carries the DB-assigned `id` so a follow-up
          * `transaction(tx => tx.issues.deleteById(row.id))` can target
@@ -3423,6 +3537,51 @@ declare function resetLogger(): void;
 /** Inspect the active logger. Test-only — production code uses `log`. */
 declare function getActiveLogger(): LoggerPort;
 
+/**
+ * Hook lifecycle dispatcher (spec § A.11). Indexes the supplied hooks
+ * by trigger and fans the matching event out to every subscribed
+ * deterministic hook in registration order. Probabilistic hooks are
+ * skipped here with a stderr advisory; they will dispatch via the job
+ * subsystem once it ships (Decision #114).
+ *
+ * Filter handling: when the hook declares a `filter` map, the dispatcher
+ * walks `event.data` for each declared key and short-circuits the
+ * invocation when any value disagrees. Top-level fields only in v0.x
+ * (deep-path matching is deferred until a real use case justifies the
+ * complexity).
+ *
+ * Error policy: a hook that throws is caught here, logged through a
+ * synthetic `extension.error` event with kind `hook-error`, and the
+ * caller continues. A buggy hook MUST NOT block the main pipeline (or
+ * the CLI exit path) — that would invert the design intent (hooks
+ * REACT to events, they never steer them).
+ *
+ * The module lives under `kernel/extensions/` (alongside the `IHook`
+ * contract itself) so two callers share it: `runScan` for the eight
+ * pipeline-driven triggers (`scan.*`, `extractor.completed`,
+ * `analyzer.completed`, `action.completed`, `job.*`) and the CLI entry
+ * for the two CLI-process-driven triggers (`boot`, `shutdown`).
+ * Pulling the dispatcher out of the orchestrator keeps both consumers
+ * symmetric — same indexing, same filter semantics, same error
+ * policy.
+ */
+
+interface IHookDispatcher {
+    /**
+     * Fan the event out to every hook subscribed to `trigger`. Awaits each
+     * hook's `on(ctx)` in registration order. Errors are caught and
+     * logged via `extension.error`; they never propagate.
+     */
+    dispatch(trigger: THookTrigger, event: ProgressEvent): Promise<void>;
+}
+/**
+ * Build a dispatcher over the given hooks. Empty `hooks` returns a
+ * cheap no-op shape so the call sites can dispatch unconditionally.
+ */
+declare function makeHookDispatcher(hooks: IHook[], emitter: ProgressEmitterPort): IHookDispatcher;
+/** Construct a `ProgressEvent` envelope. Mirrors the orchestrator helper. */
+declare function makeEvent(type: string, data: unknown): ProgressEvent;
+
 /**
  * Kernel entry point. `createKernel()` returns a shell with an empty registry
  * and no bound ports. Driving adapters (CLI, Server, Skill) are expected to
@@ -3462,4 +3621,4 @@ interface Kernel {
 }
 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 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 };
+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 IAnalyzer, type IAnalyzerContext, 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 IHookDispatcher, 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 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 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 TSlotName, type TWatchEventKind, type TripleSplit, applyExportQuery, computeScanDelta, configureLogger, createChokidarWatcher, createKernel, detectRenamesAndOrphans, getActiveLogger, isEmptyDelta, isLogLevel, log, logLevelRank, makeDedicatedStoreWrapper, makeEvent, makeHookDispatcher, makeKvStoreWrapper, makePluginStore, mergeNodeWithEnrichments, parseExportQuery, parseLogLevel, qualifiedExtensionId, resetLogger, runExtractorsForNode, runScan, runScanWithRenames };