@monoes/monograph 1.6.0 → 1.6.2

package/dist/src/pipeline/phases/structure.js.map

@@ -1 +1 @@
-{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../../../src/pipeline/phases/structure.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../../../src/pipeline/phases/structure.ts"],"names":[],"mappings":"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"}

package/dist/src/pipeline/phases/variables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../../../../src/pipeline/phases/variables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAqBD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CAyBjF;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,aAAa,CAW7D"}
+{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../../../../src/pipeline/phases/variables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAqBD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CAyBjF;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,aAAa,CAW7D"}

package/dist/src/pipeline/phases/variables.js

@@ -1,3 +1,4 @@
+import { symbolId } from '../../types.js';
 // Regex for top-level variable declarations.
 // We detect nesting depth by counting braces before the match.
 const TOP_LEVEL_VAR = /^(export\s+)?(const|let|var)\s+(\w+)\s*[=:]/gm;
@@ -42,7 +43,7 @@ export function extractVariables(source, filePath) {
 }
 export function variableToNode(v) {
     return {
-        id: `var:${v.filePath}:${v.name}`,
+        id: symbolId({ filePath: v.filePath, scope: [], name: v.name, kind: 'Variable' }),
         label: 'Variable',
         name: v.name,
         normLabel: v.name.toLowerCase(),

package/dist/src/pipeline/phases/variables.js.map

@@ -1 +1 @@
-{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../../../src/pipeline/phases/variables.ts"],"names":[],"mappings":"AASA,6CAA6C;AAC7C,+DAA+D;AAC/D,MAAM,aAAa,GAAG,+CAA+C,CAAC;AAEtE;;;GAGG;AACH,SAAS,kBAAkB,CAAC,GAAW;IACrC,8EAA8E;IAC9E,mFAAmF;IACnF,OAAO,GAAG;SACP,OAAO,CAAC,gCAAgC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;SACtE,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;SAC1D,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;SAC1D,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;SACzD,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,QAAgB;IAC/D,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,IAAI,KAA6B,CAAC;IAClC,aAAa,CAAC,SAAS,GAAG,CAAC,CAAC;IAE5B,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAE5C,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9C,iDAAiD;QACjD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,IAAI,EAAE,KAAK,GAAG;gBAAE,KAAK,EAAE,CAAC;iBACnB,IAAI,EAAE,KAAK,GAAG;gBAAE,KAAK,EAAE,CAAC;QAC/B,CAAC;QACD,IAAI,KAAK,KAAK,CAAC;YAAE,SAAS;QAE1B,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QACvC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,CAAe;IAC5C,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE;QACjC,KAAK,EAAE,UAAU;QACjB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE;QAC/B,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,SAAS,EAAE,CAAC,CAAC,IAAI;QACjB,OAAO,EAAE,CAAC,CAAC,IAAI;QACf,UAAU,EAAE,CAAC,CAAC,UAAU;KACzB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../../../src/pipeline/phases/variables.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAS1C,6CAA6C;AAC7C,+DAA+D;AAC/D,MAAM,aAAa,GAAG,+CAA+C,CAAC;AAEtE;;;GAGG;AACH,SAAS,kBAAkB,CAAC,GAAW;IACrC,8EAA8E;IAC9E,mFAAmF;IACnF,OAAO,GAAG;SACP,OAAO,CAAC,gCAAgC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;SACtE,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;SAC1D,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;SAC1D,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;SACzD,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,QAAgB;IAC/D,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,IAAI,KAA6B,CAAC;IAClC,aAAa,CAAC,SAAS,GAAG,CAAC,CAAC;IAE5B,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAE5C,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9C,iDAAiD;QACjD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,IAAI,EAAE,KAAK,GAAG;gBAAE,KAAK,EAAE,CAAC;iBACnB,IAAI,EAAE,KAAK,GAAG;gBAAE,KAAK,EAAE,CAAC;QAC/B,CAAC;QACD,IAAI,KAAK,KAAK,CAAC;YAAE,SAAS;QAE1B,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QACvC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,CAAe;IAC5C,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QACjF,KAAK,EAAE,UAAU;QACjB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE;QAC/B,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,SAAS,EAAE,CAAC,CAAC,IAAI;QACjB,OAAO,EAAE,CAAC,CAAC,IAAI;QACf,UAAU,EAAE,CAAC,CAAC,UAAU;KACzB,CAAC;AACJ,CAAC"}

package/dist/src/search/hybrid-query.d.ts

@@ -1,21 +1,80 @@
 /**
- * BM25 search (FTS5) with the historical "hybrid" entry-point signature.
+ * The single lexical retrieval service for the monograph knowledge graph.
  *
- * Monograph search is BM25-only. The former embedding/vector branch
+ * Every adapter — the package-level `monograph_query` MCP tool, the
+ * CLI-hosted `monograph_query` MCP tool, `augmentContext`, the eval server —
+ * calls {@link searchGraph} rather than assembling its own BM25/LIKE/fuzzy
+ * combination. Two adapters answering the same query differently was a real
+ * bug, not a hypothetical one.
+ *
+ * SCORE CONVENTION — higher is better, always non-negative.
+ * SQLite FTS5's `rank` is the opposite (negative, more negative = better).
+ * That inversion is resolved in exactly one place,
+ * {@link relevanceFromFtsRank} in `../storage/fts-store.js`, at the boundary
+ * where a rank enters the system. Nothing downstream ever sees a raw rank, so
+ * the sign cannot be forwarded into a ranker again.
+ *
+ * Monograph search is lexical-only. The former embedding/vector branch
  * (gated on MONOGRAPH_EMBEDDINGS=true) was removed — it was never run in
- * practice (the embeddings table stayed empty) and did a JS cosine full
- * scan. The exported function signatures are unchanged so callers do not
- * need to change.
+ * practice (the embeddings table stayed empty) and did a JS cosine full scan.
  */
 import type Database from 'better-sqlite3';
 import type { RankedResult } from './rrf.js';
+/**
+ * Retrieval strategies, named for what they actually do.
+ *
+ * - `hybrid` — FTS5 BM25 + LIKE fallback + in-memory fuzzy + node-type bonus.
+ *   The default: it degrades gracefully on short identifiers, where bare BM25
+ *   over a trigram index returns nothing.
+ * - `bm25` — FTS5 BM25 only. Narrower, but predictable; used where a caller
+ *   wants pure lexical ranking with no heuristic bonuses.
+ */
+export type RetrievalMode = 'bm25' | 'hybrid';
+export interface GraphSearchOptions {
+    limit?: number;
+    label?: string;
+    /** Retrieval strategy (default: `hybrid`). */
+    mode?: RetrievalMode;
+}
+export interface GraphSearchResult {
+    id: string;
+    name: string;
+    normLabel: string;
+    filePath: string | null;
+    label: string;
+    /** Higher is better, always ≥ 0. See the score-convention note above. */
+    relevance: number;
+    /** First line of the symbol in its source file (1-based, null if unknown). */
+    startLine: number | null;
+    /** Last line of the symbol in its source file (1-based, null if unknown). */
+    endLine: number | null;
+    /** Which retrieval strategy surfaced this row. */
+    matchStrategy: 'fts' | 'like' | 'fuzzy';
+}
+/**
+ * Run a lexical search over the graph and return results under the
+ * higher-is-better score convention.
+ *
+ * The query is prepared identically for every mode so that two adapters
+ * asking the same question in the same mode get the same answer.
+ *
+ * Preparation is `trim()` only, deliberately. The FTS5 index uses the trigram
+ * tokenizer, which folds ASCII case but does NOT fold diacritics, and the
+ * index stores `name`/`norm_label` verbatim. Stripping diacritics from the
+ * query (as the old `bm25Query` did) therefore could never *gain* a match —
+ * it only stopped `naïveResolver` from finding the symbol literally named
+ * `naïveResolver`. Lowercasing is likewise skipped: it is a no-op for ASCII
+ * under both the trigram tokenizer and SQLite's LIKE, and for non-ASCII it
+ * would break the LIKE fallback against a capitalized name.
+ */
+export declare function searchGraph(db: Database.Database, query: string, options?: GraphSearchOptions): GraphSearchResult[];
 export interface BM25QueryOptions {
     limit?: number;
     label?: string;
-    /** @deprecated Embeddings are disabled — this option is ignored; search is BM25-only. Will be removed in the next major version. */
+    /** @deprecated Embeddings are disabled — this option is ignored; search is lexical-only. Will be removed in the next major version. */
     embedder?: unknown;
 }
-/** @deprecated Use {@link BM25QueryOptions} — this alias will be removed in the next major version. */
+/** @deprecated Use {@link GraphSearchOptions} — this alias will be removed in the next major version. */
 export type HybridQueryOptions = BM25QueryOptions;
 export interface BM25Result extends RankedResult {
     id: string;
@@ -23,24 +82,28 @@ export interface BM25Result extends RankedResult {
     normLabel: string;
     filePath: string | null;
     label: string;
+    /** Higher is better, always ≥ 0 — see the score-convention note above. */
     score: number;
     /** First line of the symbol in its source file (1-based, null if unknown). */
     startLine?: number | null;
     /** Last line of the symbol in its source file (1-based, null if unknown). */
     endLine?: number | null;
 }
-/** @deprecated Use {@link BM25Result} — this alias will be removed in the next major version. */
+/** @deprecated Use {@link GraphSearchResult} — this alias will be removed in the next major version. */
 export type HybridResult = BM25Result;
 /**
- * Run a BM25 (FTS5) search. The `embedder` option is ignored — the vector
- * branch was removed; search is BM25-only.
+ * @deprecated Use {@link searchGraph} with `mode: 'bm25'`. Retained as a thin
+ * wrapper so existing callers keep working; it now reports the same
+ * higher-is-better `score` as every other path (it used to forward FTS5's
+ * raw negative `rank`, which inverted ranking for anything downstream that
+ * compared or propagated scores).
  */
 export declare function bm25Query(db: Database.Database, query: string, options?: BM25QueryOptions): Promise<BM25Result[]>;
 /**
- * @deprecated Use {@link bm25Query} instead — this is a misleading name
- * (search here is BM25-only, not a hybrid of multiple retrieval strategies).
- * `hybridQuery` remains as an alias for backward compatibility and will be
- * removed in the next major version.
+ * @deprecated Use {@link searchGraph} instead — this is a misleading name
+ * (search here is lexical-only, not a hybrid of multiple retrieval
+ * *modalities*). `hybridQuery` remains as an alias for backward compatibility
+ * and will be removed in the next major version.
  */
 export declare const hybridQuery: typeof bm25Query;
 //# sourceMappingURL=hybrid-query.d.ts.map

package/dist/src/search/hybrid-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-query.d.ts","sourceRoot":"","sources":["../../../src/search/hybrid-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oIAAoI;IACpI,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,uGAAuG;AACvG,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAElD,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,iGAAiG;AACjG,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAEtC;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,UAAU,EAAE,CAAC,CAqBvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,kBAAY,CAAC"}
+{"version":3,"file":"hybrid-query.d.ts","sourceRoot":"","sources":["../../../src/search/hybrid-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kDAAkD;IAClD,aAAa,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;CACzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,EAAE,CAqCrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uIAAuI;IACvI,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,yGAAyG;AACzG,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAElD,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wGAAwG;AACxG,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,UAAU,EAAE,CAAC,CAYvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,kBAAY,CAAC"}

package/dist/src/search/hybrid-query.js

@@ -1,42 +1,102 @@
 /**
- * BM25 search (FTS5) with the historical "hybrid" entry-point signature.
+ * The single lexical retrieval service for the monograph knowledge graph.
  *
- * Monograph search is BM25-only. The former embedding/vector branch
+ * Every adapter — the package-level `monograph_query` MCP tool, the
+ * CLI-hosted `monograph_query` MCP tool, `augmentContext`, the eval server —
+ * calls {@link searchGraph} rather than assembling its own BM25/LIKE/fuzzy
+ * combination. Two adapters answering the same query differently was a real
+ * bug, not a hypothetical one.
+ *
+ * SCORE CONVENTION — higher is better, always non-negative.
+ * SQLite FTS5's `rank` is the opposite (negative, more negative = better).
+ * That inversion is resolved in exactly one place,
+ * {@link relevanceFromFtsRank} in `../storage/fts-store.js`, at the boundary
+ * where a rank enters the system. Nothing downstream ever sees a raw rank, so
+ * the sign cannot be forwarded into a ranker again.
+ *
+ * Monograph search is lexical-only. The former embedding/vector branch
  * (gated on MONOGRAPH_EMBEDDINGS=true) was removed — it was never run in
- * practice (the embeddings table stayed empty) and did a JS cosine full
- * scan. The exported function signatures are unchanged so callers do not
- * need to change.
+ * practice (the embeddings table stayed empty) and did a JS cosine full scan.
+ */
+import { ftsSearch, hybridSearch, relevanceFromFtsRank } from '../storage/fts-store.js';
+/**
+ * Run a lexical search over the graph and return results under the
+ * higher-is-better score convention.
+ *
+ * The query is prepared identically for every mode so that two adapters
+ * asking the same question in the same mode get the same answer.
+ *
+ * Preparation is `trim()` only, deliberately. The FTS5 index uses the trigram
+ * tokenizer, which folds ASCII case but does NOT fold diacritics, and the
+ * index stores `name`/`norm_label` verbatim. Stripping diacritics from the
+ * query (as the old `bm25Query` did) therefore could never *gain* a match —
+ * it only stopped `naïveResolver` from finding the symbol literally named
+ * `naïveResolver`. Lowercasing is likewise skipped: it is a no-op for ASCII
+ * under both the trigram tokenizer and SQLite's LIKE, and for non-ASCII it
+ * would break the LIKE fallback against a capitalized name.
  */
-import { ftsSearch } from '../storage/fts-store.js';
-import { normalizeSearchTerm } from './diacritic.js';
+export function searchGraph(db, query, options = {}) {
+    const { limit = 20, label, mode = 'hybrid' } = options;
+    if (limit <= 0)
+        return [];
+    const normalizedQuery = (query ?? '').trim();
+    if (!normalizedQuery)
+        return [];
+    if (mode === 'bm25') {
+        // Over-fetch a little: FTS5's own ordering is what we keep, but a wider
+        // window gives the caller's label filter something to bite on.
+        const rows = ftsSearch(db, normalizedQuery, Math.max(limit, 50), label);
+        return rows.slice(0, limit).map((r) => ({
+            id: r.id,
+            name: r.name,
+            normLabel: r.normLabel,
+            filePath: r.filePath,
+            label: r.label,
+            relevance: relevanceFromFtsRank(r.rank),
+            startLine: r.startLine,
+            endLine: r.endLine,
+            matchStrategy: 'fts',
+        }));
+    }
+    // hybridSearch already reports a positive, higher-is-better combinedScore
+    // (it routes its FTS rows through relevanceFromFtsRank).
+    return hybridSearch(db, normalizedQuery, limit, label).map((r) => ({
+        id: r.id,
+        name: r.name,
+        normLabel: r.normLabel,
+        filePath: r.filePath,
+        label: r.label,
+        relevance: r.combinedScore,
+        startLine: r.startLine,
+        endLine: r.endLine,
+        matchStrategy: r.matchStrategy,
+    }));
+}
 /**
- * Run a BM25 (FTS5) search. The `embedder` option is ignored — the vector
- * branch was removed; search is BM25-only.
+ * @deprecated Use {@link searchGraph} with `mode: 'bm25'`. Retained as a thin
+ * wrapper so existing callers keep working; it now reports the same
+ * higher-is-better `score` as every other path (it used to forward FTS5's
+ * raw negative `rank`, which inverted ranking for anything downstream that
+ * compared or propagated scores).
  */
 export async function bm25Query(db, query, options = {}) {
     const { limit = 20, label } = options;
-    // Normalize the query for text-based lookups (strip diacritics, lowercase, trim)
-    const normalizedQuery = normalizeSearchTerm(query);
-    // ── BM25 via FTS5 ──────────────────────────────────────────────────────────
-    const bm25Limit = Math.max(limit, 50);
-    const bm25Raw = ftsSearch(db, normalizedQuery, bm25Limit, label);
-    const bm25Results = bm25Raw.map((r) => ({
+    return searchGraph(db, query, { limit, label, mode: 'bm25' }).map((r) => ({
         id: r.id,
         name: r.name,
         normLabel: r.normLabel,
         filePath: r.filePath,
         label: r.label,
-        score: r.rank,
+        score: r.relevance,
         startLine: r.startLine,
         endLine: r.endLine,
     }));
-    return bm25Results.slice(0, limit);
 }
 /**
- * @deprecated Use {@link bm25Query} instead — this is a misleading name
- * (search here is BM25-only, not a hybrid of multiple retrieval strategies).
- * `hybridQuery` remains as an alias for backward compatibility and will be
- * removed in the next major version.
+ * @deprecated Use {@link searchGraph} instead — this is a misleading name
+ * (search here is lexical-only, not a hybrid of multiple retrieval
+ * *modalities*). `hybridQuery` remains as an alias for backward compatibility
+ * and will be removed in the next major version.
  */
 export const hybridQuery = bm25Query;
 //# sourceMappingURL=hybrid-query.js.map

package/dist/src/search/hybrid-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-query.js","sourceRoot":"","sources":["../../../src/search/hybrid-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AA6BrD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAqB,EACrB,KAAa,EACb,OAAO,GAAqB,EAAE;IAE9B,MAAM,EAAE,KAAK,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAEtC,iFAAiF;IACjF,MAAM,eAAe,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAEnD,8EAA8E;IAC9E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,SAAS,CAAC,EAAE,EAAE,eAAe,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IACjE,MAAM,WAAW,GAAmB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtD,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,KAAK,EAAE,CAAC,CAAC,IAAI;QACb,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,OAAO,EAAE,CAAC,CAAC,OAAO;KACnB,CAAC,CAAC,CAAC;IAEJ,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAiB,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC"}
+{"version":3,"file":"hybrid-query.js","sourceRoot":"","sources":["../../../src/search/hybrid-query.ts"],"names":[],"mappings":"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"}

package/dist/src/staleness/git-staleness.d.ts

@@ -1,11 +1,57 @@
 import type { MonographDb } from '../storage/db.js';
+/**
+ * Explicit index freshness. A boolean cannot distinguish "proven up to date"
+ * from "we could not check", and reporting the latter as the former is how a
+ * confident-but-baseless "fresh" answer reaches a caller.
+ *
+ * - `fresh`    — index matches HEAD, worktree is clean, no recorded warnings.
+ * - `stale`    — index is behind HEAD, or the worktree has uncommitted edits.
+ * - `building` — a build lock is held by a live process right now.
+ * - `partial`  — index matches HEAD but is known incomplete (parser warnings
+ *                or a recorded refresh error).
+ * - `unknown`  — freshness could not be determined (git unavailable, no
+ *                recorded revision, or the dirty-worktree probe failed).
+ */
+export type IndexFreshnessState = 'fresh' | 'stale' | 'building' | 'partial' | 'unknown';
 export interface StalenessReport {
+    /**
+     * Commit-divergence only: true when the indexed commit is known to differ
+     * from HEAD (or no commit was recorded). Deliberately unchanged — the
+     * pipeline's skip-when-fresh guard reads it together with `currentCommit`.
+     * It is NOT a freshness verdict: a clean-commit / dirty-worktree index has
+     * `isStale: false` and `state: 'stale'`. New callers should read `state`.
+     */
     isStale: boolean;
+    /** Timestamp of the last build, from `index_meta.indexed_at`. */
     indexedAt: string | null;
+    /** Short (7-char) SHA of the indexed revision. */
     indexedCommit: string | null;
+    /** Short (7-char) SHA of current HEAD. */
     currentCommit: string | null;
     changedSince: string[];
     staleSince: string | null;
+    /** Explicit freshness state — prefer this over `isStale`. */
+    state: IndexFreshnessState;
+    /** One sentence explaining why `state` has this value; safe to show a user. */
+    reason: string;
+    /** Full SHA of the revision the index was built from, null when unrecorded. */
+    indexedRevision: string | null;
+    /** Source scope the index was built with (e.g. 'code-only'), null when unrecorded. */
+    sourceScope: string | null;
+    /** true/false when git could be consulted, null when the probe failed. */
+    dirtyWorktree: boolean | null;
+    /** Sample of uncommitted paths, capped at {@link DIRTY_PATH_CAP}. */
+    dirtyPaths: string[];
+    /** True number of uncommitted paths, null when undetermined. */
+    dirtyFileCount: number | null;
+    /** Parser warnings recorded by the last build, null when none recorded. */
+    parserWarnings: string[] | null;
+    /** Error recorded by the last refresh attempt, null when none recorded. */
+    lastRefreshError: string | null;
+    /** A build lock is currently held by a live process. */
+    buildInProgress: boolean;
+    /** True whenever `state !== 'fresh'`: graph answers may be incomplete. */
+    mayBeIncomplete: boolean;
 }
 export declare function checkStaleness(db: MonographDb, repoPath: string): StalenessReport;
 //# sourceMappingURL=git-staleness.d.ts.map

package/dist/src/staleness/git-staleness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-staleness.d.ts","sourceRoot":"","sources":["../../../src/staleness/git-staleness.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CA6FjF"}
+{"version":3,"file":"git-staleness.d.ts","sourceRoot":"","sources":["../../../src/staleness/git-staleness.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAKzF,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kDAAkD;IAClD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0CAA0C;IAC1C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,6DAA6D;IAC7D,KAAK,EAAE,mBAAmB,CAAC;IAC3B,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sFAAsF;IACtF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0EAA0E;IAC1E,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,qEAAqE;IACrE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gEAAgE;IAChE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2EAA2E;IAC3E,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAChC,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wDAAwD;IACxD,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAgKD,wBAAgB,cAAc,CAAC,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAuHjF"}

package/dist/src/staleness/git-staleness.js

@@ -1,58 +1,216 @@
 import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+/** Cap on the dirty-path sample carried in the report; `dirtyFileCount` keeps the true total. */
+const DIRTY_PATH_CAP = 50;
+function readMeta(db) {
+    try {
+        const rows = db.prepare('SELECT key, value FROM index_meta').all();
+        return new Map(rows.map((r) => [r.key, r.value]));
+    }
+    catch {
+        return new Map();
+    }
+}
+/** Accepts either a JSON array or a newline-separated list; null when empty. */
+function parseWarnings(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            const items = parsed.map(String).filter(Boolean);
+            return items.length > 0 ? items : null;
+        }
+    }
+    catch {
+        /* not JSON — fall through to line parsing */
+    }
+    const lines = raw
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+    return lines.length > 0 ? lines : null;
+}
+/**
+ * The pipeline serializes builds with a `<dbPath>.build-lock` file holding the
+ * builder's pid. A live holder means a rebuild is under way right now, which is
+ * a different answer than "stale" for a caller deciding whether to wait.
+ */
+function isBuildInProgress(db) {
+    const dbPath = typeof db.name === 'string' ? db.name : '';
+    if (!dbPath || dbPath === ':memory:')
+        return false;
+    let pid;
+    try {
+        pid = Number.parseInt(readFileSync(`${dbPath}.build-lock`, 'utf8'), 10);
+    }
+    catch {
+        return false; // no lock file
+    }
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists but belongs to another user.
+        return err?.code === 'EPERM';
+    }
+}
+/**
+ * Commit comparison alone cannot see uncommitted work, which is exactly the
+ * code an agent is most likely to ask about. Cheap `git status --porcelain`;
+ * a failure reports "undetermined" rather than "clean".
+ */
+function checkDirtyWorktree(repoPath) {
+    try {
+        const out = execSync('git status --porcelain --no-renames', {
+            cwd: repoPath,
+            encoding: 'utf8',
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        // Porcelain v1 lines are `XY <path>`; ignored files are excluded by default.
+        const paths = out
+            .split('\n')
+            .filter((line) => line.length > 3)
+            .map((line) => line.slice(3).trim())
+            .filter(Boolean);
+        return { dirty: paths.length > 0, paths: paths.slice(0, DIRTY_PATH_CAP), count: paths.length };
+    }
+    catch {
+        return { dirty: null, paths: [], count: null };
+    }
+}
+function buildReport(meta, parts) {
+    return {
+        isStale: parts.isStale,
+        indexedAt: meta.get('indexed_at') ?? null,
+        indexedCommit: parts.indexedCommit,
+        currentCommit: parts.currentCommit,
+        changedSince: parts.changedSince,
+        staleSince: parts.staleSince,
+        state: parts.state,
+        reason: parts.reason,
+        indexedRevision: parts.indexedRevision,
+        sourceScope: meta.get('source_scope') ?? meta.get('scope') ?? null,
+        dirtyWorktree: parts.dirty.dirty,
+        dirtyPaths: parts.dirty.paths,
+        dirtyFileCount: parts.dirty.count,
+        parserWarnings: parseWarnings(meta.get('parser_warnings') ?? meta.get('parse_errors')),
+        lastRefreshError: meta.get('last_refresh_error') ?? null,
+        buildInProgress: parts.state === 'building',
+        mayBeIncomplete: parts.state !== 'fresh',
+    };
+}
+/**
+ * State for an index whose recorded commit equals HEAD. Matching commits are
+ * necessary but not sufficient for "fresh": the worktree may be dirty, the
+ * probe may have failed, or the last build may have recorded problems.
+ */
+function stateForMatchingCommit(meta, dirty) {
+    if (dirty.dirty === null) {
+        return {
+            state: 'unknown',
+            reason: 'Index matches HEAD, but the working tree could not be checked for uncommitted edits.',
+        };
+    }
+    if (dirty.dirty) {
+        return {
+            state: 'stale',
+            reason: `Index matches HEAD but ${dirty.count} path(s) have uncommitted changes that are not in the graph.`,
+        };
+    }
+    const warnings = parseWarnings(meta.get('parser_warnings') ?? meta.get('parse_errors'));
+    const refreshError = meta.get('last_refresh_error') ?? null;
+    if (warnings) {
+        return {
+            state: 'partial',
+            reason: `Index matches HEAD but the last build recorded ${warnings.length} parser warning(s); some symbols may be missing.`,
+        };
+    }
+    if (refreshError) {
+        return {
+            state: 'partial',
+            reason: `Index matches HEAD but the last refresh reported an error: ${refreshError}`,
+        };
+    }
+    return { state: 'fresh', reason: 'Index matches HEAD and the working tree is clean.' };
+}
 export function checkStaleness(db, repoPath) {
-    // 1. Get stored commit hash
-    const row = db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get();
-    const indexedCommitFull = row?.value ?? null;
-    // 2. Get current HEAD (full SHA — --short output length varies by repo size)
+    const meta = readMeta(db);
+    const indexedCommitFull = meta.get('last_commit_hash') ?? null;
+    const indexedCommitShort = indexedCommitFull ? indexedCommitFull.slice(0, 7) : null;
+    const building = isBuildInProgress(db);
+    // 1. Current HEAD (full SHA — `--short` output length varies by repo size)
     let currentCommit = null;
     try {
         currentCommit = execSync('git rev-parse HEAD', { cwd: repoPath, encoding: 'utf8' }).trim();
     }
     catch {
-        // Not a git repo or git not available
-        return {
+        // Not a git repo, no git binary, or a broken checkout. Nothing is known
+        // about freshness here — `unknown`, never `fresh`.
+        return buildReport(meta, {
             isStale: false,
-            indexedAt: null,
             indexedCommit: null,
             currentCommit: null,
             changedSince: [],
             staleSince: null,
-        };
+            state: building ? 'building' : 'unknown',
+            reason: building
+                ? 'A build is currently running; git is unavailable so freshness cannot be checked.'
+                : 'Git is unavailable in this directory, so index freshness cannot be determined. Treat graph results as possibly incomplete.',
+            indexedRevision: indexedCommitFull,
+            dirty: { dirty: null, paths: [], count: null },
+        });
     }
-    // Display short SHA (7 chars) for the interface field; compare short SHAs for staleness
-    const indexedCommitShort = indexedCommitFull ? indexedCommitFull.slice(0, 7) : null;
-    const currentCommitShort = currentCommit ? currentCommit.slice(0, 7) : null;
-    // 3. If SHAs match → fresh. If no stored commit → staleness unknown (not "fresh").
+    const currentCommitShort = currentCommit.slice(0, 7);
+    const dirty = checkDirtyWorktree(repoPath);
+    // 2. Commits match → freshness still depends on worktree state and warnings.
     if (indexedCommitShort === currentCommitShort) {
-        return {
+        const { state, reason } = stateForMatchingCommit(meta, dirty);
+        return buildReport(meta, {
             isStale: false,
-            indexedAt: null,
             indexedCommit: indexedCommitShort,
             currentCommit: currentCommitShort,
             changedSince: [],
             staleSince: null,
-        };
+            state: building ? 'building' : state,
+            reason: building ? 'A build is currently running.' : reason,
+            indexedRevision: indexedCommitFull,
+            dirty,
+        });
     }
+    // 3. No recorded revision → staleness is unknown, not merely "stale".
+    //    `isStale` stays true so the rebuild guard keeps its conservative behavior.
     if (!indexedCommitFull) {
-        return {
+        return buildReport(meta, {
             isStale: true,
-            indexedAt: null,
             indexedCommit: null,
             currentCommit: currentCommitShort,
             changedSince: [],
             staleSince: null,
-        };
+            state: building ? 'building' : 'unknown',
+            reason: building
+                ? 'A build is currently running; no indexed revision has been recorded yet.'
+                : 'No indexed revision was recorded, so the index cannot be compared against HEAD.',
+            indexedRevision: null,
+            dirty,
+        });
     }
     // Guard: indexedCommitFull is read from SQLite — validate before shell interpolation
     if (!/^[0-9a-f]{7,40}$/i.test(indexedCommitFull)) {
-        return {
+        return buildReport(meta, {
             isStale: true,
-            indexedAt: null,
             indexedCommit: indexedCommitShort,
             currentCommit: currentCommitShort,
             changedSince: [],
             staleSince: null,
-        };
+            state: building ? 'building' : 'unknown',
+            reason: 'The recorded index revision is not a valid commit SHA, so freshness cannot be determined. Re-run the build.',
+            indexedRevision: indexedCommitFull,
+            dirty,
+        });
     }
     // 4. Get changed files between indexed commit and HEAD
     let changedSince = [];
@@ -75,13 +233,19 @@ export function checkStaleness(db, repoPath) {
     catch {
         staleSince = null;
     }
-    return {
+    const dirtyNote = dirty.dirty ? ` ${dirty.count} path(s) also have uncommitted changes.` : '';
+    return buildReport(meta, {
         isStale: true,
-        indexedAt: null,
         indexedCommit: indexedCommitShort,
         currentCommit: currentCommitShort,
         changedSince,
         staleSince,
-    };
+        state: building ? 'building' : 'stale',
+        reason: building
+            ? 'A build is currently running.'
+            : `Index was built at ${indexedCommitShort} but HEAD is ${currentCommitShort}; ${changedSince.length} file(s) changed since.${dirtyNote}`,
+        indexedRevision: indexedCommitFull,
+        dirty,
+    });
 }
 //# sourceMappingURL=git-staleness.js.map