@gtrabanco/agentic-workflow 0.1.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Canonical envelope for the `doc` retrieval entry point (unit 65, D3).
3
+ *
4
+ * Under `--json-only` stdout carries exactly one JSON document:
5
+ * {ok, command, results[], degradations[], store}
6
+ * with the frozen key order above and result rows
7
+ * {path, section, lines, score, meta}
8
+ * in that order. `lines` is a 1-based inclusive [start, end] pair (D5).
9
+ * No timestamps anywhere (AC2/AC12): the envelope is byte-stable for an
10
+ * unchanged corpus and answer.
11
+ *
12
+ * `degradations[]` is a CLOSED vocabulary frozen here and asserted by test:
13
+ * unavailable-sqlite-<runtime> (runtime ∈ {node, bun})
14
+ * unavailable-embeddings-not-configured
15
+ * unavailable-embeddings-<cause> (kebab-case cause)
16
+ * embeddings-model-mismatch (AC18 fails closed)
17
+ * An unknown value is rejected at construction time — it fails, never ships.
18
+ *
19
+ * Exit codes (D3): 0 success including degraded · 1 usage/IO · 2 path
20
+ * refusal (edit services only).
21
+ */
22
+
23
+ // Lazy TypeBox import — typebox is only loaded when validateEnvelope is called.
24
+ // The bin/hook path that builds envelopes (buildEnvelope, buildResultRow)
25
+ // never calls validateEnvelope, so the cold path stays typebox-free.
26
+
27
+ let _Type = null;
28
+ let _Compile = null;
29
+
30
+ async function ensureTypes() {
31
+ if (_Type === null) {
32
+ const mod = await import("typebox");
33
+ _Type = mod.Type;
34
+ const compileMod = await import("typebox/compile");
35
+ _Compile = compileMod.Compile;
36
+ }
37
+ return { Type: _Type, Compile: _Compile };
38
+ }
39
+
40
+ let _ResultRowSchema = null;
41
+ let _EnvelopeSchema = null;
42
+
43
+ async function ensureSchemas() {
44
+ if (_ResultRowSchema === null) {
45
+ const { Type, Compile } = await ensureTypes();
46
+ _ResultRowSchema = Type.Object({
47
+ path: Type.String(),
48
+ section: Type.Union([Type.String(), Type.Null()]),
49
+ lines: Type.Tuple([Type.Integer({ minimum: 1 }), Type.Integer({ minimum: 1 })]),
50
+ score: Type.Number(),
51
+ meta: Type.Record(Type.String(), Type.Unknown()),
52
+ });
53
+ _EnvelopeSchema = Type.Object({
54
+ ok: Type.Boolean(),
55
+ command: Type.Union(DOC_COMMANDS.map((c) => Type.Literal(c))),
56
+ results: Type.Array(_ResultRowSchema),
57
+ degradations: Type.Array(Type.String()),
58
+ store: Type.Union([Type.Null(), Type.Record(Type.String(), Type.Unknown())]),
59
+ });
60
+ }
61
+ return { _ResultRowSchema, _EnvelopeSchema };
62
+ }
63
+
64
+ export const DOC_COMMANDS = ["sync", "query", "status", "rebuild"];
65
+
66
+ const DEGRADATION_PATTERNS = [
67
+ /^unavailable-sqlite-(node|bun)$/,
68
+ /^unavailable-embeddings-not-configured$/,
69
+ /^unavailable-embeddings-[a-z0-9]+(?:-[a-z0-9]+)*$/,
70
+ /^embeddings-model-mismatch$/,
71
+ ];
72
+
73
+ /** True only for values in the closed degradation vocabulary (D3). */
74
+ export function degradationIsKnown(degradation) {
75
+ return DEGRADATION_PATTERNS.some((re) => re.test(degradation));
76
+ }
77
+
78
+
79
+ let _compiled = null;
80
+
81
+ async function getCompiled() {
82
+ if (_compiled === null) {
83
+ const { _EnvelopeSchema: EnvelopeSchema } = await ensureSchemas();
84
+ const { Compile } = await ensureTypes();
85
+ _compiled = Compile(EnvelopeSchema);
86
+ }
87
+ return _compiled;
88
+ }
89
+
90
+ /** TypeBox validation of a full envelope. Returns `{ok, errors[]}`. */
91
+ export async function validateEnvelope(value) {
92
+ const Compiled = await getCompiled();
93
+ const ok = Compiled.Check(value);
94
+ const errors = ok
95
+ ? []
96
+ : [...Compiled.Errors(value)].map((e) => `${e.path || "/"}: ${e.message}`);
97
+ return { ok, errors };
98
+ }
99
+
100
+ /**
101
+ * Build the canonical envelope. Key order is the contract — constructed as a
102
+ * literal in the frozen order. Unknown commands and unknown degradations
103
+ * throw (fail closed, D3).
104
+ */
105
+ export function buildEnvelope({ command, results = [], degradations = [], store = null, ok = true }) {
106
+ if (!DOC_COMMANDS.includes(command)) {
107
+ throw new Error(`usage: unknown doc command "${command}" (expected one of ${DOC_COMMANDS.join("|")})`);
108
+ }
109
+ for (const d of degradations) {
110
+ if (!degradationIsKnown(d)) {
111
+ throw new Error(`unknown degradation "${d}" — the vocabulary is closed (D3)`);
112
+ }
113
+ }
114
+ return { ok, command, results, degradations: [...degradations], store };
115
+ }
116
+
117
+ /** Build one result row in the frozen key order. */
118
+ export function buildResultRow({ path, section = null, lines, score, meta = {} }) {
119
+ return { path, section, lines: [lines[0], lines[1]], score, meta };
120
+ }
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Argument grammar for the `doc` retrieval entry point (unit 65, D2).
3
+ *
4
+ * One grammar branch: the first token after `doc` starting with `-` selects
5
+ * a retrieval operation (`--sync` / `--query <term>` / `--status` /
6
+ * `--rebuild`); a positional first token is a half-A doc operation that ships
7
+ * with unit 71 and is refused here. `--json-only` may appear anywhere and
8
+ * switches stdout to exactly one JSON document (AC8).
9
+ *
10
+ * Exit codes (D3): 0 success including degraded · 1 usage/IO · 2 path
11
+ * refusal (owned by the crate's edit services, not this grammar).
12
+ */
13
+
14
+ export const RETRIEVAL_FLAGS = {
15
+ "--sync": "sync",
16
+ "--query": "query",
17
+ "--status": "status",
18
+ "--rebuild": "rebuild",
19
+ };
20
+
21
+ function usageError(msg) {
22
+ const e = new Error(
23
+ `usage: agentic-workflow doc (--sync [--quiet] | --query <term> [--since <ISO>] [--until <ISO>] [--file <path>] [--mode keyword|hybrid] | --status | --rebuild) [--json-only] — ${msg}`,
24
+ );
25
+ e.code = "USAGE";
26
+ return e;
27
+ }
28
+
29
+ /**
30
+ * Parse the arguments after `doc`. Returns
31
+ * `{op: "sync"|"query"|"status"|"rebuild", query: string|null, jsonOnly: boolean}`.
32
+ * Throws a usage error (exit 1 territory) on any malformed invocation.
33
+ */
34
+ export function parseDocArgs(argv) {
35
+ const out = { op: null, query: null, jsonOnly: false, quiet: false };
36
+ const filters = { since: null, until: null, file: null };
37
+ const FILTER_FLAGS = { "--since": "since", "--until": "until", "--file": "file" };
38
+ const MODES = new Set(["keyword", "hybrid"]);
39
+ let sawFilter = false;
40
+ let sawMode = false;
41
+ if (!Array.isArray(argv) || argv.length === 0) throw usageError("no operation given");
42
+
43
+ // D2: a positional first token is the half-A branch — not shipped in this unit.
44
+ if (!argv[0].startsWith("-")) {
45
+ throw usageError(
46
+ `positional doc operations (read/edit/index) ship with unit 71; retrieval ops: ${Object.keys(RETRIEVAL_FLAGS).join(" | ")}`,
47
+ );
48
+ }
49
+
50
+ let i = 0;
51
+ while (i < argv.length) {
52
+ const arg = argv[i];
53
+ if (arg === "--json-only") {
54
+ out.jsonOnly = true;
55
+ i++;
56
+ continue;
57
+ }
58
+ if (arg === "--quiet") {
59
+ out.quiet = true;
60
+ i++;
61
+ continue;
62
+ }
63
+ if (arg === "--mode") {
64
+ const value = argv[i + 1];
65
+ if (value === undefined || value === "") throw usageError("--mode requires a value (keyword | hybrid)");
66
+ if (!MODES.has(value)) throw usageError(`unknown mode "${value}" (expected keyword | hybrid)`);
67
+ out.mode = value;
68
+ sawMode = true;
69
+ i += 2;
70
+ continue;
71
+ }
72
+ if (arg in FILTER_FLAGS) {
73
+ const value = argv[i + 1];
74
+ if (value === undefined || value === "") {
75
+ throw usageError(`${arg} requires a non-empty value`);
76
+ }
77
+ filters[FILTER_FLAGS[arg]] = value;
78
+ sawFilter = true;
79
+ i += 2;
80
+ continue;
81
+ }
82
+ const op = RETRIEVAL_FLAGS[arg];
83
+ if (!op) throw usageError(`unknown flag "${arg}"`);
84
+ if (out.op) throw usageError("only one retrieval operation allowed");
85
+ out.op = op;
86
+ if (op === "query") {
87
+ const term = argv[i + 1];
88
+ if (term === undefined || term === "" || term.startsWith("-")) {
89
+ throw usageError("--query requires a non-empty term");
90
+ }
91
+ out.query = term;
92
+ i += 2;
93
+ continue;
94
+ }
95
+ i++;
96
+ }
97
+
98
+ if (!out.op) throw usageError("no retrieval operation given");
99
+ // AC14's structured filters and the P7 mode flag belong to queries only.
100
+ if (out.op === "query") {
101
+ out.since = filters.since;
102
+ out.until = filters.until;
103
+ out.file = filters.file;
104
+ out.mode = out.mode ?? "keyword";
105
+ } else if (sawFilter || sawMode) {
106
+ throw usageError("--since/--until/--file/--mode are query flags and require --query");
107
+ }
108
+ return out;
109
+ }
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Canonical manifest for the `doc` retrieval index (unit 65, D4/D5).
3
+ *
4
+ * The manifest is the freshness surface: per-file sha256 over the tracked
5
+ * markdown corpus plus the git HEAD. It is a canonical JSON document —
6
+ * sorted keys at every level, no timestamps — so AC12's byte-for-byte
7
+ * determinism assertion compares two `collectManifest` runs' exports
8
+ * directly. `manifestHash` is the store's freshness fingerprint.
9
+ */
10
+
11
+ import { createHash } from "node:crypto";
12
+ import { execFileSync } from "node:child_process";
13
+ import { readFileSync } from "node:fs";
14
+ import { join } from "node:path";
15
+
16
+ /** Recursively JSON-stringify with object keys sorted — the canonical form. */
17
+ export function canonicalJson(value) {
18
+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
19
+ if (value !== null && typeof value === "object") {
20
+ const keys = Object.keys(value).sort();
21
+ return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
22
+ }
23
+ return JSON.stringify(value);
24
+ }
25
+
26
+ export function manifestHash(manifest) {
27
+ return createHash("sha256").update(canonicalJson(manifest)).digest("hex");
28
+ }
29
+
30
+ /**
31
+ * Build the manifest document. `files` rows arrive in any order; the output
32
+ * is key-sorted. Rows carry exactly `{sha256, bytes}` — no mtimes, no
33
+ * timestamps anywhere (AC2/AC12).
34
+ */
35
+ export function buildManifest({ head, files }) {
36
+ const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
37
+ const entries = Object.fromEntries(
38
+ sorted.map((f) => [f.path, { sha256: f.sha256, bytes: f.bytes }]),
39
+ );
40
+ return { files: entries, head, version: 1 };
41
+ }
42
+
43
+ /** Tracked markdown corpus: `git ls-files '*.md'` under `root`. */
44
+ export function corpusFiles(root) {
45
+ const out = execFileSync("git", ["ls-files", "--", "*.md"], {
46
+ cwd: root,
47
+ encoding: "utf8",
48
+ maxBuffer: 64 * 1024 * 1024,
49
+ });
50
+ return out.split("\n").map((s) => s.trim()).filter((s) => s !== "");
51
+ }
52
+
53
+ /**
54
+ * Collect the manifest over the live repo at `root`: git HEAD plus one
55
+ * sha256 per tracked markdown file. Deterministic for an unchanged corpus
56
+ * (AC12): same files, same bytes, same HEAD ⇒ byte-identical canonical form.
57
+ */
58
+ export function collectManifest(root) {
59
+ const head = execFileSync("git", ["rev-parse", "HEAD"], {
60
+ cwd: root,
61
+ encoding: "utf8",
62
+ maxBuffer: 1024 * 1024,
63
+ }).trim();
64
+ const files = corpusFiles(root).map((rel) => {
65
+ const abs = join(root, rel);
66
+ let bytes;
67
+ try {
68
+ bytes = readFileSync(abs);
69
+ } catch (e) {
70
+ if (e.code === "ENOENT") {
71
+ // File deleted in working tree but not yet committed — skip it
72
+ // (AC11: treat as deletion, sync.mjs will reap it)
73
+ return null;
74
+ }
75
+ throw e;
76
+ }
77
+ return {
78
+ path: rel,
79
+ sha256: createHash("sha256").update(bytes).digest("hex"),
80
+ bytes: bytes.length,
81
+ };
82
+ }).filter((f) => f !== null); // drop missing files
83
+ return buildManifest({ head, files });
84
+ }
@@ -0,0 +1,327 @@
1
+ /**
2
+ * Keyword query core for the `doc` retrieval index (unit 65, P5).
3
+ *
4
+ * Every query answers after the freshness invariant (AC9: `ensureFresh`),
5
+ * fully offline — no network, no API key (AC13). FTS5 keyword search with
6
+ * result rows `{path, section, lines, score, meta}` in the frozen D3
7
+ * ordering (score desc → path asc → section asc → lines[0] asc; `score` is
8
+ * the negated FTS5 bm25 rank, higher is better).
9
+ *
10
+ * The structured session-log filter (AC14) narrows to `docs/LOGS.md`
11
+ * entries — `log-session` owns that entry shape and the index consumes it
12
+ * as-is: the `## <ISO timestamp> — <branch> — mode` heading and the
13
+ * `- **Files:**` cell become queryable metadata, never an index-side edit.
14
+ */
15
+
16
+ import { join } from "node:path";
17
+ import { decodeVector } from "./embeddings.mjs";
18
+ import { openDatabase } from "./sqlite.mjs";
19
+ import { storePath, storePresent } from "./store.mjs";
20
+ import { ensureFresh } from "./sync.mjs";
21
+ import { storedEmbeddingModel, resolveEmbedConfig, makeOpenAIProvider } from "./embeddings.mjs";
22
+ import { buildEnvelope, buildResultRow } from "./envelope.mjs";
23
+ import { loadConfig } from "./config.mjs";
24
+
25
+ const LOGS_PATH = "docs/LOGS.md";
26
+ const MAX_RESULTS = 20;
27
+ const MATCH_POOL = 200; // candidate pool before filters and the top-K cut
28
+
29
+ /** Quote every token as an FTS5 phrase and AND them — hyphens stay literal. */
30
+ export function ftsQueryFor(term) {
31
+ const tokens = String(term).split(/\s+/).map((t) => t.trim()).filter((t) => t !== "");
32
+ if (tokens.length === 0) return null;
33
+ return tokens.map((t) => `"${t.replace(/"/g, '""')}"`).join(" AND ");
34
+ }
35
+
36
+ /**
37
+ * Parse a `docs/LOGS.md` entry chunk body into queryable metadata
38
+ * `{timestamp, branch, mode, files}` — null when the chunk is not a log
39
+ * entry (the shape is log-session's; consumed as-is, D-log).
40
+ */
41
+ export function parseLogEntry(body) {
42
+ const lines = String(body).split(/\r?\n/);
43
+ const heading = lines[0]?.match(/^##\s+(\S+)\s+—\s+(\S+)\s+—\s+(.+)$/);
44
+ if (!heading) return null;
45
+ let files = null;
46
+ for (const line of lines.slice(1)) {
47
+ const f = line.match(/^-\s+\*\*Files:\*\*\s+(.+)$/);
48
+ if (f) {
49
+ files = f[1].trim();
50
+ break;
51
+ }
52
+ }
53
+ return { timestamp: heading[1], branch: heading[2], mode: heading[3].trim(), files };
54
+ }
55
+
56
+ function logEntryMatches(entry, filters) {
57
+ if (filters.since !== undefined && filters.since !== null) {
58
+ if (entry.timestamp < filters.since) return false;
59
+ }
60
+ if (filters.until !== undefined && filters.until !== null) {
61
+ if (entry.timestamp > filters.until) return false;
62
+ }
63
+ if (filters.file !== undefined && filters.file !== null) {
64
+ const cell = (entry.files ?? "").replace(/`/g, "");
65
+ if (!cell.includes(filters.file)) return false;
66
+ }
67
+ return true;
68
+ }
69
+
70
+ async function storeValue(root) {
71
+ if (!storePresent(root)) {
72
+ return { path: storePath(root), present: false, files: 0, chunks: 0 };
73
+ }
74
+ const { db } = await openDatabase(storePath(root));
75
+ // Check if the chunks table exists (AC11: schema-less store is not an error —
76
+ // it just means sync hasn't run yet, so the table is missing).
77
+ const tableExists = db
78
+ .prepare(
79
+ "select count(*) as n from sqlite_master where type='table' and name='chunks'",
80
+ )
81
+ .get().n;
82
+ if (tableExists === 0) {
83
+ db.close();
84
+ return { path: storePath(root), present: true, files: 0, chunks: 0 };
85
+ }
86
+ const files = db.prepare("select count(distinct path) as n from chunks").get().n;
87
+ const chunks = db.prepare("select count(*) as n from chunks").get().n;
88
+ db.close();
89
+ return { path: storePath(root), present: true, files, chunks };
90
+ }
91
+
92
+ /**
93
+ * Run one query. `filters` carries the optional AC14 structured filter
94
+ * `{since, until, file}`; when any is present, results narrow to matching
95
+ * `docs/LOGS.md` entries. `opts.mode` is `"keyword"` (default) or
96
+ * `"hybrid"` (P7); `opts.embedder` overrides the resolved provider for
97
+ * tests. Returns the canonical query envelope — degraded hybrid answers
98
+ * keyword-only with the cause declared (AC17/AC18), exit-0 ok throughout.
99
+ */
100
+ export async function queryIndex(root, term, filters = {}, opts = {}) {
101
+ const mode = opts.mode ?? "keyword";
102
+ await ensureFresh(root);
103
+ const store = await storeValue(root);
104
+
105
+ const match = ftsQueryFor(term);
106
+ const keywordRows = [];
107
+ if (match !== null) {
108
+ const { db } = await openDatabase(storePath(root));
109
+ const rows = db
110
+ .prepare(
111
+ `select c.chunk_id, c.path, c.section, c.line_start, c.line_end, c.meta, c.body, bm25(chunks_fts) as rank
112
+ from chunks_fts join chunks c on c.rowid = chunks_fts.rowid
113
+ where chunks_fts match ?
114
+ order by rank, c.path, c.section, c.line_start
115
+ limit ${MATCH_POOL}`,
116
+ )
117
+ .all(match);
118
+ db.close();
119
+ keywordRows.push(...rows);
120
+ }
121
+
122
+ const hasLogFilters = filters.since != null || filters.until != null || filters.file != null;
123
+
124
+ if (mode === "hybrid") {
125
+ const provider = opts.embedder !== undefined ? opts.embedder : realProviderOrNull(root);
126
+ if (provider === null) {
127
+ // AC17: no key ⇒ declared degradation, keyword still answers.
128
+ return buildEnvelope({
129
+ command: "query",
130
+ results: toResults(keywordRows, hasLogFilters, filters),
131
+ degradations: ["unavailable-embeddings-not-configured"],
132
+ store,
133
+ });
134
+ }
135
+ const pinned = await storedEmbeddingModel(root);
136
+ if (pinned !== null && pinned !== provider.model) {
137
+ // AC18: never rank across models.
138
+ return buildEnvelope({
139
+ command: "query",
140
+ results: toResults(keywordRows, hasLogFilters, filters),
141
+ degradations: ["embeddings-model-mismatch"],
142
+ store,
143
+ });
144
+ }
145
+ const { db } = await openDatabase(storePath(root));
146
+ const embeddedCount = db.prepare("select count(*) as n from chunks where embedding is not null").get().n;
147
+ if (embeddedCount === 0) {
148
+ db.close();
149
+ return buildEnvelope({
150
+ command: "query",
151
+ results: toResults(keywordRows, hasLogFilters, filters),
152
+ degradations: ["unavailable-embeddings-not-indexed"],
153
+ store,
154
+ });
155
+ }
156
+ // F39: the store-wide pin is not enough — a row embedded under a foreign
157
+ // model (or left unmodelled by an older schema) must fail closed too.
158
+ const foreignRows = db
159
+ .prepare(
160
+ "select count(*) as n from chunks where embedding is not null and (emb_model is null or emb_model is not ?)",
161
+ )
162
+ .get(provider.model).n;
163
+ if (foreignRows > 0) {
164
+ db.close();
165
+ return buildEnvelope({
166
+ command: "query",
167
+ results: toResults(keywordRows, hasLogFilters, filters),
168
+ degradations: ["embeddings-model-mismatch"],
169
+ store,
170
+ });
171
+ }
172
+ try {
173
+ const [queryVector] = await provider.embed([term]);
174
+ const vectorRows = vectorTopK(db, queryVector, MATCH_POOL);
175
+ const fused = fuseRrf(keywordRows, vectorRows);
176
+ // F46: chunk bodies are huge (≈9 MB across this repo's corpus) and are
177
+ // needed only for log-entry rows (the AC14 metadata). Fetch them for the
178
+ // fused candidates that can reach a result row — never for the whole scan.
179
+ for (const r of fused) {
180
+ if (r.path === LOGS_PATH && r.body === undefined) {
181
+ r.body = db.prepare("select body from chunks where chunk_id = ?").get(r.chunk_id)?.body ?? "";
182
+ }
183
+ }
184
+ const results = toResults(
185
+ fused.map((r) => ({ ...r, rank: -r.fusedScore })),
186
+ hasLogFilters,
187
+ filters,
188
+ );
189
+ return buildEnvelope({ command: "query", results, degradations: [], store });
190
+ } catch (e) {
191
+ // F40: a stored vector whose dimensionality differs from the query
192
+ // vector is corrupt or foreign-shaped — degrade, never truncate-and-rank.
193
+ if (e instanceof VectorShapeMismatch) {
194
+ return buildEnvelope({
195
+ command: "query",
196
+ results: toResults(keywordRows, hasLogFilters, filters),
197
+ degradations: ["embeddings-model-mismatch"],
198
+ store,
199
+ });
200
+ }
201
+ // AC17: provider down ⇒ declared cause, keyword results survive.
202
+ return buildEnvelope({
203
+ command: "query",
204
+ results: toResults(keywordRows, hasLogFilters, filters),
205
+ degradations: ["unavailable-embeddings-provider-down"],
206
+ store,
207
+ });
208
+ } finally {
209
+ db.close();
210
+ }
211
+ }
212
+
213
+ const results = toResults(keywordRows, hasLogFilters, filters);
214
+ return buildEnvelope({ command: "query", results, degradations: [], store });
215
+ }
216
+
217
+ /** Map ranked store rows to result rows, applying the AC14 log filters. */
218
+ function toResults(rows, hasLogFilters, filters) {
219
+ const results = [];
220
+ for (const r of rows) {
221
+ let meta = {};
222
+ try {
223
+ meta = JSON.parse(r.meta);
224
+ } catch {
225
+ meta = {};
226
+ }
227
+ const isLog = r.path === LOGS_PATH;
228
+ if (isLog) {
229
+ const entry = r.body === undefined ? null : parseLogEntry(r.body); // F46: parsed once per row
230
+ if (hasLogFilters) {
231
+ if (entry === null || !logEntryMatches(entry, filters)) continue;
232
+ meta = entry;
233
+ } else if (entry !== null) {
234
+ meta = entry;
235
+ }
236
+ } else if (hasLogFilters) {
237
+ continue; // structured filters narrow to log entries by definition
238
+ }
239
+ const score = r.fusedScore !== undefined ? r.fusedScore : -r.rank;
240
+ results.push(
241
+ buildResultRow({
242
+ path: r.path,
243
+ section: r.section,
244
+ lines: [r.line_start, r.line_end],
245
+ score,
246
+ meta,
247
+ }),
248
+ );
249
+ if (results.length >= MAX_RESULTS) break;
250
+ }
251
+ return results;
252
+ }
253
+
254
+ /** Status reporting — informational, never syncs. */
255
+ export async function statusIndex(root) {
256
+ const store = await storeValue(root);
257
+ return buildEnvelope({ command: "status", results: [], store });
258
+ }
259
+
260
+ // ── Hybrid mode (P7) ───────────────────────────────────────────────────
261
+
262
+ const RRF_K = 60;
263
+
264
+ /** A stored vector's dimensionality differs from the query vector (F40). */
265
+ class VectorShapeMismatch extends Error {}
266
+
267
+ function cosine(a, b) {
268
+ if (a.length !== b.length) {
269
+ // F40: truncating to the shorter vector ranked confidently on garbage;
270
+ // a shape mismatch is a corrupt or foreign-model vector — fail closed.
271
+ throw new VectorShapeMismatch(`vector dimension mismatch: ${a.length} vs ${b.length}`);
272
+ }
273
+ let dot = 0;
274
+ let na = 0;
275
+ let nb = 0;
276
+ const n = a.length;
277
+ for (let i = 0; i < n; i++) {
278
+ dot += a[i] * b[i];
279
+ na += a[i] * a[i];
280
+ nb += b[i] * b[i];
281
+ }
282
+ const denom = Math.sqrt(na) * Math.sqrt(nb);
283
+ return denom === 0 ? 0 : dot / denom;
284
+ }
285
+
286
+ /** JS-cosine kNN over D4's float32-LE BLOBs (decision D11 — no second vec0 store). */
287
+ function vectorTopK(db, queryVector, pool) {
288
+ // F46: the scan scores vectors — it must NOT drag every chunk's body
289
+ // (megabytes) out of SQLite per query; bodies are fetched lazily for the
290
+ // few fused candidates that need them.
291
+ const rows = db
292
+ .prepare(
293
+ "select chunk_id, path, section, line_start, line_end, meta, embedding from chunks where embedding is not null",
294
+ )
295
+ .all();
296
+ const scored = rows.map((r) => ({ ...r, sim: cosine(decodeVector(r.embedding), queryVector) }));
297
+ scored.sort((a, b) => b.sim - a.sim || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
298
+ return scored.slice(0, pool);
299
+ }
300
+
301
+ /** Reciprocal-rank fusion over the keyword and vector lists. */
302
+ function fuseRrf(keywordRows, vectorRows) {
303
+ const fused = new Map();
304
+ keywordRows.forEach((r, i) => {
305
+ fused.set(r.chunk_id, { row: r, score: 1 / (RRF_K + i + 1) });
306
+ });
307
+ vectorRows.forEach((r, i) => {
308
+ const contribution = 1 / (RRF_K + i + 1);
309
+ const existing = fused.get(r.chunk_id);
310
+ if (existing) existing.score += contribution;
311
+ else fused.set(r.chunk_id, { row: r, score: contribution });
312
+ });
313
+ return [...fused.values()]
314
+ .sort(
315
+ (a, b) =>
316
+ b.score - a.score ||
317
+ (a.row.path < b.row.path ? -1 : a.row.path > b.row.path ? 1 : 0) ||
318
+ (a.row.section ?? "").localeCompare(b.row.section ?? "") ||
319
+ a.row.line_start - b.row.line_start,
320
+ )
321
+ .map((e) => ({ ...e.row, fusedScore: e.score }));
322
+ }
323
+
324
+ function realProviderOrNull(root) {
325
+ const cfg = resolveEmbedConfig({ config: loadConfig(root), env: process.env });
326
+ return cfg.configured ? makeOpenAIProvider(cfg) : null;
327
+ }