@skill-map/cli 0.61.5 → 0.62.0

package/dist/kernel/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]="5077263a-bf07-58af-b37d-ea6ab8f9a27c")}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]="ca2610ab-aae0-5366-8634-73a2d8fd3eda")}catch(e){}}();
 var REGISTRY_TEXTS = {
   duplicateExtension: "Extension already registered: {{kind}}:{{qualifiedId}}",
   unknownKind: "Unknown extension kind: {{kind}}",
@@ -96,13 +96,13 @@ var Registry = class {
 
 // kernel/orchestrator/index.ts
 import { existsSync as existsSync10, statSync as statSync4 } from "fs";
-import { isAbsolute as isAbsolute3, resolve as resolve9 } from "path";
+import { isAbsolute as isAbsolute5, resolve as resolve11 } from "path";
 import { Tiktoken as Tiktoken2 } from "js-tiktoken/lite";
 
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.61.5",
+  version: "0.62.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -2155,9 +2155,12 @@ function detectRenamesAndOrphans(prior, current, issues, silenced) {
   return ops;
 }
 
+// kernel/orchestrator/walk.ts
+import { isAbsolute as isAbsolute4, resolve as resolve10 } from "path";
+
 // kernel/scan/walk-content.ts
 import { readFile, readdir, lstat } from "fs/promises";
-import { join as join4, relative as relative2, sep } from "path";
+import { isAbsolute as isAbsolute2, join as join4, relative as relative2, resolve as resolve7, sep } from "path";
 
 // kernel/scan/ignore.ts
 import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
@@ -2336,33 +2339,116 @@ async function* walkContent(roots, options) {
   const filter = options.ignoreFilter ?? buildIgnoreFilter();
   const extensions = options.extensions;
   const sizeLimit = buildSizeLimit(options);
+  if (options.scopedPaths !== void 0) {
+    yield* walkScoped(roots, options.scopedPaths, extensions, sizeLimit, parser);
+    return;
+  }
   for (const root of roots) {
     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(entry.full, "utf8");
-      } catch {
-        continue;
-      }
-      const parsed = parser.parse(raw, relPath);
-      yield {
-        path: relPath,
-        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
-        // when the parser reported no issues (happy path).
-        ...parsed.issues && parsed.issues.length > 0 ? { parseIssues: parsed.issues } : {}
-      };
+      const rec = await traversedEntryToNode(entry, relPath, options.priorMtimes, parser);
+      if (rec !== null) yield rec;
     }
   }
 }
+async function traversedEntryToNode(entry, relPath, priorMtimes, parser) {
+  const priorMtime = priorMtimes?.get(relPath);
+  if (priorMtime !== void 0 && priorMtime === entry.modifiedAtMs) {
+    return buildUnchangedRecord(entry.full, relPath, entry.modifiedAtMs, parser);
+  }
+  const parsed = await readAndParse(entry.full, relPath, parser);
+  if (parsed === null) return null;
+  return {
+    path: relPath,
+    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
+    // when the parser reported no issues (happy path).
+    ...parsed.parseIssues ? { parseIssues: parsed.parseIssues } : {}
+  };
+}
+function buildUnchangedRecord(full, relPath, modifiedAtMs, parser) {
+  return {
+    path: relPath,
+    body: "",
+    frontmatterRaw: "",
+    frontmatter: {},
+    modifiedAtMs,
+    unchanged: true,
+    reread: async () => {
+      const re = await readAndParse(full, relPath, parser);
+      return re ?? { body: "", frontmatterRaw: "", frontmatter: {} };
+    }
+  };
+}
+async function* walkScoped(roots, scopedPaths, extensions, sizeLimit, parser) {
+  const absRoots = roots.map((r) => isAbsolute2(r) ? r : resolve7(r));
+  for (const scoped of scopedPaths) {
+    const rec = await scopedPathToNode(scoped, absRoots, extensions, sizeLimit, parser);
+    if (rec !== null) yield rec;
+  }
+}
+async function scopedPathToNode(scoped, absRoots, extensions, sizeLimit, parser) {
+  const full = isAbsolute2(scoped) ? scoped : resolve7(scoped);
+  const relPath = relativeFromRoots(full, absRoots);
+  if (relPath === null) return null;
+  if (!hasMatchingExtension(full, extensions)) return null;
+  const s = await statRegularFile(full, relPath, sizeLimit);
+  if (s === null) return null;
+  const parsed = await readAndParse(full, relPath, parser);
+  if (parsed === null) return null;
+  return {
+    path: relPath,
+    body: parsed.body,
+    frontmatterRaw: parsed.frontmatterRaw,
+    frontmatter: parsed.frontmatter,
+    modifiedAtMs: Math.round(s.mtimeMs),
+    ...parsed.parseIssues ? { parseIssues: parsed.parseIssues } : {}
+  };
+}
+async function statRegularFile(full, relPath, sizeLimit) {
+  let s;
+  try {
+    s = await lstat(full);
+  } catch {
+    return null;
+  }
+  if (!s.isFile()) return null;
+  if (sizeLimit.maxFileSizeBytes !== void 0 && s.size > sizeLimit.maxFileSizeBytes) {
+    sizeLimit.onOversizedFile?.({ path: relPath, bytes: s.size });
+    return null;
+  }
+  return s;
+}
+function relativeFromRoots(full, absRoots) {
+  for (const root of absRoots) {
+    const rel = relative2(root, full);
+    if (rel === "" || rel.startsWith("..") || isAbsolute2(rel)) continue;
+    return rel.split(sep).join("/");
+  }
+  return null;
+}
+async function readAndParse(full, relPath, parser) {
+  let raw;
+  try {
+    raw = await readFile(full, "utf8");
+  } catch {
+    return null;
+  }
+  const parsed = parser.parse(raw, relPath);
+  return {
+    body: parsed.body,
+    frontmatterRaw: parsed.frontmatterRaw,
+    frontmatter: parsed.frontmatter,
+    ...parsed.issues && parsed.issues.length > 0 ? { parseIssues: parsed.issues } : {}
+  };
+}
 function buildSizeLimit(options) {
   const sizeLimit = {};
   if (options.maxFileSizeBytes !== void 0) {
@@ -2418,23 +2504,29 @@ function resolveProviderWalk(provider) {
     return walk2;
   }
   const read = provider.read ?? DEFAULT_READ_CONFIG;
-  return (roots, options) => {
-    const walkOptions = {
-      extensions: read.extensions,
-      parser: read.parser
-    };
-    if (options?.ignoreFilter) walkOptions.ignoreFilter = options.ignoreFilter;
-    if (options?.maxFileSizeBytes !== void 0) {
-      walkOptions.maxFileSizeBytes = options.maxFileSizeBytes;
-    }
-    if (options?.onOversizedFile) walkOptions.onOversizedFile = options.onOversizedFile;
-    return walkContent(roots, walkOptions);
+  return (roots, options) => walkContent(roots, buildWalkContentOptions(read, options));
+}
+function buildWalkContentOptions(read, options) {
+  const walkOptions = {
+    extensions: read.extensions,
+    parser: read.parser
   };
+  if (options) copyOptionalWalkOptions(walkOptions, options);
+  return walkOptions;
+}
+function copyOptionalWalkOptions(walkOptions, options) {
+  if (options.ignoreFilter) walkOptions.ignoreFilter = options.ignoreFilter;
+  if (options.maxFileSizeBytes !== void 0) {
+    walkOptions.maxFileSizeBytes = options.maxFileSizeBytes;
+  }
+  if (options.onOversizedFile) walkOptions.onOversizedFile = options.onOversizedFile;
+  if (options.priorMtimes) walkOptions.priorMtimes = options.priorMtimes;
+  if (options.scopedPaths) walkOptions.scopedPaths = options.scopedPaths;
 }
 
 // kernel/sidecar/parse.ts
 import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
-import { dirname as dirname4, resolve as resolve7 } from "path";
+import { dirname as dirname4, resolve as resolve8 } from "path";
 import { createRequire as createRequire3 } from "module";
 import { Ajv2020 as Ajv20204 } from "ajv/dist/2020.js";
 import yaml2 from "js-yaml";
@@ -2513,10 +2605,10 @@ function getSidecarValidator() {
   applyAjvFormats(ajv);
   const specRoot = resolveSpecRoot2();
   const annotationsSchema = JSON.parse(
-    readFileSync6(resolve7(specRoot, "schemas/annotations.schema.json"), "utf8")
+    readFileSync6(resolve8(specRoot, "schemas/annotations.schema.json"), "utf8")
   );
   const sidecarSchema = JSON.parse(
-    readFileSync6(resolve7(specRoot, "schemas/sidecar.schema.json"), "utf8")
+    readFileSync6(resolve8(specRoot, "schemas/sidecar.schema.json"), "utf8")
   );
   ajv.addSchema(annotationsSchema);
   cachedSidecarValidator = ajv.compile(sidecarSchema);
@@ -2587,7 +2679,7 @@ function safeIsFile(path) {
 
 // kernel/sidecar/store.ts
 import { existsSync as existsSync8, readFileSync as readFileSync8 } from "fs";
-import { dirname as dirname6, resolve as resolve8 } from "path";
+import { dirname as dirname6, resolve as resolve9 } from "path";
 import { createRequire as createRequire4 } from "module";
 import { Ajv2020 as Ajv20205 } from "ajv/dist/2020.js";
 import yaml3 from "js-yaml";
@@ -2610,7 +2702,7 @@ import { dirname as dirname5 } from "path";
 // kernel/orchestrator/node-build.ts
 import { createHash } from "crypto";
 import { existsSync as existsSync9 } from "fs";
-import { isAbsolute as isAbsolute2, resolve as resolvePath } from "path";
+import { isAbsolute as isAbsolute3, resolve as resolvePath } from "path";
 import "js-tiktoken/lite";
 import yaml4 from "js-yaml";
 
@@ -2773,7 +2865,7 @@ function resolveSidecarOverlay(relativePath, nodePathForIssue, roots, liveBodyHa
   };
 }
 function resolveAbsoluteMdPath(relativePath, roots) {
-  if (isAbsolute2(relativePath)) {
+  if (isAbsolute3(relativePath)) {
     return existsSync9(relativePath) ? relativePath : null;
   }
   for (const root of roots) {
@@ -2862,34 +2954,46 @@ async function walkAndExtract(opts) {
     oversizedSeen.add(info.path);
     oversizedFiles.push(info);
   };
+  const priorMtimes = buildPriorMtimes(opts);
   const walkOptions = {
     ...opts.ignoreFilter ? { ignoreFilter: opts.ignoreFilter } : {},
     onOversizedFile,
-    ...opts.maxFileSizeBytes !== void 0 ? { maxFileSizeBytes: opts.maxFileSizeBytes } : {}
+    ...opts.maxFileSizeBytes !== void 0 ? { maxFileSizeBytes: opts.maxFileSizeBytes } : {},
+    ...priorMtimes ? { priorMtimes } : {}
   };
-  let filesWalked = 0;
+  let filesWalked;
   let index = 0;
-  const effectiveMaxNodes = opts.overrideMaxNodes ?? opts.recommendedNodeLimit;
+  const { effectiveScanCeiling, effectiveMaxRenderNodes } = resolveEffectiveCaps(opts);
   let capReached = false;
-  const activeProviders = opts.providers.filter((provider) => {
-    if (!provider.gatedByActiveLens) return true;
-    if (opts.activeProvider === null) return true;
-    return provider.id === opts.activeProvider;
-  });
+  const activeProviders = opts.providers.filter(
+    (provider) => providerParticipates(provider, opts.activeProvider)
+  );
   const advance = async (raw, provider) => {
     const advanced = await processRawNode(raw, provider, wctx, accum, claimedPaths, index + 1);
     if (advanced) index += 1;
   };
-  outer: for (const provider of activeProviders) {
-    for await (const raw of resolveProviderWalk(provider)(opts.roots, walkOptions)) {
-      filesWalked += 1;
-      if (claimedPaths.has(raw.path)) continue;
-      if (accum.nodes.length >= effectiveMaxNodes) {
-        capReached = true;
-        break outer;
-      }
-      await advance(raw, provider);
-    }
+  if (opts.incrementalChangedPaths !== void 0) {
+    filesWalked = await walkIncremental({
+      changedPaths: opts.incrementalChangedPaths,
+      activeProviders,
+      walkOptions,
+      wctx,
+      accum,
+      claimedPaths,
+      advance
+    });
+  } else {
+    const full = await walkFullTraversal({
+      activeProviders,
+      roots: opts.roots,
+      walkOptions,
+      accum,
+      claimedPaths,
+      effectiveScanCeiling,
+      advance
+    });
+    filesWalked = full.filesWalked;
+    capReached = full.capReached;
   }
   const orphanSidecars = discoverOrphanSidecars(opts.roots);
   return {
@@ -2900,9 +3004,9 @@ async function walkAndExtract(opts) {
     frontmatterIssues: accum.frontmatterIssues,
     filesWalked,
     oversizedFiles,
-    recommendedNodeLimit: opts.recommendedNodeLimit,
-    overrideMaxNodes: opts.overrideMaxNodes,
-    capReached,
+    scanCeiling: effectiveScanCeiling,
+    scanTruncated: capReached,
+    maxRenderNodes: effectiveMaxRenderNodes,
     enrichments: [...accum.enrichmentBuffer.values()],
     extractorRuns: accum.extractorRuns,
     contributions: accum.contributionsBuffer,
@@ -2913,6 +3017,119 @@ async function walkAndExtract(opts) {
     signals: accum.signals
   };
 }
+async function walkFullTraversal(args) {
+  let filesWalked = 0;
+  let capReached = false;
+  outer: for (const provider of args.activeProviders) {
+    for await (const raw of resolveProviderWalk(provider)(args.roots, args.walkOptions)) {
+      filesWalked += 1;
+      if (args.claimedPaths.has(raw.path)) continue;
+      if (args.accum.nodes.length >= args.effectiveScanCeiling) {
+        capReached = true;
+        break outer;
+      }
+      await args.advance(raw, provider);
+    }
+  }
+  return { filesWalked, capReached };
+}
+async function walkIncremental(args) {
+  const changed = expandSidecarPaths(args.changedPaths.changed, args.wctx.priorNodesByPath);
+  const removed = expandSidecarPaths(args.changedPaths.removed, args.wctx.priorNodesByPath);
+  let filesWalked = 0;
+  const scopedAbs = [...changed].map((rel) => toAbsolute(rel, args.wctx.opts.roots));
+  if (scopedAbs.length > 0) {
+    const scopedWalkOptions = { ...args.walkOptions, scopedPaths: scopedAbs };
+    for (const provider of args.activeProviders) {
+      for await (const raw of resolveProviderWalk(provider)(args.wctx.opts.roots, scopedWalkOptions)) {
+        filesWalked += 1;
+        if (args.claimedPaths.has(raw.path)) continue;
+        await args.advance(raw, provider);
+      }
+    }
+  }
+  filesWalked += await injectUnchangedPriorNodes(args, changed, removed);
+  return filesWalked;
+}
+async function injectUnchangedPriorNodes(args, changed, removed) {
+  const providerById = new Map(args.activeProviders.map((p) => [p.id, p]));
+  const universalFallback = args.activeProviders.find((p) => !p.gatedByActiveLens) ?? args.activeProviders[0];
+  let injected = 0;
+  for (const priorNode of args.wctx.opts.prior?.nodes ?? []) {
+    if (!shouldInjectPriorNode(priorNode, changed, removed, args.claimedPaths)) continue;
+    const provider = providerById.get(priorNode.provider) ?? universalFallback;
+    if (!provider) continue;
+    const raw = buildUnchangedRawNode(priorNode, provider, args.wctx.opts.roots);
+    await args.advance(raw, provider);
+    injected += 1;
+  }
+  return injected;
+}
+function shouldInjectPriorNode(priorNode, changed, removed, claimedPaths) {
+  const path = priorNode.path;
+  if (changed.has(path) || removed.has(path) || claimedPaths.has(path)) return false;
+  if (priorNode.virtual === true) return false;
+  return true;
+}
+function buildUnchangedRawNode(priorNode, provider, roots) {
+  const path = priorNode.path;
+  return {
+    path,
+    body: "",
+    frontmatterRaw: "",
+    frontmatter: {},
+    ...typeof priorNode.modifiedAtMs === "number" ? { modifiedAtMs: priorNode.modifiedAtMs } : {},
+    unchanged: true,
+    reread: async () => {
+      const abs = toAbsolute(path, roots);
+      for await (const re of resolveProviderWalk(provider)(roots, { scopedPaths: [abs] })) {
+        return {
+          body: re.body,
+          frontmatterRaw: re.frontmatterRaw,
+          frontmatter: re.frontmatter,
+          ...re.parseIssues ? { parseIssues: re.parseIssues } : {}
+        };
+      }
+      return { body: "", frontmatterRaw: "", frontmatter: {} };
+    }
+  };
+}
+function expandSidecarPaths(paths, priorNodesByPath) {
+  const out = /* @__PURE__ */ new Set();
+  for (const path of paths) {
+    if (path.endsWith(".sm")) {
+      const mdPath = `${path.slice(0, -".sm".length)}.md`;
+      if (priorNodesByPath.has(mdPath)) out.add(mdPath);
+      continue;
+    }
+    out.add(path);
+  }
+  return out;
+}
+function toAbsolute(relPath, roots) {
+  const root = roots[0] ?? ".";
+  const absRoot = isAbsolute4(root) ? root : resolve10(root);
+  return resolve10(absRoot, relPath);
+}
+function resolveEffectiveCaps(opts) {
+  return {
+    effectiveScanCeiling: opts.overrideScanCeiling ?? opts.scanCeiling,
+    effectiveMaxRenderNodes: opts.overrideMaxRenderNodes ?? opts.maxRenderNodes
+  };
+}
+function buildPriorMtimes(opts) {
+  if (!opts.enableCache || opts.prior === null || opts.tokenizerChanged) return void 0;
+  const map = /* @__PURE__ */ new Map();
+  for (const node of opts.prior.nodes) {
+    if (typeof node.modifiedAtMs === "number") map.set(node.path, node.modifiedAtMs);
+  }
+  return map.size > 0 ? map : void 0;
+}
+function providerParticipates(provider, activeProvider) {
+  if (!provider.gatedByActiveLens) return true;
+  if (activeProvider === null) return true;
+  return provider.id === activeProvider;
+}
 function createWalkAccumulators() {
   return {
     nodes: [],
@@ -2941,61 +3158,106 @@ function buildWalkContext(opts) {
   return { opts, priorNodesByPath, priorLinksByOriginating, priorFrontmatterIssuesByNode, shortIdToQualified };
 }
 async function processRawNode(raw, provider, wctx, accum, claimedPaths, nextIndex) {
-  const bodyHash = sha256(raw.body);
-  const frontmatterHash = sha256(canonicalFrontmatter(raw.frontmatter, raw.frontmatterRaw));
   if (Array.isArray(provider.roots) && provider.roots.length > 0) {
     if (!matchesAnyRoot(raw.path, provider.roots)) return false;
   }
+  if (raw.unchanged === true) {
+    const handled = await handleUnchangedRawNode(raw, provider, wctx, accum, claimedPaths, nextIndex);
+    if (handled) return true;
+  }
+  const bodyHash = sha256(raw.body);
+  const frontmatterHash = sha256(canonicalFrontmatter(raw.frontmatter, raw.frontmatterRaw));
   const kind = provider.classify(raw.path, raw.frontmatter);
   if (kind === null) {
     return false;
   }
   claimedPaths.add(raw.path);
   const priorNode = wctx.priorNodesByPath.get(raw.path);
-  const nodeHashCacheEligible = wctx.opts.enableCache && // Tokenizer-change invalidation: when the resolved encoder differs
-  // from the one that produced the prior snapshot's counts, no node is
-  // cache-eligible, every node rebuilds so `buildNode` re-tokenizes
-  // with the current encoder. See `tokenizerChanged` on the options.
-  !wctx.opts.tokenizerChanged && wctx.opts.prior !== null && priorNode !== void 0 && priorNode.bodyHash === bodyHash && priorNode.frontmatterHash === frontmatterHash;
+  const nodeHashCacheEligible = isNodeHashCacheEligible(wctx, priorNode, bodyHash, frontmatterHash);
+  await dispatchNode(
+    { raw, provider, kind, bodyHash, frontmatterHash, nodeHashCacheEligible, priorNode },
+    wctx,
+    accum,
+    nextIndex
+  );
+  return true;
+}
+function isNodeHashCacheEligible(wctx, priorNode, bodyHash, frontmatterHash) {
+  return wctx.opts.enableCache && !wctx.opts.tokenizerChanged && wctx.opts.prior !== null && priorNode !== void 0 && priorNode.bodyHash === bodyHash && priorNode.frontmatterHash === frontmatterHash;
+}
+async function handleUnchangedRawNode(raw, provider, wctx, accum, claimedPaths, nextIndex) {
+  const prior = wctx.priorNodesByPath.get(raw.path);
+  if (prior) {
+    claimedPaths.add(raw.path);
+    await dispatchNode(
+      {
+        raw,
+        provider,
+        kind: prior.kind,
+        bodyHash: prior.bodyHash,
+        frontmatterHash: prior.frontmatterHash,
+        nodeHashCacheEligible: true,
+        priorNode: prior,
+        ensureBody: () => rereadInto(raw)
+      },
+      wctx,
+      accum,
+      nextIndex
+    );
+    return true;
+  }
+  await rereadInto(raw);
+  return false;
+}
+async function dispatchNode(args, wctx, accum, nextIndex) {
   const sidecarResolution = resolveSidecarOverlay(
-    raw.path,
-    raw.path,
+    args.raw.path,
+    args.raw.path,
     wctx.opts.roots,
-    bodyHash,
-    frontmatterHash
+    args.bodyHash,
+    args.frontmatterHash
   );
   const sidecarAnnotationsHash = sha256(
     canonicalSidecarAnnotations(sidecarResolution.overlay.annotations)
   );
   const cacheDecision = computeCacheDecision({
     extractors: wctx.opts.extractors,
-    kind,
+    kind: args.kind,
     activeProvider: wctx.opts.activeProvider,
-    nodePath: raw.path,
-    bodyHash,
+    nodePath: args.raw.path,
+    bodyHash: args.bodyHash,
     sidecarAnnotationsHash,
-    nodeHashCacheEligible,
+    nodeHashCacheEligible: args.nodeHashCacheEligible,
     priorExtractorRuns: wctx.opts.priorExtractorRuns
   });
   const ctx = {
-    raw,
-    provider,
-    kind,
-    bodyHash,
-    frontmatterHash,
+    raw: args.raw,
+    provider: args.provider,
+    kind: args.kind,
+    bodyHash: args.bodyHash,
+    frontmatterHash: args.frontmatterHash,
     sidecarResolution,
     sidecarAnnotationsHash,
-    nodeHashCacheEligible,
+    nodeHashCacheEligible: args.nodeHashCacheEligible,
     cacheDecision,
-    priorNode,
+    priorNode: args.priorNode,
     index: nextIndex
   };
-  if (cacheDecision.fullCacheHit && priorNode) {
+  if (cacheDecision.fullCacheHit && args.priorNode) {
     applyFullCacheHit(ctx, wctx, accum);
   } else {
+    if (args.ensureBody) await args.ensureBody();
     await applyExtractPath(ctx, wctx, accum);
   }
-  return true;
+}
+async function rereadInto(raw) {
+  if (!raw.reread) return;
+  const re = await raw.reread();
+  raw.body = re.body;
+  raw.frontmatter = re.frontmatter;
+  raw.frontmatterRaw = re.frontmatterRaw;
+  raw.unchanged = false;
+  if (re.parseIssues) raw.parseIssues = re.parseIssues;
 }
 function attachSidecar(node, resolution, sidecarRoots) {
   node.sidecar = resolution.overlay;
@@ -3208,9 +3470,18 @@ async function runScanInternal(_kernel, options) {
     providerFrontmatter: setup.providerFrontmatter,
     pluginStores: options.pluginStores,
     activeProvider: activeProviderId,
-    recommendedNodeLimit: options.recommendedNodeLimit ?? 256,
-    overrideMaxNodes: options.overrideMaxNodes ?? null,
-    ...options.maxFileSizeBytes !== void 0 ? { maxFileSizeBytes: options.maxFileSizeBytes } : {}
+    scanCeiling: options.scanCeiling ?? 5e4,
+    overrideScanCeiling: options.overrideScanCeiling ?? null,
+    maxRenderNodes: options.maxRenderNodes ?? 256,
+    overrideMaxRenderNodes: options.overrideMaxRenderNodes ?? null,
+    ...options.maxFileSizeBytes !== void 0 ? { maxFileSizeBytes: options.maxFileSizeBytes } : {},
+    // Watcher incremental fast path: only honoured when a prior exists,
+    // cache reuse is on, and the tokenizer is unchanged (else a scoped
+    // read would skip nodes whose token counts must be recomputed). The
+    // walker enumerates from the prior snapshot + reads only the changed
+    // files instead of traversing the corpus. Falls back to the full
+    // traversal + mtime-gate when the gate does not hold.
+    ...options.incrementalChangedPaths !== void 0 && prior !== null && setup.enableCache && !tokenizerChanged ? { incrementalChangedPaths: options.incrementalChangedPaths } : {}
   });
   const activeProvider = activeProviderId ? exts.providers.find((p) => p.id === activeProviderId) ?? null : null;
   const resolved = resolveSignals({
@@ -3408,8 +3679,9 @@ function buildScanReturn(walked, issues, renameOps, stats, options, setup, linkS
       providers: setup.exts.providers.map((a) => a.id),
       scannedBy: SCANNED_BY,
       tokenizer: setup.tokenizer,
-      recommendedNodeLimit: walked.recommendedNodeLimit,
-      overrideMaxNodes: walked.overrideMaxNodes,
+      scanCeiling: walked.scanCeiling,
+      scanTruncated: walked.scanTruncated,
+      maxRenderNodes: walked.maxRenderNodes,
       oversizedFiles: walked.oversizedFiles,
       nodes: walked.nodes,
       links: walked.internalLinks,
@@ -3438,7 +3710,7 @@ function validateRoots(roots) {
 function resolveActiveProviderOption(optionValue, roots, providers) {
   if (optionValue !== void 0) return optionValue;
   for (const root of roots) {
-    const absRoot = isAbsolute3(root) ? root : resolve9(root);
+    const absRoot = isAbsolute5(root) ? root : resolve11(root);
     if (!existsSync10(absRoot)) continue;
     const detected = detectProvidersFromFilesystem(absRoot, providers)[0] ?? null;
     if (detected !== null) return detected;
@@ -3447,10 +3719,10 @@ function resolveActiveProviderOption(optionValue, roots, providers) {
 }
 
 // kernel/scan/watcher.ts
-import { resolve as resolve10, relative as relative4, sep as sep3 } from "path";
+import { resolve as resolve12, relative as relative4, sep as sep3 } from "path";
 import chokidar from "chokidar";
 function createChokidarWatcher(opts) {
-  const absRoots = opts.roots.map((r) => resolve10(opts.cwd, r));
+  const absRoots = opts.roots.map((r) => resolve12(opts.cwd, r));
   const ignoreFilterOpt = opts.ignoreFilter;
   const getFilter = ignoreFilterOpt === void 0 ? void 0 : typeof ignoreFilterOpt === "function" ? ignoreFilterOpt : () => ignoreFilterOpt;
   const ignored = getFilter ? (path) => {
@@ -3851,4 +4123,4 @@ export {
   runScanWithRenames
 };
 //# sourceMappingURL=index.js.map
-//# debugId=5077263a-bf07-58af-b37d-ea6ab8f9a27c
+//# debugId=ca2610ab-aae0-5366-8634-73a2d8fd3eda

package/dist/migrations/001_initial.sql

@@ -289,14 +289,24 @@ CREATE TABLE scan_meta (
   stats_files_walked INTEGER NOT NULL,
   stats_files_skipped INTEGER NOT NULL,
   stats_duration_ms INTEGER NOT NULL,
-  -- Node-cap envelope (see spec/cli-contract.md §Scan, `scan.maxNodes` setting
-  -- and `--max-nodes` flag). `recommended_node_limit` is the effective default
-  -- (from `scan.maxNodes`) that produced this scan; the UI raises a persistent
-  -- "oversized graph" banner when `stats_files_walked >= recommended_node_limit`.
-  -- `override_max_nodes` is the per-invocation override (when `--max-nodes <N>`
-  -- was passed) or NULL when the value above came from the setting.
-  recommended_node_limit INTEGER NOT NULL,
-  override_max_nodes INTEGER,
+  -- Scan-ceiling vs render-cap envelope (see spec/cli-contract.md §Scan).
+  -- Two independent knobs:
+  --   - `scan_ceiling` is the effective WALK-INTAKE ceiling that produced
+  --     this scan (`scan.maxScan` setting, default 50000, or the
+  --     `--max-scan <N>` override). The walker walks, parses, analyzes, and
+  --     reference-validates the full corpus up to this number, so references
+  --     resolve across the whole project regardless of how many nodes the
+  --     map renders.
+  --   - `scan_truncated` is 1 when the walker reached `scan_ceiling` and
+  --     dropped files (in stable provider-walker order), 0 otherwise. The UI
+  --     raises a persistent banner pointing at the `.skillmapignore` editor.
+  --   - `max_render_nodes` is the effective MAP RENDER cap (`scan.maxNodes`
+  --     setting, default 256, or the `--max-nodes <N>` override). Pure
+  --     metadata: it does NOT bound the walk, only the graph projection the
+  --     UI draws onto the canvas.
+  scan_ceiling INTEGER NOT NULL,
+  scan_truncated INTEGER NOT NULL DEFAULT 0,
+  max_render_nodes INTEGER NOT NULL,
   -- File-size skip envelope (see spec/cli-contract.md §Scan, `scan.maxFileSizeBytes`
   -- setting, default 1 MiB). `files_oversized` is the count of files the walker
   -- skipped before reading because they exceeded the limit (= `stats.filesOversized`);