gitnexus 1.6.10-rc.151 → 1.6.10-rc.152

package/dist/core/analyzer-identity.d.ts

@@ -109,6 +109,24 @@ export declare function normalizeAnalyzerRootPath(p: string, platform: NodeJS.Pl
 declare function isInside(parent: string, candidate: string, pathApi?: typeof path): boolean;
 /** Test seam for {@link isInside} (see `_hashAnalyzerIdentityFramesForTests`). */
 export declare const _isInsideForTests: typeof isInside;
+/**
+ * Whether a REALPATH'd package root lives inside some installed dependency
+ * tree. Used as the resolved-location half of "is this dependency a checkout
+ * this repository owns?" (see {@link undeclaredLocalDevDependencyNames}).
+ *
+ * The input must already be realpath'd: `resolveDependencyPackageRoot` returns
+ * `realpathSync.native`, so a package reached through a link out of
+ * `node_modules` reports its checkout location and a package that merely lives
+ * in `node_modules` reports a path that still carries the segment.
+ *
+ * `pathApi` is injectable so the Windows separator handling is unit-testable
+ * from a POSIX runner, exactly as {@link isInside} does. The separator sets
+ * differ deliberately: `\` is a legal filename character on POSIX, so only
+ * win32 may treat it as a boundary.
+ */
+declare function hasNodeModulesSegment(candidate: string, pathApi?: typeof path): boolean;
+/** Test seam for {@link hasNodeModulesSegment} (see {@link _isInsideForTests}). */
+export declare const _hasNodeModulesSegmentForTests: typeof hasNodeModulesSegment;
 export type AnalyzerRunnerSemanticIdentity = Omit<AnalyzerRunnerIdentity, 'invokedArtifact'>;
 /**
  * Normalize a raw diagnostic receipt for freshness comparison. The entrypoint

package/dist/core/analyzer-identity.js

@@ -154,6 +154,24 @@ function snapshotReadableFile(candidate) {
         ...(link.isSymbolicLink() ? { symlinkTarget: readlinkSync(candidate) } : {}),
     };
 }
+/**
+ * Snapshot a symbolic link without resolving it. Unlike
+ * {@link snapshotReadableFile} this never stats the target, so it is total over
+ * linked directories, dangling links, and links to device nodes — the inputs
+ * that make the readable-file snapshot throw.
+ */
+function snapshotSymlinkArtifact(candidate) {
+    const link = lstatSync(candidate, { bigint: true });
+    if (!link.isSymbolicLink()) {
+        throw new Error(`Analyzer identity input is not a symbolic link: ${candidate}`);
+    }
+    return { link: statState(link), symlinkTarget: readlinkSync(candidate) };
+}
+function snapshotRuntimeArtifact(artifact) {
+    return artifact.kind === 'unfollowed-symlink'
+        ? snapshotSymlinkArtifact(artifact.absolutePath)
+        : snapshotReadableFile(artifact.absolutePath);
+}
 function snapshotDirectory(candidate) {
     const stat = lstatSync(candidate, { bigint: true });
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
@@ -597,6 +615,96 @@ function runtimePackageLocator(packageRoot, runtimeRoot) {
     const relative = path.relative(packageRoot, runtimeRoot).split(path.sep).join('/');
     return `relative:${relative}`;
 }
+/** Protocols that name a checkout-local package instead of a registry tarball. */
+const LOCAL_LINK_PROTOCOL_PATTERN = /^(?:file|link|workspace|portal):/;
+/** npm's bare local-path shorthands: `./x`, `../x`, `/x`, `~/x`, `C:\x`. */
+const LOCAL_LINK_PATH_PATTERN = /^(?:\.\.?[/\\]|~[/\\]|[/\\]|[A-Za-z]:)/;
+function isLocallyLinkedSpecifier(specifier) {
+    if (typeof specifier !== 'string')
+        return false;
+    const value = specifier.trim();
+    return LOCAL_LINK_PROTOCOL_PATTERN.test(value) || LOCAL_LINK_PATH_PATTERN.test(value);
+}
+/**
+ * Whether a REALPATH'd package root lives inside some installed dependency
+ * tree. Used as the resolved-location half of "is this dependency a checkout
+ * this repository owns?" (see {@link undeclaredLocalDevDependencyNames}).
+ *
+ * The input must already be realpath'd: `resolveDependencyPackageRoot` returns
+ * `realpathSync.native`, so a package reached through a link out of
+ * `node_modules` reports its checkout location and a package that merely lives
+ * in `node_modules` reports a path that still carries the segment.
+ *
+ * `pathApi` is injectable so the Windows separator handling is unit-testable
+ * from a POSIX runner, exactly as {@link isInside} does. The separator sets
+ * differ deliberately: `\` is a legal filename character on POSIX, so only
+ * win32 may treat it as a boundary.
+ */
+function hasNodeModulesSegment(candidate, pathApi = path) {
+    const segments = pathApi.sep === '\\' ? candidate.split(/[\\/]+/) : candidate.split('/');
+    return segments.includes('node_modules');
+}
+/** Test seam for {@link hasNodeModulesSegment} (see {@link _isInsideForTests}). */
+export const _hasNodeModulesSegmentForTests = hasNodeModulesSegment;
+/**
+ * How many dev dependencies may be admitted by RESOLVED LOCATION alone before
+ * the whole resolved-location channel is treated as untrustworthy and disabled.
+ *
+ * "Realpath carries no `node_modules` segment" is a proxy for "checkout-local",
+ * and a layout that materializes packages outside `node_modules` — pnpm with a
+ * relocated `virtual-store-dir`, a custom linker — makes every dev dependency
+ * pass it. Folding an entire dev tree into the receipt is not a graceful
+ * degradation: `runtimePackages`/`runtimeEntries`/`runtimeBytes` THROW, so a
+ * mis-fired proxy on a legitimate install would abort analyze outright.
+ *
+ * The bound is therefore on ADMISSIONS, and overflow admits NONE of them rather
+ * than an arbitrary prefix. A prefix would not bound the failure — the abort
+ * comes from the transitive payload of whichever trees get folded in — and it
+ * would make the receipt depend on an arbitrary slice of a sorted name list.
+ * Dropping the channel wholesale falls back to the specifier-only receipt,
+ * which is the behaviour that ships today and is known not to abort, and leaves
+ * the declared-intent half in {@link dependencyNames} untouched.
+ *
+ * Four is measured, not guessed. Monorepo and workspace links are declared
+ * (`file:`/`link:`/`workspace:`) and travel the uncapped declared half, so this
+ * channel only ever carries UNDECLARED `npm link <pkg>` — a manual, per-package
+ * developer action, in practice one or two packages. A mis-fire admits the
+ * entire dev-only set instead: 13 names in this repository's own install, tens
+ * in a typical application. The cap sits an order of magnitude below the
+ * mis-fire population and comfortably above realistic link counts.
+ */
+const MAX_UNDECLARED_LOCAL_DEV_DEPENDENCIES = 4;
+/**
+ * Dependency names whose resolved packages can contribute analyzer semantics.
+ *
+ * The three runtime sections are enumerated wholesale. `devDependencies` are
+ * deliberately not: a registry dev tool (vitest, eslint, typescript) is never
+ * loaded by the analyzer, and folding the dev tree into the receipt would churn
+ * `dependencyRuntime.digest` — and force a full re-analysis — on every unrelated
+ * devDependency bump.
+ *
+ * Locally linked dev dependencies are the exception. A `file:`/`link:`/
+ * `workspace:` sibling is part of this checkout and ships code the analyzer
+ * imports at runtime: GitNexus links `gitnexus-shared`, whose schema constants
+ * feed `RELATION_SCHEMA`/`NODE_SCHEMA_QUERIES`. In `kind: 'source'` runs that
+ * sibling sits outside `buildRoot`, so leaving it out let a semantic change
+ * there alter analyzer behaviour while moving neither `build.digest` nor
+ * `dependencyRuntime.digest` — DDL-affecting edits were still caught by the
+ * schema fingerprint, semantics-only edits by nothing.
+ *
+ * An unresolvable link (a published install, where the sibling checkout does not
+ * exist) still contributes its `<missing>` edge, so the linked package appearing
+ * or disappearing remains a receipt change rather than a silent one. That is why
+ * the specifier check cannot be replaced by resolution: resolution returns
+ * `null` for an absent linked checkout exactly as it does for an uninstalled
+ * registry dev tool, and the two must not be conflated.
+ *
+ * This function is the DECLARED-INTENT half and is enumerated for every package
+ * in the dependency BFS, so it must stay a pure function of the manifest. The
+ * RESOLVED-LOCATION half — `npm link <pkg>`, which leaves the specifier a
+ * registry range — lives in {@link undeclaredLocalDevDependencyNames} and is
+ * applied to the root package only.
+ */
 function dependencyNames(manifest) {
     const names = new Set();
     for (const section of [
@@ -609,6 +717,13 @@ function dependencyNames(manifest) {
         for (const name of Object.keys(section))
             names.add(name);
     }
+    const development = manifest.devDependencies;
+    if (development && typeof development === 'object') {
+        for (const [name, specifier] of Object.entries(development)) {
+            if (isLocallyLinkedSpecifier(specifier))
+                names.add(name);
+        }
+    }
     return [...names].sort(compareBytes);
 }
 function resolveDependencyPackageRoot(fromRoot, packageName, pathGuards, limits) {
@@ -641,6 +756,51 @@ function resolveDependencyPackageRoot(fromRoot, packageName, pathGuards, limits)
         cursor = parent;
     }
 }
+/**
+ * Dev dependencies that are locally linked by INSTALLED LOCATION rather than by
+ * declared specifier — the `npm link <pkg>` shape, where the manifest still
+ * carries a registry range while `node_modules/<pkg>` is a symlink into a
+ * working checkout. {@link isLocallyLinkedSpecifier} is blind to those, yet the
+ * linked code is exactly as load-bearing for analyzer semantics as a declared
+ * `file:` sibling, so a semantic-only edit there would move neither digest.
+ *
+ * The resolver already knows: {@link resolveDependencyPackageRoot} returns a
+ * realpath, so a linked package reports a root outside every `node_modules`
+ * tree while an ordinary installed package cannot.
+ *
+ * Two properties are load-bearing and must not be relaxed:
+ *
+ * 1. ROOT ONLY. {@link dependencyNames} runs for every package in the BFS, and
+ *    published tarballs keep their `devDependencies`, so probing dev-only names
+ *    everywhere costs 1998 resolutions rather than the ~13 this manifest
+ *    declares — measured on this install, with 0 true positives. Persisted
+ *    `dependencyPathGuards` grow 2220 → 11049, and every guard is re-probed on
+ *    each warm validation, so the cost is recurring and on the `status` path.
+ *    Root-only costs 13 resolutions and ~29 guards.
+ * 2. An unresolvable name is NEVER admitted. `null` here means "uninstalled
+ *    registry dev tool" far more often than "broken link", and admitting it
+ *    would emit a `<missing>` edge for every dev tool absent from a published
+ *    install. Declared links keep that edge through {@link dependencyNames};
+ *    undeclared ones have no declaration to honour.
+ *
+ * The admission count is bounded by {@link MAX_UNDECLARED_LOCAL_DEV_DEPENDENCIES}.
+ */
+function undeclaredLocalDevDependencyNames(rootPackage, pathGuards, limits) {
+    const development = rootPackage.manifest.devDependencies;
+    if (!development || typeof development !== 'object')
+        return [];
+    const admitted = [];
+    for (const [name, specifier] of Object.entries(development)) {
+        // Already carried by the declared half; resolving again would only add
+        // guards. Its `<missing>` edge is that half's responsibility.
+        if (isLocallyLinkedSpecifier(specifier))
+            continue;
+        const resolved = resolveDependencyPackageRoot(rootPackage.root, name, pathGuards, limits);
+        if (resolved !== null && !hasNodeModulesSegment(resolved))
+            admitted.push(name);
+    }
+    return admitted.length <= MAX_UNDECLARED_LOCAL_DEV_DEPENDENCIES ? admitted : [];
+}
 function collectRuntimePackages(packageRoot, directoryGuards, pathGuards, options, budget, limits) {
     const rootManifestPath = path.join(packageRoot, 'package.json');
     recordDirectoryGuard(directoryGuards, packageRoot);
@@ -660,7 +820,20 @@ function collectRuntimePackages(packageRoot, directoryGuards, pathGuards, option
     budget.packages = 1;
     for (let index = 0; index < queue.length; index += 1) {
         const parent = queue[index];
-        for (const dependencyName of dependencyNames(parent.manifest)) {
+        // The declared half is enumerated for every package; the resolved-location
+        // half is scoped to the root package, where the 1998-resolution /
+        // 8829-extra-guard blow-up documented on
+        // `undeclaredLocalDevDependencyNames` cannot occur. Dropping this scope is
+        // the expensive regression, so it is pinned by a guard-count test.
+        const dependencies = parent.root === packageRoot
+            ? [
+                ...new Set([
+                    ...dependencyNames(parent.manifest),
+                    ...undeclaredLocalDevDependencyNames(parent, pathGuards, limits),
+                ]),
+            ].sort(compareBytes)
+            : dependencyNames(parent.manifest);
+        for (const dependencyName of dependencies) {
             budget.edges += 1;
             if (budget.edges > limits.runtimeEdges) {
                 throw new Error(`Analyzer dependency graph exceeded ${limits.runtimeEdges} edges: ${packageRoot}`);
@@ -736,22 +909,63 @@ function collectArtifacts(root, canonicalPrefix, directoryGuards, options, budge
             throw new Error(`Analyzer runtime payload scan exceeded ${limits.runtimeEntries} entries: ${root}`);
         }
         for (const entry of entries) {
+            const absolutePath = path.join(absoluteDir, entry.name);
+            const relativePath = path.relative(root, absolutePath).split(path.sep).join('/');
+            const stat = lstatSync(absolutePath);
             // Nested dependencies are collected from their manifests as separate
             // packages. Only prune those separately traversed trees and VCS
             // metadata; generic cache/model directories can contain loadable code,
             // native addons, Wasm modules, or data consumed by the runtime.
-            if (entry.isDirectory() && PRUNED_RUNTIME_DIRECTORIES.has(entry.name)) {
+            //
+            // Pruning is decided by NAME alone. These four names never carry analyzer
+            // payload in any form: `node_modules` is traversed separately through
+            // `resolveDependencyPackageRoot` (which follows links and guards each
+            // hop), and a `.git`/`.hg`/`.svn` entry is VCS metadata whether it is a
+            // directory, a symbolic link into a shared store, or — inside a submodule
+            // or linked worktree checkout — a regular file holding a gitdir pointer.
+            // Hashing that pointer would make analyzer identity depend on where the
+            // checkout happens to live, which is a false-stale source, not a
+            // semantic input.
+            if (PRUNED_RUNTIME_DIRECTORIES.has(entry.name))
                 continue;
-            }
-            const absolutePath = path.join(absoluteDir, entry.name);
-            const relativePath = path.relative(root, absolutePath).split(path.sep).join('/');
-            const stat = lstatSync(absolutePath);
             if (stat.isDirectory()) {
                 if (depth >= limits.runtimeDepth) {
                     throw new Error(`Analyzer runtime payload scan exceeded depth ${limits.runtimeDepth}: ${absolutePath}`);
                 }
                 pending.push({ absoluteDir: absolutePath, depth: depth + 1 });
             }
+            else if (stat.isSymbolicLink() && !isFile(absolutePath)) {
+                // A symbolic link that does not resolve to a regular file must never
+                // reach the payload branch below: `snapshotReadableFile` stats the
+                // target, and a directory (or a dangling link) makes it throw, aborting
+                // the entire analyze. Workspace-linked checkouts made this reachable
+                // for every name, not just the pruned four — `dist -> build`, a
+                // vendored-grammar link, anything a sibling checkout ships.
+                //
+                // Such links are RECORDED by their link text rather than followed.
+                // Following them would (a) recurse without cycle protection — this
+                // traversal has none, so `self -> .` would ride the depth limit, which
+                // THROWS, trading one hard abort for another; (b) re-scan trees already
+                // reached by their real path, inflating the entry/byte budgets that
+                // also throw; and (c) need a whole containment/TOCTOU trust boundary
+                // for targets outside the package. Recording the text is cycle-free,
+                // costs one `readlink`, and still moves the receipt when the link is
+                // retargeted. The trade-off is that a link's target contributes no
+                // content of its own: when it points outside the package, only the
+                // link text is covered. Links that DO resolve to a regular file keep
+                // their content digest below, unchanged.
+                if (shouldHashRuntimePayload(relativePath)) {
+                    budget.artifacts += 1;
+                    if (budget.artifacts > limits.runtimePayloads) {
+                        throw new Error(`Analyzer runtime payload scan exceeded ${limits.runtimePayloads} payloads: ${root}`);
+                    }
+                    artifacts.push({
+                        absolutePath,
+                        canonicalPath: `${canonicalPrefix}/${relativePath}`,
+                        kind: 'unfollowed-symlink',
+                    });
+                }
+            }
             else if ((stat.isFile() || stat.isSymbolicLink()) &&
                 shouldHashRuntimePayload(relativePath)) {
                 const readableState = snapshotReadableFile(absolutePath);
@@ -889,7 +1103,7 @@ function dependencySnapshot(inputs) {
             absolutePath: artifact.absolutePath,
             canonicalPath: artifact.canonicalPath,
             kind: artifact.kind,
-            state: snapshotReadableFile(artifact.absolutePath),
+            state: snapshotRuntimeArtifact(artifact),
         })),
         directories: [...inputs.directoryGuards.entries()]
             .map(([absolutePath, guard]) => ({ absolutePath, ...guard }))
@@ -903,9 +1117,26 @@ function artifactCacheKey(artifact) {
     return JSON.stringify([artifact.kind, artifact.canonicalPath, artifact.absolutePath]);
 }
 function hashRuntimeArtifact(artifact, cache, options) {
+    if (artifact.kind === 'unfollowed-symlink') {
+        // The link text is the entire payload, so there is no file read for a
+        // cached digest to amortize: recompute it and stay independent of the
+        // cache's freshness. The distinct frame label keeps a link recording from
+        // ever colliding with a content digest.
+        const state = snapshotSymlinkArtifact(artifact.absolutePath);
+        return {
+            ...artifact,
+            state,
+            digest: hashCanonicalFrames([
+                ['runtime-payload-link-v1', artifact.kind, state.symlinkTarget],
+            ]),
+        };
+    }
     const before = snapshotReadableFile(artifact.absolutePath);
-    if (cache && SHA256_PATTERN.test(cache.digest) && isDeepStrictEqual(cache.state, before)) {
-        return { digest: cache.digest, state: before };
+    if (cache &&
+        cache.kind !== 'unfollowed-symlink' &&
+        SHA256_PATTERN.test(cache.digest) &&
+        isDeepStrictEqual(cache.state, before)) {
+        return { ...artifact, state: before, digest: cache.digest };
     }
     const stable = hashStableFile(artifact.absolutePath);
     const digest = hashCanonicalFrames([
@@ -921,7 +1152,7 @@ function hashRuntimeArtifact(artifact, cache, options) {
         path: artifact.absolutePath,
         bytes: stable.bytes,
     });
-    return { digest, state: stable.state };
+    return { ...artifact, state: stable.state, digest };
 }
 function compareEdges(a, b) {
     return compareBytes(JSON.stringify([
@@ -986,7 +1217,7 @@ function hashDependencyRuntime(inputs, cache, options, runtimeVariant) {
             artifact.kind,
             digestBytes(hashed.digest),
         ]);
-        nextArtifacts.push({ ...artifact, state: hashed.state, digest: hashed.digest });
+        nextArtifacts.push(hashed);
     }
     return {
         identity: {
@@ -1014,6 +1245,17 @@ function isReadableFileState(value) {
         isStatState(record.target) &&
         (record.symlinkTarget === undefined || typeof record.symlinkTarget === 'string'));
 }
+function isSymlinkArtifactState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    // `target === undefined` keeps a readable-file state from masquerading as an
+    // unresolved link recording, which would otherwise be validated against the
+    // wrong guard mode on the warm path.
+    return (isStatState(record.link) &&
+        typeof record.symlinkTarget === 'string' &&
+        record.target === undefined);
+}
 function isDependencyPathGuardResult(value) {
     if (value === null)
         return true;
@@ -1159,13 +1401,16 @@ function isIdentityCachePayload(value, packageRoot, buildRoot, runtimeVariant, t
         if (typeof entry !== 'object' || entry === null)
             return false;
         const item = entry;
-        return (typeof item.absolutePath === 'string' &&
-            path.isAbsolute(item.absolutePath) &&
-            typeof item.canonicalPath === 'string' &&
-            (item.kind === 'file' || item.kind === 'symlink') &&
-            isReadableFileState(item.state) &&
-            typeof item.digest === 'string' &&
-            SHA256_PATTERN.test(item.digest));
+        if (typeof item.absolutePath !== 'string' ||
+            !path.isAbsolute(item.absolutePath) ||
+            typeof item.canonicalPath !== 'string' ||
+            typeof item.digest !== 'string' ||
+            !SHA256_PATTERN.test(item.digest)) {
+            return false;
+        }
+        return item.kind === 'unfollowed-symlink'
+            ? isSymlinkArtifactState(item.state)
+            : (item.kind === 'file' || item.kind === 'symlink') && isReadableFileState(item.state);
     });
     const hasBuildRootGuard = record.buildDirectoryGuards.some((entry) => typeof entry === 'object' &&
         entry !== null &&
@@ -1587,9 +1832,24 @@ function validateIdentityCache(cache, options) {
         }
     }
     for (const artifact of cache.artifactEntries) {
-        if (!add({ absolutePath: artifact.absolutePath, mode: 'readable-file' }, { type: 'readable-file', state: artifact.state })) {
+        // A recorded link is re-probed as a link, never as a readable file: the
+        // readable-file probe resolves the target and would report `null` for the
+        // very inputs this kind exists to describe, failing every warm validation.
+        const probe = artifact.kind === 'unfollowed-symlink'
+            ? {
+                request: { absolutePath: artifact.absolutePath, mode: 'link' },
+                expected: {
+                    type: 'symlink',
+                    state: artifact.state.link,
+                    symlinkTarget: artifact.state.symlinkTarget,
+                },
+            }
+            : {
+                request: { absolutePath: artifact.absolutePath, mode: 'readable-file' },
+                expected: { type: 'readable-file', state: artifact.state },
+            };
+        if (!add(probe.request, probe.expected))
             return false;
-        }
     }
     const entries = [...expected.entries()];
     const requests = entries.map(([key]) => {

package/dist/core/lbug/schema.d.ts

@@ -98,3 +98,111 @@ export declare const CREATE_VECTOR_INDEX_QUERY = "\nCALL CREATE_VECTOR_INDEX('Co
 export declare const NODE_SCHEMA_QUERIES: string[];
 export declare const REL_SCHEMA_QUERIES: string[];
 export declare const SCHEMA_QUERIES: string[];
+/**
+ * Digest of the graph DDL this build creates — the exact statements
+ * {@link runSchemaCreationQueries} (lbug-adapter.ts) executes for the node and
+ * relation tables.
+ *
+ * This REPLACED `INCREMENTAL_SCHEMA_VERSION` (#2798), a hand-incremented
+ * integer in repo-manager.ts that had to PREDICT whether an on-disk database
+ * was created from this build's DDL. It could not: the number collided with
+ * `main` eight times, twice EXACTLY, and an exact clash was the quiet failure —
+ * two builds stamp the same number over different DDL, the strict `===` gate
+ * reads the index as current, every `CREATE … TABLE` is skipped as "already
+ * exists" (suppressed in `runSchemaCreationQueries`), and the edges whose
+ * endpoint pair the live DB cannot persist are dropped by
+ * `fallbackRelationshipInserts`' bare `catch`. A wrong graph, not an error.
+ *
+ * A digest cannot collide BY ACCIDENT at this scale: 12 hex chars is 48 bits,
+ * so even 1,000 distinct DDL variants over the project's whole life put the
+ * birthday probability of any pair matching at ≈1.8e-9. Two builds agree
+ * exactly when their DDL agrees, so concurrent branches never need renumbering.
+ * Do not shorten the slice: the odds double per bit dropped. On mismatch —
+ * including the ABSENT stamp every pre-#2798 index carries — run-analyze warns
+ * and forces a full re-analyze, which wipes the database and recreates the
+ * tables from the DDL below.
+ *
+ * {@link EMBEDDING_SCHEMA} is deliberately EXCLUDED. Its `FLOAT[N]` width comes
+ * from `GITNEXUS_EMBEDDING_DIMS` at module load, so folding it in would make
+ * this a function of the ENVIRONMENT rather than of code: two runs of the same
+ * build under different env would disagree and force alternating full rebuilds.
+ * Vector-column drift is therefore a SEPARATE gate, not an ungated hazard:
+ * {@link embeddingDimsMismatch} compares the width stamped in
+ * `RepoMeta.embeddingDims` against {@link EMBEDDING_DIMS} and run-analyze
+ * forces a rebuild on drift. Do not merge the two — an env-derived value in a
+ * code digest makes the same build disagree with itself. (The older reaction in
+ * run-analyze remains, and is to the CACHE, not the schema: when the cached
+ * vectors' length differs from `EMBEDDING_DIMS` it discards the cache and
+ * re-embeds.)
+ */
+export declare const SCHEMA_FINGERPRINT: string;
+/**
+ * Whether an index built under `recorded` can be reused by this build.
+ *
+ * Lives here rather than in run-analyze so the query side can ask the same
+ * question without importing the analyze pipeline — the reason
+ * `cjkSegmentationModeMismatch` sits in `core/search/` rather than beside its
+ * caller. ABSENT counts as a mismatch: that is the backward-compatibility path
+ * for every index written before the field existed, and grandfathering it would
+ * stamp a fresh fingerprint onto a database whose DDL was never verified.
+ */
+export declare const schemaFingerprintMismatch: (recorded: string | undefined) => boolean;
+/**
+ * Whether a stamped value has the shape {@link SCHEMA_FINGERPRINT} produces —
+ * the lowercase-hex prefix of a sha256 digest. The width is read from the live
+ * constant, so changing the slice above needs no edit here.
+ *
+ * Used to decide whether a stamp is worth NAMING in a diagnostic: an index with
+ * no fingerprint and one carrying a malformed value are both "not this build",
+ * but only the first has an explanation worth printing. Not a comparison gate —
+ * {@link schemaFingerprintMismatch} already rejects every value that is not
+ * exactly this build's.
+ */
+export declare const isSchemaFingerprintShaped: (value: unknown) => value is string;
+/**
+ * Whether the vector-column width an index's `CodeEmbedding` table was created
+ * at (as persisted in `RepoMeta.embeddingDims`) differs from the width this
+ * process would embed at ({@link EMBEDDING_DIMS}). The gate
+ * {@link SCHEMA_FINGERPRINT} deliberately cannot be: `FLOAT[N]` comes from
+ * `GITNEXUS_EMBEDDING_DIMS` at module load, so folding it into a digest of the
+ * DDL would make that digest a function of the ENVIRONMENT. Splitting it out
+ * here keeps the fingerprint purely code-derived and still gates the width —
+ * before this, flipping `GITNEXUS_EMBEDDING_DIMS` on a same-commit clean tree
+ * fired no guard at all: `alreadyUpToDate` returned over a `FLOAT[384]` table
+ * while the process embedded at 768. (The one pre-existing reaction, in
+ * run-analyze, discards the embedding CACHE and re-embeds — into a column whose
+ * width was never revisited.) A single scalar, so plain equality suffices.
+ *
+ * ABSENT does NOT count as a mismatch — the opposite of
+ * {@link schemaFingerprintMismatch}, and deliberately:
+ *
+ *  - Absence carries no signal about the width. A missing fingerprint means
+ *    "DDL this build cannot vouch for", and the field ships WITH a DDL change,
+ *    so absence is itself evidence of drift. A missing dims stamp means only
+ *    "written before the field existed"; the width was whatever that run's env
+ *    resolved, almost always the 384 default, and it was consistent with the
+ *    table it wrote. Drift needs the env to CHANGE, which absence says nothing
+ *    about.
+ *  - Forcing on absence would buy no safety anyway. Every index that lacks this
+ *    stamp also lacks `schemaFingerprint` (both landed together in #2798), and
+ *    that guard already forces a rebuild for exactly those indexes — after
+ *    which the width is stamped and the hazard is closed for good. A second
+ *    trigger for the same one rebuild is dead weight that would keep firing
+ *    forever on any future path that legitimately omits the stamp.
+ *  - The cost of guessing wrong is asymmetric: a fleet-wide full re-analyze
+ *    (minutes to hours per repo) for a hazard that requires a rare, deliberate
+ *    env change.
+ *
+ * Absence is precisely `undefined`. Any other recorded value that is not this
+ * build's width — including a malformed one, since `meta.json` is a schema-less
+ * `JSON.parse` of on-disk state — reads as a mismatch and errs toward a
+ * rebuild, which is the safe direction.
+ *
+ * Pure + exported for testing, and takes `current` explicitly rather than
+ * closing over {@link EMBEDDING_DIMS}: that constant is frozen at module load,
+ * so a parameter is the only way to exercise both sides of the comparison.
+ * Lives here rather than in run-analyze for the reason
+ * `cjkSegmentationModeMismatch` lives in `core/search/` — a caller that only
+ * needs the comparator should not have to pull in the analyze pipeline.
+ */
+export declare const embeddingDimsMismatch: (recorded: number | undefined, current: number) => boolean;

package/dist/core/lbug/schema.js

@@ -8,6 +8,7 @@
  * This allows LLMs to write natural Cypher queries like:
  *   MATCH (f:Function)-[r:CodeRelation {type: 'CALLS'}]->(g:Function) RETURN f, g
  */
+import { createHash } from 'crypto';
 // Import from shared package (single source of truth) — used in DDL templates below
 import { NODE_TABLES, REL_TABLE_NAME, REL_TYPES, EMBEDDING_TABLE_NAME } from '../../_shared/index.js';
 import { parseRelationSchemaPairs } from './rel-pair-routing.js';
@@ -614,3 +615,116 @@ export const NODE_SCHEMA_QUERIES = [
 ];
 export const REL_SCHEMA_QUERIES = [RELATION_SCHEMA];
 export const SCHEMA_QUERIES = [...NODE_SCHEMA_QUERIES, ...REL_SCHEMA_QUERIES, EMBEDDING_SCHEMA];
+/**
+ * Digest of the graph DDL this build creates — the exact statements
+ * {@link runSchemaCreationQueries} (lbug-adapter.ts) executes for the node and
+ * relation tables.
+ *
+ * This REPLACED `INCREMENTAL_SCHEMA_VERSION` (#2798), a hand-incremented
+ * integer in repo-manager.ts that had to PREDICT whether an on-disk database
+ * was created from this build's DDL. It could not: the number collided with
+ * `main` eight times, twice EXACTLY, and an exact clash was the quiet failure —
+ * two builds stamp the same number over different DDL, the strict `===` gate
+ * reads the index as current, every `CREATE … TABLE` is skipped as "already
+ * exists" (suppressed in `runSchemaCreationQueries`), and the edges whose
+ * endpoint pair the live DB cannot persist are dropped by
+ * `fallbackRelationshipInserts`' bare `catch`. A wrong graph, not an error.
+ *
+ * A digest cannot collide BY ACCIDENT at this scale: 12 hex chars is 48 bits,
+ * so even 1,000 distinct DDL variants over the project's whole life put the
+ * birthday probability of any pair matching at ≈1.8e-9. Two builds agree
+ * exactly when their DDL agrees, so concurrent branches never need renumbering.
+ * Do not shorten the slice: the odds double per bit dropped. On mismatch —
+ * including the ABSENT stamp every pre-#2798 index carries — run-analyze warns
+ * and forces a full re-analyze, which wipes the database and recreates the
+ * tables from the DDL below.
+ *
+ * {@link EMBEDDING_SCHEMA} is deliberately EXCLUDED. Its `FLOAT[N]` width comes
+ * from `GITNEXUS_EMBEDDING_DIMS` at module load, so folding it in would make
+ * this a function of the ENVIRONMENT rather than of code: two runs of the same
+ * build under different env would disagree and force alternating full rebuilds.
+ * Vector-column drift is therefore a SEPARATE gate, not an ungated hazard:
+ * {@link embeddingDimsMismatch} compares the width stamped in
+ * `RepoMeta.embeddingDims` against {@link EMBEDDING_DIMS} and run-analyze
+ * forces a rebuild on drift. Do not merge the two — an env-derived value in a
+ * code digest makes the same build disagree with itself. (The older reaction in
+ * run-analyze remains, and is to the CACHE, not the schema: when the cached
+ * vectors' length differs from `EMBEDDING_DIMS` it discards the cache and
+ * re-embeds.)
+ */
+export const SCHEMA_FINGERPRINT = createHash('sha256')
+    .update([...NODE_SCHEMA_QUERIES, ...REL_SCHEMA_QUERIES].join('\n'))
+    .digest('hex')
+    .slice(0, 12);
+/**
+ * Whether an index built under `recorded` can be reused by this build.
+ *
+ * Lives here rather than in run-analyze so the query side can ask the same
+ * question without importing the analyze pipeline — the reason
+ * `cjkSegmentationModeMismatch` sits in `core/search/` rather than beside its
+ * caller. ABSENT counts as a mismatch: that is the backward-compatibility path
+ * for every index written before the field existed, and grandfathering it would
+ * stamp a fresh fingerprint onto a database whose DDL was never verified.
+ */
+export const schemaFingerprintMismatch = (recorded) => recorded !== SCHEMA_FINGERPRINT;
+/**
+ * Whether a stamped value has the shape {@link SCHEMA_FINGERPRINT} produces —
+ * the lowercase-hex prefix of a sha256 digest. The width is read from the live
+ * constant, so changing the slice above needs no edit here.
+ *
+ * Used to decide whether a stamp is worth NAMING in a diagnostic: an index with
+ * no fingerprint and one carrying a malformed value are both "not this build",
+ * but only the first has an explanation worth printing. Not a comparison gate —
+ * {@link schemaFingerprintMismatch} already rejects every value that is not
+ * exactly this build's.
+ */
+export const isSchemaFingerprintShaped = (value) => typeof value === 'string' &&
+    value.length === SCHEMA_FINGERPRINT.length &&
+    /^[0-9a-f]+$/.test(value);
+/**
+ * Whether the vector-column width an index's `CodeEmbedding` table was created
+ * at (as persisted in `RepoMeta.embeddingDims`) differs from the width this
+ * process would embed at ({@link EMBEDDING_DIMS}). The gate
+ * {@link SCHEMA_FINGERPRINT} deliberately cannot be: `FLOAT[N]` comes from
+ * `GITNEXUS_EMBEDDING_DIMS` at module load, so folding it into a digest of the
+ * DDL would make that digest a function of the ENVIRONMENT. Splitting it out
+ * here keeps the fingerprint purely code-derived and still gates the width —
+ * before this, flipping `GITNEXUS_EMBEDDING_DIMS` on a same-commit clean tree
+ * fired no guard at all: `alreadyUpToDate` returned over a `FLOAT[384]` table
+ * while the process embedded at 768. (The one pre-existing reaction, in
+ * run-analyze, discards the embedding CACHE and re-embeds — into a column whose
+ * width was never revisited.) A single scalar, so plain equality suffices.
+ *
+ * ABSENT does NOT count as a mismatch — the opposite of
+ * {@link schemaFingerprintMismatch}, and deliberately:
+ *
+ *  - Absence carries no signal about the width. A missing fingerprint means
+ *    "DDL this build cannot vouch for", and the field ships WITH a DDL change,
+ *    so absence is itself evidence of drift. A missing dims stamp means only
+ *    "written before the field existed"; the width was whatever that run's env
+ *    resolved, almost always the 384 default, and it was consistent with the
+ *    table it wrote. Drift needs the env to CHANGE, which absence says nothing
+ *    about.
+ *  - Forcing on absence would buy no safety anyway. Every index that lacks this
+ *    stamp also lacks `schemaFingerprint` (both landed together in #2798), and
+ *    that guard already forces a rebuild for exactly those indexes — after
+ *    which the width is stamped and the hazard is closed for good. A second
+ *    trigger for the same one rebuild is dead weight that would keep firing
+ *    forever on any future path that legitimately omits the stamp.
+ *  - The cost of guessing wrong is asymmetric: a fleet-wide full re-analyze
+ *    (minutes to hours per repo) for a hazard that requires a rare, deliberate
+ *    env change.
+ *
+ * Absence is precisely `undefined`. Any other recorded value that is not this
+ * build's width — including a malformed one, since `meta.json` is a schema-less
+ * `JSON.parse` of on-disk state — reads as a mismatch and errs toward a
+ * rebuild, which is the safe direction.
+ *
+ * Pure + exported for testing, and takes `current` explicitly rather than
+ * closing over {@link EMBEDDING_DIMS}: that constant is frozen at module load,
+ * so a parameter is the only way to exercise both sides of the comparison.
+ * Lives here rather than in run-analyze for the reason
+ * `cjkSegmentationModeMismatch` lives in `core/search/` — a caller that only
+ * needs the comparator should not have to pull in the analyze pipeline.
+ */
+export const embeddingDimsMismatch = (recorded, current) => recorded !== undefined && recorded !== current;