ctxtop 4.0.0 → 4.1.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.
Files changed (89) hide show
  1. package/.antigravity-plugin/plugin.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHECKSUMS.sha256 +59 -42
  4. package/README.md +351 -330
  5. package/bin/ah-statusline.mjs +30 -0
  6. package/bin/ctxtop.mjs +330 -5
  7. package/config/default_flightcheck.json +19 -0
  8. package/config/modelCatalog.json +165 -0
  9. package/hooks/handlers/compact-lifecycle.mjs +323 -8
  10. package/hooks/handlers/config-change.mjs +402 -0
  11. package/hooks/handlers/hookIo.mjs +56 -0
  12. package/hooks/handlers/post-model-switch.mjs +111 -0
  13. package/hooks/handlers/post-tool-use.mjs +117 -16
  14. package/hooks/handlers/pre-model-switch.mjs +823 -24
  15. package/hooks/handlers/pre-tool-use.mjs +271 -4
  16. package/hooks/handlers/stop-gate.mjs +297 -11
  17. package/hooks/handlers/user-prompt-submit.mjs +224 -0
  18. package/hooks/hooks.json +50 -0
  19. package/hooks/post_tool_use.mjs +8 -0
  20. package/hooks/register.js +48 -9
  21. package/hooks/session_start.mjs +11 -1
  22. package/hooks/stop.mjs +11 -1
  23. package/package.json +11 -4
  24. package/packages/antigravity/package.json +1 -1
  25. package/packages/claude-code/package.json +1 -1
  26. package/packages/core/package.json +1 -1
  27. package/packages/engine-node/package.json +1 -1
  28. package/packages/mcp/package.json +1 -1
  29. package/packages/mcp/src/server.mjs +1 -1
  30. package/packages/pro/package.json +1 -1
  31. package/plugin.json +1 -1
  32. package/sidecars/horizon-daemon/server.mjs +38 -2
  33. package/skills/handoff/SKILL.md +8 -0
  34. package/src/adapters/antigravity/index.mjs +31 -1
  35. package/src/adapters/claude-code/index.mjs +40 -1
  36. package/src/cli/horizon_hud.mjs +254 -52
  37. package/src/config/modelCatalog.json +84 -0
  38. package/src/core/bucket_b_runtime.mjs +1200 -0
  39. package/src/core/constants.mjs +191 -4
  40. package/src/core/detectors_det01_to_16.mjs +54 -5
  41. package/src/core/doc_indexer.mjs +338 -0
  42. package/src/core/layer5_hygiene.mjs +118 -0
  43. package/src/core/parser.mjs +2 -1
  44. package/src/core/paths.mjs +3 -2
  45. package/src/core/rsl_clash_auditor.mjs +423 -0
  46. package/src/core/rsl_distiller.mjs +372 -0
  47. package/src/core/rsl_ledger.mjs +969 -0
  48. package/src/core/rsl_triage.mjs +909 -0
  49. package/src/core/session_auditor.mjs +658 -0
  50. package/src/core/shield_manager.mjs +1417 -0
  51. package/src/core/task_quota_router.mjs +1 -1
  52. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +874 -47
  53. package/src/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
  54. package/src/core-isomorphic/coach/smartCompactAdvisor.mjs +305 -0
  55. package/src/core-isomorphic/coach/ttlWatchdog.mjs +13 -6
  56. package/src/core-isomorphic/config/anthropicModelCatalog.json +404 -1
  57. package/src/core-isomorphic/config/catalogLoader.mjs +546 -46
  58. package/src/core-isomorphic/config/horizonConfig.mjs +47 -1
  59. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +266 -0
  60. package/src/core-isomorphic/economics/cacheGravity.mjs +18 -0
  61. package/src/core-isomorphic/economics/cliffBreaker.mjs +98 -12
  62. package/src/core-isomorphic/economics/driftLatency.mjs +114 -0
  63. package/src/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
  64. package/src/core-isomorphic/guards/bucketBGamma.mjs +442 -0
  65. package/src/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
  66. package/src/core-isomorphic/guards/circuitBreakers.mjs +191 -191
  67. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +154 -5
  68. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +103 -11
  69. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +311 -1
  70. package/src/core-isomorphic/guards/docIndexCore.mjs +446 -0
  71. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +16 -0
  72. package/src/core-isomorphic/guards/slopsquatGate.mjs +551 -0
  73. package/src/core-isomorphic/index.js +1 -0
  74. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +36 -12
  75. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +293 -237
  76. package/src/core-isomorphic/ui/modViews.mjs +35 -9
  77. package/src/diagnostics/claudeHookCapabilities.mjs +396 -0
  78. package/src/diagnostics/doctorEngine.mjs +95 -3
  79. package/src/engine-node/db/probe.mjs +234 -2
  80. package/src/engine-node/index.mjs +3 -0
  81. package/src/engine-node/sensors/blindspots.mjs +13 -6
  82. package/src/hooks/antigravity_rsl_hook.mjs +250 -0
  83. package/src/hooks/claude_rsl_hook.mjs +288 -0
  84. package/src/hooks/post_invocation.mjs +196 -4
  85. package/src/hooks/pre_invocation.mjs +732 -22
  86. package/src/hooks/session_start.mjs +39 -1
  87. package/src/utils/modelSwitchTelemetry.mjs +308 -0
  88. package/src/utils/sessionCalibration.mjs +657 -0
  89. package/src/webview/horizon_panel.html +1325 -317
@@ -0,0 +1,446 @@
1
+ /**
2
+ * @file src/guards/docIndexCore.mjs
3
+ * Pure JavaScript zero-token structural document & log indexer (`< 20ms`, 0 LLM tokens).
4
+ *
5
+ * Architectural Invariants:
6
+ * - ZERO `node:*` imports, ZERO `require()`, ZERO dynamic ESM imports (Mod Law 4 compliant).
7
+ * - Strictly excludes `ctxvault` SKU paths (`packages/airlock/`, `airlock-schema-canary.yml`,
8
+ * `docs/HIGHBEAM_AIRLOCK_*.md`).
9
+ * - Scans outside fenced code blocks for Markdown headings (`#`..`####`), code definitions
10
+ * (`export`, `function`, `class`, `interface`, `type`, `def`, `async def`, `func`, `struct`),
11
+ * or top-level JSON/YAML keys, with a contiguous 150-line unstructured fallback when `< 3`
12
+ * structural boundaries exist in files `> 400` lines.
13
+ */
14
+
15
+ import { normalizeSlashes, sha256Hex } from '../utils/runtime.mjs';
16
+
17
+ export const UNSTRUCTURED_FALLBACK_LINE_THRESHOLD = 400;
18
+ export const UNSTRUCTURED_SPAN_SIZE = 150;
19
+ export const MIN_STRUCTURAL_BOUNDARIES = 3;
20
+ export const MAX_IDENTIFIERS_PER_SPAN = 8;
21
+
22
+ const STOPWORDS = new Set([
23
+ 'const', 'let', 'var', 'function', 'async', 'await', 'return', 'export', 'import', 'from',
24
+ 'default', 'class', 'interface', 'type', 'extends', 'implements', 'public', 'private',
25
+ 'protected', 'static', 'true', 'false', 'null', 'undefined', 'this', 'super', 'new',
26
+ 'throw', 'catch', 'try', 'finally', 'else', 'switch', 'case', 'break', 'continue',
27
+ 'while', 'for', 'typeof', 'instanceof', 'void', 'delete', 'with', 'yield', 'def',
28
+ 'self', 'none', 'pass', 'elif', 'lambda', 'func', 'struct', 'impl', 'pub', 'mut',
29
+ 'string', 'number', 'boolean', 'object', 'array', 'promise', 'record', 'the', 'and',
30
+ 'with', 'that', 'this', 'from', 'into', 'when', 'where', 'then', 'only', 'also',
31
+ 'must', 'should', 'never', 'always', 'line', 'lines', 'file', 'files', 'test', 'data'
32
+ ]);
33
+
34
+ /**
35
+ * Checks whether a path belongs to the isolated sister security SKU and must never be indexed or read.
36
+ *
37
+ * @param {string} [filePath='']
38
+ * @returns {boolean}
39
+ */
40
+ export function isForbiddenSkuPath(filePath = '') {
41
+ const norm = normalizeSlashes(String(filePath || '')).trim();
42
+ if (!norm) return false;
43
+ const lower = norm.toLowerCase();
44
+ if (
45
+ /(?:^|\/)packages\/airlock(?:\/|$)/i.test(lower) ||
46
+ lower.endsWith('.github/workflows/airlock-schema-canary.yml') ||
47
+ /(?:^|\/)\.github\/workflows\/airlock-schema-canary\.yml$/i.test(lower) ||
48
+ /(?:^|\/)docs\/highbeam_airlock_[^/]*\.md$/i.test(lower)
49
+ ) {
50
+ return true;
51
+ }
52
+ return false;
53
+ }
54
+
55
+ /**
56
+ * Splits text into lines across CRLF and LF line endings.
57
+ *
58
+ * @param {string} [rawText='']
59
+ * @returns {string[]}
60
+ */
61
+ export function splitLinesNormalized(rawText = '') {
62
+ const str = String(rawText ?? '');
63
+ if (str.length === 0) return [];
64
+ return str.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
65
+ }
66
+
67
+ /**
68
+ * Parses YAML frontmatter from a `.index.md` document.
69
+ *
70
+ * @param {string} [markdownText='']
71
+ * @returns {{ indexed_file: string, sha256: string, total_lines: number, generated_by: string } | null}
72
+ */
73
+ export function parseIndexFrontmatter(markdownText = '') {
74
+ const lines = splitLinesNormalized(markdownText);
75
+ if (lines.length < 3 || lines[0].trim() !== '---') return null;
76
+ const meta = {
77
+ indexed_file: '',
78
+ sha256: '',
79
+ total_lines: 0,
80
+ generated_by: ''
81
+ };
82
+ let closed = false;
83
+ for (let i = 1; i < Math.min(lines.length, 25); i++) {
84
+ const trimmed = lines[i].trim();
85
+ if (trimmed === '---') {
86
+ closed = true;
87
+ break;
88
+ }
89
+ const sepIdx = trimmed.indexOf(':');
90
+ if (sepIdx === -1) continue;
91
+ const key = trimmed.slice(0, sepIdx).trim();
92
+ const val = trimmed.slice(sepIdx + 1).trim().replace(/^["']|["']$/g, '');
93
+ if (key === 'indexed_file') meta.indexed_file = val;
94
+ else if (key === 'sha256') meta.sha256 = val;
95
+ else if (key === 'total_lines') meta.total_lines = Number(val) || 0;
96
+ else if (key === 'generated_by') meta.generated_by = val;
97
+ }
98
+ return closed && meta.sha256 ? meta : null;
99
+ }
100
+
101
+ /**
102
+ * Compares live SHA-256 of a file against `.index.md` YAML frontmatter.
103
+ * Returns `0` (`FRESH`), `1` (`STALE`), or `2` (`MISSING`).
104
+ *
105
+ * @param {string} liveSha256
106
+ * @param {string | null | undefined} indexMarkdownText
107
+ * @returns {{ code: 0 | 1 | 2, status: 'FRESH' | 'STALE' | 'MISSING', recordedSha256: string | null }}
108
+ */
109
+ export function compareIndexFreshness(liveSha256, indexMarkdownText) {
110
+ if (!indexMarkdownText || typeof indexMarkdownText !== 'string') {
111
+ return { code: 2, status: 'MISSING', recordedSha256: null };
112
+ }
113
+ const fm = parseIndexFrontmatter(indexMarkdownText);
114
+ if (!fm || !fm.sha256) {
115
+ return { code: 2, status: 'MISSING', recordedSha256: null };
116
+ }
117
+ if (String(fm.sha256).toLowerCase() === String(liveSha256 || '').toLowerCase()) {
118
+ return { code: 0, status: 'FRESH', recordedSha256: fm.sha256 };
119
+ }
120
+ return { code: 1, status: 'STALE', recordedSha256: fm.sha256 };
121
+ }
122
+
123
+ function sanitizeTableCell(text = '') {
124
+ return String(text || '')
125
+ .replace(/\|/g, '\\|')
126
+ .replace(/\s+/g, ' ')
127
+ .trim()
128
+ .slice(0, 96);
129
+ }
130
+
131
+ /**
132
+ * Extracts up to `maxCount` backticked terms or high-signal identifiers from a slice of lines.
133
+ *
134
+ * @param {string[]} lines
135
+ * @param {number} startIdx - 0-based inclusive
136
+ * @param {number} endIdx - 0-based inclusive
137
+ * @param {number} [maxCount=MAX_IDENTIFIERS_PER_SPAN]
138
+ * @returns {string[]}
139
+ */
140
+ export function extractSpanIdentifiers(lines, startIdx, endIdx, maxCount = MAX_IDENTIFIERS_PER_SPAN) {
141
+ const counts = new Map();
142
+ const backtickTerms = [];
143
+ const backtickSeen = new Set();
144
+
145
+ const upper = Math.min(lines.length - 1, endIdx);
146
+ for (let i = Math.max(0, startIdx); i <= upper; i++) {
147
+ const line = lines[i] || '';
148
+ if (line.length > 500) continue;
149
+
150
+ // 1. Backticked terms first (high signal in Markdown/JSDoc/logs)
151
+ const btRegex = /`([A-Za-z0-9_./:-]{3,48})`/g;
152
+ let btMatch;
153
+ while ((btMatch = btRegex.exec(line)) !== null) {
154
+ const term = btMatch[1];
155
+ if (!backtickSeen.has(term) && !STOPWORDS.has(term.toLowerCase())) {
156
+ backtickSeen.add(term);
157
+ backtickTerms.push(term);
158
+ if (backtickTerms.length >= maxCount) break;
159
+ }
160
+ }
161
+
162
+ // 2. Identifiers (camelCase, PascalCase, snake_case, SCREAMING_SNAKE, error codes)
163
+ const idRegex = /\b([A-Za-z_][A-Za-z0-9_]{3,44})\b/g;
164
+ let idMatch;
165
+ while ((idMatch = idRegex.exec(line)) !== null) {
166
+ const ident = idMatch[1];
167
+ const lower = ident.toLowerCase();
168
+ if (STOPWORDS.has(lower)) continue;
169
+ const isStructuredIdent =
170
+ /[A-Z]/.test(ident) || ident.includes('_') || ident.length >= 6;
171
+ if (!isStructuredIdent) continue;
172
+ counts.set(ident, (counts.get(ident) || 0) + 1);
173
+ }
174
+ }
175
+
176
+ const out = [...backtickTerms.slice(0, maxCount)];
177
+ if (out.length < maxCount) {
178
+ const ranked = Array.from(counts.entries())
179
+ .filter(([ident]) => !backtickSeen.has(ident))
180
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
181
+ for (const [ident] of ranked) {
182
+ out.push(ident);
183
+ if (out.length >= maxCount) break;
184
+ }
185
+ }
186
+ return out;
187
+ }
188
+
189
+ /**
190
+ * Detects structural boundary label on a single line (outside Markdown code fences).
191
+ *
192
+ * @param {string} line
193
+ * @param {boolean} isMarkdownLike
194
+ * @returns {string | null}
195
+ */
196
+ function matchStructuralBoundary(line, isMarkdownLike) {
197
+ const trimmed = line.trim();
198
+ if (!trimmed || trimmed.length > 240) return null;
199
+
200
+ // Markdown headings (# .. ####)
201
+ const mdMatch = /^(#{1,4})\s+(.+)$/.exec(line);
202
+ if (mdMatch) {
203
+ return `${mdMatch[1]} ${mdMatch[2].trim().slice(0, 72)}`;
204
+ }
205
+ if (isMarkdownLike) return null;
206
+
207
+ // JS/TS exports, functions, classes, interfaces, types
208
+ const jsMatch =
209
+ /^(?:export\s+(?:default\s+)?)?(?:async\s+)?(?:function\*?\s+([A-Za-z_$][A-Za-z0-9_$]*)|class\s+([A-Za-z_$][A-Za-z0-9_$]*)|interface\s+([A-Za-z_$][A-Za-z0-9_$]*)|type\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=|const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s*)?(?:\([^\x29]*\)|[A-Za-z_$][A-Za-z0-9_$]*)\s*=>|(?:export\s+const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=))/.exec(
210
+ line
211
+ );
212
+ if (jsMatch) {
213
+ const sym = jsMatch[1] || jsMatch[2] || jsMatch[3] || jsMatch[4] || jsMatch[5] || jsMatch[6];
214
+ if (sym) return sym;
215
+ }
216
+
217
+ // Python / Go / Rust definitions
218
+ const pyGoRustMatch =
219
+ /^(?:async\s+def|def|class|func(?:\s*\([^\x29]+\))?|pub\s+(?:async\s+)?fn|fn|pub\s+struct|struct|impl)\s+([A-Za-z_][A-Za-z0-9_]*)/.exec(
220
+ line
221
+ );
222
+ if (pyGoRustMatch) {
223
+ return pyGoRustMatch[1];
224
+ }
225
+
226
+ // Top-level JSON or YAML keys (0-2 leading spaces)
227
+ const jsonKeyMatch = /^ {0,2}"([A-Za-z0-9_.-]{2,48})"\s*:\s*[\x7b\x5b]/.exec(line);
228
+ if (jsonKeyMatch) {
229
+ return `"${jsonKeyMatch[1]}"`;
230
+ }
231
+ const yamlKeyMatch = /^([A-Za-z][A-Za-z0-9_.-]{1,48}):\s*(?:#.*)?$/.exec(line);
232
+ if (yamlKeyMatch && !/^(?:https?|file|mailto)$/i.test(yamlKeyMatch[1])) {
233
+ return `${yamlKeyMatch[1]}:`;
234
+ }
235
+
236
+ return null;
237
+ }
238
+
239
+ /**
240
+ * Builds deterministic zero-token `.index.md` content for any text/code/log file.
241
+ *
242
+ * @param {object} params
243
+ * @param {string} params.filePath
244
+ * @param {string} [params.displayPath]
245
+ * @param {string} params.rawText
246
+ * @param {string} [params.sha256]
247
+ * @returns {{
248
+ * markdown: string,
249
+ * sha256: string,
250
+ * totalLines: number,
251
+ * spanCount: number,
252
+ * usedFallback: boolean,
253
+ * indexTokens: number
254
+ * }}
255
+ */
256
+ export function buildStructuralIndexMarkdown({
257
+ filePath = '',
258
+ displayPath = '',
259
+ rawText = '',
260
+ sha256 = ''
261
+ } = {}) {
262
+ const normalizedRaw = String(rawText ?? '').replace(/\r\n/g, '\n');
263
+ const computedSha = sha256 || sha256Hex(normalizedRaw);
264
+ const lines = splitLinesNormalized(rawText);
265
+ const totalLines = lines.length;
266
+ const labelPath = normalizeSlashes(displayPath || filePath || 'unknown');
267
+ const isMarkdownLike = /\.(?:md|mdx|markdown)$/i.test(labelPath);
268
+
269
+ const boundaries = [];
270
+ let inFence = false;
271
+ let fenceMarker = '';
272
+
273
+ for (let i = 0; i < totalLines; i++) {
274
+ const line = lines[i];
275
+ const fenceMatch = /^\s*(`{3,}|~{3,})/.exec(line);
276
+ if (fenceMatch) {
277
+ const marker = fenceMatch[1][0];
278
+ if (!inFence) {
279
+ inFence = true;
280
+ fenceMarker = marker;
281
+ } else if (marker === fenceMarker) {
282
+ inFence = false;
283
+ fenceMarker = '';
284
+ }
285
+ continue;
286
+ }
287
+ if (inFence) continue;
288
+
289
+ const label = matchStructuralBoundary(line, isMarkdownLike);
290
+ if (label) {
291
+ boundaries.push({ lineNum: i + 1, label });
292
+ }
293
+ }
294
+
295
+ let spans = [];
296
+ let usedFallback = false;
297
+
298
+ if (boundaries.length < MIN_STRUCTURAL_BOUNDARIES && totalLines > UNSTRUCTURED_FALLBACK_LINE_THRESHOLD) {
299
+ usedFallback = true;
300
+ for (let start = 1; start <= totalLines; start += UNSTRUCTURED_SPAN_SIZE) {
301
+ const end = Math.min(totalLines, start + UNSTRUCTURED_SPAN_SIZE - 1);
302
+ const idents = extractSpanIdentifiers(lines, start - 1, end - 1);
303
+ spans.push({
304
+ startLine: start,
305
+ endLine: end,
306
+ label: `Unstructured Span L${start}-L${end}`,
307
+ identifiers: idents
308
+ });
309
+ }
310
+ } else if (boundaries.length > 0) {
311
+ // Include leading preamble if boundary 0 starts after line 1
312
+ if (boundaries[0].lineNum > 1) {
313
+ const preEnd = boundaries[0].lineNum - 1;
314
+ spans.push({
315
+ startLine: 1,
316
+ endLine: preEnd,
317
+ label: 'Preamble / Imports',
318
+ identifiers: extractSpanIdentifiers(lines, 0, preEnd - 1)
319
+ });
320
+ }
321
+ for (let idx = 0; idx < boundaries.length; idx++) {
322
+ const curr = boundaries[idx];
323
+ const next = boundaries[idx + 1];
324
+ const endLine = next ? Math.max(curr.lineNum, next.lineNum - 1) : totalLines;
325
+ spans.push({
326
+ startLine: curr.lineNum,
327
+ endLine,
328
+ label: curr.label,
329
+ identifiers: extractSpanIdentifiers(lines, curr.lineNum - 1, endLine - 1)
330
+ });
331
+ }
332
+ } else {
333
+ const end = Math.max(1, totalLines);
334
+ spans.push({
335
+ startLine: 1,
336
+ endLine: end,
337
+ label: totalLines === 0 ? 'Empty File' : `Full Span L1-L${end}`,
338
+ identifiers: totalLines === 0 ? [] : extractSpanIdentifiers(lines, 0, end - 1)
339
+ });
340
+ }
341
+
342
+ // Cap extreme table rows at 120 spans by coalescing adjacent micro-spans if needed
343
+ if (spans.length > 120) {
344
+ const bucketSize = Math.ceil(spans.length / 80);
345
+ const merged = [];
346
+ for (let i = 0; i < spans.length; i += bucketSize) {
347
+ const group = spans.slice(i, i + bucketSize);
348
+ const combinedIdents = [];
349
+ const seen = new Set();
350
+ for (const g of group) {
351
+ for (const id of g.identifiers) {
352
+ if (!seen.has(id)) {
353
+ seen.add(id);
354
+ combinedIdents.push(id);
355
+ }
356
+ if (combinedIdents.length >= MAX_IDENTIFIERS_PER_SPAN) break;
357
+ }
358
+ }
359
+ merged.push({
360
+ startLine: group[0].startLine,
361
+ endLine: group[group.length - 1].endLine,
362
+ label: group.length > 1 ? `${group[0].label} (+${group.length - 1} more)` : group[0].label,
363
+ identifiers: combinedIdents
364
+ });
365
+ }
366
+ spans = merged;
367
+ }
368
+
369
+ const rows = spans.map((sp) => {
370
+ const rangeStr = `L${sp.startLine}-L${sp.endLine}`;
371
+ const sectionStr = sanitizeTableCell(sp.label);
372
+ const identStr =
373
+ sp.identifiers.length > 0
374
+ ? sp.identifiers.map((id) => `\`${sanitizeTableCell(id)}\``).join(', ')
375
+ : '—';
376
+ return `| ${rangeStr} | ${sectionStr} | ${identStr} |`;
377
+ });
378
+
379
+ const markdown = [
380
+ '---',
381
+ `indexed_file: "${labelPath}"`,
382
+ `sha256: "${computedSha}"`,
383
+ `total_lines: ${totalLines}`,
384
+ 'generated_by: "ctxtop-doc-indexer"',
385
+ '---',
386
+ '',
387
+ `# Structural Index: \`${labelPath}\` (${totalLines} lines)`,
388
+ '',
389
+ '| Lines | Section / Symbol | High-Signal Identifiers |',
390
+ '| :--- | :--- | :--- |',
391
+ ...rows,
392
+ ''
393
+ ].join('\n');
394
+
395
+ return {
396
+ markdown,
397
+ sha256: computedSha,
398
+ totalLines,
399
+ spanCount: spans.length,
400
+ usedFallback,
401
+ indexTokens: Math.max(1, Math.ceil(markdown.length / 4))
402
+ };
403
+ }
404
+
405
+ /**
406
+ * Formats 1-indexed line-numbered slice output (` 142 | ...`) across CRLF and LF inputs.
407
+ *
408
+ * @param {string} [rawText='']
409
+ * @param {number} [startLine=1]
410
+ * @param {number} [endLine=1]
411
+ * @returns {{ text: string, startLine: number, endLine: number, totalLines: number }}
412
+ */
413
+ export function formatSlicedLines(rawText = '', startLine = 1, endLine = 1) {
414
+ const lines = splitLinesNormalized(rawText);
415
+ const totalLines = lines.length;
416
+ if (totalLines === 0) {
417
+ return { text: '', startLine: 0, endLine: 0, totalLines: 0 };
418
+ }
419
+ const s = Math.max(1, Math.min(totalLines, Math.floor(Number(startLine) || 1)));
420
+ const e = Math.max(s, Math.min(totalLines, Math.floor(Number(endLine) || s)));
421
+ const width = Math.max(6, String(e).length);
422
+ const out = [];
423
+ for (let lineNum = s; lineNum <= e; lineNum++) {
424
+ out.push(`${String(lineNum).padStart(width, ' ')} | ${lines[lineNum - 1]}`);
425
+ }
426
+ return {
427
+ text: out.join('\n'),
428
+ startLine: s,
429
+ endLine: e,
430
+ totalLines
431
+ };
432
+ }
433
+
434
+ export default {
435
+ UNSTRUCTURED_FALLBACK_LINE_THRESHOLD,
436
+ UNSTRUCTURED_SPAN_SIZE,
437
+ MIN_STRUCTURAL_BOUNDARIES,
438
+ MAX_IDENTIFIERS_PER_SPAN,
439
+ isForbiddenSkuPath,
440
+ splitLinesNormalized,
441
+ parseIndexFrontmatter,
442
+ compareIndexFreshness,
443
+ extractSpanIdentifiers,
444
+ buildStructuralIndexMarkdown,
445
+ formatSlicedLines
446
+ };
@@ -9,6 +9,7 @@
9
9
  */
10
10
 
11
11
  import { path, getCwd, sha256Hex, writeTextAtomic } from '../utils/runtime.mjs';
12
+ import { buildStructuralIndexMarkdown } from './docIndexCore.mjs';
12
13
 
13
14
  export const OFFLOAD_TOKEN_THRESHOLD = 4000; // ~16 KB (~4 chars/token)
14
15
  export const CHARS_PER_TOKEN_ESTIMATE = 4;
@@ -213,12 +214,14 @@ export function sanitizePostToolOutput(params = {}, options = {}) {
213
214
  // Step 6: Programmatic Artifact Offloading when structured/command output exceeds 4,000 tokens
214
215
  let offloaded = false;
215
216
  let artifactPath = null;
217
+ let artifactIndexPath = null;
216
218
  let finalOutput = sanitizedText;
217
219
 
218
220
  if (originalTokens > offloadThresholdTokens || postFilterTokens > offloadThresholdTokens) {
219
221
  const sha256 = computeSha256(cleaned, options);
220
222
  const cwd = getCwd(options);
221
223
  const relativeArtifactPath = `.claude/cache/artifacts/ah_${sha256}.txt`;
224
+ const relativeIndexPath = `${relativeArtifactPath}.index.md`;
222
225
  const candidateArtifactPath = path.join(
223
226
  cwd,
224
227
  '.claude',
@@ -226,11 +229,21 @@ export function sanitizePostToolOutput(params = {}, options = {}) {
226
229
  'artifacts',
227
230
  `ah_${sha256}.txt`
228
231
  );
232
+ const candidateIndexPath = `${candidateArtifactPath}.index.md`;
229
233
 
230
234
  offloaded = writeTextAtomic(candidateArtifactPath, cleaned, options);
231
235
 
232
236
  if (offloaded) {
233
237
  artifactPath = candidateArtifactPath;
238
+ const idxBuilt = buildStructuralIndexMarkdown({
239
+ filePath: candidateArtifactPath,
240
+ displayPath: relativeArtifactPath,
241
+ rawText: cleaned,
242
+ sha256
243
+ });
244
+ if (writeTextAtomic(candidateIndexPath, idxBuilt.markdown, options)) {
245
+ artifactIndexPath = candidateIndexPath;
246
+ }
234
247
  const nonEmptyLines = filteredLines.filter((l) => l.trim().length > 0);
235
248
  const sampleLines = nonEmptyLines.slice(0, 3);
236
249
  const schemaSummary = inferPayloadSchema(cleaned);
@@ -239,6 +252,7 @@ export function sanitizePostToolOutput(params = {}, options = {}) {
239
252
  `[Highbeam Artifact Offload: ${originalTokens.toLocaleString()} tokens (${rawLines.length} lines) -> ${relativeArtifactPath}]`,
240
253
  `Schema: ${schemaSummary}`,
241
254
  `Full lossless output saved to: ${artifactPath}`,
255
+ ...(artifactIndexPath ? [`Structural index map: ${relativeIndexPath}`] : []),
242
256
  `Sample lines (1..${sampleLines.length}):`,
243
257
  ...sampleLines.map((l, idx) => ` ${idx + 1}: ${l.slice(0, 200)}`)
244
258
  ];
@@ -256,6 +270,7 @@ export function sanitizePostToolOutput(params = {}, options = {}) {
256
270
  } else {
257
271
  // ISS-034: Never truncate to a broken pointer stub if offload write fails! Preserve full ANSI-cleaned output.
258
272
  artifactPath = null;
273
+ artifactIndexPath = null;
259
274
  finalOutput = cleaned;
260
275
  }
261
276
  }
@@ -271,6 +286,7 @@ export function sanitizePostToolOutput(params = {}, options = {}) {
271
286
  sanitized: wasModified,
272
287
  offloaded,
273
288
  artifactPath,
289
+ artifactIndexPath,
274
290
  originalTokens,
275
291
  finalTokens,
276
292
  savedTokens,