@remnic/coding-graph 9.3.759

package/src/row-types.ts

@@ -0,0 +1,45 @@
+/**
+ * Typed-row helpers for better-sqlite3 — narrow the library's `unknown`
+ * return values with a runtime shape check before reading properties.
+ *
+ * better-sqlite3 returns `unknown` for `.get()` and `unknown[]` for
+ * `.all()`. The codebase has historically relied on inline `as` casts;
+ * this module provides a typed wrapper that validates the SHAPE at runtime
+ * so a bad query (column renames, dropped columns) fails loudly instead
+ * of silently reading `undefined`.
+ */
+
+export type SqliteRow = Record<string, unknown>;
+
+export function isSqliteRow(value: unknown): value is SqliteRow {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Narrow a `.get()` result. Returns `undefined` when the row is missing
+ * OR when the expected columns are absent. Callers can then assert the
+ * expected shape (the columns are guaranteed to exist after this check).
+ */
+export function expectRow<T extends SqliteRow>(
+  value: unknown,
+  columns: readonly (keyof T)[],
+): T | undefined {
+  if (!isSqliteRow(value)) return undefined;
+  for (const col of columns) {
+    if (!(col in value)) return undefined;
+  }
+  return value as T;
+}
+
+export function expectRows<T extends SqliteRow>(
+  value: unknown,
+  columns: readonly (keyof T)[],
+): T[] {
+  if (!Array.isArray(value)) return [];
+  const out: T[] = [];
+  for (const row of value) {
+    const narrowed = expectRow<T>(row, columns);
+    if (narrowed) out.push(narrowed);
+  }
+  return out;
+}

package/src/semantic/canonical-text.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Canonical-text builder tests (issue #1556 step 1 — prove-fail-before).
+ *
+ * Rule 23/38: ONE canonical form. Two formatting-variant fixtures of the
+ * same function MUST produce the same canonical text; the embedded string
+ * equals the hashed string (one assertion).
+ *
+ * Rule 37: cache invalidation. When canonical text changes (rename / body
+ * edit), the hash changes.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildCanonicalText,
+  buildCanonicalTextAndHash,
+  canonicalTextHash,
+  collapseWhitespace,
+} from "./canonical-text.js";
+import type { SymbolIR } from "@remnic/core";
+
+function fn(qname: string, rawText: string): SymbolIR {
+  return {
+    kind: "function",
+    name: qname.split(".").pop() ?? qname,
+    qualifiedName: qname,
+    span: { startByte: 0, endByte: rawText.length },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Rule 23/38: ONE canonical form — formatting variants hash identically.
+// ──────────────────────────────────────────────────────────────────────────
+
+test("canonical text: whitespace-only variants produce identical text", () => {
+  const variantA = `function add(a, b) {\n    return a + b;\n}`;
+  const variantB = `function  add(a,b){\n\treturn a+b;\n}`;
+  const sym = fn("mod.add", variantA);
+  const textA = buildCanonicalText({ symbol: sym, rawText: variantA });
+  const textB = buildCanonicalText({ symbol: sym, rawText: variantB });
+  assert.equal(textA, textB, "indentation/spacing variants must canonicalize identically");
+});
+
+test("canonical text: brace-style variants produce identical text", () => {
+  const sameLine = `function foo(x) { return x * 2; }`;
+  const newLine = `function foo(x)\n{\n  return x * 2;\n}`;
+  const sym = fn("mod.foo", sameLine);
+  assert.equal(
+    buildCanonicalText({ symbol: sym, rawText: sameLine }),
+    buildCanonicalText({ symbol: sym, rawText: newLine }),
+  );
+});
+
+test("canonical text: the embedded string equals the hashed string (rule 23)", () => {
+  const raw = `function bar(n) { return n + 1; }`;
+  const sym = fn("mod.bar", raw);
+  const { text, hash } = buildCanonicalTextAndHash({ symbol: sym, rawText: raw });
+  // The hash is over the EXACT text returned — no transformation gap.
+  assert.equal(hash, canonicalTextHash(text));
+  // And a different text produces a different hash.
+  const other = buildCanonicalTextAndHash({ symbol: fn("mod.baz", raw), rawText: raw });
+  assert.notEqual(hash, other.hash);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Rule 37: cache invalidation — rename / body change changes the hash.
+// ──────────────────────────────────────────────────────────────────────────
+
+test("canonical hash: rename changes the hash (cache invalidation)", () => {
+  const raw = `function f() { return 42; }`;
+  const before = buildCanonicalTextAndHash({ symbol: fn("mod.oldName", raw), rawText: raw });
+  const after = buildCanonicalTextAndHash({ symbol: fn("mod.newName", raw), rawText: raw });
+  assert.notEqual(before.hash, after.hash, "a rename must invalidate the cache");
+});
+
+test("canonical hash: body change changes the hash", () => {
+  const rawA = `function f() { return 1; }`;
+  const rawB = `function f() { return 2; }`;
+  const before = buildCanonicalTextAndHash({ symbol: fn("mod.f", rawA), rawText: rawA });
+  const after = buildCanonicalTextAndHash({ symbol: fn("mod.f", rawB), rawText: rawB });
+  assert.notEqual(before.hash, after.hash);
+});
+
+test("canonical hash: unchanged symbol is stable (idempotent)", () => {
+  const raw = `function stable() { console.log("hi"); }`;
+  const a = buildCanonicalTextAndHash({ symbol: fn("mod.stable", raw), rawText: raw });
+  const b = buildCanonicalTextAndHash({ symbol: fn("mod.stable", raw), rawText: raw });
+  assert.equal(a.hash, b.hash);
+  assert.equal(a.text, b.text);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// collapseWhitespace unit
+// ──────────────────────────────────────────────────────────────────────────
+
+test("collapseWhitespace: tabs/newlines/multiple-spaces → single space", () => {
+  assert.equal(collapseWhitespace("\t\thello   world\t"), "hello world");
+  assert.equal(collapseWhitespace("a\n\n\n\nb"), "a b");
+  assert.equal(collapseWhitespace("  line one \n line two  "), "line one line two");
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Body truncation respects maxBodyLines
+// ──────────────────────────────────────────────────────────────────────────
+
+test("canonical text: body truncated to maxBodyLines (token budget)", () => {
+  const raw = `function big() { ${Array.from({ length: 50 }, (_, i) => `const x${i} = ${i};`).join(" ")} }`;
+  const sym = fn("mod.big", raw);
+  const text4 = buildCanonicalText({ symbol: sym, rawText: raw, maxBodyLines: 4 });
+  const textAll = buildCanonicalText({ symbol: sym, rawText: raw, maxBodyLines: 0 });
+  const body4 = text4.split("BODY:")[1]!.trim();
+  const bodyAll = textAll.split("BODY:")[1]!.trim();
+  assert.ok(body4.split(/\s+/).length <= 4, `truncated body should have <=4 tokens, got ${body4.split(/\s+/).length}`);
+  assert.ok(bodyAll.split(/\s+/).length > 4, "full body should have more than 4 tokens");
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Braceless arrow functions keep their body (cursor Bugbot: 'Arrow bodies
+// lost in canonical text'). collapseWhitespace splits `=>` into `= >`, so
+// the signature/body split must search the NORMALIZED arrow form.
+// ──────────────────────────────────────────────────────────────────────────
+
+test("canonical text: braceless arrow body is captured, not empty", () => {
+  const raw = "const double = (x) => x * 2";
+  const sym = fn("mod.double", raw);
+  const text = buildCanonicalText({ symbol: sym, rawText: raw });
+  const body = text.split("BODY:")[1]!.trim();
+  assert.ok(body.length > 0, `braceless arrow should keep a non-empty body, got "${body}"`);
+  assert.ok(body.includes("x"), `body should include the expression text, got "${body}"`);
+});
+
+test("canonical text: braceless arrow variants canonicalize identically", () => {
+  const spaced = "const f = (x) => x + 1";
+  const tight = "const f=(x)=>x+1";
+  const sym = fn("mod.f", spaced);
+  assert.equal(
+    buildCanonicalText({ symbol: sym, rawText: spaced }),
+    buildCanonicalText({ symbol: sym, rawText: tight }),
+  );
+});
+
+test("canonical text: braced arrow still splits at the brace", () => {
+  const raw = "const f = (x) => { return x + 1; }";
+  const sym = fn("mod.f", raw);
+  const text = buildCanonicalText({ symbol: sym, rawText: raw });
+  const body = text.split("BODY:")[1]!.trim();
+  assert.ok(body.length > 0, "braced arrow should keep a body");
+  assert.ok(body.includes("return"), `braced arrow body should include the block, got "${body}"`);
+});
+

package/src/semantic/canonical-text.ts

@@ -0,0 +1,219 @@
+/**
+ * Canonical-text builder for symbol embeddings (issue #1556).
+ *
+ * Rule 23/38 — ONE canonical form. The exact string that is embedded is
+ * the exact string that is hashed for the embedding cache. Two formatting-
+ * variant fixtures of the same function MUST produce the same canonical
+ * text; the cache-hash test asserts this end to end.
+ *
+ * The canonical form (per the issue design):
+ *   `signature + doc comment + first N lines of body`,
+ * normalized (sorted-key serialization where structured, stable truncation).
+ *
+ * Normalization strategy: ALL whitespace (including newlines) is collapsed
+ * to single spaces BEFORE signature/body split. This absorbs every
+ * formatting variant (indentation, brace placement, trailing whitespace,
+ * tabs vs spaces) so two semantically-identical functions produce IDENTICAL
+ * canonical text. The "first N lines" budget is then applied as a stable
+ * TOKEN budget over the collapsed text — stable because token count is
+ * formatting-independent.
+ *
+ * IMPORTANT: this module takes pre-extracted text spans, not raw source.
+ * The caller (the indexer) slices `[startByte, endByte)` from disk and
+ * passes the raw symbol text. Canonicalization here is about producing a
+ * stable embedding input from that raw text, not about re-parsing.
+ */
+import { createHash } from "node:crypto";
+
+import type { SymbolIR } from "@remnic/core";
+
+import { DEFAULT_CANONICAL_BODY_LINES } from "./config.js";
+
+/**
+ * Input to the canonical-text builder. `rawText` is the symbol's on-disk
+ * source slice `[startByte, endByte)`. `docComment` is the leading
+ * comment block immediately above the symbol, if the caller extracted one
+ * (the parser does not currently emit doc comments on SymbolIR, so this
+ * is optional and may be empty/undefined — the canonical form degrades
+ * gracefully to `signature + body`).
+ */
+export interface CanonicalTextInput {
+  readonly symbol: SymbolIR;
+  /** Raw source text of the symbol span. */
+  readonly rawText: string;
+  /** Optional leading doc comment (/** … *\/ or // … lines). */
+  readonly docComment?: string;
+  /** Body token budget (default {@link DEFAULT_CANONICAL_BODY_LINES}). */
+  readonly maxBodyLines?: number;
+}
+
+/**
+ * Collapse ALL whitespace runs (including newlines) to single spaces and
+ * trim. This is the universal normalization pass: it absorbs indentation,
+ * brace placement, trailing whitespace, tabs vs spaces, and line-ending
+ * differences. After this pass, two formatting variants of the same
+ * function are byte-identical.
+ */
+export function collapseWhitespace(text: string): string {
+  return text
+    // Insert spaces around punctuation so a,b and a, b canonicalize identically.
+    .replace(/([{}()<>\[\],;:?!=+\-*/%&|^~])/g, " $1 ")
+    // Collapse all whitespace runs (including those introduced above) to single spaces.
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Line-oriented whitespace collapse (preserves line structure). Used when
+ * line boundaries matter (e.g. the "first N lines" budget needs real
+ * lines). Collapses intra-line whitespace runs but keeps newlines.
+ */
+export function collapseWhitespaceKeepLines(text: string): string {
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.replace(/[ \t]+/g, " ").trim())
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/**
+ * Split normalized symbol text into signature + body at the first body-
+ * open marker (`{`, `=>`, `:` preceded by a non-type context). The split
+ * is CHARACTER-level on the fully-whitespace-normalized text, so a
+ * same-line function `function f() { return 1; }` and a brace-newline
+ * variant `function f()\n{ return 1; }` both split at the same `{`.
+ *
+ * Returns `{ signature, body }` — both whitespace-normalized. The
+ * signature includes the marker char so the canonical form is stable.
+ */
+function splitSignatureBody(normalized: string): { readonly signature: string; readonly body: string } {
+  // Find the body-open marker. `{` is the universal one (functions,
+  // classes, blocks). When there is no `{` we fall back to the arrow
+  // form so braceless arrow functions (`const f = (x) => x + 1`) split
+  // at the arrow instead of collapsing to an empty body.
+  //
+  // collapseWhitespace's punctuation-spacer turns `=>` into `= >`, so
+  // the raw `=>` marker NEVER appears in the normalized text — search
+  // the normalized form (`= >`) or this whole branch is dead and
+  // braceless arrows lose their body (cursor Bugbot: 'Arrow bodies lost
+  // in canonical text'). Embeddings, cache hashes, and MinHash inputs
+  // then omitted arrow-function logic.
+  const braceIdx = normalized.indexOf("{");
+  if (braceIdx >= 0) {
+    const signature = normalized.slice(0, braceIdx + 1).trim();
+    const body = normalized.slice(braceIdx + 1).trim();
+    return { signature, body };
+  }
+  const arrowIdx = normalized.indexOf("=>");
+  const arrowNormIdx = normalized.indexOf("= >");
+  if (arrowIdx >= 0) {
+    const signature = normalized.slice(0, arrowIdx + 2).trim();
+    const body = normalized.slice(arrowIdx + 2).trim();
+    return { signature, body };
+  }
+  if (arrowNormIdx >= 0) {
+    // `= >` spans 3 chars (`= `, ` `, `>`); cut after the `>`.
+    const bodyStart = arrowNormIdx + 3;
+    const signature = normalized.slice(0, bodyStart).trim();
+    const body = normalized.slice(bodyStart).trim();
+    return { signature, body };
+  }
+  // No body marker — treat the whole text as signature (e.g. `type Foo = string`).
+  return { signature: normalized, body: "" };
+}
+
+/**
+ * Extract a coarse signature string from raw symbol text. The text is
+ * fully whitespace-normalized first, then split at the first body-open
+ * marker. The returned signature is stable across all formatting variants
+ * of the same function.
+ */
+export function extractSignatureLine(
+  rawText: string,
+  _kind: SymbolIR["kind"],
+): string {
+  const normalized = collapseWhitespace(rawText);
+  return splitSignatureBody(normalized).signature;
+}
+
+/**
+ * Extract the body (everything after the signature/header marker) from
+ * raw symbol text, truncated to the first `maxBodyLines` tokens. Tokens
+ * are whitespace-delimited words/operators in the normalized body text —
+ * this is a STABLE budget (formatting-independent) unlike line-based
+ * truncation. `maxBodyLines` is the config field name; it functions as a
+ * token budget here (each "line" ≈ one significant token).
+ *
+ * `maxBodyLines <= 0` means unlimited (return the full normalized body).
+ */
+export function extractBodyText(rawText: string, maxBodyLines: number): string {
+  const normalized = collapseWhitespace(rawText);
+  const body = splitSignatureBody(normalized).body;
+  if (maxBodyLines <= 0 || body.length === 0) return body;
+  const tokens = body.split(/\s+/);
+  return tokens.slice(0, maxBodyLines).join(" ");
+}
+
+/**
+ * Build the canonical embedding text for a symbol.
+ *
+ * The form (rule 23/38 — ONE form, every consumer):
+ *   KIND:<kind>\nQNAME:<qualifiedName>\nSIG:<signature>\n[DOC:<doc>]\nBODY:<body>
+ *
+ * `kind` and `qualifiedName` are included as stable prefix lines so two
+ * functions with identical bodies but different names (the "renamed
+ * variable" clone fixture) embed close but not identically — the qualified
+ * name differentiates them at the embedding level while the body dominates
+ * the similarity. The cache hash, by contrast, is over the FULL canonical
+ * text including the name, so a rename invalidates the cache (rule 37).
+ *
+ * Normalization:
+ *   - ALL whitespace collapsed (indentation/brace-style/newlines absorbed)
+ *   - body truncated to maxBodyLines tokens (stable budget)
+ */
+export function buildCanonicalText(input: CanonicalTextInput): string {
+  const { symbol, rawText, docComment, maxBodyLines } = input;
+  const budget = maxBodyLines ?? DEFAULT_CANONICAL_BODY_LINES;
+  const signature = extractSignatureLine(rawText, symbol.kind);
+  const body = extractBodyText(rawText, budget);
+  const doc = docComment ? collapseWhitespace(docComment) : "";
+  const parts = [
+    `KIND:${symbol.kind}`,
+    `QNAME:${symbol.qualifiedName}`,
+    `SIG:${signature}`,
+  ];
+  if (doc.length > 0) parts.push(`DOC:${doc}`);
+  parts.push(`BODY:${body}`);
+  return parts.join("\n");
+}
+
+/**
+ * The cache key for a canonical text. This is sha256 over the EXACT
+ * canonical text string (rule 23 — the embedded string equals the hashed
+ * string). When the canonical text changes (e.g. a rename edits the
+ * qualified name, or the body changes), the hash changes, and:
+ *   1. the cached vector is invalidated (re-embedded), and
+ *   2. any SIMILAR_TO edge derived from it is recomputed.
+ *
+ * This is the single chokepoint for cache invalidation (rule 37). Every
+ * layer that persists a vector persists THIS hash alongside it; every
+ * re-index compares THIS hash to decide whether to re-embed.
+ */
+export function canonicalTextHash(canonicalText: string): string {
+  return createHash("sha256").update(canonicalText, "utf8").digest("hex");
+}
+
+/**
+ * Convenience: build canonical text AND its hash in one call. The hash is
+ * over the returned text — callers that store both MUST store the exact
+ * `text` alongside the `hash` (never re-derive the text from disk and hash
+ * separately, or a formatter run between the two would silently
+ * re-embed — rule 37).
+ */
+export function buildCanonicalTextAndHash(
+  input: CanonicalTextInput,
+): { readonly text: string; readonly hash: string } {
+  const text = buildCanonicalText(input);
+  return { text, hash: canonicalTextHash(text) };
+}

package/src/semantic/config.ts

@@ -0,0 +1,235 @@
+/**
+ * Semantic-layer configuration for @remnic/coding-graph (issue #1556).
+ *
+ * Rule 30/48: the semantic layer is OFF by default. Embedding costs compute
+ * and possibly tokens, so nothing in this module touches a provider, writes
+ * a vector, or sends symbol text off-machine unless `enabled` is explicitly
+ * true. The gate-off characterization test (`gate-off.test.ts`) asserts
+ * this end to end.
+ *
+ * The config object is intentionally self-contained in this package rather
+ * than wired into @remnic/core/config.ts — the coding-graph package is an
+ * optional peer dep and must compile standalone. Host integrations
+ * (core/config.ts + openclaw.plugin.json schema) resolve to this same
+ * shape via `resolveSemanticConfig()`, which reads the documented env vars
+ * with the `ENGRAM_` fallback (gotcha 9).
+ */
+import type { EdgeProvenance } from "../graph-schema.js";
+
+/**
+ * Default SIMILAR_TO cosine confirmation threshold (issue #1556 design).
+ * 0.92 is the codebase-memory-mcp precedent — high enough to avoid
+ * false near-clone pairs across structurally-similar but logically-distinct
+ * functions, low enough to catch genuine copy-paste with a renamed
+ * variable.
+ */
+export const DEFAULT_SIMILAR_TO_THRESHOLD = 0.92;
+
+/**
+ * Default maximum symbols embedded per indexing run. Bounds per-run
+ * provider cost. 0 means unlimited (the host budget is the only cap).
+ */
+export const DEFAULT_MAX_SYMBOLS_PER_RUN = 0;
+
+/**
+ * Confidence band assigned to MinHash-only SIMILAR_TO edges when no
+ * embedding provider is available (deterministic, local). Kept below the
+ * embedding-confirmed band so consumers can distinguish provenance quality.
+ * The issue designates this a distinct, documented lower band.
+ */
+export const MINHASH_ONLY_CONFIDENCE = 0.5;
+
+/**
+ * Confidence band assigned to embedding-confirmed SIMILAR_TO edges. Uses
+ * the actual cosine similarity score (≥ similarToThreshold), so this is
+ * the FLOOR for that band — the real confidence is the cosine value.
+ */
+export const EMBEDDING_CONFIRMED_MIN_CONFIDENCE = 0.92;
+
+/**
+ * Edge type emitted by the SIMILAR_TO pipeline. Lives in the `edges`
+ * table with `provenance: "semantic"` (already in EDGE_PROVENANCE_VALUES).
+ */
+export const SIMILAR_TO_EDGE_TYPE = "SIMILAR_TO";
+
+/**
+ * The single provenance tag for every edge this module writes.
+ */
+export const SEMANTIC_PROVENANCE: EdgeProvenance = "semantic";
+
+/**
+ * Canonical-text body line budget. `signature + doc comment + first N lines
+ * of body` per the issue design. N is bounded so a 5k-line function does
+ * not dominate the embedded string (and the provider token budget).
+ */
+export const DEFAULT_CANONICAL_BODY_LINES = 16;
+
+/**
+ * Token shingle width for MinHash. 3 tokens per shingle is the standard
+ * near-duplicate-detection width — small enough to catch renamed-variable
+ * clones (most shingles survive a single rename), large enough that
+ * boilerplate coincidence does not flood the candidate set.
+ */
+export const MINHASH_SHINGLE_WIDTH = 2;
+
+/**
+ * Number of MinHash permutations (hash functions). More = tighter Jaccard
+ * estimate = more compute. 128 gives ~±5% Jaccard error at p=0.95 which
+ * is well inside the 0.92 cosine confirmation gate's margin.
+ */
+export const MINHASH_NUM_PERMUTATIONS = 128;
+
+/**
+ * Number of LSH bands. More bands = more candidate pairs (higher recall,
+ * lower precision before the cosine gate). 32 bands of 4 rows each is the
+ * banding that pairs a Jaccard ≥ 0.4 with high probability while keeping
+ * the candidate set small for typical repos.
+ */
+export const LSH_NUM_BANDS = 32;
+
+/**
+ * The LSH banding — derived: rows per band = permutations / bands.
+ */
+export const LSH_ROWS_PER_BAND = MINHASH_NUM_PERMUTATIONS / LSH_NUM_BANDS;
+
+/**
+ * LSH candidate-pair Jaccard floor implied by the banding (s ≈ (1/b)^(1/r)).
+ * Below this Jaccard similarity a pair is almost never a candidate. Kept as
+ * a named constant so the determinism test can assert the candidate set is
+ * a pure function of (seeds, inputs) without a hidden threshold drift.
+ */
+export const LSH_CANDIDATE_JACCARD_FLOOR = Math.pow(1 / LSH_NUM_BANDS, 1 / LSH_ROWS_PER_BAND);
+
+/**
+ * Self-contained semantic config. Resolved from host config + env.
+ *
+ * `enabled` is the single gate for the whole layer. When false, every
+ * semantic entry point (index-time vector writes, SIMILAR_TO edges,
+ * semantic_query) returns a tagged `{ ok: false, code: "semantic_disabled" }`
+ * WITHOUT touching the provider or the vectors table (gate-off parity).
+ */
+export interface SemanticConfig {
+  /** Master gate. Default false (rule 30/48). */
+  readonly enabled: boolean;
+  /** Cosine threshold for SIMILAR_TO confirmation. Default 0.92. */
+  readonly similarToThreshold: number;
+  /** Per-run embedding budget (0 = unlimited). Default 0. */
+  readonly maxSymbolsPerRun: number;
+  /** Canonical-text body line budget. Default 16. */
+  readonly canonicalBodyLines: number;
+}
+
+/**
+ * Environment variable names. `REMNIC_*` is primary; `ENGRAM_*` is the
+ * fallback (gotcha 9 — legacy env names still bind).
+ */
+const ENV_ENABLED = ["REMNIC_CODING_GRAPH_SEMANTIC_ENABLED", "ENGRAM_CODING_GRAPH_SEMANTIC_ENABLED"];
+const ENV_THRESHOLD = ["REMNIC_CODING_GRAPH_SEMANTIC_SIMILAR_TO_THRESHOLD", "ENGRAM_CODING_GRAPH_SEMANTIC_SIMILAR_TO_THRESHOLD"];
+const ENV_MAX_SYMBOLS = ["REMNIC_CODING_GRAPH_SEMANTIC_MAX_SYMBOLS_PER_RUN", "ENGRAM_CODING_GRAPH_SEMANTIC_MAX_SYMBOLS_PER_RUN"];
+
+/**
+ * Resolve a boolean env var. Accepts true/false/1/0 (case-insensitive).
+ */
+/**
+ * Coerce a host-provided boolean (which may arrive as a string/number from
+ * JSON or CLI config) to a real boolean, so "false"/"0"/"no" do not become
+ * truthy and silently enable vector indexing despite an explicit opt-out
+ * (chatgpt-codex-connector: 'Coerce host enabled before trusting it').
+ * undefined/null → undefined (fall through to env/default).
+ */
+function coerceHostBool(value: unknown): boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const v = value.trim().toLowerCase();
+    // Fail CLOSED: only explicit affirmatives enable the layer. Any other
+    // value ("false"/"0"/"no"/"off"/"disabled"/""/unknown) is an opt-out,
+    // so a malformed or unrecognized host string can never silently enable
+    // remote embedding against operator intent (cursor Bugbot: 'Unknown
+    // enabled strings enable semantic').
+    if (v === "true" || v === "1" || v === "yes" || v === "on") return true;
+    return false;
+  }
+  if (typeof value === "number") return value !== 0;
+  return Boolean(value);
+}
+
+/**
+ * Coerce a host-provided number (which may arrive as a numeric string from
+ * JSON/CLI config) to a finite number, so a malformed value like
+ * maxSymbolsPerRun:"abc" cannot become NaN and silently disable the vector
+ * budget (NaN > 0 is false → unlimited) or break cosine confirmation
+ * (comparisons against NaN are false). undefined/null/non-finite → undefined
+ * (fall through to env/default). Negative finite numbers pass through so the
+ * downstream clamp still controls range (chatgpt-codex-connector: 'Validate
+ * host numeric config before clamping').
+ */
+function coerceHostNumber(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (typeof value === "string") {
+    const n = Number(value.trim());
+    return Number.isFinite(n) ? n : undefined;
+  }
+  return undefined;
+}
+
+function resolveBoolEnv(names: readonly string[], fallback: boolean, env: NodeJS.ProcessEnv): boolean {
+  for (const name of names) {
+    const raw = env[name];
+    if (raw === undefined) continue;
+    const v = raw.trim().toLowerCase();
+    if (v === "true" || v === "1") return true;
+    if (v === "false" || v === "0") return false;
+    // Malformed value: ignore (do not throw — a typo must not crash indexing).
+  }
+  return fallback;
+}
+
+/**
+ * Resolve a positive-number env var. Ignores malformed/NaN/negative values
+ * rather than throwing (a config typo must not crash the indexer).
+ */
+function resolveNumberEnv(names: readonly string[], fallback: number, env: NodeJS.ProcessEnv): number {
+  for (const name of names) {
+    const raw = env[name];
+    if (raw === undefined) continue;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return fallback;
+}
+
+/**
+ * Resolve the semantic config from an optional host-provided partial plus
+ * the environment. Explicit host values win; env vars fill the gaps;
+ * documented defaults apply last.
+ *
+ * `env` defaults to `process.env` but is a parameter so tests can pin the
+ * environment deterministically (rule 38 — no implicit process state).
+ */
+export function resolveSemanticConfig(
+  host?: Partial<SemanticConfig>,
+  env: NodeJS.ProcessEnv = process.env,
+): SemanticConfig {
+  const enabled =
+    coerceHostBool(host?.enabled) ?? resolveBoolEnv(ENV_ENABLED, false, env);
+  const similarToThreshold =
+    coerceHostNumber(host?.similarToThreshold) ?? resolveNumberEnv(ENV_THRESHOLD, DEFAULT_SIMILAR_TO_THRESHOLD, env);
+  const maxSymbolsPerRun =
+    coerceHostNumber(host?.maxSymbolsPerRun) ?? resolveNumberEnv(ENV_MAX_SYMBOLS, DEFAULT_MAX_SYMBOLS_PER_RUN, env);
+  const canonicalBodyLines =
+    coerceHostNumber(host?.canonicalBodyLines) ?? DEFAULT_CANONICAL_BODY_LINES;
+  return {
+    enabled,
+    // Clamp threshold into [0,1] — a malformed env must not produce an
+    // out-of-range confidence gate.
+    similarToThreshold: Math.min(1, Math.max(0, similarToThreshold)),
+    maxSymbolsPerRun: Math.max(0, Math.floor(maxSymbolsPerRun)),
+    // canonicalBodyLines: a negative/zero value must NOT clamp to 0 because
+    // extractBodyText treats <= 0 as unlimited — sending full symbol bodies to
+    // the embedding provider instead of the bounded excerpt (defeats the
+    // privacy/cost cap). Fall back to the default instead (#1680).
+    canonicalBodyLines: canonicalBodyLines >= 1 ? Math.floor(canonicalBodyLines) : DEFAULT_CANONICAL_BODY_LINES,
+  };
+}