@skill-map/cli 0.46.0 → 0.47.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 // cli/entry.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]="7c131b78-b7ad-5f03-b19c-1f70afdfeefb")}catch(e){}}();
-import { existsSync as existsSync32 } from "fs";
+!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]="926243f9-3707-54bc-9aa6-c68955118161")}catch(e){}}();
+import { existsSync as existsSync33 } from "fs";
 import { Builtins, Cli as Cli2 } from "clipanion";
 
 // kernel/adapters/in-memory-progress.ts
@@ -246,7 +246,7 @@ function bucketByKind(kind, instance, bag) {
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.46.0",
+  version: "0.47.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -6220,12 +6220,12 @@ var SmCommand = class extends Command {
 };
 
 // core/sqlite/with-sqlite.ts
-import { existsSync as existsSync10 } from "fs";
+import { existsSync as existsSync11 } from "fs";
 
 // kernel/adapters/sqlite/storage-adapter.ts
 import { mkdirSync as mkdirSync4 } from "fs";
 import { dirname as dirname8, resolve as resolve12 } from "path";
-import { DatabaseSync as DatabaseSync3 } from "node:sqlite";
+import { DatabaseSync as DatabaseSync4 } from "node:sqlite";
 import { CamelCasePlugin, Kysely, sql as sql3 } from "kysely";
 
 // kernel/i18n/storage.texts.ts
@@ -7513,6 +7513,12 @@ async function loadScanResult(db) {
       roots: parseJsonArray(metaRow.rootsJson),
       providers: parseJsonArray(metaRow.providersJson),
       scannedBy,
+      // Resolved encoder of the prior scan (see project-config.schema.json
+      // §tokenizer). NULL column → `undefined` domain field; the
+      // orchestrator's tokenizer-change check compares this against the
+      // freshly-resolved encoder and treats a missing prior value as a
+      // change (forcing a token recompute).
+      ...metaRow.tokenizer !== null ? { tokenizer: metaRow.tokenizer } : {},
       recommendedNodeLimit: metaRow.recommendedNodeLimit,
       overrideMaxNodes: metaRow.overrideMaxNodes,
       oversizedFiles,
@@ -7846,6 +7852,58 @@ function rowToContribution(row) {
   };
 }
 
+// core/sqlite/schema-fingerprint.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
+import { DatabaseSync as DatabaseSync3 } from "node:sqlite";
+var memoized = null;
+function schemaFingerprint(files) {
+  if (files === void 0 && memoized !== null) return memoized;
+  const migrations = files ?? discoverMigrations();
+  const hash = createHash("sha256");
+  for (const m of migrations) {
+    const sql4 = existsSync10(m.filePath) ? readFileSync10(m.filePath, "utf8") : "";
+    hash.update(`${m.version}\0${m.description}\0${Buffer.byteLength(sql4)}\0`);
+    hash.update(sql4);
+  }
+  const digest = hash.digest("hex");
+  if (files === void 0) memoized = digest;
+  return digest;
+}
+function readStoredFingerprint(dbPath) {
+  if (dbPath === ":memory:" || !existsSync10(dbPath)) return { kind: "no-meta" };
+  let raw = null;
+  try {
+    raw = new DatabaseSync3(dbPath, { readOnly: true });
+    return readStoredFingerprintFrom(raw);
+  } catch {
+    return { kind: "no-meta" };
+  } finally {
+    raw?.close();
+  }
+}
+function readStoredFingerprintFrom(raw) {
+  if (!columnExists(raw, "scan_meta", "schema_fingerprint")) {
+    const hasRow = raw.prepare("SELECT 1 AS present FROM scan_meta LIMIT 1").get();
+    return hasRow ? { kind: "absent" } : { kind: "no-meta" };
+  }
+  const row = raw.prepare("SELECT schema_fingerprint AS fp FROM scan_meta LIMIT 1").get();
+  if (!row) return { kind: "no-meta" };
+  const fp = row.fp;
+  if (typeof fp !== "string" || fp.length === 0) return { kind: "absent" };
+  return { kind: "value", fingerprint: fp };
+}
+function columnExists(db, table, column) {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+  return rows.some((r) => r.name === column);
+}
+function classifyFingerprint(dbPath) {
+  const stored = readStoredFingerprint(dbPath);
+  if (stored.kind === "no-meta") return { kind: "no-meta" };
+  if (stored.kind === "absent") return { kind: "drift" };
+  return stored.fingerprint === schemaFingerprint() ? { kind: "ok" } : { kind: "drift" };
+}
+
 // kernel/adapters/sqlite/tags.ts
 async function replaceAllScanTags(trx, records, livePaths = /* @__PURE__ */ new Set()) {
   if (livePaths.size > 0) {
@@ -8125,10 +8183,21 @@ function metaToRow(result) {
     scannedByName: result.scannedBy?.name ?? "skill-map",
     scannedByVersion: result.scannedBy?.version ?? "unknown",
     scannedBySpecVersion: result.scannedBy?.specVersion ?? "unknown",
+    // Schema-drift fingerprint: sha256 over the bundled migration DDL.
+    // Sibling of `scannedByVersion`, the second drift axis the next
+    // write-side open compares (see spec/db-schema.md §Schema drift
+    // (pre-1.0)). Internal DB metadata, never on the ScanResult wire.
+    schemaFingerprint: schemaFingerprint(),
     providersJson: JSON.stringify(result.providers),
     statsFilesWalked: result.stats.filesWalked,
     statsFilesSkipped: result.stats.filesSkipped,
     statsDurationMs: result.stats.durationMs,
+    // Resolved encoder that produced the token counts (see
+    // project-config.schema.json §tokenizer). NULL on synthetic results
+    // that bypass the orchestrator / skip tokenization; a real scan always
+    // carries it. The next incremental scan reads this back to detect an
+    // encoder switch and force a token recompute.
+    tokenizer: result.tokenizer ?? null,
     ...projectNodeLimitColumns(result),
     ...projectOversizedColumns(result)
   };
@@ -8263,7 +8332,7 @@ var SqliteStorageAdapter = class {
     if (this.#options.autoMigrate !== false) {
       const files = discoverMigrations();
       if (files.length > 0) {
-        const raw = new DatabaseSync3(path);
+        const raw = new DatabaseSync4(path);
         try {
           raw.exec("PRAGMA foreign_keys = ON");
           applyMigrations(
@@ -8650,7 +8719,7 @@ async function listFavoritePaths(db) {
   return new Set(rows.map((r) => r.nodePath));
 }
 function withRawDb(path, fn) {
-  const raw = new DatabaseSync3(path);
+  const raw = new DatabaseSync4(path);
   try {
     return fn(raw);
   } finally {
@@ -8729,7 +8798,14 @@ var DB_VERSION_TEXTS = {
   dbVersionMajorMismatch: "{{glyph}}  This DB was written by skill-map {{dbVersion}}; the CLI you are running ({{currentVersion}}) is on a different major series.\n   {{hint}}\n",
   dbVersionMajorMismatchHint: "Delete the `.skill-map/` directory and re-scan, or revert to a CLI in the {{dbMajor}}.x series.",
   dbVersionOlder: "{{glyph}}  This DB was last written by an older skill-map ({{dbVersion}}, you have {{currentVersion}}).\n   {{hint}}\n",
-  dbVersionOlderHint: "Behaviour may differ until the next `sm scan` rewrites the metadata; downstream parse errors are likely a symptom of this skew."
+  dbVersionOlderHint: "Behaviour may differ until the next `sm scan` rewrites the metadata; downstream parse errors are likely a symptom of this skew.",
+  // Schema-fingerprint drift on a same-version DB (pre-1.0 greenfield:
+  // a column was added inline to a migration with no version bump, so
+  // the version axis reads as compatible but the on-disk schema is
+  // older). WARN, `⚠` yellow, the read continues but a query may hit a
+  // missing column. Has no `dbVersion` placeholder, the version matched.
+  dbSchemaDrift: "{{glyph}}  This DB predates a schema change in skill-map {{currentVersion}} (same version, older columns).\n   {{hint}}\n",
+  dbSchemaDriftHint: "Run `sm scan` to rebuild the local cache (your .sm sidecars are untouched), or `sm db reset`; some columns may be missing until then."
   // The defensive wrapper for `parseConfidence` / `parseLinkKind` /
   // `parseSeverity` failures during `loadScanResult` (when the meta
   // row was wiped and the version check returned `no-meta`) lives in
@@ -8744,10 +8820,17 @@ var DB_VERSION_TEXTS = {
 // core/sqlite/db-version-runner.ts
 var WARN_SEEN = /* @__PURE__ */ new Set();
 async function runDbVersionCheck(db, opts) {
-  const outcome = await detectDbVersionSkew(db, opts.currentVersion);
+  const versionOutcome = await detectDbVersionSkew(db, opts.currentVersion);
+  const outcome = layerFingerprintOutcome(versionOutcome, opts);
   applyDbVersionOutcome(outcome, opts);
   return outcome;
 }
+function layerFingerprintOutcome(versionOutcome, opts) {
+  if (versionOutcome.kind !== "ok") return versionOutcome;
+  const fp = classifyFingerprint(opts.dbPath);
+  if (fp.kind === "drift") return { kind: "warn-schema", currentVersion: opts.currentVersion };
+  return versionOutcome;
+}
 function applyDbVersionOutcome(outcome, opts) {
   switch (outcome.kind) {
     case "ok":
@@ -8760,6 +8843,9 @@ function applyDbVersionOutcome(outcome, opts) {
     case "warn-older":
       renderWarnOlder(outcome, opts);
       break;
+    case "warn-schema":
+      renderWarnSchema(outcome, opts);
+      break;
   }
 }
 function renderErrorNewer(outcome, opts) {
@@ -8813,6 +8899,21 @@ function renderWarnOlder(outcome, opts) {
     })
   );
 }
+function renderWarnSchema(outcome, opts) {
+  const seen = opts.warnSeen ?? WARN_SEEN;
+  if (seen.has(opts.dbPath)) return;
+  seen.add(opts.dbPath);
+  if (!opts.printer) return;
+  const warnGlyph = opts.style?.warnGlyph ?? "\u26A0";
+  const dim = opts.style?.dim ?? ((s) => s);
+  opts.printer.warn(
+    tx(DB_VERSION_TEXTS.dbSchemaDrift, {
+      glyph: warnGlyph,
+      currentVersion: outcome.currentVersion,
+      hint: dim(DB_VERSION_TEXTS.dbSchemaDriftHint)
+    })
+  );
+}
 
 // core/sqlite/with-sqlite.ts
 async function withSqlite(options, fn) {
@@ -8832,7 +8933,7 @@ async function withSqlite(options, fn) {
   }
 }
 async function tryWithSqlite(options, fn) {
-  if (options.databasePath !== ":memory:" && !existsSync10(options.databasePath)) {
+  if (options.databasePath !== ":memory:" && !existsSync11(options.databasePath)) {
     return null;
   }
   return withSqlite(options, fn);
@@ -9433,6 +9534,19 @@ var CHECK_TEXTS = {
   unknownAnalyzerIds: "sm check: unknown analyzer id(s) in --analyzers: {{unknown}}.\nValid ids (qualified or short form accepted):\n{{known}}\n"
 };
 
+// cli/util/db-version-check.ts
+function buildReadVersionCheck(printer, stderrAnsi) {
+  return {
+    currentVersion: VERSION,
+    printer,
+    style: {
+      warnGlyph: stderrAnsi.yellow("\u26A0"),
+      errorGlyph: stderrAnsi.red("\u2715"),
+      dim: stderrAnsi.dim
+    }
+  };
+}
+
 // cli/util/conformance-env.ts
 var ENV_DISABLE_PROVIDERS = "SKILL_MAP_DISABLE_ALL_PROVIDERS";
 var ENV_DISABLE_EXTRACTORS = "SKILL_MAP_DISABLE_ALL_EXTRACTORS";
@@ -9477,7 +9591,7 @@ var PLUGIN_LOADER_TEXTS = {
 
 // kernel/adapters/plugin-loader/index.ts
 import { createRequire as createRequire5 } from "module";
-import { existsSync as existsSync12, readFileSync as readFileSync12, readdirSync as readdirSync4, statSync as statSync2 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync13, readdirSync as readdirSync4, statSync as statSync2 } from "fs";
 import { join as join8, resolve as resolve17 } from "path";
 import { pathToFileURL } from "url";
 import semver from "semver";
@@ -9580,7 +9694,7 @@ function stripFunctionsAndPluginId(input) {
 
 // kernel/adapters/plugin-loader/validation.ts
 import * as nodeFs from "fs";
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync12 } from "fs";
 import { dirname as dirname9, join as join7 } from "path";
 import { Ajv2020 as Ajv20205 } from "ajv/dist/2020.js";
 
@@ -9706,7 +9820,7 @@ function validateActionFileConventions(pluginPath, pluginId, manifest, relEntry,
   const reportSchemaPath = join7(actionDir, "report.schema.json");
   const promptPath = join7(actionDir, "prompt.md");
   const mode = isRecord(manifestView) && typeof manifestView["mode"] === "string" ? manifestView["mode"] : "deterministic";
-  if (!existsSync11(reportSchemaPath)) {
+  if (!existsSync12(reportSchemaPath)) {
     return {
       ...fail(
         pluginPath,
@@ -9717,7 +9831,7 @@ function validateActionFileConventions(pluginPath, pluginId, manifest, relEntry,
       manifest
     };
   }
-  const promptExists = existsSync11(promptPath);
+  const promptExists = existsSync12(promptPath);
   if (mode === "probabilistic" && !promptExists) {
     return {
       ...fail(
@@ -9829,7 +9943,7 @@ function isDirectorySafe(path, statSync12) {
 }
 
 // kernel/adapters/plugin-loader/storage-schemas.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync12 } from "fs";
 import { resolve as resolve16 } from "path";
 import { Ajv2020 as Ajv20206 } from "ajv/dist/2020.js";
 
@@ -9897,7 +10011,7 @@ function compilePluginSchema(pluginPath, relPath) {
   const abs = resolve16(pluginPath, relPath);
   let raw;
   try {
-    raw = JSON.parse(readFileSync11(abs, "utf8"));
+    raw = JSON.parse(readFileSync12(abs, "utf8"));
   } catch (err) {
     return { ok: false, phase: "read", errDescription: describe(err) };
   }
@@ -9931,11 +10045,11 @@ var PluginLoader = class {
   discoverPaths() {
     const out = [];
     for (const root of this.#options.searchPaths) {
-      if (!existsSync12(root)) continue;
+      if (!existsSync13(root)) continue;
       for (const entry of readdirSync4(root, { withFileTypes: true })) {
         if (!entry.isDirectory()) continue;
         const candidate = join8(root, entry.name);
-        if (existsSync12(join8(candidate, "plugin.json"))) {
+        if (existsSync13(join8(candidate, "plugin.json"))) {
           out.push(resolve17(candidate));
         }
       }
@@ -10019,7 +10133,7 @@ var PluginLoader = class {
     const manifestPath = join8(pluginPath, "plugin.json");
     let raw;
     try {
-      raw = JSON.parse(readFileSync12(manifestPath, "utf8"));
+      raw = JSON.parse(readFileSync13(manifestPath, "utf8"));
     } catch (err) {
       return { ok: false, failure: fail(
         pluginPath,
@@ -10096,7 +10210,7 @@ var PluginLoader = class {
       } };
     }
     const abs = resolve17(pluginPath, relEntry);
-    if (!existsSync12(abs)) {
+    if (!existsSync13(abs)) {
       return { ok: false, failure: {
         ...fail(
           pluginPath,
@@ -10294,7 +10408,7 @@ function discoverExtensionEntries(pluginPath) {
 }
 function collectKindEntries(pluginPath, kindDir, out) {
   const kindAbs = resolve17(pluginPath, kindDir);
-  if (!existsSync12(kindAbs)) return;
+  if (!existsSync13(kindAbs)) return;
   let entries;
   try {
     entries = readdirSync4(kindAbs);
@@ -10321,7 +10435,7 @@ function isDirectorySafe2(path) {
 }
 function findIndexCandidate(entryAbs) {
   for (const candidate of INDEX_CANDIDATES) {
-    if (existsSync12(resolve17(entryAbs, candidate))) return candidate;
+    if (existsSync13(resolve17(entryAbs, candidate))) return candidate;
   }
   return null;
 }
@@ -10329,7 +10443,7 @@ function installedSpecVersion() {
   const require2 = createRequire5(import.meta.url);
   const indexPath = require2.resolve("@skill-map/spec/index.json");
   const pkgPath = resolve17(indexPath, "..", "package.json");
-  const pkg = JSON.parse(readFileSync12(pkgPath, "utf8"));
+  const pkg = JSON.parse(readFileSync13(pkgPath, "utf8"));
   return pkg.version;
 }
 
@@ -10417,7 +10531,7 @@ import { readFile, readdir, lstat } from "fs/promises";
 import { join as join9, relative as relative2, sep as sep3 } from "path";
 
 // kernel/scan/ignore.ts
-import { existsSync as existsSync13, readFileSync as readFileSync13 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync14 } from "fs";
 import { dirname as dirname10, resolve as resolve18 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import ignoreFactory from "ignore";
@@ -10448,9 +10562,9 @@ function loadBundledIgnoreText() {
 }
 function readIgnoreFileText(scopeRoot) {
   const path = resolve18(scopeRoot, ".skillmapignore");
-  if (!existsSync13(path)) return void 0;
+  if (!existsSync14(path)) return void 0;
   try {
-    return readFileSync13(path, "utf8");
+    return readFileSync14(path, "utf8");
   } catch {
     return void 0;
   }
@@ -10483,9 +10597,9 @@ function readDefaultsFromDisk() {
     resolve18(here, "config/defaults/skillmapignore")
   ];
   for (const candidate of candidates) {
-    if (existsSync13(candidate)) {
+    if (existsSync14(candidate)) {
       try {
-        return readFileSync13(candidate, "utf8");
+        return readFileSync14(candidate, "utf8");
       } catch {
       }
     }
@@ -11103,27 +11217,35 @@ var CheckCommand = class extends SmCommand {
     const analyzerFilter = parseAnalyzersFlag(this.analyzers);
     const preflight = await this.#preflightAnalyzerCatalog(analyzerFilter);
     if (preflight.exit !== null) return preflight.exit;
-    return withSqlite({ databasePath: dbPath, autoBackup: false }, async (adapter) => {
-      let issues = await adapter.issues.listAll();
-      if (this.node !== void 0) {
-        const nodePath = this.node;
-        issues = issues.filter((i) => i.nodeIds.includes(nodePath));
-      }
-      if (analyzerFilter !== void 0) {
-        issues = issues.filter((i) => matchesAnalyzerFilter(i.analyzerId, analyzerFilter));
-      }
-      const ansi = this.ansiFor("stdout");
-      if (this.json) {
-        this.printer.data(JSON.stringify(issues) + "\n");
-      } else if (issues.length === 0) {
-        this.printer.data(
-          tx(CHECK_TEXTS.noIssues, { glyph: ansi.green("\u2713") })
-        );
-      } else {
-        this.printer.data(renderHuman(issues, ansi));
+    const stderrAnsi = this.ansiFor("stderr");
+    return withSqlite(
+      {
+        databasePath: dbPath,
+        autoBackup: false,
+        versionCheck: buildReadVersionCheck(this.printer, stderrAnsi)
+      },
+      async (adapter) => {
+        let issues = await adapter.issues.listAll();
+        if (this.node !== void 0) {
+          const nodePath = this.node;
+          issues = issues.filter((i) => i.nodeIds.includes(nodePath));
+        }
+        if (analyzerFilter !== void 0) {
+          issues = issues.filter((i) => matchesAnalyzerFilter(i.analyzerId, analyzerFilter));
+        }
+        const ansi = this.ansiFor("stdout");
+        if (this.json) {
+          this.printer.data(JSON.stringify(issues) + "\n");
+        } else if (issues.length === 0) {
+          this.printer.data(
+            tx(CHECK_TEXTS.noIssues, { glyph: ansi.green("\u2713") })
+          );
+        } else {
+          this.printer.data(renderHuman(issues, ansi));
+        }
+        return issues.some((i) => i.severity === "error") ? ExitCode.Issues : ExitCode.Ok;
       }
-      return issues.some((i) => i.severity === "error") ? ExitCode.Issues : ExitCode.Ok;
-    });
+    );
   }
   /**
    * Either an explicit `--analyzers` list or `--include-prob` forces a
@@ -11292,11 +11414,11 @@ function trimRedundantPath(message, primary) {
 }
 
 // cli/commands/config.ts
-import { existsSync as existsSync15 } from "fs";
+import { existsSync as existsSync16 } from "fs";
 import { Command as Command4, Option as Option4 } from "clipanion";
 
 // core/config/active-provider.ts
-import { existsSync as existsSync14 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 import { join as join10 } from "path";
 function resolveActiveProvider(cwd, providers = []) {
   const detected = detectProvidersFromFilesystem(cwd, providers);
@@ -11316,7 +11438,7 @@ function detectProvidersFromFilesystem(cwd, providers) {
     if (seen.has(provider.id)) continue;
     const markers = provider.detect?.markers;
     if (!markers || markers.length === 0) continue;
-    if (!markers.some((marker) => existsSync14(join10(cwd, marker)))) continue;
+    if (!markers.some((marker) => existsSync15(join10(cwd, marker)))) continue;
     seen.add(provider.id);
     out.push(provider.id);
   }
@@ -11333,7 +11455,7 @@ function relativeIfBelow(path, cwd) {
 }
 
 // cli/util/scan-zone-drop.ts
-import { DatabaseSync as DatabaseSync4 } from "node:sqlite";
+import { DatabaseSync as DatabaseSync5 } from "node:sqlite";
 
 // cli/commands/db/shared.ts
 var SAFE_SQL_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
@@ -11345,7 +11467,7 @@ function assertSafeIdentifier(name) {
 
 // cli/util/scan-zone-drop.ts
 function dropScanZone(dbPath) {
-  const db = new DatabaseSync4(dbPath);
+  const db = new DatabaseSync5(dbPath);
   try {
     const rows = db.prepare(
       "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'scan\\_%' ESCAPE '\\'"
@@ -11936,7 +12058,7 @@ var ConfigSetCommand = class extends SmCommand {
   announceLensSwitch(cwd, ansi) {
     const dbPath = resolveDbPath({ db: void 0, cwd });
     const okGlyph = ansi.green("\u2713");
-    if (!existsSync15(dbPath)) {
+    if (!existsSync16(dbPath)) {
       this.printer.info(tx(CONFIG_TEXTS.lensSwitchedNoDb, { glyph: okGlyph }));
       return;
     }
@@ -11976,7 +12098,7 @@ var ConfigResetCommand = class extends SmCommand {
     const path = targetSettingsPath2(target, ctx.cwd);
     const ansi = this.ansiFor("stdout");
     const okGlyph = ansi.green("\u2713");
-    if (!existsSync15(path)) {
+    if (!existsSync16(path)) {
       this.printer.data(
         tx(CONFIG_TEXTS.unsetNoOverride, {
           glyph: okGlyph,
@@ -12051,14 +12173,14 @@ var CONFIG_COMMANDS = [
 ];
 
 // cli/commands/conformance.ts
-import { existsSync as existsSync18, readFileSync as readFileSync15 } from "fs";
+import { existsSync as existsSync19, readFileSync as readFileSync16 } from "fs";
 import { dirname as dirname12, resolve as resolve22 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command5, Option as Option5 } from "clipanion";
 
 // conformance/index.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { cpSync, existsSync as existsSync16, mkdtempSync, readdirSync as readdirSync5, readFileSync as readFileSync14, rmSync, statSync as statSync3 } from "fs";
+import { cpSync, existsSync as existsSync17, mkdtempSync, readdirSync as readdirSync5, readFileSync as readFileSync15, rmSync, statSync as statSync3 } from "fs";
 import { tmpdir } from "os";
 import { isAbsolute as isAbsolute5, join as join11, relative as relative3, resolve as resolve20 } from "path";
 
@@ -12140,7 +12262,7 @@ function pickSafeEnv(source) {
   return out;
 }
 function runConformanceCase(options) {
-  const raw = readFileSync14(options.casePath, "utf8");
+  const raw = readFileSync15(options.casePath, "utf8");
   const c = JSON.parse(raw);
   const fixturesRoot = options.fixturesRoot ?? join11(options.specRoot, "conformance", "fixtures");
   const safeId = c.id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 32);
@@ -12255,7 +12377,7 @@ function evaluateAssertion(a, ctx) {
         return { ok: false, type: a.type, reason: formatErrorMessage(err) };
       }
       const abs = resolve20(ctx.scope, a.path);
-      return existsSync16(abs) ? { ok: true, type: a.type } : {
+      return existsSync17(abs) ? { ok: true, type: a.type } : {
         ok: false,
         type: a.type,
         reason: tx(CONFORMANCE_RUNNER_TEXTS.fileNotFound, { path: a.path })
@@ -12270,15 +12392,15 @@ function evaluateAssertion(a, ctx) {
       }
       const fixturePath = join11(ctx.fixturesRoot, a.fixture);
       const targetPath = resolve20(ctx.scope, a.path);
-      if (!existsSync16(targetPath)) {
+      if (!existsSync17(targetPath)) {
         return {
           ok: false,
           type: a.type,
           reason: tx(CONFORMANCE_RUNNER_TEXTS.targetNotFound, { path: a.path })
         };
       }
-      const needle = readFileSync14(fixturePath);
-      const haystack = readFileSync14(targetPath);
+      const needle = readFileSync15(fixturePath);
+      const haystack = readFileSync15(targetPath);
       return haystack.includes(needle) ? { ok: true, type: a.type } : {
         ok: false,
         type: a.type,
@@ -12451,7 +12573,7 @@ var CONFORMANCE_TEXTS = {
 };
 
 // cli/util/conformance-scopes.ts
-import { existsSync as existsSync17, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
+import { existsSync as existsSync18, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
 import { dirname as dirname11, resolve as resolve21 } from "path";
 import { createRequire as createRequire6 } from "module";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -12471,7 +12593,7 @@ function resolveCliWorkspaceRoot() {
   let cursor = here;
   for (let depth = 0; depth < 6; depth += 1) {
     const candidate = resolve21(cursor, "plugins");
-    if (existsSync17(candidate) && statSync4(candidate).isDirectory()) {
+    if (existsSync18(candidate) && statSync4(candidate).isDirectory()) {
       return cursor;
     }
     const parent = dirname11(cursor);
@@ -12491,7 +12613,7 @@ function collectProviderScopes(specRoot) {
     return out;
   }
   const pluginsRoot = resolve21(workspaceRoot, "plugins");
-  if (!existsSync17(pluginsRoot)) return out;
+  if (!existsSync18(pluginsRoot)) return out;
   for (const pluginEntry of readdirSync6(pluginsRoot)) {
     const pluginDir = resolve21(pluginsRoot, pluginEntry);
     if (!isDir(pluginDir)) continue;
@@ -12503,7 +12625,7 @@ function collectProviderScopes(specRoot) {
 }
 function isDir(path) {
   try {
-    return existsSync17(path) && statSync4(path).isDirectory();
+    return existsSync18(path) && statSync4(path).isDirectory();
   } catch {
     return false;
   }
@@ -12513,10 +12635,10 @@ function collectPluginProviderScopes(providersRoot, specRoot, out) {
     const providerDir = resolve21(providersRoot, entry);
     if (!isDir(providerDir)) continue;
     const conformanceDir = resolve21(providerDir, "conformance");
-    if (!existsSync17(conformanceDir)) continue;
+    if (!existsSync18(conformanceDir)) continue;
     const casesDir = resolve21(conformanceDir, "cases");
     const fixturesDir = resolve21(conformanceDir, "fixtures");
-    if (!existsSync17(casesDir) || !existsSync17(fixturesDir)) continue;
+    if (!existsSync18(casesDir) || !existsSync18(fixturesDir)) continue;
     out.push({
       id: `provider:${entry}`,
       kind: "provider",
@@ -12554,7 +12676,7 @@ function selectConformanceScopes(scope) {
   return [match];
 }
 function listCaseFiles(scope) {
-  if (!existsSync17(scope.casesDir)) return [];
+  if (!existsSync18(scope.casesDir)) return [];
   return readdirSync6(scope.casesDir).filter((entry) => entry.endsWith(".json")).sort().map((entry) => resolve21(scope.casesDir, entry));
 }
 
@@ -12573,7 +12695,7 @@ function resolveBinary() {
   let cursor = here;
   for (let depth = 0; depth < 6; depth += 1) {
     const candidate = resolve22(cursor, "bin", "sm.js");
-    if (existsSync18(candidate)) return candidate;
+    if (existsSync19(candidate)) return candidate;
     const parent = dirname12(cursor);
     if (parent === cursor) break;
     cursor = parent;
@@ -12639,7 +12761,7 @@ var ConformanceRunCommand = class extends SmCommand {
       return ExitCode.Error;
     }
     const binary = resolveBinary();
-    if (!existsSync18(binary)) {
+    if (!existsSync19(binary)) {
       if (this.json) {
         this.#emitJsonError(
           "internal",
@@ -12813,7 +12935,7 @@ function projectAssertionFailures(assertions) {
 }
 function readCaseId(casePath) {
   try {
-    const raw = readFileSync15(casePath, "utf8");
+    const raw = readFileSync16(casePath, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.id === "string") return parsed.id;
   } catch {
@@ -13068,18 +13190,18 @@ var DbRestoreCommand = class extends SmCommand {
 };
 
 // cli/commands/db/reset.ts
-import { DatabaseSync as DatabaseSync5 } from "node:sqlite";
+import { DatabaseSync as DatabaseSync6 } from "node:sqlite";
 import { Command as Command8, Option as Option8 } from "clipanion";
 
 // core/sqlite/db-files.ts
-import { existsSync as existsSync19 } from "fs";
+import { existsSync as existsSync20 } from "fs";
 import { rm as rm2 } from "fs/promises";
 var DB_FILE_SUFFIXES = ["", "-wal", "-shm"];
 async function removeDbFiles(dbPath) {
   if (dbPath === ":memory:") return;
   for (const suffix of DB_FILE_SUFFIXES) {
     const p = `${dbPath}${suffix}`;
-    if (existsSync19(p)) await rm2(p);
+    if (existsSync20(p)) await rm2(p);
   }
 }
 
@@ -13165,7 +13287,7 @@ var DbResetCommand = class extends SmCommand {
         return ExitCode.Error;
       }
     }
-    const db = new DatabaseSync5(path);
+    const db = new DatabaseSync6(path);
     try {
       const rows = db.prepare(
         "SELECT name FROM sqlite_master WHERE type='table' AND (name LIKE 'scan\\_%' ESCAPE '\\'" + (this.state ? " OR name LIKE 'state\\_%' ESCAPE '\\'" : "") + ")"
@@ -13308,7 +13430,7 @@ var DbBrowserCommand = class extends SmCommand {
 };
 
 // cli/commands/db/dump.ts
-import { DatabaseSync as DatabaseSync6 } from "node:sqlite";
+import { DatabaseSync as DatabaseSync7 } from "node:sqlite";
 import { Command as Command11, Option as Option10 } from "clipanion";
 var DbDumpCommand = class extends SmCommand {
   static paths = [["db", "dump"]];
@@ -13350,7 +13472,7 @@ var DbDumpCommand = class extends SmCommand {
   }
 };
 function dumpDatabaseToStream(dbPath, out, tables) {
-  const db = new DatabaseSync6(dbPath, { readOnly: true });
+  const db = new DatabaseSync7(dbPath, { readOnly: true });
   try {
     out.write("PRAGMA foreign_keys=OFF;\n");
     out.write("BEGIN TRANSACTION;\n");
@@ -14198,7 +14320,7 @@ var GraphCommand = class extends SmCommand {
 };
 
 // cli/commands/help.ts
-import { readFileSync as readFileSync16 } from "fs";
+import { readFileSync as readFileSync17 } from "fs";
 import { createRequire as createRequire7 } from "module";
 import { resolve as resolve26 } from "path";
 import { Command as Command15, Option as Option14 } from "clipanion";
@@ -14499,7 +14621,7 @@ function resolveSpecVersion() {
     const req = createRequire7(import.meta.url);
     const indexPath = req.resolve("@skill-map/spec/index.json");
     const pkgPath = resolve26(indexPath, "..", "package.json");
-    const pkg = JSON.parse(readFileSync16(pkgPath, "utf8"));
+    const pkg = JSON.parse(readFileSync17(pkgPath, "utf8"));
     return pkg.version;
   } catch {
     return "unknown";
@@ -14984,10 +15106,9 @@ import { join as join17 } from "path";
 import { Command as Command17, Option as Option16 } from "clipanion";
 
 // kernel/orchestrator/index.ts
-import { existsSync as existsSync22, statSync as statSync6 } from "fs";
+import { existsSync as existsSync23, statSync as statSync6 } from "fs";
 import { isAbsolute as isAbsolute7, resolve as resolve28 } from "path";
 import { Tiktoken as Tiktoken2 } from "js-tiktoken/lite";
-import cl100k_base from "js-tiktoken/ranks/cl100k_base";
 
 // kernel/i18n/orchestrator.texts.ts
 var ORCHESTRATOR_TEXTS = {
@@ -16031,7 +16152,7 @@ function computeDriftStatus(args2) {
 }
 
 // kernel/sidecar/discover-orphans.ts
-import { existsSync as existsSync20, readdirSync as readdirSync7, statSync as statSync5 } from "fs";
+import { existsSync as existsSync21, readdirSync as readdirSync7, statSync as statSync5 } from "fs";
 import { join as join13, relative as relative4, sep as sep4 } from "path";
 function discoverOrphanSidecars(roots, shouldSkip) {
   const out = [];
@@ -16059,7 +16180,7 @@ function walk2(root, current, shouldSkip, out) {
     if (!entry.isFile()) continue;
     if (!entry.name.endsWith(".sm")) continue;
     const expectedMd = `${full.slice(0, -".sm".length)}.md`;
-    if (existsSync20(expectedMd) && safeIsFile(expectedMd)) continue;
+    if (existsSync21(expectedMd) && safeIsFile(expectedMd)) continue;
     out.push({ sidecarPath: full, relativePath: rel, expectedMdPath: expectedMd });
   }
 }
@@ -16072,8 +16193,8 @@ function safeIsFile(path) {
 }
 
 // kernel/orchestrator/node-build.ts
-import { createHash } from "crypto";
-import { existsSync as existsSync21 } from "fs";
+import { createHash as createHash2 } from "crypto";
+import { existsSync as existsSync22 } from "fs";
 import { isAbsolute as isAbsolute6, resolve as resolvePath } from "path";
 import "js-tiktoken/lite";
 import yaml4 from "js-yaml";
@@ -16160,7 +16281,7 @@ function countTokens(encoder, frontmatterRaw, body) {
   return { frontmatter, body: bodyTokens, total: frontmatter + bodyTokens };
 }
 function sha256(input) {
-  return createHash("sha256").update(input, "utf8").digest("hex");
+  return createHash2("sha256").update(input, "utf8").digest("hex");
 }
 function canonicalFrontmatter(parsed, raw) {
   const hasParsedKeys = Object.keys(parsed).length > 0;
@@ -16237,11 +16358,11 @@ function resolveSidecarOverlay(relativePath2, nodePathForIssue, roots, liveBodyH
 }
 function resolveAbsoluteMdPath(relativePath2, roots) {
   if (isAbsolute6(relativePath2)) {
-    return existsSync21(relativePath2) ? relativePath2 : null;
+    return existsSync22(relativePath2) ? relativePath2 : null;
   }
   for (const root of roots) {
     const candidate = resolvePath(root, relativePath2);
-    if (existsSync21(candidate)) return candidate;
+    if (existsSync22(candidate)) return candidate;
   }
   return null;
 }
@@ -16394,7 +16515,11 @@ async function processRawNode(raw, provider, wctx, accum, claimedPaths, nextInde
   }
   claimedPaths.add(raw.path);
   const priorNode = wctx.priorNodesByPath.get(raw.path);
-  const nodeHashCacheEligible = wctx.opts.enableCache && wctx.opts.prior !== null && priorNode !== void 0 && priorNode.bodyHash === bodyHash && priorNode.frontmatterHash === frontmatterHash;
+  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 sidecarResolution = resolveSidecarOverlay(
     raw.path,
     raw.path,
@@ -16596,6 +16721,16 @@ function resolveSpecVersionSafe() {
     return "unknown";
   }
 }
+var DEFAULT_TOKENIZER = "cl100k_base";
+function resolveTokenizerName(name) {
+  return name === "o200k_base" ? "o200k_base" : DEFAULT_TOKENIZER;
+}
+async function loadTokenizerRanks(name) {
+  if (name === "o200k_base") {
+    return (await import("js-tiktoken/ranks/o200k_base")).default;
+  }
+  return (await import("js-tiktoken/ranks/cl100k_base")).default;
+}
 async function runScanWithRenames(_kernel, options) {
   return runScanInternal(_kernel, options);
 }
@@ -16605,7 +16740,7 @@ async function runScan(_kernel, options) {
 }
 async function runScanInternal(_kernel, options) {
   validateRoots(options.roots);
-  const setup = buildScanSetup(options);
+  const setup = await buildScanSetup(options);
   const { emitter, exts, hookDispatcher, encoder, prior, start } = setup;
   const scanStartedEvent = makeEvent("scan.started", { roots: options.roots });
   emitter.emit(scanStartedEvent);
@@ -16615,6 +16750,7 @@ async function runScanInternal(_kernel, options) {
     options.roots,
     exts.providers
   );
+  const tokenizerChanged = encoder !== null && prior !== null && prior.tokenizer !== setup.tokenizer;
   const walked = await walkAndExtract({
     providers: exts.providers,
     extractors: exts.extractors,
@@ -16624,6 +16760,7 @@ async function runScanInternal(_kernel, options) {
     encoder,
     strict: setup.strict,
     enableCache: setup.enableCache,
+    tokenizerChanged,
     prior,
     priorIndex: setup.priorIndex,
     priorExtractorRuns: setup.priorExtractorRuns,
@@ -16739,13 +16876,14 @@ function buildReservedNodePaths(nodes, kindRegistry, reservedNamesByProviderKind
 function hasEntries(set) {
   return set !== void 0 && set.size > 0;
 }
-function buildScanSetup(options) {
+async function buildScanSetup(options) {
   const start = Date.now();
   const emitter = options.emitter ?? new InMemoryProgressEmitter();
   const exts = options.extensions ?? { providers: [], extractors: [], analyzers: [] };
   const hookDispatcher = makeHookDispatcher(exts.hooks ?? [], emitter);
   const tokenize = options.tokenize !== false;
-  const encoder = tokenize ? new Tiktoken2(cl100k_base) : null;
+  const tokenizer = resolveTokenizerName(options.tokenizer);
+  const encoder = tokenize ? new Tiktoken2(await loadTokenizerRanks(tokenizer)) : null;
   const prior = options.priorSnapshot ?? null;
   const priorIndex = indexPriorSnapshot(prior);
   const providerFrontmatter = buildProviderFrontmatterValidator(exts.providers);
@@ -16756,6 +16894,7 @@ function buildScanSetup(options) {
     exts,
     hookDispatcher,
     encoder,
+    tokenizer,
     prior,
     priorIndex,
     priorExtractorRuns: options.priorExtractorRuns,
@@ -16806,6 +16945,7 @@ function buildScanReturn(walked, issues, renameOps, stats, options, setup) {
       roots: options.roots,
       providers: setup.exts.providers.map((a) => a.id),
       scannedBy: SCANNED_BY,
+      tokenizer: setup.tokenizer,
       recommendedNodeLimit: walked.recommendedNodeLimit,
       overrideMaxNodes: walked.overrideMaxNodes,
       oversizedFiles: walked.oversizedFiles,
@@ -16826,7 +16966,7 @@ function validateRoots(roots) {
     throw new Error(ORCHESTRATOR_TEXTS.runScanRootEmptyArray);
   }
   for (const root of roots) {
-    if (!existsSync22(root) || !statSync6(root).isDirectory()) {
+    if (!existsSync23(root) || !statSync6(root).isDirectory()) {
       throw new Error(tx(ORCHESTRATOR_TEXTS.runScanRootMissing, { root }));
     }
   }
@@ -16835,7 +16975,7 @@ function resolveActiveProviderOption(optionValue, roots, providers) {
   if (optionValue !== void 0) return optionValue;
   for (const root of roots) {
     const absRoot = isAbsolute7(root) ? root : resolve28(root);
-    if (!existsSync22(absRoot)) continue;
+    if (!existsSync23(absRoot)) continue;
     const detected = resolveActiveProvider(absRoot, providers).resolved;
     if (detected !== null) return detected;
   }
@@ -17475,45 +17615,61 @@ async function promptForLens(detected, stdin, stderr, warnGlyph) {
 }
 
 // core/sqlite/db-drift-reset.ts
-import { existsSync as existsSync23 } from "fs";
+import { existsSync as existsSync24 } from "fs";
 import { createInterface as createInterface4 } from "readline";
-import { DatabaseSync as DatabaseSync7 } from "node:sqlite";
+import { DatabaseSync as DatabaseSync8 } from "node:sqlite";
 
 // core/sqlite/i18n/db-drift.texts.ts
 var DB_DRIFT_TEXTS = {
   // Interactive confirm (TTY `sm scan`, no `--yes`). The block is
   // written to stderr, then the question line drives `readline`.
-  driftPrompt: "{{glyph}}  The local cache was built by skill-map {{dbVersion}} and you are on {{currentVersion}}.\n   {{hint}}\n",
-  driftPromptHint: "Pre-1.0 the DB is a derived cache (your .sm sidecars hold the real data); it cannot be carried across a version change and has to be rebuilt.",
+  // `{{reason}}` is one of the `driftReason*` strings below so the
+  // operator sees WHY the cache is being rebuilt (version skew vs an
+  // inline schema change the version did not bump).
+  driftPrompt: "{{glyph}}  The local cache was built by skill-map {{dbVersion}} and you are on {{currentVersion}} ({{reason}}).\n   {{hint}}\n",
+  driftPromptHint: "Pre-1.0 the DB is a derived cache (your .sm sidecars hold the real data); it cannot be carried across a schema change and has to be rebuilt.",
   driftPromptQuestion: "Delete the local cache and rebuild it on this scan? [y/N] ",
   // Receipt after the rebuild (printed by the scan / refresh path).
-  driftReset: "{{glyph}}  Local cache rebuilt: it was written by skill-map {{dbVersion}}, you are on {{currentVersion}}.\n   {{hint}}\n",
+  driftReset: "{{glyph}}  Local cache rebuilt ({{reason}}): it was written by skill-map {{dbVersion}}, you are on {{currentVersion}}.\n   {{hint}}\n",
   driftResetHint: "The DB was deleted and is being regenerated by this scan; .sm sidecars were not touched.",
   // Abort headline when the operator declines (wrapped by the caller's
   // `sm scan: {message}` shell, so it carries no glyph / verb prefix).
-  driftAborted: "cache rebuild declined: the {{dbVersion}} cache cannot be reused on {{currentVersion}}. {{hint}}",
-  driftAbortedHint: "Re-run with --yes, or run `sm db reset --hard` then `sm scan`."
+  driftAborted: "cache rebuild declined: the {{dbVersion}} cache cannot be reused on {{currentVersion}} ({{reason}}). {{hint}}",
+  driftAbortedHint: "Re-run with --yes, or run `sm db reset --hard` then `sm scan`.",
+  // Drift reason fragments, interpolated as `{{reason}}` above. Version
+  // skew = the recorded scanned_by_version differs at major.minor.
+  // Schema fingerprint = an inline migration edit (no version bump,
+  // greenfield posture) changed the DDL.
+  driftReasonVersion: "version skew",
+  driftReasonSchema: "schema change in this version"
 };
 
 // core/sqlite/db-drift-reset.ts
 async function maybeResetOnDrift(dbPath, policy) {
-  const dbVersion = readScannedByVersion(dbPath);
-  if (dbVersion === null) return { kind: "no-drift" };
-  const skew = classifyVersionSkew(dbVersion, policy.currentVersion);
-  if (skew.kind === "ok" || skew.kind === "no-meta") return { kind: "no-drift" };
-  const confirmed = await confirmDriftReset(dbVersion, policy);
+  const reason = detectDriftReason(dbPath, policy.currentVersion);
+  if (reason === null) return { kind: "no-drift" };
+  const dbVersion = readScannedByVersion(dbPath) ?? "unknown";
+  const confirmed = await confirmDriftReset(dbVersion, reason, policy);
   if (!confirmed) {
-    return { kind: "aborted", dbVersion, currentVersion: policy.currentVersion };
+    return { kind: "aborted", dbVersion, currentVersion: policy.currentVersion, reason };
   }
   await removeDbFiles(dbPath);
-  renderResetReceipt(dbVersion, policy);
-  return { kind: "reset", dbVersion, currentVersion: policy.currentVersion };
+  renderResetReceipt(dbVersion, reason, policy);
+  return { kind: "reset", dbVersion, currentVersion: policy.currentVersion, reason };
+}
+function detectDriftReason(dbPath, currentVersion) {
+  const dbVersion = readScannedByVersion(dbPath);
+  if (dbVersion !== null) {
+    const skew = classifyVersionSkew(dbVersion, currentVersion);
+    if (skew.kind !== "ok" && skew.kind !== "no-meta") return "version";
+  }
+  return classifyFingerprint(dbPath).kind === "drift" ? "schema" : null;
 }
 function readScannedByVersion(dbPath) {
-  if (dbPath === ":memory:" || !existsSync23(dbPath)) return null;
+  if (dbPath === ":memory:" || !existsSync24(dbPath)) return null;
   let raw = null;
   try {
-    raw = new DatabaseSync7(dbPath, { readOnly: true });
+    raw = new DatabaseSync8(dbPath, { readOnly: true });
     const row = raw.prepare("SELECT scanned_by_version AS v FROM scan_meta LIMIT 1").get();
     const v = row?.v;
     return typeof v === "string" && v.length > 0 ? v : null;
@@ -17523,16 +17679,19 @@ function readScannedByVersion(dbPath) {
     raw?.close();
   }
 }
-async function confirmDriftReset(dbVersion, policy) {
+async function confirmDriftReset(dbVersion, reason, policy) {
   if (!shouldPromptForReset(policy)) return true;
-  return askDriftReset(dbVersion, policy);
+  return askDriftReset(dbVersion, reason, policy);
+}
+function reasonText(reason) {
+  return reason === "version" ? DB_DRIFT_TEXTS.driftReasonVersion : DB_DRIFT_TEXTS.driftReasonSchema;
 }
 function shouldPromptForReset(policy) {
   if (policy.assumeYes) return false;
   if (!policy.stdin || !policy.stderr) return false;
   return policy.stdin.isTTY === true;
 }
-async function askDriftReset(dbVersion, policy) {
+async function askDriftReset(dbVersion, reason, policy) {
   const warnGlyph = policy.style?.warnGlyph ?? "\u26A0";
   const dim = policy.style?.dim ?? ((s) => s);
   policy.stderr.write(
@@ -17540,6 +17699,7 @@ async function askDriftReset(dbVersion, policy) {
       glyph: warnGlyph,
       dbVersion,
       currentVersion: policy.currentVersion,
+      reason: reasonText(reason),
       hint: dim(DB_DRIFT_TEXTS.driftPromptHint)
     })
   );
@@ -17553,7 +17713,7 @@ async function askDriftReset(dbVersion, policy) {
     rl.close();
   }
 }
-function renderResetReceipt(dbVersion, policy) {
+function renderResetReceipt(dbVersion, reason, policy) {
   if (!policy.printer) return;
   const warnGlyph = policy.style?.warnGlyph ?? "\u26A0";
   const dim = policy.style?.dim ?? ((s) => s);
@@ -17562,6 +17722,7 @@ function renderResetReceipt(dbVersion, policy) {
       glyph: warnGlyph,
       dbVersion,
       currentVersion: policy.currentVersion,
+      reason: reasonText(reason),
       hint: dim(DB_DRIFT_TEXTS.driftResetHint)
     })
   );
@@ -17605,7 +17766,8 @@ async function runScanForCommand(opts) {
     ctx.cwd,
     activeProvider,
     cfg.scan.maxNodes,
-    cfg.scan.maxFileSizeBytes
+    cfg.scan.maxFileSizeBytes,
+    cfg.tokenizer
   );
   const willPersist = !opts.noBuiltIns && !opts.dryRun;
   const scanned = await (willPersist ? runPersistPath(opts, dbPath, jobsDir, strict, loadPrior, runScanWith, extensions) : runEphemeralPath(opts, dbPath, strict, loadPrior, runScanWith));
@@ -17719,7 +17881,7 @@ function makePriorLoader(noBuiltIns, strict) {
     return loaded;
   };
 }
-function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, extensions, referenceablePaths, scanCwd, activeProvider, recommendedNodeLimit, maxFileSizeBytes) {
+function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, extensions, referenceablePaths, scanCwd, activeProvider, recommendedNodeLimit, maxFileSizeBytes, tokenizer) {
   return async (prior, priorExtractorRuns, orphanJobFiles) => {
     if (opts.changed && prior === null) {
       opts.stderr.write(SCAN_RUNNER_TEXTS.changedNoPriorWarning);
@@ -17736,6 +17898,7 @@ function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, exte
       activeProvider,
       recommendedNodeLimit,
       maxFileSizeBytes,
+      tokenizer,
       ...priorExtractorRuns ? { priorExtractorRuns } : {},
       ...orphanJobFiles ? { orphanJobFiles } : {}
     });
@@ -17747,6 +17910,7 @@ function buildRunScanOptions(args2) {
   const runOptions = {
     roots: args2.effectiveRoots.slice(),
     tokenize: !opts.noTokens,
+    tokenizer: args2.tokenizer,
     ignoreFilter: args2.ignoreFilter,
     strict: args2.strict,
     emitter: buildRunScanEmitter(opts),
@@ -17792,6 +17956,7 @@ async function rebuildOnDrift(opts, dbPath) {
     message: tx(DB_DRIFT_TEXTS.driftAborted, {
       dbVersion: drift.dbVersion,
       currentVersion: drift.currentVersion,
+      reason: drift.reason === "version" ? DB_DRIFT_TEXTS.driftReasonVersion : DB_DRIFT_TEXTS.driftReasonSchema,
       hint: dim(DB_DRIFT_TEXTS.driftAbortedHint)
     })
   };
@@ -18961,7 +19126,11 @@ var ListCommand = class extends SmCommand {
     const exit = requireDbOrExit(dbPath, this.context.stderr);
     if (exit !== null) return exit;
     return withSqlite(
-      { databasePath: dbPath, autoBackup: false },
+      {
+        databasePath: dbPath,
+        autoBackup: false,
+        versionCheck: buildReadVersionCheck(this.printer, stderrAnsi)
+      },
       (adapter) => this.#runQuery(adapter, flags)
     );
   }
@@ -21121,7 +21290,7 @@ function resolveBareToggle(id, catalogue) {
 }
 
 // cli/commands/plugins/create.ts
-import { existsSync as existsSync24, mkdirSync as mkdirSync5, writeFileSync } from "fs";
+import { existsSync as existsSync25, mkdirSync as mkdirSync5, writeFileSync } from "fs";
 import { join as join18, resolve as resolve33 } from "path";
 import { Command as Command26, Option as Option25 } from "clipanion";
 var PluginsCreateCommand = class extends SmCommand {
@@ -21150,7 +21319,7 @@ var PluginsCreateCommand = class extends SmCommand {
     const ctx = defaultRuntimeContext();
     const baseDir = defaultProjectPluginsDir(ctx);
     const targetDir = this.at ? resolve33(this.at) : join18(baseDir, this.pluginId);
-    if (existsSync24(targetDir) && !this.force) {
+    if (existsSync25(targetDir) && !this.force) {
       this.printer.error(
         tx(PLUGINS_TEXTS.createRefuseOverwrite, {
           glyph: errGlyph,
@@ -22035,6 +22204,7 @@ function createWatcherRuntime(opts) {
       const runOptions = {
         roots: opts.roots,
         tokenize,
+        tokenizer: cfg.tokenizer,
         ignoreFilter,
         strict,
         emitter,
@@ -23185,7 +23355,7 @@ function renderDeltaIssues(issues) {
 
 // cli/commands/serve.ts
 import { spawn as spawn2 } from "child_process";
-import { existsSync as existsSync30 } from "fs";
+import { existsSync as existsSync31 } from "fs";
 import { Command as Command33, Option as Option31 } from "clipanion";
 
 // kernel/util/dev-mode.ts
@@ -23982,7 +24152,7 @@ function contentTypeFor(format) {
 }
 
 // server/health.ts
-import { existsSync as existsSync25 } from "fs";
+import { existsSync as existsSync26 } from "fs";
 var FALLBACK_SCHEMA_VERSION = "1";
 function buildHealth(deps) {
   const dev = isDevBuild();
@@ -23991,7 +24161,7 @@ function buildHealth(deps) {
     schemaVersion: FALLBACK_SCHEMA_VERSION,
     specVersion: deps.specVersion,
     implVersion: VERSION,
-    db: existsSync25(deps.dbPath) ? "present" : "missing",
+    db: existsSync26(deps.dbPath) ? "present" : "missing",
     cwd: deps.cwd,
     dbPath: deps.dbPath,
     // Only emit when truthy so a published install keeps the wire
@@ -24900,15 +25070,15 @@ var parsePatchBody2 = makeBodyValidator(PATCH_BODY_SCHEMA, {
 import { HTTPException as HTTPException11 } from "hono/http-exception";
 
 // server/util/skillmapignore-io.ts
-import { existsSync as existsSync26, readFileSync as readFileSync17, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync27, readFileSync as readFileSync18, writeFileSync as writeFileSync2 } from "fs";
 import { resolve as resolve35 } from "path";
 var IGNORE_FILENAME2 = ".skillmapignore";
 function readPatterns(cwd) {
   const path = resolve35(cwd, IGNORE_FILENAME2);
-  if (!existsSync26(path)) return [];
+  if (!existsSync27(path)) return [];
   let raw;
   try {
-    raw = readFileSync17(path, "utf8");
+    raw = readFileSync18(path, "utf8");
   } catch {
     return [];
   }
@@ -24916,13 +25086,13 @@ function readPatterns(cwd) {
 }
 function writePatterns(cwd, nextPatterns) {
   const path = resolve35(cwd, IGNORE_FILENAME2);
-  const prior = existsSync26(path) ? safeRead(path) : "";
+  const prior = existsSync27(path) ? safeRead(path) : "";
   const content = buildContent(prior, nextPatterns);
   writeFileSync2(path, content, "utf8");
 }
 function safeRead(path) {
   try {
-    return readFileSync17(path, "utf8");
+    return readFileSync18(path, "utf8");
   } catch {
     return "";
   }
@@ -25266,7 +25436,7 @@ var parsePatchBody4 = makeBodyValidator(PATCH_BODY_SCHEMA3, {
 });
 
 // server/routes/active-provider.ts
-import { existsSync as existsSync27 } from "fs";
+import { existsSync as existsSync28 } from "fs";
 import { HTTPException as HTTPException13 } from "hono/http-exception";
 function registerActiveProviderRoute(app, deps) {
   app.get("/api/active-provider", (c) => {
@@ -25299,7 +25469,7 @@ function applyLensSwitch(deps, newValue) {
     });
   }
   const dbPath = resolveDbPath({ db: void 0, cwd });
-  if (!existsSync27(dbPath)) return { dropped: null };
+  if (!existsSync28(dbPath)) return { dropped: null };
   const dropResult = dropScanZone(dbPath);
   return {
     dropped: {
@@ -25566,7 +25736,16 @@ async function buildBffResolverOverride(deps) {
 }
 async function loadPersistedScan(deps) {
   const opened = await tryWithSqlite(
-    { databasePath: deps.options.dbPath, autoBackup: false },
+    {
+      databasePath: deps.options.dbPath,
+      autoBackup: false,
+      // Read-side drift advisory (version skew + schema fingerprint).
+      // The BFF has no TTY, warnings go to the server log; a newer /
+      // different-major DB throws `DbVersionMismatchError`, which the
+      // global `app.onError` maps to a 500 so the SPA surfaces it
+      // rather than crashing on a cryptic missing-column read.
+      versionCheck: { currentVersion: VERSION, printer: bffVersionCheckPrinter }
+    },
     async (adapter) => {
       const [loaded, favSet] = await Promise.all([
         adapter.scans.load(),
@@ -25661,6 +25840,13 @@ var bffScanRunnerPrinter = {
   warn: (text) => log.warn(sanitizeForTerminal(text.trimEnd())),
   error: (text) => log.warn(sanitizeForTerminal(text.trimEnd()))
 };
+var bffVersionCheckPrinter = {
+  data: () => {
+  },
+  info: (text) => log.warn(sanitizeForTerminal(text.trimEnd())),
+  warn: (text) => log.warn(sanitizeForTerminal(text.trimEnd())),
+  error: (text) => log.warn(sanitizeForTerminal(text.trimEnd()))
+};
 function emptyScanResult() {
   return {
     schemaVersion: 1,
@@ -25847,7 +26033,7 @@ function registerUpdateStatusRoute(app, deps) {
 }
 
 // server/static.ts
-import { existsSync as existsSync28 } from "fs";
+import { existsSync as existsSync29 } from "fs";
 import { readFile as readFile6 } from "fs/promises";
 import { extname, join as join19 } from "path";
 import { serveStatic } from "@hono/node-server/serve-static";
@@ -25902,7 +26088,7 @@ function createSpaFallback(opts) {
     if (c.req.method !== "GET" && c.req.method !== "HEAD") return c.notFound();
     if (opts.uiDist === null) return htmlResponse(c, placeholder);
     const indexPath = join19(opts.uiDist, INDEX_HTML);
-    if (!existsSync28(indexPath)) return htmlResponse(c, placeholder);
+    if (!existsSync29(indexPath)) return htmlResponse(c, placeholder);
     return fileResponse(c, indexPath);
   };
 }
@@ -26512,7 +26698,7 @@ function validateNoUi(noUi, uiDist) {
 }
 
 // server/paths.ts
-import { existsSync as existsSync29, statSync as statSync10 } from "fs";
+import { existsSync as existsSync30, statSync as statSync10 } from "fs";
 import { dirname as dirname18, isAbsolute as isAbsolute11, join as join20, resolve as resolve37 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
 var DEFAULT_UI_REL = join20("ui", "dist", "ui", "browser");
@@ -26527,10 +26713,10 @@ function resolveExplicitUiDist(ctx, raw) {
   return isAbsolute11(raw) ? raw : resolve37(ctx.cwd, raw);
 }
 function isUiBundleDir(path) {
-  if (!existsSync29(path)) return false;
+  if (!existsSync30(path)) return false;
   try {
     if (!statSync10(path).isDirectory()) return false;
-    return existsSync29(join20(path, INDEX_HTML2));
+    return existsSync30(join20(path, INDEX_HTML2));
   } catch {
     return false;
   }
@@ -26824,7 +27010,14 @@ var SERVE_TEXTS = {
   // Shutdown trace, printed once the listener has closed. Informational
   // (`ℹ` cyan) per §3.1: no failure, no action; just a marker that the
   // long-running daemon has wound down cleanly.
-  shutdown: "{{glyph}}  sm serve: shutdown complete.\n"
+  shutdown: "{{glyph}}  sm serve: shutdown complete.\n",
+  /**
+   * §3.1b error block when the operator declines the pre-boot
+   * schema-drift rebuild (TTY, no `--yes`). The server never starts;
+   * the cache is left untouched. `{{reason}}` names the drift axis
+   * (version skew vs an inline schema change).
+   */
+  driftDeclined: "{{glyph}}  sm serve: cache rebuild declined; the {{dbVersion}} cache cannot be reused on {{currentVersion}} ({{reason}}).\n   {{hint}}\n"
 };
 
 // cli/util/serve-banner.ts
@@ -27051,6 +27244,9 @@ var ServeCommand = class extends SmCommand {
   noWatcher = Option31.Boolean("--no-watcher", false, {
     description: "Disable the chokidar-fed scan-and-broadcast loop. Use only for CI / read-only deployments."
   });
+  yes = Option31.Boolean("--yes", false, {
+    description: "Skip the interactive prompt and rebuild the local cache when the on-disk DB has drifted (version skew or an inline schema change). Non-TTY invocations rebuild without asking regardless of this flag."
+  });
   // `--watcher-debounce-ms` is undocumented sugar for advanced users
   // who want to tighten / relax the watcher's batching window without
   // editing settings.json. Hidden flag, the Usage block omits it.
@@ -27085,7 +27281,7 @@ var ServeCommand = class extends SmCommand {
       return ExitCode.Error;
     }
     const dbPath = resolveDbPath({ db: this.db, ...runtimeCtx });
-    if (this.db !== void 0 && !existsSync30(dbPath)) {
+    if (this.db !== void 0 && !existsSync31(dbPath)) {
       this.printer.info(
         tx(SERVE_TEXTS.dbNotFound, {
           glyph: errGlyph,
@@ -27167,6 +27363,8 @@ var ServeCommand = class extends SmCommand {
       this.printer.info(formatValidationError(validation.error, stderrAnsi));
       return ExitCode.Error;
     }
+    const driftAbort = await this.#rebuildOnDrift(dbPath, stderrAnsi, warnGlyph);
+    if (driftAbort !== null) return driftAbort;
     await initSentryBff(VERSION);
     let handle;
     try {
@@ -27219,6 +27417,35 @@ var ServeCommand = class extends SmCommand {
     this.printer.info(tx(SERVE_TEXTS.shutdown, { glyph: infoGlyph }));
     return ExitCode.Ok;
   }
+  /**
+   * Pre-1.0 schema-drift rebuild for `sm serve`, run before boot. Reuses
+   * the shared `maybeResetOnDrift` (same prompt / `--yes` / non-TTY
+   * policy as `sm scan`), threading the verb's stdin / stderr so a TTY
+   * operator is asked y/N. Returns `null` to proceed (no drift, or the
+   * cache was rebuilt) or an `ExitCode` to abort boot when the operator
+   * declines the rebuild.
+   */
+  async #rebuildOnDrift(dbPath, stderrAnsi, warnGlyph) {
+    const outcome = await maybeResetOnDrift(dbPath, {
+      currentVersion: VERSION,
+      assumeYes: this.yes,
+      stdin: this.context.stdin,
+      stderr: this.context.stderr,
+      printer: this.printer,
+      style: { warnGlyph, dim: stderrAnsi.dim }
+    });
+    if (outcome.kind !== "aborted") return null;
+    this.printer.error(
+      tx(SERVE_TEXTS.driftDeclined, {
+        glyph: stderrAnsi.red("\u2715"),
+        dbVersion: outcome.dbVersion,
+        currentVersion: outcome.currentVersion,
+        reason: outcome.reason === "version" ? DB_DRIFT_TEXTS.driftReasonVersion : DB_DRIFT_TEXTS.driftReasonSchema,
+        hint: stderrAnsi.dim(DB_DRIFT_TEXTS.driftAbortedHint)
+      })
+    );
+    return ExitCode.Error;
+  }
 };
 function parsePort(raw) {
   if (raw === void 0) return { ok: true, port: void 0 };
@@ -27434,26 +27661,34 @@ var ShowCommand = class extends SmCommand {
     const dbPath = resolveDbPath({ db: this.db, ...defaultRuntimeContext() });
     const exit = requireDbOrExit(dbPath, this.context.stderr);
     if (exit !== null) return exit;
-    return withSqlite({ databasePath: dbPath, autoBackup: false }, async (adapter) => {
-      const bundle = await adapter.scans.findNode(this.nodePath);
-      if (!bundle) {
-        this.printer.error(tx(SHOW_TEXTS.nodeNotFound, { nodePath: this.nodePath }));
-        return ExitCode.NotFound;
-      }
-      const doc = {
-        node: bundle.node,
-        linksOut: bundle.linksOut,
-        linksIn: bundle.linksIn,
-        issues: bundle.issues
-      };
-      if (this.json) {
-        this.printer.data(JSON.stringify(doc) + "\n");
+    const stderrAnsi = this.ansiFor("stderr");
+    return withSqlite(
+      {
+        databasePath: dbPath,
+        autoBackup: false,
+        versionCheck: buildReadVersionCheck(this.printer, stderrAnsi)
+      },
+      async (adapter) => {
+        const bundle = await adapter.scans.findNode(this.nodePath);
+        if (!bundle) {
+          this.printer.error(tx(SHOW_TEXTS.nodeNotFound, { nodePath: this.nodePath }));
+          return ExitCode.NotFound;
+        }
+        const doc = {
+          node: bundle.node,
+          linksOut: bundle.linksOut,
+          linksIn: bundle.linksIn,
+          issues: bundle.issues
+        };
+        if (this.json) {
+          this.printer.data(JSON.stringify(doc) + "\n");
+          return ExitCode.Ok;
+        }
+        const ansi = this.ansiFor("stdout");
+        this.printer.data(renderHuman2(doc, ansi));
         return ExitCode.Ok;
       }
-      const ansi = this.ansiFor("stdout");
-      this.printer.data(renderHuman2(doc, ansi));
-      return ExitCode.Ok;
-    });
+    );
   }
 };
 function renderHuman2(doc, ansi) {
@@ -28351,7 +28586,7 @@ var STUB_COMMANDS = [
 ];
 
 // cli/commands/tutorial.ts
-import { cpSync as cpSync2, existsSync as existsSync31, mkdirSync as mkdirSync6, readdirSync as readdirSync10, rmSync as rmSync2, statSync as statSync11 } from "fs";
+import { cpSync as cpSync2, existsSync as existsSync32, mkdirSync as mkdirSync6, readdirSync as readdirSync10, rmSync as rmSync2, statSync as statSync11 } from "fs";
 import { dirname as dirname19, join as join21, resolve as resolve39 } from "path";
 import { createInterface as createInterface5 } from "readline";
 import { fileURLToPath as fileURLToPath7 } from "url";
@@ -28695,7 +28930,7 @@ function resolveSkillSourceDir(variant) {
     resolve39(here, "../cli/tutorial", spec.slug)
   ];
   for (const candidate of candidates) {
-    if (existsSync31(candidate) && statSync11(candidate).isDirectory()) {
+    if (existsSync32(candidate) && statSync11(candidate).isDirectory()) {
       cachedSourceDirs.set(variant, candidate);
       return candidate;
     }
@@ -28896,7 +29131,7 @@ function resolveBareInvocation(rawArgs) {
   if (first !== void 0 && first.startsWith("-") && !passthrough.has(first)) {
     const isSingleDashLong = !first.startsWith("--") && first.length > 2;
     if (isSingleDashLong) return null;
-    if (existsSync32(defaultProjectDbPath(defaultRuntimeContext()))) {
+    if (existsSync33(defaultProjectDbPath(defaultRuntimeContext()))) {
       return ["serve", ...rawArgs];
     }
     return resolveBareDefault();
@@ -28905,7 +29140,7 @@ function resolveBareInvocation(rawArgs) {
 }
 function resolveBareDefault() {
   const ctx = defaultRuntimeContext();
-  if (existsSync32(defaultProjectDbPath(ctx))) {
+  if (existsSync33(defaultProjectDbPath(ctx))) {
     return ["serve"];
   }
   const stderr = process.stderr;
@@ -28920,4 +29155,4 @@ function resolveBareDefault() {
   process.exit(ExitCode.Error);
 }
 //# sourceMappingURL=cli.js.map
-//# debugId=7c131b78-b7ad-5f03-b19c-1f70afdfeefb
+//# debugId=926243f9-3707-54bc-9aa6-c68955118161