pi-braid 0.43.7 → 0.43.8

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.
Files changed (56) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/TOOLS.md +1 -1
  3. package/build-info.json +4 -4
  4. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  5. package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
  6. package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
  7. package/dist/extensions/core/skills-tool/index.js +20 -2
  8. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  9. package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
  10. package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
  11. package/dist/extensions/core/skills-tool/session-records.js +141 -5
  12. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  13. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  14. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  15. package/dist/extensions/enforcement/verification-judge.js +28 -21
  16. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  17. package/dist/extensions/memory/session-recall/ask.js +376 -0
  18. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  19. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  20. package/dist/extensions/memory/session-recall/index.js +173 -21
  21. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  22. package/dist/extensions/memory/session-recall/search.js +42 -9
  23. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  24. package/dist/lib/ai/payload-hygiene.js +34 -2
  25. package/dist/lib/config/braid-paths.d.ts +4 -0
  26. package/dist/lib/config/braid-paths.js +6 -0
  27. package/dist/lib/config/braid-settings.d.ts +22 -0
  28. package/dist/lib/config/braid-settings.js +15 -0
  29. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  30. package/dist/lib/detection/tool-loop-detector.js +288 -180
  31. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  32. package/dist/lib/reasoning/dreamer.js +12 -7
  33. package/docs/LOCAL_DEV.md +1 -1
  34. package/docs/SETUP.md +1 -0
  35. package/package.json +1 -1
  36. package/src/extensions/core/AGENTS.md +3 -2
  37. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  38. package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
  39. package/src/extensions/core/skills-tool/index.ts +21 -1
  40. package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
  41. package/src/extensions/core/skills-tool/session-records.ts +201 -9
  42. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  43. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  44. package/src/extensions/enforcement/verification-judge.ts +32 -25
  45. package/src/extensions/memory/AGENTS.md +2 -2
  46. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  47. package/src/extensions/memory/session-recall/ask.ts +435 -0
  48. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  49. package/src/extensions/memory/session-recall/index.ts +202 -21
  50. package/src/extensions/memory/session-recall/search.ts +61 -10
  51. package/src/lib/ai/payload-hygiene.ts +47 -3
  52. package/src/lib/config/braid-paths.ts +7 -0
  53. package/src/lib/config/braid-settings.ts +42 -3
  54. package/src/lib/detection/AGENTS.md +8 -7
  55. package/src/lib/detection/tool-loop-detector.ts +339 -195
  56. package/src/lib/reasoning/dreamer.ts +13 -6
@@ -0,0 +1,376 @@
1
+ /**
2
+ * Session corpus ask - lexical retrieval over the user-turn index.
3
+ *
4
+ * BM25 over one document per user turn. At this corpus size the lexical model
5
+ * is the cheap, testable choice: no embedding pass to keep current, no vector
6
+ * store to back up, no key to spend on a query, and a score a reader can
7
+ * re-derive by eye from the terms it names. What would earn a vector store is
8
+ * a measured failure: recall@3 below the bar on questions whose answering
9
+ * passage is in the index (the report's falsifier is that measurement).
10
+ *
11
+ * Every hit carries its citation - project, session path, line, timestamp -
12
+ * because the answer is the owner's own words and a reader must be able to
13
+ * check them against the session file. The refusal is a first-class result: a
14
+ * query whose terms appear nowhere in the population says so and names what it
15
+ * searched, rather than returning the least bad rows.
16
+ */
17
+ /** BM25 term-frequency saturation. */
18
+ export const BM25_K1 = 1.2;
19
+ /** BM25 length normalisation. */
20
+ export const BM25_B = 0.75;
21
+ /** Hits a query returns when the caller names no limit. */
22
+ export const MAX_ASK_HITS = 5;
23
+ /** Characters of a turn the answer prints before it trims. */
24
+ const PASSAGE_CHARS = 360;
25
+ /**
26
+ * Words that carry no retrieval signal in a question about work. A fixed
27
+ * language table, not a project vocabulary: it holds English function words
28
+ * only, so a query term that names something always survives it.
29
+ */
30
+ const STOPWORDS = new Set([
31
+ "a",
32
+ "about",
33
+ "after",
34
+ "all",
35
+ "also",
36
+ "am",
37
+ "an",
38
+ "and",
39
+ "any",
40
+ "are",
41
+ "as",
42
+ "at",
43
+ "be",
44
+ "been",
45
+ "before",
46
+ "being",
47
+ "both",
48
+ "but",
49
+ "by",
50
+ "can",
51
+ "could",
52
+ "did",
53
+ "do",
54
+ "does",
55
+ "doing",
56
+ "done",
57
+ "for",
58
+ "from",
59
+ "had",
60
+ "has",
61
+ "have",
62
+ "having",
63
+ "he",
64
+ "her",
65
+ "here",
66
+ "him",
67
+ "his",
68
+ "how",
69
+ "i",
70
+ "if",
71
+ "in",
72
+ "into",
73
+ "is",
74
+ "it",
75
+ "its",
76
+ "just",
77
+ "me",
78
+ "my",
79
+ "no",
80
+ "not",
81
+ "of",
82
+ "on",
83
+ "once",
84
+ "only",
85
+ "or",
86
+ "other",
87
+ "our",
88
+ "out",
89
+ "over",
90
+ "own",
91
+ "same",
92
+ "she",
93
+ "should",
94
+ "so",
95
+ "some",
96
+ "such",
97
+ "than",
98
+ "that",
99
+ "the",
100
+ "their",
101
+ "them",
102
+ "then",
103
+ "there",
104
+ "these",
105
+ "they",
106
+ "this",
107
+ "those",
108
+ "to",
109
+ "too",
110
+ "under",
111
+ "up",
112
+ "us",
113
+ "very",
114
+ "was",
115
+ "we",
116
+ "were",
117
+ "what",
118
+ "when",
119
+ "where",
120
+ "which",
121
+ "while",
122
+ "who",
123
+ "why",
124
+ "will",
125
+ "with",
126
+ "would",
127
+ "you",
128
+ "your",
129
+ ]);
130
+ /**
131
+ * Fold one token to its retrieval stem.
132
+ *
133
+ * Inflected forms of a word are one word for retrieval: a question saying
134
+ * "rendered" must reach a turn saying "renders", and "picks" must reach
135
+ * "pick". The fold is symmetric - the query and the turns pass through the
136
+ * same function - so a fold that is linguistically wrong ("boxes" -> "boxe")
137
+ * is still a fold both sides agree on. The doubled-consonant rule exists for
138
+ * the same reason: "hitting" must reach "hit".
139
+ */
140
+ function foldToken(token) {
141
+ if (token.length <= 3)
142
+ return token;
143
+ let stem = token;
144
+ if (stem.endsWith("ies") && stem.length > 4)
145
+ stem = `${stem.slice(0, -3)}y`;
146
+ else if (stem.endsWith("s") && !stem.endsWith("ss"))
147
+ stem = stem.slice(0, -1);
148
+ if (stem.endsWith("ing") && stem.length > 5)
149
+ stem = stem.slice(0, -3);
150
+ else if (stem.endsWith("ed") && stem.length > 4)
151
+ stem = stem.slice(0, -2);
152
+ const last = stem.at(-1);
153
+ if (/[bdfglmnprt]/.test(last ?? "") && stem.at(-2) === last && stem.length > 3) {
154
+ stem = stem.slice(0, -1);
155
+ }
156
+ return stem;
157
+ }
158
+ /**
159
+ * Words a document is scored on: letter/number runs, lowercased, stemmed.
160
+ *
161
+ * A hyphen separates words: the owner's compound names ("looping-clanker",
162
+ * "anti-crowd") are two words a question may spell either way, and a tokenizer
163
+ * that keeps the compound as one token can never match its own parts.
164
+ */
165
+ export function tokenizeForIndex(text) {
166
+ const raw = text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
167
+ const tokens = [];
168
+ for (const token of raw) {
169
+ if (token.length < 2 && !/\d/.test(token))
170
+ continue;
171
+ tokens.push(foldToken(token));
172
+ }
173
+ return tokens;
174
+ }
175
+ /**
176
+ * Query terms: the document tokens minus function words. Duplicates collapse,
177
+ * so a word typed twice scores once.
178
+ */
179
+ export function askQueryTerms(query) {
180
+ const seen = new Set();
181
+ for (const token of tokenizeForIndex(query)) {
182
+ if (STOPWORDS.has(token))
183
+ continue;
184
+ seen.add(token);
185
+ }
186
+ return [...seen];
187
+ }
188
+ /** BM25 score of one document against the query terms. */
189
+ function scoreDocument(termFrequencies, docLength, averageLength, idf) {
190
+ const lengthNorm = averageLength > 0 ? 1 - BM25_B + (BM25_B * docLength) / averageLength : 1;
191
+ let score = 0;
192
+ const matched = [];
193
+ for (const [term, frequency] of termFrequencies) {
194
+ const weight = idf.get(term);
195
+ if (weight === undefined)
196
+ continue;
197
+ matched.push(term);
198
+ score += (weight * (frequency * (BM25_K1 + 1))) / (frequency + BM25_K1 * lengthNorm);
199
+ }
200
+ return { score, matched };
201
+ }
202
+ /**
203
+ * Retrieve the turns that answer a question, with citations.
204
+ *
205
+ * The population searched is stated in the result, so a refusal can show what
206
+ * it looked at. `df` and the average document length are computed over the
207
+ * filtered population: an index narrowed by `--project` or `--since` is the
208
+ * corpus the answer claims, not a sample of a larger one it never read.
209
+ */
210
+ export function askCorpusIndex(shards, query, opts) {
211
+ const terms = askQueryTerms(query);
212
+ const allowed = new Set(terms);
213
+ const candidates = [];
214
+ const projects = new Set();
215
+ const builtAt = new Set();
216
+ for (const shard of shards) {
217
+ projects.add(shard.manifest.project);
218
+ builtAt.add(shard.manifest.built_at);
219
+ for (const turn of shard.turns) {
220
+ if (opts.excludeSession && turn.session === opts.excludeSession)
221
+ continue;
222
+ if (opts.since && turn.ts.slice(0, 10) < opts.since)
223
+ continue;
224
+ candidates.push(turn);
225
+ }
226
+ }
227
+ const sessions = new Set();
228
+ for (const turn of candidates)
229
+ sessions.add(turn.session);
230
+ // One pass: term frequencies for the query terms, and the document's length.
231
+ const frequencies = new Array(candidates.length);
232
+ const lengths = new Array(candidates.length);
233
+ const documentFrequency = new Map();
234
+ let totalLength = 0;
235
+ for (let i = 0; i < candidates.length; i++) {
236
+ const tokens = tokenizeForIndex(candidates[i].text);
237
+ lengths[i] = tokens.length;
238
+ totalLength += tokens.length;
239
+ const counts = new Map();
240
+ for (const token of tokens) {
241
+ if (!allowed.has(token))
242
+ continue;
243
+ counts.set(token, (counts.get(token) ?? 0) + 1);
244
+ }
245
+ frequencies[i] = counts;
246
+ for (const term of counts.keys()) {
247
+ documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
248
+ }
249
+ }
250
+ const total = candidates.length;
251
+ const averageLength = total > 0 ? totalLength / total : 0;
252
+ const idf = new Map();
253
+ for (const [term, df] of documentFrequency) {
254
+ idf.set(term, Math.log(1 + (total - df + 0.5) / (df + 0.5)));
255
+ }
256
+ const limit = Math.max(1, opts.limit ?? MAX_ASK_HITS);
257
+ const scored = [];
258
+ for (let i = 0; i < candidates.length; i++) {
259
+ const counts = frequencies[i];
260
+ const turn = candidates[i];
261
+ if (!counts || !turn || counts.size === 0)
262
+ continue;
263
+ const { score, matched } = scoreDocument(counts, lengths[i] ?? 0, averageLength, idf);
264
+ if (score <= 0)
265
+ continue;
266
+ scored.push({ turn, score, matched });
267
+ }
268
+ scored.sort((a, b) => b.score - a.score ||
269
+ b.turn.ts.localeCompare(a.turn.ts) ||
270
+ a.turn.session.localeCompare(b.turn.session) ||
271
+ a.turn.line - b.turn.line);
272
+ const matchedTerms = terms.filter((term) => (documentFrequency.get(term) ?? 0) > 0);
273
+ return {
274
+ query,
275
+ terms,
276
+ matched_terms: matchedTerms,
277
+ unmatched_terms: terms.filter((term) => !matchedTerms.includes(term)),
278
+ hits: scored.slice(0, limit),
279
+ answered: scored.length > 0,
280
+ population: {
281
+ turns: total,
282
+ sessions: sessions.size,
283
+ projects: [...projects].sort(),
284
+ built_oldest: [...builtAt].sort()[0] ?? "",
285
+ built_newest: [...builtAt].sort().at(-1) ?? "",
286
+ shards: shards.length,
287
+ },
288
+ freshness: opts.freshness,
289
+ filters: { project: opts.project ?? null, since: opts.since ?? null },
290
+ self_excluded: Boolean(opts.excludeSession),
291
+ };
292
+ }
293
+ /** One passage, trimmed around the best-matching term. */
294
+ function passage(text, matched) {
295
+ const flat = text.replace(/\s+/g, " ").trim();
296
+ if (flat.length <= PASSAGE_CHARS)
297
+ return flat;
298
+ const anchor = matched.find((term) => flat.toLowerCase().includes(term)) ?? "";
299
+ const at = anchor ? flat.toLowerCase().indexOf(anchor) : -1;
300
+ if (at < 0)
301
+ return `${flat.slice(0, PASSAGE_CHARS)}...`;
302
+ const start = Math.max(0, at - Math.floor(PASSAGE_CHARS / 3));
303
+ const end = Math.min(flat.length, start + PASSAGE_CHARS);
304
+ return `${start > 0 ? "..." : ""}${flat.slice(start, end)}${end < flat.length ? "..." : ""}`;
305
+ }
306
+ /** Freshness in one phrase, or null when the index is current. */
307
+ function freshnessNote(freshness) {
308
+ const parts = [];
309
+ if (freshness.changed > 0)
310
+ parts.push(`${freshness.changed} changed`);
311
+ if (freshness.added > 0)
312
+ parts.push(`${freshness.added} new`);
313
+ if (freshness.removed > 0)
314
+ parts.push(`${freshness.removed} gone`);
315
+ if (parts.length === 0)
316
+ return null;
317
+ const newest = freshness.newest_change ? `, newest ${freshness.newest_change}` : "";
318
+ return `${parts.join(", ")} session file(s) since the build${newest}; rerun the index build for them`;
319
+ }
320
+ function number(value) {
321
+ return value.toLocaleString("en-US");
322
+ }
323
+ /**
324
+ * Render the answer: cited passages, or a refusal that names the population it
325
+ * searched and the terms it found.
326
+ */
327
+ export function formatAskResult(result) {
328
+ const population = `${number(result.population.turns)} user turns from ` +
329
+ `${number(result.population.sessions)} sessions across ` +
330
+ `${result.population.projects.length} project(s)`;
331
+ const built = result.population.built_oldest === result.population.built_newest
332
+ ? `built ${result.population.built_newest}`
333
+ : `shards built ${result.population.built_oldest} to ${result.population.built_newest}`;
334
+ const note = freshnessNote(result.freshness);
335
+ const header = [
336
+ `**Ask:** ${result.query}`,
337
+ `Index: ${population}; ${built}.${note ? `\nStaleness: ${note}.` : ""}`,
338
+ result.filters.project || result.filters.since
339
+ ? `Filters: project=${result.filters.project ?? "all"}, since=${result.filters.since ?? "none"}`
340
+ : "",
341
+ result.self_excluded ? "Withheld: this session's own turns." : "",
342
+ ].filter(Boolean);
343
+ if (!result.answered) {
344
+ const found = result.matched_terms.length > 0
345
+ ? `terms found elsewhere in the population: ${result.matched_terms.join(", ")}`
346
+ : "none of the query terms appear in the population";
347
+ const missing = result.unmatched_terms.length > 0
348
+ ? `terms not found: ${result.unmatched_terms.join(", ")}`
349
+ : "every term was found, but no turn carries them together";
350
+ return [
351
+ ...header,
352
+ "",
353
+ "**The index cannot answer this.**",
354
+ `Searched ${population}.`,
355
+ `Result: ${found}; ${missing}.`,
356
+ "Widen the words used, drop the project filter, or rebuild the index if the sessions are newer than the build.",
357
+ ].join("\n");
358
+ }
359
+ const blocks = result.hits.map((hit, index) => {
360
+ const where = `**${index + 1}.** ${hit.turn.project} - ${hit.turn.ts} - line ${hit.turn.line}\n` +
361
+ `Session: \`${hit.turn.session}\``;
362
+ return `${where}\n> ${passage(hit.turn.text, hit.matched)}`;
363
+ });
364
+ const lines = [
365
+ ...header,
366
+ "",
367
+ `${result.hits.length} turn(s) carry the query, ranked by BM25:`,
368
+ "",
369
+ blocks.join("\n\n"),
370
+ ];
371
+ if (result.unmatched_terms.length > 0) {
372
+ lines.push("", `Terms found in no turn (the lexical index cannot see them): ${result.unmatched_terms.join(", ")}.`);
373
+ }
374
+ return lines.join("\n");
375
+ }
376
+ //# sourceMappingURL=ask.js.map
@@ -0,0 +1,200 @@
1
+ /**
2
+ * Session corpus index - the user's own turns, extracted once and stored as a
3
+ * derived population.
4
+ *
5
+ * The transcript corpus is measured in gigabytes while every user message in it
6
+ * is measured in megabytes: the human's words are a fraction of one percent of
7
+ * the archive, and the rest is the agent's own reasoning and tool output. A
8
+ * grep over the archive therefore drowns that fraction in noise, and no tool
9
+ * reads it as a population. This module is the population: one row per user
10
+ * turn, carrying the session file, the session id, the project label, the entry
11
+ * timestamp, the line number in the session file, and the text as typed.
12
+ *
13
+ * Derived, never authoritative: every shard is rebuildable from the session
14
+ * files alone. One shard per project under `corpusIndexDir()`, so a query can
15
+ * read one project or all of them without walking a transcript tree.
16
+ *
17
+ * Two properties the readers depend on:
18
+ *
19
+ * - **Fail closed.** A shard is accepted whole or not at all. A manifest that
20
+ * does not parse, a format this build does not know, a row count that
21
+ * disagrees with the manifest, or a row that does not parse makes the shard
22
+ * UNREADABLE - the caller must say it cannot answer rather than answer from
23
+ * half a store. `loadCorpusIndex` reports which shard and which defect.
24
+ * - **Excluded by construction.** Only `message` entries with role `user`
25
+ * contribute text. Assistant turns, tool calls, tool results and
26
+ * extension-injected `custom_message` entries never enter a row, so no key,
27
+ * no tool argument and no environment value can be retrieved from the index.
28
+ * Tool results arrive as user-role messages with no text block, so the text
29
+ * filter drops them without a role list.
30
+ *
31
+ * What is NOT indexed: the compaction archives under `<session dir>/archives/`.
32
+ * An envelope there is a second copy of messages the session body already
33
+ * carries (writeOriginalsArchive stores the pre-compaction originals), so
34
+ * indexing both would count the same words twice.
35
+ */
36
+ /** Shard layout version. A shard written by another format is unreadable, not
37
+ * migrated: the build regenerates it from the sessions. */
38
+ export declare const CORPUS_INDEX_FORMAT = 1;
39
+ /** One user turn. */
40
+ export interface CorpusTurn {
41
+ /** Absolute path of the session file the turn was read from. */
42
+ session: string;
43
+ /** pi's session id, taken from the file name; the short cite handle. */
44
+ session_id: string;
45
+ /** Project label the session ran in (`projectFromPath`). */
46
+ project: string;
47
+ /** Entry timestamp, ISO-8601 (the file's date at midnight when absent). */
48
+ ts: string;
49
+ /** 1-based line number inside the session file. */
50
+ line: number;
51
+ /** The user's words, verbatim. */
52
+ text: string;
53
+ }
54
+ /** One source session file as the shard's manifest records it. */
55
+ export interface CorpusShardFile {
56
+ path: string;
57
+ /** Source mtime in ms; with `size`, the incremental key. */
58
+ mtimeMs: number;
59
+ size: number;
60
+ turns: number;
61
+ }
62
+ /** The shard's first line. Everything the reader needs to accept or refuse it. */
63
+ export interface CorpusShardManifest {
64
+ kind: "manifest";
65
+ format: number;
66
+ project: string;
67
+ built_at: string;
68
+ /** Source session files the shard covers. */
69
+ sessions: number;
70
+ /** Rows written; row count must equal this. */
71
+ turns: number;
72
+ /** Summed UTF-8 bytes of the row texts. */
73
+ bytes: number;
74
+ files: CorpusShardFile[];
75
+ }
76
+ export interface LoadedShard {
77
+ path: string;
78
+ manifest: CorpusShardManifest;
79
+ turns: CorpusTurn[];
80
+ }
81
+ export type CorpusLoad = {
82
+ ok: true;
83
+ dir: string;
84
+ shards: LoadedShard[];
85
+ } | {
86
+ ok: false;
87
+ dir: string;
88
+ reason: string;
89
+ shards: string[];
90
+ };
91
+ export interface BuildOptions {
92
+ sessionsDir: string;
93
+ indexDir?: string;
94
+ now?: () => Date;
95
+ /** Ignore existing shards and re-parse every session file. */
96
+ rebuild?: boolean;
97
+ /** Structural sink for `scripts/build-corpus-index.mjs --verbose`. */
98
+ progress?: (line: string) => void;
99
+ }
100
+ export interface BuildReport {
101
+ index_dir: string;
102
+ projects: number;
103
+ shards: number;
104
+ sessions: number;
105
+ turns: number;
106
+ bytes: number;
107
+ /** Session files parsed this run. */
108
+ parsed_files: number;
109
+ /** Session files whose rows were carried over from an unchanged shard. */
110
+ reused_files: number;
111
+ /** Session files the shard dropped because they are gone from disk. */
112
+ removed_files: number;
113
+ /** Unreadable session files, by path. */
114
+ skipped: string[];
115
+ elapsed_ms: number;
116
+ }
117
+ /** Thrown by the shard reader; the message names the shard and the defect. */
118
+ export declare class CorpusShardError extends Error {
119
+ readonly shardPath: string;
120
+ readonly defect: string;
121
+ constructor(shardPath: string, defect: string);
122
+ }
123
+ /**
124
+ * File-name stem for one project's shard.
125
+ *
126
+ * The project label is decoded from an encoded directory name, which is lossy
127
+ * (`-` is both a separator and a legal character inside a name), so two
128
+ * different projects can decode to one label and two labels can sanitize to one
129
+ * stem. The digest of the label keeps one shard per project; the readable
130
+ * prefix keeps the directory browsable. Every reader goes through here, so a
131
+ * writer and a reader cannot name different files.
132
+ */
133
+ export declare function shardSlug(project: string): string;
134
+ /** Absolute path of one project's shard. */
135
+ export declare function shardPath(indexDir: string, project: string): string;
136
+ /** The session id a session file name carries, or the file's stem when it carries none. */
137
+ export declare function sessionIdFromPath(sessionPath: string): string;
138
+ export interface ExtractOptions {
139
+ session: string;
140
+ project: string;
141
+ /** Fallback timestamp for entries that carry none. */
142
+ fileDate: string | null;
143
+ }
144
+ /**
145
+ * Every user turn in one session body, in file order.
146
+ *
147
+ * A turn is a `message` entry whose role is `user` and whose content carries
148
+ * text. The role alone is not enough: a tool result is delivered as a
149
+ * user-role message with `tool_result` blocks and no text, and a thought or a
150
+ * blank paste carries no words worth indexing. Blank text is dropped here so
151
+ * the corpus holds only what the human actually typed.
152
+ */
153
+ export declare function extractUserTurns(content: string, opts: ExtractOptions): CorpusTurn[];
154
+ /** Read and validate one shard. Whole or nothing - see CorpusShardError. */
155
+ export declare function readShard(shard: string): Promise<LoadedShard>;
156
+ /**
157
+ * Load every shard under the corpus index directory, or refuse.
158
+ *
159
+ * Refusal is the point: a caller that cannot read its evidence must say so.
160
+ * `reason` names the first unreadable shard and its defect; `shards` lists
161
+ * every shard path the directory held, so a refusal can show its population.
162
+ * A `project` filter narrows which shards are read, and a filter that matches
163
+ * nothing is still a refusal - an empty population cannot answer either.
164
+ */
165
+ export declare function loadCorpusIndex(opts?: {
166
+ indexDir?: string;
167
+ project?: string | null;
168
+ }): Promise<CorpusLoad>;
169
+ /**
170
+ * How far the index has drifted from the session files.
171
+ *
172
+ * A shard is derived data, so an answer built from it is only as new as the
173
+ * last build. The check is one walk plus one stat per session file: cheap next
174
+ * to the answer, and it lets the result carry its own freshness instead of
175
+ * presenting a stale population as current.
176
+ */
177
+ export interface CorpusFreshness {
178
+ /** Session files the index covers. */
179
+ indexed: number;
180
+ /** Indexed files whose mtime or size moved since the build. */
181
+ changed: number;
182
+ /** Session files present on disk that no shard covers. */
183
+ added: number;
184
+ /** Indexed files that are gone from disk. */
185
+ removed: number;
186
+ /** Newest source mtime seen among changed and added files, ISO-8601. */
187
+ newest_change: string | null;
188
+ }
189
+ export declare function corpusIndexFreshness(shards: LoadedShard[], sessionsDir: string): Promise<CorpusFreshness>;
190
+ /**
191
+ * Walk the session files once and write one shard per project.
192
+ *
193
+ * Incremental by (mtime, size): a session file whose stamp still matches its
194
+ * manifest entry contributes its previous rows without being parsed, so a
195
+ * daily refresh costs what changed rather than the corpus. A shard that cannot
196
+ * be read is not repaired in place - it is rebuilt from its session files,
197
+ * which is the only authority for derived data.
198
+ */
199
+ export declare function buildCorpusIndex(opts: BuildOptions): Promise<BuildReport>;
200
+ //# sourceMappingURL=corpus-index.d.ts.map