@skill-map/cli 0.54.0 → 0.55.0

package/dist/index.js

@@ -1,6 +1,6 @@
 // kernel/i18n/registry.texts.ts
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f476faaa-267b-52a2-84d7-7b8859286768")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1f2129d2-2039-52b2-acb6-f7adcf338044")}catch(e){}}();
 var REGISTRY_TEXTS = {
   duplicateExtension: "Extension already registered: {{kind}}:{{qualifiedId}}",
   unknownKind: "Unknown extension kind: {{kind}}",
@@ -102,7 +102,7 @@ import { Tiktoken as Tiktoken2 } from "js-tiktoken/lite";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.54.0",
+  version: "0.55.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -1190,6 +1190,81 @@ function isExternalUrlLink(link) {
   return EXTERNAL_URL_SCHEME_RE.test(link.target);
 }
 
+// kernel/orchestrator/action-projections.ts
+function runActionProjections(actions, nodes, links, emitter) {
+  const contributions = [];
+  const contributionErrors = [];
+  const validators = loadSchemaValidators();
+  for (const action of actions) {
+    if (typeof action.project !== "function") continue;
+    const qualifiedId = qualifiedExtensionId(action.pluginId, action.id);
+    const declaredContributions = readDeclaredContributionRefs(action);
+    const emitContribution = (nodePath, ref, payload) => {
+      const declared = typeof ref === "object" && ref !== null ? declaredContributions.get(ref) : void 0;
+      if (!declared) {
+        const message = tx(ORCHESTRATOR_TEXTS.extensionErrorContributionUndeclaredRef, {
+          extractorId: qualifiedId,
+          nodePath
+        });
+        emitExtensionError(emitter, qualifiedId, nodePath, {
+          phase: "emitContribution",
+          reason: "undeclared-contribution-ref",
+          message
+        });
+        contributionErrors.push({
+          pluginId: action.pluginId,
+          extensionId: action.id,
+          nodePath,
+          reason: "undeclared-contribution-ref",
+          message,
+          emittedAt: Date.now()
+        });
+        return;
+      }
+      const result = validators.validateContributionPayload(declared.slot, payload);
+      if (!result.ok) {
+        const message = tx(ORCHESTRATOR_TEXTS.extensionErrorContributionPayloadInvalid, {
+          extractorId: qualifiedId,
+          contributionId: declared.id,
+          nodePath,
+          slot: declared.slot,
+          errors: result.errors
+        });
+        emitExtensionError(emitter, qualifiedId, nodePath, {
+          phase: "emitContribution",
+          contributionId: declared.id,
+          slot: declared.slot,
+          reason: result.errors,
+          message
+        });
+        contributionErrors.push({
+          pluginId: action.pluginId,
+          extensionId: action.id,
+          nodePath,
+          reason: result.errors,
+          message,
+          contributionId: declared.id,
+          slot: declared.slot,
+          emittedAt: Date.now()
+        });
+        return;
+      }
+      contributions.push({
+        pluginId: action.pluginId,
+        extensionId: action.id,
+        nodePath,
+        contributionId: declared.id,
+        slot: declared.slot,
+        payload,
+        emittedAt: Date.now()
+      });
+    };
+    const ctx = { nodes, links, emitContribution };
+    action.project(ctx);
+  }
+  return { contributions, contributionErrors };
+}
+
 // kernel/orchestrator/analyzers.ts
 async function runAnalyzers(analyzers, nodes, internalLinks, orphanSidecars, sidecarRoots, annotationContributions, viewContributions, orphanJobFiles, referenceablePaths, cwd, registeredActionIds, emitter, hookDispatcher, reservedNodePaths, signals, seedIssues = []) {
   const issues = [...seedIssues];
@@ -1560,17 +1635,26 @@ function readDirname(node) {
 
 // kernel/orchestrator/lift-resolved-link-confidence.ts
 var RESERVED_TARGET_CONFIDENCE = 0.1;
+var BROKEN_TARGET_CONFIDENCE = 0.5;
 function liftResolvedLinkConfidence(links, nodes, ctx) {
   if (!links.some((l) => l.confidence < 1)) return;
   const indexes = buildIndexes(nodes, ctx);
   for (const link of links) {
-    if (link.confidence >= 1) continue;
-    const resolution = resolve5(link, indexes, ctx);
-    if (resolution === "none") continue;
-    link.confidence = ctx.reservedNodePaths.has(resolution) ? RESERVED_TARGET_CONFIDENCE : 1;
-    link.resolvedTarget = resolution;
+    if (link.confidence < 1) applyResolution(link, indexes, ctx);
   }
 }
+function applyResolution(link, indexes, ctx) {
+  const resolution = resolve5(link, indexes, ctx);
+  if (resolution === "none") {
+    if (isGenuinelyBroken(link, indexes)) {
+      link.confidence = Math.min(link.confidence, BROKEN_TARGET_CONFIDENCE);
+    }
+    return;
+  }
+  link.resolvedTarget = resolution;
+  if (indexes.nodeByPath.get(resolution)?.virtual) return;
+  link.confidence = ctx.reservedNodePaths.has(resolution) ? RESERVED_TARGET_CONFIDENCE : 1;
+}
 function buildIndexes(nodes, ctx) {
   const byPath2 = /* @__PURE__ */ new Set();
   const byName = /* @__PURE__ */ new Map();
@@ -1586,6 +1670,12 @@ function resolve5(link, indexes, ctx) {
   if (indexes.byPath.has(link.target)) return link.target;
   return resolveByName(link, indexes, ctx);
 }
+function isGenuinelyBroken(link, indexes) {
+  if (indexes.byPath.has(link.target)) return false;
+  const stripped = stripTriggerSigil(link.trigger?.normalizedTrigger);
+  if (stripped !== null && indexes.byName.has(stripped)) return false;
+  return true;
+}
 function resolveByName(link, indexes, ctx) {
   const stripped = stripTriggerSigil(link.trigger?.normalizedTrigger);
   if (stripped === null) return "none";
@@ -2146,11 +2236,11 @@ async function* walkContent(roots, options) {
   const extensions = options.extensions;
   const sizeLimit = buildSizeLimit(options);
   for (const root of roots) {
-    for await (const file of walkRoot(root, root, filter, extensions, sizeLimit)) {
-      const relPath = relative2(root, file).split(sep).join("/");
+    for await (const entry of walkRoot(root, root, filter, extensions, sizeLimit)) {
+      const relPath = relative2(root, entry.full).split(sep).join("/");
       let raw;
       try {
-        raw = await readFile(file, "utf8");
+        raw = await readFile(entry.full, "utf8");
       } catch {
         continue;
       }
@@ -2160,6 +2250,9 @@ async function* walkContent(roots, options) {
         body: parsed.body,
         frontmatterRaw: parsed.frontmatterRaw,
         frontmatter: parsed.frontmatter,
+        // File mtime from the TOCTOU `lstat` (zero extra syscalls).
+        // Threaded onto the persisted `Node` as `modifiedAtMs`.
+        modifiedAtMs: entry.modifiedAtMs,
         // Audit L1: forward parser diagnostics (e.g. malformed YAML)
         // through the IRawNode surface so the orchestrator can
         // convert them into warn-level kernel `Issue` rows. Omitted
@@ -2200,7 +2293,7 @@ async function* walkRoot(root, current, filter, extensions, sizeLimit) {
           sizeLimit.onOversizedFile?.({ path: rel, bytes: s.size });
           continue;
         }
-        yield full;
+        yield { full, modifiedAtMs: Math.round(s.mtimeMs) };
       } catch {
       }
     }
@@ -2491,6 +2584,7 @@ function buildNode(args) {
     externalRefsCount: 0,
     frontmatter: args.frontmatter
   };
+  if (args.modifiedAtMs !== void 0) node.modifiedAtMs = args.modifiedAtMs;
   if (args.encoder) {
     node.tokens = countTokens(args.encoder, args.frontmatterRaw, args.body);
   }
@@ -2606,7 +2700,10 @@ function buildFreshNodeAndValidateFrontmatter(opts) {
     frontmatter: opts.raw.frontmatter,
     bodyHash: opts.bodyHash,
     frontmatterHash: opts.frontmatterHash,
-    encoder: opts.encoder
+    encoder: opts.encoder,
+    // Thread the walker's mtime through; `buildNode` only attaches it
+    // when present, so virtual / walk()-without-stat sources stay absent.
+    modifiedAtMs: opts.raw.modifiedAtMs
   });
   const frontmatterIssues = [];
   if (opts.raw.parseIssues && opts.raw.parseIssues.length > 0) {
@@ -3056,6 +3153,13 @@ async function runScanInternal(_kernel, options) {
     walked.frontmatterIssues
   );
   mergeAnalyzerEmissions(walked, analyzerResult, exts.analyzers);
+  const projectionResult = runActionProjections(
+    exts.actions ?? [],
+    walked.nodes,
+    walked.internalLinks,
+    emitter
+  );
+  mergeActionProjections(walked, projectionResult, exts.actions);
   const issues = analyzerResult.issues;
   const silenced = options.ignoreFilter ? (path) => options.ignoreFilter.ignores(path) : void 0;
   const renameOps = prior ? detectRenamesAndOrphans(prior, walked.nodes, issues, silenced) : [];
@@ -3164,6 +3268,16 @@ function mergeAnalyzerEmissions(walked, analyzerResult, analyzers) {
     }
   }
 }
+function mergeActionProjections(walked, projectionResult, actions) {
+  for (const c of projectionResult.contributions) walked.contributions.push(c);
+  for (const e of projectionResult.contributionErrors) walked.contributionErrors.push(e);
+  for (const action of actions ?? []) {
+    if (action.ui === void 0 || typeof action.project !== "function") continue;
+    for (const node of walked.nodes) {
+      walked.freshlyRunTuples.add(`${action.pluginId}\0${action.id}\0${node.path}`);
+    }
+  }
+}
 function buildScanStats(walked, issues, start) {
   return {
     // `filesSkipped` is "files walked but not classified by any
@@ -3632,4 +3746,4 @@ export {
   runScanWithRenames
 };
 //# sourceMappingURL=index.js.map
-//# debugId=f476faaa-267b-52a2-84d7-7b8859286768
+//# debugId=1f2129d2-2039-52b2-acb6-f7adcf338044

package/dist/kernel/index.d.ts

@@ -1,87 +1,3 @@
-/**
- * Extension registry, six kinds, first-class, loaded through a single API.
- *
- * The `IExtension` shape is aligned with `spec/schemas/extensions/base.schema.json`.
- * 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.
- *
- * **Spec § A.6, qualified ids.** Every extension is keyed in the registry
- * by `<pluginId>/<id>` (e.g. `core/annotations`, `core/slash-command`,
- * `my-plugin/my-extractor`). `IExtension.id` carries the **short** id as authored;
- * `IExtension.pluginId` carries the namespace; the registry composes the
- * qualifier internally and exposes lookup APIs that operate on either form
- * (qualified for direct lookup, kind-scoped listing for enumeration).
- *
- * Boot invariant: `new Registry()` is empty. `registry.totalCount() === 0`
- * when the kernel boots with zero extensions. This is the data side of the
- * `kernel-empty-boot` conformance contract.
- */
-type ExtensionKind = 'provider' | 'extractor' | 'analyzer' | 'action' | 'formatter' | 'hook';
-declare const EXTENSION_KINDS: readonly ExtensionKind[];
-interface IExtension {
-    /** Short (unqualified) extension id, injected by the loader from the leaf folder name. */
-    id: string;
-    /** Owning plugin namespace, injected by the loader from the plugin folder name. */
-    pluginId: string;
-    kind: ExtensionKind;
-    version: string;
-    /** Required short description; surfaced in `sm <kind>s list` and the UI. */
-    description: string;
-    entry?: string;
-}
-/**
- * Compose the qualified registry key for an extension. Single source of
- * truth so callers don't reinvent the format and a future change (e.g. a
- * different separator) lands in one place.
- */
-declare function qualifiedExtensionId(pluginId: string, id: string): string;
-declare class DuplicateExtensionError extends Error {
-    constructor(kind: ExtensionKind, qualifiedId: string);
-}
-declare class Registry {
-    #private;
-    constructor();
-    register(ext: IExtension): void;
-    /**
-     * Lookup by qualified id (`<pluginId>/<id>`). Returns `undefined` when
-     * no extension of that kind is registered under the qualifier.
-     */
-    get(kind: ExtensionKind, qualifiedId: string): IExtension | undefined;
-    /**
-     * Convenience wrapper that composes the qualified id for the caller.
-     * Equivalent to `get(kind, qualifiedExtensionId(pluginId, id))`.
-     */
-    find(kind: ExtensionKind, pluginId: string, id: string): IExtension | undefined;
-    all(kind: ExtensionKind): IExtension[];
-    count(kind: ExtensionKind): number;
-    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, `IAnalyzerContext`, 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>;
-}
-
 /**
  * Closed enum of view slot names. Mirror of
  * `spec/schemas/view-slots.schema.json#/$defs/SlotName`.
@@ -554,13 +470,24 @@ type TSettingValue = string | string[] | boolean | number | ISetting_KeyValueLis
  */
 
 /**
- * Lifecycle label an extension manifest MAY declare. Presentation-only
- * metadata: the non-default values render as a badge next to the
- * extension in `sm plugins list` / `sm plugins show` and the Settings
- * plugins panel, and the kernel never gates behaviour on it (a
- * `deprecated` extension still runs). Default: missing == `stable`,
- * and `stable` (declared or defaulted) renders no badge. Mirrors
+ * Lifecycle label an extension manifest MAY declare. Renders as a badge
+ * next to the extension in `sm plugins list <id>` / `sm plugins show` and
+ * the Settings plugins panel for the non-default values.
+ *
+ * Two values ALSO change behaviour: `experimental` (not ready yet) and
+ * `deprecated` (on its way out) flip the extension's installed default
+ * to DISABLED, so the extension does not load (does not run, does not
+ * register) unless the operator opts in (`sm plugins enable
+ * <plugin>/<ext>`, the Settings toggle, or a `settings.json` /
+ * `config_plugins` override). The opt-in is a plain enable override,
+ * once set it wins over the installed default exactly like any other
+ * extension (so a deprecated extension can still be kept running during
+ * a migration). The remaining values are presentation-only and default
+ * to ENABLED: `beta` runs by default with a badge, `stable` (declared
+ * or defaulted) runs with no badge. Missing == `stable` == enabled, no
+ * badge. Mirrors
  * `spec/schemas/extensions/base.schema.json#/properties/stability`.
+ *
  * Deliberately a superset of the node-level annotations enum (which has
  * no `beta`): this describes the maturity of the extension itself, not
  * of a scanned node.
@@ -620,8 +547,9 @@ interface IExtensionBase {
     description: string;
     /**
      * Optional lifecycle label (`experimental` / `beta` / `stable` /
-     * `deprecated`). Missing == `stable`, no badge rendered. See
-     * `TExtensionStability` for the full semantics.
+     * `deprecated`). Missing == `stable`, no badge rendered. `experimental`
+     * and `deprecated` additionally flip the installed default to disabled.
+     * See `TExtensionStability` for the full semantics.
      */
     stability?: TExtensionStability;
     /**
@@ -657,14 +585,107 @@ interface IExtensionBase {
      * `viewContributions` with the structure-as-truth refactor. Each
      * entry maps a local contribution id (kebab-case, unique within the
      * extension) to an `IViewContribution` that picks a view slot by
-     * name from the closed catalog. Only `extractor` and `analyzer` kinds
-     * may declare this field.
+     * name from the closed catalog. Declared by `extractor` and
+     * `analyzer` kinds (emitted during scan / graph evaluation) and by
+     * `action` kinds (emitted from the Action's scan-time `project()`
+     * self-projection, see `IActionProjectionContext`).
      */
     ui?: Record<string, IViewContribution>;
     /** Runtime-only, absolute path of the extension entry file. */
     entry?: string;
 }
 
+/**
+ * Extension registry, six kinds, first-class, loaded through a single API.
+ *
+ * The `IExtension` shape is aligned with `spec/schemas/extensions/base.schema.json`.
+ * 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.
+ *
+ * **Spec § A.6, qualified ids.** Every extension is keyed in the registry
+ * by `<pluginId>/<id>` (e.g. `core/annotations`, `core/slash-command`,
+ * `my-plugin/my-extractor`). `IExtension.id` carries the **short** id as authored;
+ * `IExtension.pluginId` carries the namespace; the registry composes the
+ * qualifier internally and exposes lookup APIs that operate on either form
+ * (qualified for direct lookup, kind-scoped listing for enumeration).
+ *
+ * Boot invariant: `new Registry()` is empty. `registry.totalCount() === 0`
+ * when the kernel boots with zero extensions. This is the data side of the
+ * `kernel-empty-boot` conformance contract.
+ */
+
+type ExtensionKind = 'provider' | 'extractor' | 'analyzer' | 'action' | 'formatter' | 'hook';
+declare const EXTENSION_KINDS: readonly ExtensionKind[];
+interface IExtension {
+    /** Short (unqualified) extension id, injected by the loader from the leaf folder name. */
+    id: string;
+    /** Owning plugin namespace, injected by the loader from the plugin folder name. */
+    pluginId: string;
+    kind: ExtensionKind;
+    version: string;
+    /** Required short description; surfaced in `sm <kind>s list` and the UI. */
+    description: string;
+    /**
+     * Optional lifecycle label (`IExtensionBase.stability`). Carried on the
+     * registry view so the enabled-resolver can read it: `experimental`
+     * flips an extension's installed default to disabled. Absent == stable.
+     */
+    stability?: TExtensionStability;
+    entry?: string;
+}
+/**
+ * Compose the qualified registry key for an extension. Single source of
+ * truth so callers don't reinvent the format and a future change (e.g. a
+ * different separator) lands in one place.
+ */
+declare function qualifiedExtensionId(pluginId: string, id: string): string;
+declare class DuplicateExtensionError extends Error {
+    constructor(kind: ExtensionKind, qualifiedId: string);
+}
+declare class Registry {
+    #private;
+    constructor();
+    register(ext: IExtension): void;
+    /**
+     * Lookup by qualified id (`<pluginId>/<id>`). Returns `undefined` when
+     * no extension of that kind is registered under the qualifier.
+     */
+    get(kind: ExtensionKind, qualifiedId: string): IExtension | undefined;
+    /**
+     * Convenience wrapper that composes the qualified id for the caller.
+     * Equivalent to `get(kind, qualifiedExtensionId(pluginId, id))`.
+     */
+    find(kind: ExtensionKind, pluginId: string, id: string): IExtension | undefined;
+    all(kind: ExtensionKind): IExtension[];
+    count(kind: ExtensionKind): number;
+    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, `IAnalyzerContext`, 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>;
+}
+
 /**
  * Domain types, byte-aligned with `spec/schemas/{node,link,issue,scan-result}.schema.json`.
  *
@@ -897,6 +918,16 @@ interface Node {
     externalRefs?: IExternalRef[];
     frontmatter?: Record<string, unknown>;
     tokens?: TripleSplit;
+    /**
+     * File modification time (`mtime`) in Unix milliseconds, captured at
+     * scan time from the on-disk `lstat`. Absent for virtual / derived
+     * nodes (`virtual === true`, no backing file) and for nodes built by a
+     * Provider `walk()` that does not stat its sources. Persisted to
+     * `scan_nodes.modified_at_ms` and surfaced on `/api/nodes` /
+     * `/api/scan` so the UI can show and sort a "last modified" column.
+     * NOT content: never participates in `bodyHash` / `frontmatterHash`.
+     */
+    modifiedAtMs?: number;
     /**
      * Step 9.6.2, sidecar denormalisation surface. Populated by the
      * orchestrator at scan time; absent when the orchestrator did not
@@ -2190,6 +2221,15 @@ interface IRawNode {
     frontmatterRaw: string;
     /** Parsed frontmatter, or `{}` when absent / unparseable. */
     frontmatter: Record<string, unknown>;
+    /**
+     * File modification time (`mtime`) in Unix milliseconds, captured by
+     * the kernel walker from the same `lstat` that guards the read (zero
+     * extra syscalls). Threaded onto the persisted `Node` as
+     * `modifiedAtMs`. Optional: a Provider that ships its own `walk()` and
+     * does not stat its sources MAY omit it; virtual / derived nodes carry
+     * no file and never set it.
+     */
+    modifiedAtMs?: number;
     /**
      * Parser diagnostics (audit L1). Populated by the walker when the
      * parser surfaced `IParseIssue` entries (e.g. malformed YAML).
@@ -3126,6 +3166,32 @@ interface IActionContext {
      */
     settings: Record<string, unknown>;
 }
+/**
+ * Read-only graph context handed to an Action's scan-time `project()`
+ * method. Mirrors the Analyzer emit path (`IAnalyzerContext`): the
+ * Action sees the full merged graph (`nodes` + `links`) and emits its
+ * own per-node view contributions via `emitContribution`, supplying the
+ * target node path explicitly because, like the Analyzer, it walks the
+ * whole graph rather than running per-node.
+ *
+ * The contribution is declared in the Action's manifest `ui` map and
+ * passed BY REFERENCE (same object-identity model as Extractor /
+ * Analyzer emit). The orchestrator validates the payload against the
+ * slot's schema at call time, dropping invalid emissions with an
+ * `extension.error` event.
+ *
+ * `project()` is strictly DETERMINISTIC and side-effect-free: no writes,
+ * no runner, no IO. It runs during the scan's contribution phase on
+ * EVERY scan, exactly like an Analyzer's emit path, so its cost is the
+ * same per-scan cost as today's projector analyzers. Even an Action
+ * whose `invoke` is `mode: 'probabilistic'` MUST keep `project()`
+ * deterministic, only `invoke` may be probabilistic.
+ */
+interface IActionProjectionContext {
+    readonly nodes: readonly Node[];
+    readonly links: readonly Link[];
+    emitContribution(nodePath: string, ref: IViewContribution, payload: unknown): void;
+}
 /**
  * Declarative filter applied by `--all` fan-out, UI button gating, and
  * `sm actions show`. Same shape used by Extractor and Analyzer so the
@@ -3182,6 +3248,23 @@ interface IAction extends IExtensionBase {
      * kernel materialises any returned `writes` after the call.
      */
     invoke?: <TInput, TReport>(input: TInput, ctx: IActionContext) => IActionResult<TReport>;
+    /**
+     * Optional scan-time self-projection. When present, the orchestrator
+     * calls it during the contribution phase (right after the analyzer
+     * pass) with read-only graph access, and the Action emits its OWN
+     * `inspector.action.button` (or any declared `ui` contribution) per
+     * node. This replaces the former "projector analyzer" pattern: the
+     * button now lives with the Action that dispatches it, not in a
+     * sibling Analyzer.
+     *
+     * MUST be deterministic and side-effect-free (no writes, no runner,
+     * no IO), exactly like an Analyzer's emit path. The button declares
+     * its own qualified id as `actionId` in the payload. Actions that ship
+     * for the future probabilistic runner / record path leave it absent;
+     * an Action MAY declare both `project` and `invoke` (advertiser +
+     * executor), or only one.
+     */
+    project?(ctx: IActionProjectionContext): void;
 }
 
 /**
@@ -3648,6 +3731,16 @@ interface IScanExtensions {
      * advisory until the job subsystem ships once the job subsystem ships.
      */
     hooks?: IHook[];
+    /**
+     * Optional enabled actions. When supplied, the orchestrator runs the
+     * action-projection pass right after the analyzer pass: every action
+     * carrying a scan-time `project()` self-projection emits its own view
+     * contributions (e.g. `inspector.action.button`) onto the merged
+     * graph. Actions without `project` (only `invoke`) ride along inert.
+     * Absent → no projection pass runs (the gate is the composed enabled
+     * set, so a disabled / experimental action never reaches here).
+     */
+    actions?: IAction[];
 }
 interface RunScanOptions {
     /**