knodin 0.12.0 → 0.12.1

package/dist/src/engine/index.js

@@ -1728,6 +1728,34 @@ function createLanguageMemo() {
  * `isLineComment` below, which also requires the `//` prefix.
  */
 const LINE_COMMENT_NODE_TYPES = new Set(["comment", "line_comment", "hash_comment"]);
+/**
+ * Repo-relative files that reference `symbol` and are test files, read from raw
+ * reference rows rather than from resolved callers.
+ *
+ * Resolved callers cannot answer this. A call inside an anonymous callback --
+ * `it("...", () => { target() })`, which is how essentially all test code is
+ * written -- has no enclosing NAMED symbol, so it is stored with a null
+ * `callerSymbol` and every caller-resolution path drops it. Measured on this
+ * repository: 29,158 of 31,467 references from test files (92.7%) have a null
+ * caller, against 390 of 18,399 (2.1%) from production files. So a coverage
+ * question answered from callers is roughly 93% blind in exactly the files it is
+ * asking about, and reported `untested: true` for 642 symbols that have tests
+ * (KNODIN-36).
+ *
+ * The reference row itself carries `callerFile`, which is all this question
+ * needs. Attributing the call to the file instead would be the other repair, and
+ * `call-graph.spec.ts` deliberately forbids it: a file path must never appear as
+ * a caller. So the fix belongs here, at the question, not in the graph.
+ *
+ * Shared by `explain`'s `untested`, `tests_for`, and `detectKnowledgeGaps` so the
+ * definition of "covered by a test" cannot drift between them.
+ */
+function testCallerFilesFor(db, symbol, relativeFile) {
+    const statement = db.query('SELECT DISTINCT callerFile FROM "references" WHERE calleeSymbol = ? AND (calleeFile = ? OR calleeFile IS NULL)');
+    const rows = statement.all(symbol, relativeFile);
+    statement.finalize();
+    return rows.map((row) => row.callerFile).filter((file) => isTestFilePath(file));
+}
 /** Clean up and format comment/docstring blocks in JavaScript/TypeScript. */
 function getPrecedingComment(node) {
     let target = node;
@@ -12449,7 +12477,20 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 })
                 : [];
             const allBlastFiles = Array.from(new Set(allCallers.map((c) => c.filePath)));
-            const untested = !allCallers.some((c) => isTestFilePath(c.filePath));
+            // Asked of raw reference rows, not of resolved callers: a test that calls
+            // this symbol from inside an anonymous `it(...)` callback has no caller
+            // symbol and is invisible to `allCallers` (KNODIN-36). `untested: true`
+            // is a positive assertion with no zero-count to invite doubt, so it has
+            // to be answered from the evidence that actually exists.
+            // Three values, not two. Without the defining repository's database this
+            // question cannot be answered, and the previous fallback -- guessing from
+            // resolved callers -- is precisely the collapse that made this field
+            // wrong in the first place: it turned "cannot tell" into a confident
+            // `true`. `untested` is now simply absent when the evidence is absent,
+            // so a caller reading it gets a fact or nothing, never a guess.
+            const untested = targetDb
+                ? testCallerFilesFor(targetDb, primaryDef.name, primaryDef.filePath).length === 0
+                : undefined;
             const minimal = detailLevel === "minimal";
             const cap = minimal ? 25 : 200;
             const truncated = allCallers.length > cap ||
@@ -15459,6 +15500,60 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         seen.add(key);
                         rows.push({ symbol: r.symbol, file, line: r.lineNumber });
                     }
+                    // Resolved callers miss almost every real test. A call inside an
+                    // anonymous `it(...)` callback has no enclosing named symbol, so it
+                    // carries a null `callerSymbol` and `findCallersFederated` drops it
+                    // (92.7% of this repository's test-file references, against 2.1% of
+                    // production ones). Reading the raw rows recovers them (KNODIN-36).
+                    //
+                    // These rows carry no caller name because there genuinely is none,
+                    // and inventing one -- the file path, or the enclosing `describe`
+                    // title -- would put a non-symbol in a `symbol` field that
+                    // `call-graph.spec.ts` explicitly forbids. `symbol` is therefore
+                    // omitted and the file and line carry the answer, which is what the
+                    // question asked for anyway: which test covers this.
+                    for (const repo of allRepos) {
+                        if (defFile && repo.path !== defRepo)
+                            continue;
+                        // MIN(line) grouped by file, not DISTINCT(file, line). The rows are
+                        // deduped by file below, so a plain DISTINCT would leave SQLite free
+                        // to hand back whichever line its query plan reached first when a
+                        // test file references the symbol more than once -- a value that can
+                        // change between runs and plans, which is a flaky test waiting to be
+                        // written. The first reference is both stable and the more useful
+                        // one to report.
+                        // With no defining file the file filter is dropped rather than bound
+                        // to "", which would degrade the clause to `calleeFile IS NULL` and
+                        // silently discard every reference that does carry a file -- turning
+                        // "I do not know where this is defined" into "it is defined nowhere",
+                        // and under-reporting coverage for exactly the symbols we know least
+                        // about (ADR 008). findCallersFederated omits the filter in the same
+                        // situation; these two must not disagree.
+                        const anonymous = defFile
+                            ? (() => {
+                                const stmt = repo.db.query('SELECT callerFile, MIN(line) AS line FROM "references" WHERE calleeSymbol = ? AND (calleeFile = ? OR calleeFile IS NULL) AND callerSymbol IS NULL GROUP BY callerFile ORDER BY callerFile');
+                                const out = stmt.all(target, defFile);
+                                stmt.finalize();
+                                return out;
+                            })()
+                            : (() => {
+                                const stmt = repo.db.query('SELECT callerFile, MIN(line) AS line FROM "references" WHERE calleeSymbol = ? AND callerSymbol IS NULL GROUP BY callerFile ORDER BY callerFile');
+                                const out = stmt.all(target);
+                                stmt.finalize();
+                                return out;
+                            })();
+                        for (const row of anonymous) {
+                            const file = formatPath(repo.path, row.callerFile);
+                            if (!isTestFilePath(file))
+                                continue;
+                            const key = `|${file}`;
+                            if (seen.has(key))
+                                continue;
+                            seen.add(key);
+                            rows.push({ file, line: row.line });
+                        }
+                    }
+                    rows.sort((a, b) => (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0));
                     return finish(rows);
                 }
                 case "rename_preview": {

package/dist/src/output-telemetry.js

@@ -7,6 +7,17 @@ import { resolveDbPath } from "./engine/state-paths.js";
 import { summarizeAdoption } from "./session-telemetry.js";
 export const TELEMETRY_TOKENIZER = "gpt-tokenizer@3.4.0:o200k_base";
 export const countOutputTokens = (value) => encode(value).length;
+/** Retrieval stages the engine can report; anything else is dropped. */
+const RETRIEVAL_ROUTE_STEPS = new Set([
+    "stable-identity",
+    "exact-name",
+    "exact-path",
+    "lexical",
+    "bounded-graph",
+    "embeddings",
+]);
+/** Embedding-coverage states the engine can report; anything else is dropped. */
+const SEMANTIC_READINESS_STATES = new Set(["ready", "partial", "absent"]);
 export const DEFAULT_TELEMETRY_RETENTION_DAYS = 30;
 const DEFAULT_INPUT = ".knodin-telemetry.jsonl";
 function lineCount(value) {
@@ -105,6 +116,28 @@ export function measureOutput(options) {
     const status = typeof options.output.status === "string" ? options.output.status : undefined;
     const availability = options.output.availability;
     const freshness = options.output.freshness;
+    // Retrieval-quality fields, lifted so a repository where knodin underperforms
+    // is diagnosable from a shared bundle instead of from a hand-written field
+    // report (KNODIN-37). All four already travel in the response and all four are
+    // source-free metadata, so this persists nothing the privacy contract forbids.
+    //
+    // `semanticReadiness` is the most diagnostic of them: a partially embedded
+    // index returns confident SHORT answers, which is indistinguishable from the
+    // query being wrong unless the readiness is recorded beside the result.
+    const retrieval = options.output.retrieval;
+    const retrievalRoute = Array.isArray(retrieval?.route)
+        ? retrieval.route.filter((step) => typeof step === "string")
+        : undefined;
+    const embeddingsUsed = typeof retrieval?.embeddingsUsed === "boolean" ? retrieval.embeddingsUsed : undefined;
+    const semanticReadiness = typeof options.output.semanticReadiness === "string"
+        ? options.output.semanticReadiness
+        : undefined;
+    const results = options.output.results;
+    const resultCount = Array.isArray(results)
+        ? results.length
+        : typeof options.output.count === "number"
+            ? options.output.count
+            : undefined;
     const fidelity = options.output.fidelity;
     const database = resolveDbPath(fs.realpathSync(options.repo));
     const latencyMs = Math.round((performance.now() - options.startedAt) * 100) / 100;
@@ -137,6 +170,15 @@ export function measureOutput(options) {
         compressionFidelity,
         confidence: baseline ? "measured" : "unavailable",
         truncated: options.truncated,
+        // Non-empty or absent, never `[]`. An empty route asserts that no retrieval
+        // stage ran, which is a claim about the query; a route that is unknown or
+        // wholly unreadable is the absence of one. The sanitizer downstream makes
+        // the same distinction, and a record that collapsed it here would hand the
+        // sanitizer a falsehood to faithfully preserve (ADR 008).
+        ...(retrievalRoute && retrievalRoute.length > 0 ? { retrievalRoute } : {}),
+        ...(embeddingsUsed !== undefined ? { embeddingsUsed } : {}),
+        ...(semanticReadiness ? { semanticReadiness } : {}),
+        ...(resultCount !== undefined ? { resultCount } : {}),
         detailMode: options.detailMode,
         tokenizer: TELEMETRY_TOKENIZER,
         schemaTokens: options.schemaTokens,
@@ -232,7 +274,12 @@ export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/te
         sessionEvents: sessionEvents.length,
     };
 }
-function sanitizeTelemetryRecord(record) {
+/**
+ * Exported for the retrieval-quality spec: the allowlist is the guarantee that
+ * an unexpected field never reaches a shareable file, and that guarantee is
+ * only worth anything if it is tested directly rather than through a caller.
+ */
+export function sanitizeTelemetryRecord(record) {
     return {
         schemaVersion: record.schemaVersion,
         at: record.at,
@@ -252,6 +299,38 @@ function sanitizeTelemetryRecord(record) {
         compressionFidelity: record.compressionFidelity,
         confidence: record.confidence,
         truncated: record.truncated,
+        // Retrieval-quality fields (KNODIN-37). Validated rather than copied: the
+        // allowlist is the reason an unexpected field can never reach the file, and
+        // a new entry that trusts its input would quietly defeat that. Route steps
+        // are constrained to a known vocabulary and the array is bounded, so a
+        // malformed response cannot smuggle arbitrary strings into a shareable
+        // record.
+        // Omitted when nothing survives the allowlist, not emitted as `[]`. An
+        // empty array reads as "no retrieval stage ran", which is a fact; a route
+        // whose every step was unrecognised is the absence of a readable fact, and
+        // the two must not share a representation (ADR 008). Caught in review of
+        // this very change, which is the telemetry meant to diagnose exactly this
+        // class of confusion.
+        ...(() => {
+            if (!Array.isArray(record.retrievalRoute))
+                return {};
+            const route = record.retrievalRoute
+                .filter((step) => RETRIEVAL_ROUTE_STEPS.has(step))
+                .slice(0, 8);
+            return route.length > 0 ? { retrievalRoute: route } : {};
+        })(),
+        ...(typeof record.embeddingsUsed === "boolean"
+            ? { embeddingsUsed: record.embeddingsUsed }
+            : {}),
+        ...(typeof record.semanticReadiness === "string" &&
+            SEMANTIC_READINESS_STATES.has(record.semanticReadiness)
+            ? { semanticReadiness: record.semanticReadiness }
+            : {}),
+        ...(typeof record.resultCount === "number" &&
+            Number.isInteger(record.resultCount) &&
+            record.resultCount >= 0
+            ? { resultCount: record.resultCount }
+            : {}),
         detailMode: record.detailMode,
         tokenizer: record.tokenizer,
         schemaTokens: record.schemaTokens,

package/docs/releases/0.12.1.md

@@ -0,0 +1,98 @@
+# knodin 0.12.1
+
+A P1 correctness fix, a field made honest, and telemetry that lets a badly
+performing repository explain itself. No schema change and no re-index.
+
+## `explain` said "untested" about symbols that have tests
+
+`explain` reported `untested: true`, and `tests_for` returned `count: 0`, for
+symbols with dedicated unit tests — on a healthy, fresh graph.
+
+Test code lives almost entirely inside anonymous callbacks passed to `it(...)`
+and `describe(...)`. Such a call has no enclosing *named* symbol, so it is
+recorded with a null caller and every caller-resolution path drops it. Measured
+on this repository: **29,158 of 31,467 references from test files (92.7%) had no
+caller symbol, against 390 of 18,399 (2.1%) from production files.** A coverage
+question answered from callers was therefore about 93% blind in exactly the files
+it was asking about, and 642 symbols with real tests reported as untested.
+
+This is the worst shape a wrong answer can take. An empty result invites a second
+look; a confident positive does not. The field was written into a security
+proposal as a precondition blocking a change and reached a pull request before a
+reviewer caught it.
+
+Both questions now read the raw reference rows, which carry the calling file.
+
+Two alternatives were rejected on evidence rather than taste. Attributing the
+call to the *file* would put a non-symbol into a `symbol` field, which a
+checked-in contract forbids outright. Indexing `describe`/`it` titles as symbols
+would add roughly ten thousand rows and perturb statistics, dead-code detection,
+communities, embeddings, and the centrality term added in 0.12.0. Reading the
+rows changes no caller, so search ranking is bit-identical — verified rather than
+assumed.
+
+Rows for anonymous callers carry a file and a line and no symbol, because there
+genuinely is none.
+
+## `untested` is now three-valued
+
+The first version of that fix still collapsed "cannot tell" into a guess: without
+the defining repository's database it inferred from resolved callers, which is
+the same blindness that made the field wrong. `untested` is now simply **absent**
+when the evidence is absent. A caller gets a fact or nothing, never a guess.
+
+The control matters as much as the fix: a genuinely uncovered symbol still
+reports `untested: true`. A field that is never true would be as broken as one
+that is always true, and only that second test tells them apart.
+
+## Telemetry can now explain a repository where knodin underperforms
+
+knodin has been reported as performing poorly in other people's repositories,
+and there was no way to find out why without someone writing a field report by
+hand. The signals that explain it already travelled in every response and were
+being discarded.
+
+Four are now persisted with the existing opt-in local telemetry:
+`retrievalRoute`, `embeddingsUsed`, `semanticReadiness`, and `resultCount`.
+
+`semanticReadiness` is the most diagnostic of them. A partially embedded index
+returns confident *short* answers, which is indistinguishable from a poorly
+phrased query unless the readiness is recorded beside the result.
+
+All four are source-free metadata, so the privacy contract is unchanged: no
+source, no query text, no paths, no identities, still opt-in, still local-only,
+still no transport. Query *shape* — the remaining diagnostic gap — is
+deliberately excluded, because persisting query text would falsify the
+no-source-egress property the product is built on.
+
+The sanitizer's allowlist gained these fields with validation rather than
+pass-through. That allowlist is the only reason an unexpected field cannot reach
+a shareable file, and an entry that trusted its input would quietly defeat it.
+
+## A design principle, written down
+
+ADR 008 records what eleven defects across 0.12.0 and this release turned out to
+have in common:
+
+> A check that collapses "no" and "don't know" into a single answer will
+> eventually return the wrong one, and it will do so confidently.
+
+`untested: true`, `count: 0` for a misspelling, a review answering a different
+range, staleness defaulting to `fresh` when it was missing. Two instances in the
+ADR are deliberately not knodin bugs — another product's CI gate reporting a
+network timeout as a security advisory, and an agent truncating its own terminal
+output and concluding a remote did not exist. The shape belongs to any predicate
+whose failure path and negative path are the same path.
+
+## Measured and not shipped
+
+Three attempts at the lexical retrieval channel were implemented, measured, and
+reverted: asymmetric token floors, Porter stemming, and grading a partial match
+by how many query words it echoed. On a 44-query real-model benchmark they
+scored 0.7112, 0.7389, and "no measurable difference" against a 0.7635 baseline,
+and **none bought a single point of recall** — including on four queries added
+specifically to favour morphological matching.
+
+The reproductions behind them were sound. The inference was not: a demonstrated
+defect does not imply that removing it is an improvement. The vector channel was
+already carrying what the lexical channel could not see.

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "knodin",
-	"version": "0.12.0",
+	"version": "0.12.1",
 	"knodin": {
-		"compatibility": "breaking"
+		"compatibility": "compatible"
 	},
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
@@ -65,6 +65,7 @@
 		"docs/releases/0.10.8.md",
 		"docs/releases/0.11.0.md",
 		"docs/releases/0.12.0.md",
+		"docs/releases/0.12.1.md",
 		"docs/releases/0.3.0.md",
 		"docs/releases/0.4.0.md",
 		"docs/releases/0.4.1.md",