@skill-map/cli 0.18.0 → 0.20.0

package/dist/index.js

@@ -28,7 +28,7 @@ function tx(template, vars = {}) {
 var EXTENSION_KINDS = Object.freeze([
   "provider",
   "extractor",
-  "rule",
+  "analyzer",
   "action",
   "formatter",
   "hook"
@@ -103,7 +103,7 @@ import yaml4 from "js-yaml";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.18.0",
+  version: "0.20.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -169,7 +169,7 @@ var package_default = {
   },
   dependencies: {
     "@hono/node-server": "2.0.1",
-    "@skill-map/spec": "0.18.0",
+    "@skill-map/spec": "0.20.0",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
@@ -263,15 +263,15 @@ function readSidecarFor(mdAbsolutePath) {
     };
   }
   const root = parsedYaml;
-  const forBlock = root["for"];
+  const identityBlock = root["identity"];
   const annotationsRaw = root["annotations"];
   const annotations = isPlainObject(annotationsRaw) ? Object.keys(annotationsRaw).length === 0 ? null : annotationsRaw : null;
   return {
     parsed: {
       filePath: sidecarPath,
-      forBodyHash: String(forBlock["bodyHash"]),
-      forFrontmatterHash: String(forBlock["frontmatterHash"]),
-      forPath: String(forBlock["path"]),
+      identityBodyHash: String(identityBlock["bodyHash"]),
+      identityFrontmatterHash: String(identityBlock["frontmatterHash"]),
+      identityPath: String(identityBlock["path"]),
       annotations,
       raw: root
     },
@@ -508,18 +508,20 @@ function formatAjvErrors(errors) {
 
 // kernel/extensions/hook.ts
 var HOOK_TRIGGERS = Object.freeze([
+  "boot",
   "scan.started",
   "scan.completed",
   "extractor.completed",
-  "rule.completed",
+  "analyzer.completed",
   "action.completed",
   "job.spawning",
   "job.completed",
-  "job.failed"
+  "job.failed",
+  "shutdown"
 ]);
 
 // kernel/adapters/plugin-loader.ts
-var KNOWN_KINDS = /* @__PURE__ */ new Set(["provider", "extractor", "rule", "action", "formatter", "hook"]);
+var KNOWN_KINDS = /* @__PURE__ */ new Set(["provider", "extractor", "analyzer", "action", "formatter", "hook"]);
 var KNOWN_KINDS_LIST = [...KNOWN_KINDS].join(" / ");
 var HOOKABLE_TRIGGERS_LIST = HOOK_TRIGGERS.join(", ");
 function installedSpecVersion() {
@@ -535,6 +537,135 @@ import { readFileSync as readFileSync4 } from "fs";
 import { dirname as dirname3, resolve as resolve4 } from "path";
 import { createRequire as createRequire4 } from "module";
 import { Ajv2020 as Ajv20204 } from "ajv/dist/2020.js";
+var SCHEMA_FILES = {
+  node: "schemas/node.schema.json",
+  link: "schemas/link.schema.json",
+  issue: "schemas/issue.schema.json",
+  "scan-result": "schemas/scan-result.schema.json",
+  "execution-record": "schemas/execution-record.schema.json",
+  "project-config": "schemas/project-config.schema.json",
+  "plugins-registry": "schemas/plugins-registry.schema.json",
+  job: "schemas/job.schema.json",
+  "report-base": "schemas/report-base.schema.json",
+  "conformance-case": "schemas/conformance-case.schema.json",
+  "history-stats": "schemas/history-stats.schema.json",
+  "extension-provider": "schemas/extensions/provider.schema.json",
+  "extension-extractor": "schemas/extensions/extractor.schema.json",
+  "extension-analyzer": "schemas/extensions/analyzer.schema.json",
+  "extension-action": "schemas/extensions/action.schema.json",
+  "extension-formatter": "schemas/extensions/formatter.schema.json",
+  "extension-hook": "schemas/extensions/hook.schema.json",
+  "frontmatter-base": "schemas/frontmatter/base.schema.json"
+};
+var SUPPORTING_SCHEMAS = [
+  "schemas/extensions/base.schema.json",
+  "schemas/frontmatter/base.schema.json",
+  "schemas/summaries/security-scanner.schema.json",
+  "schemas/view-slots.schema.json",
+  "schemas/input-types.schema.json"
+];
+var cachedValidators = null;
+function loadSchemaValidators() {
+  if (cachedValidators !== null) return cachedValidators;
+  cachedValidators = buildSchemaValidators();
+  return cachedValidators;
+}
+function buildSchemaValidators() {
+  const specRoot = resolveSpecRoot2();
+  const ajv = new Ajv20204({
+    strict: false,
+    allErrors: true,
+    allowUnionTypes: true
+  });
+  applyAjvFormats(ajv);
+  for (const rel of SUPPORTING_SCHEMAS) {
+    const file = resolve4(specRoot, rel);
+    if (!existsSyncSafe(file)) continue;
+    const schema = JSON.parse(readFileSync4(file, "utf8"));
+    ajv.addSchema(schema);
+  }
+  const validators = /* @__PURE__ */ new Map();
+  for (const [name, rel] of Object.entries(SCHEMA_FILES)) {
+    const file = resolve4(specRoot, rel);
+    const schema = JSON.parse(readFileSync4(file, "utf8"));
+    const byId = typeof schema.$id === "string" ? ajv.getSchema(schema.$id) : void 0;
+    validators.set(name, byId ?? ajv.compile(schema));
+  }
+  const extensionByKind = {
+    provider: "extension-provider",
+    extractor: "extension-extractor",
+    analyzer: "extension-analyzer",
+    action: "extension-action",
+    formatter: "extension-formatter",
+    hook: "extension-hook"
+  };
+  const pluginManifestValidator = ajv.compile({
+    $ref: "https://skill-map.dev/spec/v0/plugins-registry.schema.json#/$defs/PluginManifest"
+  });
+  const contributionValidators = /* @__PURE__ */ new Map();
+  const VIEW_SLOTS_ID = "https://skill-map.dev/spec/v0/view-slots.schema.json";
+  const KNOWN_SLOTS = /* @__PURE__ */ new Set([
+    "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"
+  ]);
+  function getContributionValidator(slot) {
+    if (!KNOWN_SLOTS.has(slot)) return null;
+    const existing = contributionValidators.get(slot);
+    if (existing) return existing;
+    const ref = `${VIEW_SLOTS_ID}#/$defs/payloads/${slot}`;
+    let compiled;
+    try {
+      compiled = ajv.compile({ $ref: ref });
+    } catch {
+      return null;
+    }
+    contributionValidators.set(slot, compiled);
+    return compiled;
+  }
+  return {
+    getValidator(name) {
+      const v = validators.get(name);
+      if (!v) throw new Error(`Unknown schema: ${name}`);
+      return v;
+    },
+    validatorForExtension(kind) {
+      return validators.get(extensionByKind[kind]);
+    },
+    validate(name, data) {
+      const v = validators.get(name);
+      if (!v) throw new Error(`Unknown schema: ${name}`);
+      if (v(data)) return { ok: true, data };
+      const errors = (v.errors ?? []).map(formatError).join("; ");
+      return { ok: false, errors };
+    },
+    validatePluginManifest(data) {
+      if (pluginManifestValidator(data)) return { ok: true, data };
+      const errors = (pluginManifestValidator.errors ?? []).map(formatError).join("; ");
+      return { ok: false, errors };
+    },
+    validateContributionPayload(slot, payload) {
+      const validator = getContributionValidator(slot);
+      if (!validator) {
+        return { ok: false, errors: "unknown-slot" };
+      }
+      if (validator(payload)) return { ok: true };
+      const errors = (validator.errors ?? []).map(formatError).join("; ");
+      return { ok: false, errors };
+    }
+  };
+}
 function buildProviderFrontmatterValidator(providers) {
   const specRoot = resolveSpecRoot2();
   const ajv = new Ajv20204({
@@ -592,6 +723,14 @@ function resolveSpecRoot2() {
     );
   }
 }
+function existsSyncSafe(path) {
+  try {
+    readFileSync4(path, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // kernel/i18n/orchestrator.texts.ts
 var ORCHESTRATOR_TEXTS = {
@@ -600,7 +739,9 @@ var ORCHESTRATOR_TEXTS = {
   frontmatterMalformedByteOrderMark: "Frontmatter fence in {{path}} is preceded by a UTF-8 byte-order mark (BOM); the file was scanned as body-only. Re-save the file as UTF-8 without BOM. The metadata block was silently lost.",
   frontmatterMalformedMissingClose: "Frontmatter in {{path}} opens with `---` but never closes \u2014 no matching `---` line at column 0 was found. The file was scanned as body-only and every metadata field was silently lost. Add a closing `---` line below the metadata block.",
   extensionErrorLinkKindNotDeclared: 'Extractor "{{extractorId}}" emitted a link of kind "{{linkKind}}" outside its declared `emitsLinkKinds` set [{{declaredKinds}}]. Link dropped.',
-  extensionErrorIssueInvalidSeverity: `Rule "{{ruleId}}" emitted an issue with invalid severity {{severity}} (allowed: 'error' | 'warn' | 'info'). Issue dropped.`,
+  extensionErrorIssueInvalidSeverity: `Rule "{{analyzerId}}" emitted an issue with invalid severity {{severity}} (allowed: 'error' | 'warn' | 'info'). Issue dropped.`,
+  extensionErrorContributionUnknownId: 'Extractor "{{extractorId}}" emitted contribution "{{contributionId}}" on {{nodePath}} but did not declare it in its `viewContributions` map. Contribution dropped.',
+  extensionErrorContributionPayloadInvalid: 'Extractor "{{extractorId}}" emitted contribution "{{contributionId}}" on {{nodePath}}; payload failed the "{{slot}}" schema: {{errors}}. Contribution dropped.',
   runScanRootEmptyArray: "runScan: roots must contain at least one path (spec requires minItems: 1)",
   runScanRootMissing: "runScan: root path '{{root}}' does not exist or is not a directory"
 };
@@ -667,7 +808,7 @@ function readDefaultsFromDisk() {
   return "";
 }
 
-// kernel/scan/parsers/frontmatter-yaml.ts
+// built-in-plugins/parsers/frontmatter-yaml/index.ts
 import yaml3 from "js-yaml";
 var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 var FORBIDDEN_FRONTMATTER_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
@@ -693,7 +834,7 @@ var frontmatterYamlParser = {
   }
 };
 
-// kernel/scan/parsers/plain.ts
+// built-in-plugins/parsers/plain/index.ts
 var plainParser = {
   id: "plain",
   parse(raw, _path) {
@@ -794,6 +935,85 @@ function resolveProviderWalk(provider) {
   };
 }
 
+// kernel/extensions/hook-dispatcher.ts
+function makeHookDispatcher(hooks, emitter) {
+  if (hooks.length === 0) {
+    return { dispatch: async () => {
+    } };
+  }
+  const byTrigger = /* @__PURE__ */ new Map();
+  for (const hook of hooks) {
+    if (hook.mode === "probabilistic") {
+      const qualifiedId = qualifiedExtensionId(hook.pluginId, hook.id);
+      log.warn(
+        `Probabilistic hook ${qualifiedId} deferred to job subsystem (future job subsystem). The hook is registered but will not dispatch in-scan.`,
+        { hookId: qualifiedId, mode: "probabilistic" }
+      );
+      continue;
+    }
+    for (const trig of hook.triggers) {
+      const bucket = byTrigger.get(trig);
+      if (bucket) bucket.push(hook);
+      else byTrigger.set(trig, [hook]);
+    }
+  }
+  return {
+    async dispatch(trigger, event) {
+      const subs = byTrigger.get(trigger);
+      if (!subs || subs.length === 0) return;
+      for (const hook of subs) {
+        if (!matchesFilter(hook, event)) continue;
+        const ctx = buildHookContext(hook, trigger, event);
+        try {
+          await hook.on(ctx);
+        } catch (err) {
+          const qualifiedId = qualifiedExtensionId(hook.pluginId, hook.id);
+          const message = formatErrorMessage(err);
+          emitter.emit(
+            makeEvent("extension.error", {
+              kind: "hook-error",
+              extensionId: qualifiedId,
+              trigger,
+              message
+            })
+          );
+        }
+      }
+    }
+  };
+}
+function makeEvent(type, data) {
+  return { type, timestamp: (/* @__PURE__ */ new Date()).toISOString(), data };
+}
+function matchesFilter(hook, event) {
+  if (!hook.filter) return true;
+  const data = event.data ?? {};
+  for (const [key, expected] of Object.entries(hook.filter)) {
+    if (data[key] !== expected) return false;
+  }
+  return true;
+}
+function buildHookContext(_hook, trigger, event) {
+  const data = event.data ?? {};
+  const ctx = {
+    event: {
+      type: trigger,
+      timestamp: event.timestamp,
+      ...event.runId !== void 0 ? { runId: event.runId } : {},
+      ...event.jobId !== void 0 ? { jobId: event.jobId } : {},
+      data: event.data
+    }
+  };
+  if (typeof data["extractorId"] === "string") ctx.extractorId = data["extractorId"];
+  if (typeof data["analyzerId"] === "string") ctx.analyzerId = data["analyzerId"];
+  if (typeof data["actionId"] === "string") ctx.actionId = data["actionId"];
+  if (data["node"] && typeof data["node"] === "object") {
+    ctx.node = data["node"];
+  }
+  if (data["jobResult"] !== void 0) ctx.jobResult = data["jobResult"];
+  return ctx;
+}
+
 // kernel/orchestrator.ts
 var SCANNED_BY = {
   name: "skill-map",
@@ -819,7 +1039,7 @@ async function runScanInternal(_kernel, options) {
   const start = Date.now();
   const scannedAt = start;
   const emitter = options.emitter ?? new InMemoryProgressEmitter();
-  const exts = options.extensions ?? { providers: [], extractors: [], rules: [] };
+  const exts = options.extensions ?? { providers: [], extractors: [], analyzers: [] };
   const hookDispatcher = makeHookDispatcher(exts.hooks ?? [], emitter);
   const tokenize = options.tokenize !== false;
   const scope = options.scope ?? "project";
@@ -856,16 +1076,28 @@ async function runScanInternal(_kernel, options) {
     emitter.emit(evt);
     await hookDispatcher.dispatch("extractor.completed", evt);
   }
-  const issues = await runRules(
-    exts.rules,
+  const analyzerResult = await runAnalyzers(
+    exts.analyzers,
     walked.nodes,
     walked.internalLinks,
     walked.orphanSidecars,
     walked.sidecarRoots,
     options.annotationContributions ?? [],
+    options.viewContributions ?? [],
+    options.orphanJobFiles ?? [],
+    options.referenceablePaths,
+    options.cwd,
     emitter,
     hookDispatcher
   );
+  const issues = analyzerResult.issues;
+  for (const c of analyzerResult.contributions) walked.contributions.push(c);
+  for (const analyzer of exts.analyzers ?? []) {
+    if (analyzer.viewContributions === void 0) continue;
+    for (const node of walked.nodes) {
+      walked.freshlyRunTuples.add(`${analyzer.pluginId}/${analyzer.id}/${node.path}`);
+    }
+  }
   for (const issue of walked.frontmatterIssues) issues.push(issue);
   const renameOps = prior ? detectRenamesAndOrphans(prior, walked.nodes, issues) : [];
   const stats = {
@@ -899,7 +1131,9 @@ async function runScanInternal(_kernel, options) {
     },
     renameOps,
     extractorRuns: walked.extractorRuns,
-    enrichments: walked.enrichments
+    enrichments: walked.enrichments,
+    contributions: walked.contributions,
+    freshlyRunTuples: walked.freshlyRunTuples
   };
 }
 function validateRoots(roots) {
@@ -931,7 +1165,7 @@ function indexPriorSnapshot(prior) {
     else priorLinksByOriginating.set(key, [link]);
   }
   for (const issue of prior.issues) {
-    if (issue.ruleId !== "frontmatter-invalid" && issue.ruleId !== "frontmatter-malformed") continue;
+    if (issue.analyzerId !== "frontmatter-invalid" && issue.analyzerId !== "frontmatter-malformed") continue;
     if (issue.nodeIds.length !== 1) continue;
     const path = issue.nodeIds[0];
     const list = priorFrontmatterIssuesByNode.get(path);
@@ -944,9 +1178,10 @@ async function runExtractorsForNode(opts) {
   const internalLinks = [];
   const externalLinks = [];
   const enrichmentBuffer = /* @__PURE__ */ new Map();
+  const contributions = [];
+  const validators = loadSchemaValidators();
   for (const extractor of opts.extractors) {
     const qualifiedId = qualifiedExtensionId(extractor.pluginId, extractor.id);
-    const isProb = extractor.mode === "probabilistic";
     const emitLink = (link) => {
       const validated = validateLink(extractor, link, opts.emitter);
       if (!validated) return;
@@ -966,9 +1201,54 @@ async function runExtractorsForNode(opts) {
           bodyHashAtEnrichment: opts.bodyHash,
           value: { ...partial },
           enrichedAt: Date.now(),
-          isProbabilistic: isProb
+          // Extractors are deterministic-only; `is_probabilistic` is
+          // reserved on the row for future Action-issued enrichments.
+          isProbabilistic: false
+        });
+      }
+    };
+    const declaredContributions = readDeclaredContributions(extractor);
+    const emitContribution = (contributionId, payload) => {
+      const declared = declaredContributions.get(contributionId);
+      if (!declared) {
+        emitExtensionError(opts.emitter, qualifiedId, opts.node.path, {
+          phase: "emitContribution",
+          contributionId,
+          reason: "unknown-contribution-id",
+          message: tx(ORCHESTRATOR_TEXTS.extensionErrorContributionUnknownId, {
+            extractorId: qualifiedId,
+            contributionId,
+            nodePath: opts.node.path
+          })
+        });
+        return;
+      }
+      const result = validators.validateContributionPayload(declared.slot, payload);
+      if (!result.ok) {
+        emitExtensionError(opts.emitter, qualifiedId, opts.node.path, {
+          phase: "emitContribution",
+          contributionId,
+          slot: declared.slot,
+          reason: result.errors,
+          message: tx(ORCHESTRATOR_TEXTS.extensionErrorContributionPayloadInvalid, {
+            extractorId: qualifiedId,
+            contributionId,
+            nodePath: opts.node.path,
+            slot: declared.slot,
+            errors: result.errors
+          })
         });
+        return;
       }
+      contributions.push({
+        pluginId: extractor.pluginId,
+        extensionId: extractor.id,
+        nodePath: opts.node.path,
+        contributionId,
+        slot: declared.slot,
+        payload,
+        emittedAt: Date.now()
+      });
     };
     const store = opts.pluginStores?.get(extractor.pluginId);
     const ctx = buildExtractorContext(
@@ -978,6 +1258,7 @@ async function runExtractorsForNode(opts) {
       opts.frontmatter,
       emitLink,
       enrichNode,
+      emitContribution,
       store
     );
     await extractor.extract(ctx);
@@ -985,9 +1266,32 @@ async function runExtractorsForNode(opts) {
   return {
     internalLinks,
     externalLinks,
-    enrichments: Array.from(enrichmentBuffer.values())
+    enrichments: Array.from(enrichmentBuffer.values()),
+    contributions
   };
 }
+function readDeclaredContributions(extension) {
+  const out = /* @__PURE__ */ new Map();
+  const raw = extension.viewContributions;
+  if (typeof raw !== "object" || raw === null) return out;
+  for (const [id, value] of Object.entries(raw)) {
+    if (typeof value !== "object" || value === null) continue;
+    const slot = value.slot;
+    if (typeof slot !== "string") continue;
+    out.set(id, { slot });
+  }
+  return out;
+}
+function emitExtensionError(emitter, qualifiedId, nodePath, data) {
+  emitter.emit(
+    makeEvent("extension.error", {
+      kind: "contribution-rejected",
+      extensionId: qualifiedId,
+      nodePath,
+      ...data
+    })
+  );
+}
 function computeCacheDecision(opts) {
   const applicableExtractors = opts.extractors.filter(
     (ex) => ex.applicableKinds === void 0 || ex.applicableKinds.includes(opts.kind)
@@ -1110,6 +1414,8 @@ async function walkAndExtract(opts) {
   const cachedPaths = /* @__PURE__ */ new Set();
   const frontmatterIssues = [];
   const enrichmentBuffer = /* @__PURE__ */ new Map();
+  const contributionsBuffer = [];
+  const freshlyRunTuples = /* @__PURE__ */ new Set();
   const extractorRuns = [];
   const sidecarRoots = /* @__PURE__ */ new Map();
   let filesWalked = 0;
@@ -1122,9 +1428,11 @@ async function walkAndExtract(opts) {
     if (list) list.push(qualified);
     else shortIdToQualified.set(ex.id, [qualified]);
   }
+  const claimedPaths = /* @__PURE__ */ new Set();
   for (const provider of providers) {
     for await (const raw of resolveProviderWalk(provider)(roots, walkOptions)) {
       filesWalked += 1;
+      if (claimedPaths.has(raw.path)) continue;
       const bodyHash = sha256(raw.body);
       const frontmatterHash = sha256(canonicalFrontmatter(raw.frontmatter, raw.frontmatterRaw));
       const priorNode = priorNodesByPath.get(raw.path);
@@ -1133,6 +1441,7 @@ async function walkAndExtract(opts) {
       if (kind === null) {
         continue;
       }
+      claimedPaths.add(raw.path);
       index += 1;
       const cacheDecision = computeCacheDecision({
         extractors,
@@ -1160,8 +1469,6 @@ async function walkAndExtract(opts) {
           priorLinksByOriginating,
           priorFrontmatterIssuesByNode
         });
-        reused.node.stability = null;
-        reused.node.version = null;
         const reusedSidecarIssues = resolveAndApplySidecar(
           reused.node,
           raw.path,
@@ -1227,6 +1534,9 @@ async function walkAndExtract(opts) {
         ...partialCacheHit ? { partialCache: true } : {}
       }));
       const extractorsToRun = partialCacheHit ? missingExtractors : applicableExtractors;
+      for (const ex of extractorsToRun) {
+        freshlyRunTuples.add(`${ex.pluginId}/${ex.id}/${node.path}`);
+      }
       const extractResult = await runExtractorsForNode({
         extractors: extractorsToRun,
         node,
@@ -1241,6 +1551,7 @@ async function walkAndExtract(opts) {
       for (const enr of extractResult.enrichments) {
         enrichmentBuffer.set(`${enr.nodePath}\0${enr.extractorId}`, enr);
       }
+      for (const c of extractResult.contributions) contributionsBuffer.push(c);
       const ranAt = Date.now();
       for (const ex of applicableExtractors) {
         const qualified = qualifiedExtensionId(ex.pluginId, ex.id);
@@ -1263,6 +1574,8 @@ async function walkAndExtract(opts) {
     filesWalked,
     enrichments: [...enrichmentBuffer.values()],
     extractorRuns,
+    contributions: contributionsBuffer,
+    freshlyRunTuples,
     orphanSidecars,
     sidecarRoots
   };
@@ -1293,30 +1606,80 @@ function reuseCachedLink(link, shortIdToQualified, cachedQualifiedIds, applicabl
   if (obsoleteSources.length === 0) return link;
   return { ...link, sources: cachedSources };
 }
-async function runRules(rules, nodes, internalLinks, orphanSidecars, sidecarRoots, annotationContributions, emitter, hookDispatcher) {
+async function runAnalyzers(analyzers, nodes, internalLinks, orphanSidecars, sidecarRoots, annotationContributions, viewContributions, orphanJobFiles, referenceablePaths, cwd, emitter, hookDispatcher) {
   const issues = [];
-  const ruleOrphans = orphanSidecars.map((o) => ({
+  const contributions = [];
+  const validators = loadSchemaValidators();
+  const analyzerOrphans = orphanSidecars.map((o) => ({
     relativePath: o.relativePath,
     expectedMdPath: o.expectedMdPath
   }));
-  for (const rule of rules) {
-    const emitted = await rule.evaluate({
+  for (const analyzer of analyzers) {
+    const qualifiedId = qualifiedExtensionId(analyzer.pluginId, analyzer.id);
+    const declaredContributions = readDeclaredContributions(analyzer);
+    const emitContribution = (nodePath, contributionId, payload) => {
+      const declared = declaredContributions.get(contributionId);
+      if (!declared) {
+        emitExtensionError(emitter, qualifiedId, nodePath, {
+          phase: "emitContribution",
+          contributionId,
+          reason: "unknown-contribution-id",
+          message: tx(ORCHESTRATOR_TEXTS.extensionErrorContributionUnknownId, {
+            extractorId: qualifiedId,
+            contributionId,
+            nodePath
+          })
+        });
+        return;
+      }
+      const result = validators.validateContributionPayload(declared.slot, payload);
+      if (!result.ok) {
+        emitExtensionError(emitter, qualifiedId, nodePath, {
+          phase: "emitContribution",
+          contributionId,
+          slot: declared.slot,
+          reason: result.errors,
+          message: tx(ORCHESTRATOR_TEXTS.extensionErrorContributionPayloadInvalid, {
+            extractorId: qualifiedId,
+            contributionId,
+            nodePath,
+            slot: declared.slot,
+            errors: result.errors
+          })
+        });
+        return;
+      }
+      contributions.push({
+        pluginId: analyzer.pluginId,
+        extensionId: analyzer.id,
+        nodePath,
+        contributionId,
+        slot: declared.slot,
+        payload,
+        emittedAt: Date.now()
+      });
+    };
+    const emitted = await analyzer.evaluate({
       nodes,
       links: internalLinks,
-      orphanSidecars: ruleOrphans,
+      orphanSidecars: analyzerOrphans,
       sidecarRoots,
-      annotationContributions
+      annotationContributions,
+      viewContributions,
+      orphanJobFiles,
+      ...referenceablePaths ? { referenceablePaths } : {},
+      ...cwd ? { cwd } : {},
+      emitContribution
     });
     for (const issue of emitted) {
-      const validated = validateIssue(rule, issue, emitter);
+      const validated = validateIssue(analyzer, issue, emitter);
       if (validated) issues.push(validated);
     }
-    const ruleId = qualifiedExtensionId(rule.pluginId, rule.id);
-    const evt = makeEvent("rule.completed", { ruleId });
+    const evt = makeEvent("analyzer.completed", { analyzerId: qualifiedId });
     emitter.emit(evt);
-    await hookDispatcher.dispatch("rule.completed", evt);
+    await hookDispatcher.dispatch("analyzer.completed", evt);
   }
-  return issues;
+  return { issues, contributions };
 }
 function originatingNodeOf(link, priorNodePaths) {
   if (link.kind === "supersedes" && !priorNodePaths.has(link.source)) {
@@ -1370,7 +1733,7 @@ function claimSingletonRenames(opts) {
       const fromPath = remaining[0];
       ops.push({ from: fromPath, to: toPath, confidence: "medium" });
       opts.issues.push({
-        ruleId: "auto-rename-medium",
+        analyzerId: "auto-rename-medium",
         severity: "warn",
         nodeIds: [toPath],
         message: `Auto-rename (medium confidence): ${fromPath} \u2192 ${toPath}`,
@@ -1390,7 +1753,7 @@ function flagAmbiguousRenames(opts) {
     const remaining = candidates.filter((p) => !opts.claimedDeleted.has(p));
     if (remaining.length > 1) {
       opts.issues.push({
-        ruleId: "auto-rename-ambiguous",
+        analyzerId: "auto-rename-ambiguous",
         severity: "warn",
         nodeIds: [toPath],
         message: `Auto-rename ambiguous: ${toPath} matches ${remaining.length} prior frontmatters \u2014 pick one with \`sm orphans undo-rename ${toPath} --from <old.path>\`.`,
@@ -1403,7 +1766,7 @@ function flagOrphans(opts) {
   for (const fromPath of opts.deletedPaths) {
     if (opts.claimedDeleted.has(fromPath)) continue;
     opts.issues.push({
-      ruleId: "orphan",
+      analyzerId: "orphan",
       severity: "info",
       nodeIds: [fromPath],
       message: `Orphan history: ${fromPath} was deleted; no rename match found.`,
@@ -1452,83 +1815,6 @@ var EXTERNAL_URL_SCHEME_RE = /^[a-z][a-z0-9+\-.]+:/i;
 function isExternalUrlLink(link) {
   return EXTERNAL_URL_SCHEME_RE.test(link.target);
 }
-function makeEvent(type, data) {
-  return { type, timestamp: (/* @__PURE__ */ new Date()).toISOString(), data };
-}
-function makeHookDispatcher(hooks, emitter) {
-  if (hooks.length === 0) {
-    return { dispatch: async () => {
-    } };
-  }
-  const byTrigger = /* @__PURE__ */ new Map();
-  for (const hook of hooks) {
-    if (hook.mode === "probabilistic") {
-      const qualifiedId = qualifiedExtensionId(hook.pluginId, hook.id);
-      log.warn(
-        `Probabilistic hook ${qualifiedId} deferred to job subsystem (future job subsystem). The hook is registered but will not dispatch in-scan.`,
-        { hookId: qualifiedId, mode: "probabilistic" }
-      );
-      continue;
-    }
-    for (const trig of hook.triggers) {
-      const bucket = byTrigger.get(trig);
-      if (bucket) bucket.push(hook);
-      else byTrigger.set(trig, [hook]);
-    }
-  }
-  return {
-    async dispatch(trigger, event) {
-      const subs = byTrigger.get(trigger);
-      if (!subs || subs.length === 0) return;
-      for (const hook of subs) {
-        if (!matchesFilter(hook, event)) continue;
-        const ctx = buildHookContext(hook, trigger, event);
-        try {
-          await hook.on(ctx);
-        } catch (err) {
-          const qualifiedId = qualifiedExtensionId(hook.pluginId, hook.id);
-          const message = formatErrorMessage(err);
-          emitter.emit(
-            makeEvent("extension.error", {
-              kind: "hook-error",
-              extensionId: qualifiedId,
-              trigger,
-              message
-            })
-          );
-        }
-      }
-    }
-  };
-}
-function matchesFilter(hook, event) {
-  if (!hook.filter) return true;
-  const data = event.data ?? {};
-  for (const [key, expected] of Object.entries(hook.filter)) {
-    if (data[key] !== expected) return false;
-  }
-  return true;
-}
-function buildHookContext(_hook, trigger, event) {
-  const data = event.data ?? {};
-  const ctx = {
-    event: {
-      type: trigger,
-      timestamp: event.timestamp,
-      ...event.runId !== void 0 ? { runId: event.runId } : {},
-      ...event.jobId !== void 0 ? { jobId: event.jobId } : {},
-      data: event.data
-    }
-  };
-  if (typeof data["extractorId"] === "string") ctx.extractorId = data["extractorId"];
-  if (typeof data["ruleId"] === "string") ctx.ruleId = data["ruleId"];
-  if (typeof data["actionId"] === "string") ctx.actionId = data["actionId"];
-  if (data["node"] && typeof data["node"] === "object") {
-    ctx.node = data["node"];
-  }
-  if (data["jobResult"] !== void 0) ctx.jobResult = data["jobResult"];
-  return ctx;
-}
 function buildNode(args) {
   const bytesFrontmatter = Buffer.byteLength(args.frontmatterRaw, "utf8");
   const bytesBody = Buffer.byteLength(args.body, "utf8");
@@ -1546,11 +1832,7 @@ function buildNode(args) {
     linksOutCount: 0,
     linksInCount: 0,
     externalRefsCount: 0,
-    frontmatter: args.frontmatter,
-    title: pickString(args.frontmatter["name"]),
-    description: pickString(args.frontmatter["description"]),
-    stability: null,
-    version: null
+    frontmatter: args.frontmatter
   };
   if (args.encoder) {
     node.tokens = countTokens(args.encoder, args.frontmatterRaw, args.body);
@@ -1594,7 +1876,7 @@ function resolveAndApplySidecar(node, relativePath, roots, liveBodyHash, liveFro
     node.sidecar = { present: true, status: null, annotations: null, root: null };
     for (const parseIssue of result.issues) {
       issues.push({
-        ruleId: "invalid-sidecar",
+        analyzerId: "invalid-sidecar",
         severity: "warn",
         nodeIds: [node.path],
         message: parseIssue.message,
@@ -1604,12 +1886,11 @@ function resolveAndApplySidecar(node, relativePath, roots, liveBodyHash, liveFro
     return issues;
   }
   const status = computeDriftStatus({
-    storedBodyHash: result.parsed.forBodyHash,
-    storedFrontmatterHash: result.parsed.forFrontmatterHash,
+    storedBodyHash: result.parsed.identityBodyHash,
+    storedFrontmatterHash: result.parsed.identityFrontmatterHash,
     liveBodyHash,
     liveFrontmatterHash
   });
-  applyAnnotationsOverlay(node, result.parsed);
   node.sidecar = {
     present: true,
     status,
@@ -1619,18 +1900,6 @@ function resolveAndApplySidecar(node, relativePath, roots, liveBodyHash, liveFro
   sidecarRoots.set(node.path, result.parsed.raw);
   return issues;
 }
-function applyAnnotationsOverlay(node, parsed) {
-  const annotations = parsed.annotations;
-  if (annotations === null) return;
-  const stability = annotations["stability"];
-  if (stability === "experimental" || stability === "stable" || stability === "deprecated") {
-    node.stability = stability;
-  }
-  const version = annotations["version"];
-  if (typeof version === "number" && Number.isInteger(version) && version >= 1) {
-    node.version = version;
-  }
-}
 function resolveAbsoluteMdPath(relativePath, roots) {
   if (isAbsolute2(relativePath)) {
     return existsSync6(relativePath) ? relativePath : null;
@@ -1650,10 +1919,7 @@ function relativePathFromRoots(absolutePath, roots) {
   }
   return absolutePath;
 }
-function pickString(value) {
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-function buildExtractorContext(extractor, node, body, frontmatter, emitLink, enrichNode, store) {
+function buildExtractorContext(extractor, node, body, frontmatter, emitLink, enrichNode, emitContribution, store) {
   const scope = extractor.scope;
   return {
     node,
@@ -1661,6 +1927,7 @@ function buildExtractorContext(extractor, node, body, frontmatter, emitLink, enr
     frontmatter: scope === "body" ? {} : frontmatter,
     emitLink,
     enrichNode,
+    emitContribution,
     ...store !== void 0 ? { store } : {}
   };
 }
@@ -1690,7 +1957,7 @@ function validateFrontmatter(providerFrontmatter, provider, kind, frontmatter, p
   const result = providerFrontmatter.validate(provider, kind, frontmatter);
   if (result.ok) return null;
   return {
-    ruleId: "frontmatter-invalid",
+    analyzerId: "frontmatter-invalid",
     severity: strict ? "error" : "warn",
     nodeIds: [path],
     message: tx(ORCHESTRATOR_TEXTS.frontmatterInvalid, { path, kind, errors: result.errors }),
@@ -1701,7 +1968,7 @@ function detectMalformedFrontmatter(body, path, strict) {
   const hint = classifyMalformedFrontmatter(body);
   if (!hint) return null;
   return {
-    ruleId: "frontmatter-malformed",
+    analyzerId: "frontmatter-malformed",
     severity: strict ? "error" : "warn",
     nodeIds: [path],
     message: malformedMessage(hint, path),
@@ -1735,25 +2002,25 @@ function malformedMessage(hint, path) {
       return tx(ORCHESTRATOR_TEXTS.frontmatterMalformedMissingClose, { path });
   }
 }
-function validateIssue(rule, issue, emitter) {
+function validateIssue(analyzer, issue, emitter) {
   const severity = issue.severity;
   if (severity !== "error" && severity !== "warn" && severity !== "info") {
-    const qualifiedId = `${rule.pluginId}/${rule.id}`;
+    const qualifiedId = `${analyzer.pluginId}/${analyzer.id}`;
     emitter.emit(
       makeEvent("extension.error", {
         kind: "issue-invalid-severity",
         extensionId: qualifiedId,
         severity,
-        issue: { ruleId: issue.ruleId || rule.id, message: issue.message, nodeIds: issue.nodeIds },
+        issue: { analyzerId: issue.analyzerId || analyzer.id, message: issue.message, nodeIds: issue.nodeIds },
         message: tx(ORCHESTRATOR_TEXTS.extensionErrorIssueInvalidSeverity, {
-          ruleId: qualifiedId,
+          analyzerId: qualifiedId,
           severity: JSON.stringify(severity)
         })
       })
     );
     return null;
   }
-  return { ...issue, ruleId: issue.ruleId || rule.id };
+  return { ...issue, analyzerId: issue.analyzerId || analyzer.id };
 }
 function recomputeLinkCounts(nodes, links) {
   const byPath2 = /* @__PURE__ */ new Map();
@@ -1990,10 +2257,10 @@ function diffIssues(priorIssues, currentIssues) {
 }
 function issueIdentity(issue) {
   const ids = [...issue.nodeIds].sort().join(",");
-  return `${issue.ruleId}\0${ids}\0${issue.message}`;
+  return `${issue.analyzerId}\0${ids}\0${issue.message}`;
 }
 function byIssueSort(a, b) {
-  if (a.ruleId !== b.ruleId) return a.ruleId.localeCompare(b.ruleId);
+  if (a.analyzerId !== b.analyzerId) return a.analyzerId.localeCompare(b.analyzerId);
   return a.message.localeCompare(b.message);
 }
 
@@ -2149,6 +2416,7 @@ function parseLogLevel(value) {
 // kernel/index.ts
 function createKernel() {
   let annotationKeys = Object.freeze([]);
+  let viewContributions = Object.freeze([]);
   return {
     registry: new Registry(),
     getRegisteredAnnotationKeys() {
@@ -2156,6 +2424,12 @@ function createKernel() {
     },
     setRegisteredAnnotationKeys(entries) {
       annotationKeys = Object.freeze([...entries]);
+    },
+    getRegisteredViewContributions() {
+      return viewContributions;
+    },
+    setRegisteredViewContributions(entries) {
+      viewContributions = Object.freeze([...entries]);
     }
   };
 }
@@ -2181,6 +2455,8 @@ export {
   log,
   logLevelRank,
   makeDedicatedStoreWrapper,
+  makeEvent,
+  makeHookDispatcher,
   makeKvStoreWrapper,
   makePluginStore,
   mergeNodeWithEnrichments,