afyx-engineering-kit 0.1.0-alpha.7 → 0.1.0-alpha.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.
- package/.afyx-source-revision +1 -1
- package/afyx-context/src/budget.js +39 -153
- package/afyx-context/src/documentation.js +116 -0
- package/afyx-context/src/index.js +2 -0
- package/afyx-context/src/memory.js +122 -229
- package/afyx-context/src/usage.js +91 -0
- package/afyx-forge/src/cli.js +14 -1
- package/afyx-forge/src/index.js +3 -0
- package/afyx-forge/src/workflow-refiner.js +48 -15
- package/afyx-forge/src/workflow.js +226 -0
- package/afyx-graph/engine/release/RELEASE-MANIFEST.json +16 -6
- package/afyx-graph/engine/release/SHA256SUMS +4 -2
- package/afyx-graph/engine/release/afyx-graph-darwin-arm64.tar.gz +0 -0
- package/afyx-graph/engine/release/afyx-graph-darwin-x64.tar.gz +0 -0
- package/afyx-graph/engine/release/afyx-graph-linux-x64.tar.gz +0 -0
- package/afyx-graph/engine/release/afyx-graph-win32-x64.zip +0 -0
- package/bin/afyx-engineering-kit.mjs +14 -6
- package/install.ps1 +52 -6
- package/install.sh +11 -7
- package/package.json +3 -1
- package/scripts/afyx-capability-orchestrator.mjs +159 -41
- package/scripts/afyx-graph-artifact.mjs +1 -1
- package/scripts/afyx-graph-targets.mjs +8 -0
- package/scripts/afyx-host-adapters.mjs +52 -0
- package/scripts/afyx-host-bridge-lifecycle.mjs +4 -0
- package/scripts/afyx-host-bridge.mjs +25 -0
- package/scripts/afyx-install-backend.mjs +34 -13
- package/scripts/afyx-install-contract.mjs +5 -2
- package/scripts/afyx-install-progress.mjs +88 -0
- package/scripts/afyx-installer-environment.mjs +150 -0
- package/scripts/afyx-local-link-ownership.mjs +16 -0
- package/scripts/afyx-midnight-circuit.mjs +322 -79
- package/scripts/afyx-modular-integration.mjs +3 -0
- package/scripts/afyx-modular-runtime.mjs +3 -0
- package/scripts/afyx-native-execution.mjs +168 -0
- package/scripts/afyx-native-github.mjs +155 -0
- package/scripts/afyx-npm-installer.mjs +56 -28
- package/scripts/afyx-provider-inventory.mjs +6 -3
- package/scripts/afyx-security-auditor.mjs +61 -64
- package/scripts/afyx-skill-catalog.mjs +83 -0
- package/scripts/afyx-skill-engineering.mjs +2 -0
- package/scripts/afyx-universal-runtime.mjs +74 -12
- package/scripts/install-afyx-graph.sh +4 -4
- package/scripts/lib/AfyxInstallerProgress.psm1 +11 -0
- package/scripts/lib/AfyxSkillLifecycle.psm1 +42 -6
- package/scripts/lib/afyx-installer-progress.sh +30 -0
- package/scripts/link-global-dev.ps1 +10 -3
- package/scripts/link-global-dev.sh +10 -8
- package/scripts/prepare-g6-package.mjs +13 -28
- package/scripts/resolve-git-release-artifacts.mjs +5 -4
- package/scripts/stage-npm-release.mjs +3 -1
- package/scripts/validate-release-zip-graph.mjs +2 -2
- package/uninstall.ps1 +2 -0
- package/verify.ps1 +7 -1
- package/verify.sh +5 -3
package/.afyx-source-revision
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
57cfcf2c7b7a48d1c5bbba03fe97af98b71ac5bd
|
|
@@ -1,166 +1,52 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
3
|
-
*
|
|
4
|
-
* Provides deterministic token and byte estimation, redundancy detection,
|
|
5
|
-
* and adaptive evidence compression without external model telemetry.
|
|
6
|
-
* Ensures critical source references (file paths, symbol names, error spans)
|
|
7
|
-
* remain recoverable when trimming oversized tool outputs.
|
|
8
|
-
*/
|
|
9
|
-
|
|
10
|
-
export const DEFAULT_CONTEXT_BUDGET = Object.freeze({
|
|
11
|
-
maxTokens: 4000,
|
|
12
|
-
maxBytes: 16000,
|
|
13
|
-
maxLines: 250,
|
|
14
|
-
});
|
|
15
|
-
|
|
16
|
-
/**
|
|
17
|
-
* Deterministic token counter heuristic (provider-agnostic: ~4 chars per token).
|
|
18
|
-
*/
|
|
1
|
+
/** AFYX bounded context selection. Token counts are estimates, not provider telemetry. */
|
|
2
|
+
export const DEFAULT_CONTEXT_BUDGET = Object.freeze({ maxTokens: 4000, maxBytes: 16000, maxLines: 250 });
|
|
19
3
|
export function estimateTokens(text) {
|
|
20
4
|
if (!text) return 0;
|
|
21
|
-
const
|
|
22
|
-
|
|
23
|
-
const wordTokens = str.split(/\s+/).filter(Boolean).length;
|
|
24
|
-
const charTokens = Math.ceil(str.length / 4);
|
|
25
|
-
return Math.max(wordTokens, charTokens);
|
|
5
|
+
const value = typeof text === 'string' ? text : JSON.stringify(text);
|
|
6
|
+
return Math.max(value.split(/\s+/).filter(Boolean).length, Math.ceil(value.length / 4));
|
|
26
7
|
}
|
|
27
|
-
|
|
28
|
-
/**
|
|
29
|
-
* Calculates byte size in UTF-8.
|
|
30
|
-
*/
|
|
31
8
|
export function estimateBytes(text) {
|
|
32
9
|
if (!text) return 0;
|
|
33
|
-
|
|
34
|
-
return Buffer.byteLength(str, 'utf8');
|
|
10
|
+
return Buffer.byteLength(typeof text === 'string' ? text : JSON.stringify(text), 'utf8');
|
|
35
11
|
}
|
|
36
|
-
|
|
37
|
-
/**
|
|
38
|
-
* Detects repetitive / redundant lines across text blocks.
|
|
39
|
-
*/
|
|
40
12
|
export function detectRedundancy(lines, { minRepeatCount = 3 } = {}) {
|
|
41
|
-
const
|
|
42
|
-
for (const line of lines) {
|
|
43
|
-
|
|
44
|
-
if (trimmed.length > 10) {
|
|
45
|
-
lineCounts.set(trimmed, (lineCounts.get(trimmed) || 0) + 1);
|
|
46
|
-
}
|
|
47
|
-
}
|
|
48
|
-
const redundant = new Set();
|
|
49
|
-
for (const [line, count] of lineCounts.entries()) {
|
|
50
|
-
if (count >= minRepeatCount) {
|
|
51
|
-
redundant.add(line);
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
return redundant;
|
|
13
|
+
const counts = new Map();
|
|
14
|
+
for (const line of lines) { const value = line.trim(); if (value.length > 10) counts.set(value, (counts.get(value) || 0) + 1); }
|
|
15
|
+
return new Set([...counts].filter(([, count]) => count >= minRepeatCount).map(([line]) => line));
|
|
55
16
|
}
|
|
56
|
-
|
|
57
|
-
/**
|
|
58
|
-
* Compresses an array of text sections or source files within a bounded budget,
|
|
59
|
-
* preserving critical references and recording exact truncation metadata.
|
|
60
|
-
*
|
|
61
|
-
* @param {Array<{ id: string, text: string, priority?: number, references?: string[] }>} items
|
|
62
|
-
* @param {Object} [budget]
|
|
63
|
-
* @param {number} [budget.maxTokens]
|
|
64
|
-
* @param {number} [budget.maxBytes]
|
|
65
|
-
* @param {number} [budget.maxLines]
|
|
66
|
-
* @returns {Object} Compressed result with retained items and truncation receipts
|
|
67
|
-
*/
|
|
68
17
|
export function compressContextItems(items, budget = {}) {
|
|
69
|
-
const
|
|
70
|
-
const
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
let currentBytes = 0;
|
|
77
|
-
let currentTokens = 0;
|
|
78
|
-
let currentLines = 0;
|
|
79
|
-
|
|
80
|
-
const admitted = [];
|
|
81
|
-
const truncated = [];
|
|
82
|
-
const omitted = [];
|
|
18
|
+
const limits = {};
|
|
19
|
+
for (const [key, fallback] of Object.entries(DEFAULT_CONTEXT_BUDGET)) {
|
|
20
|
+
limits[key] = budget[key] ?? fallback;
|
|
21
|
+
if (!Number.isSafeInteger(limits[key]) || limits[key] < 1) throw new Error(`Invalid context budget: ${key}`);
|
|
22
|
+
}
|
|
23
|
+
if (!Array.isArray(items) || items.some((item) => !item || typeof item.id !== 'string' || !item.id || typeof item.text !== 'string')) throw new Error('Context items require a non-empty id and text string');
|
|
24
|
+
const admitted = [], truncated = [], omitted = [];
|
|
83
25
|
const preservedReferences = new Set();
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
currentLines + itemLinesCount <= maxLines
|
|
101
|
-
) {
|
|
102
|
-
admitted.push({
|
|
103
|
-
id: item.id,
|
|
104
|
-
text: item.text,
|
|
105
|
-
status: 'FULL',
|
|
106
|
-
originalBytes: itemBytes,
|
|
107
|
-
originalTokens: itemTokens,
|
|
108
|
-
});
|
|
109
|
-
currentBytes += itemBytes;
|
|
110
|
-
currentTokens += itemTokens;
|
|
111
|
-
currentLines += itemLinesCount;
|
|
112
|
-
continue;
|
|
113
|
-
}
|
|
114
|
-
|
|
115
|
-
// Partial budget remaining: try bounded slice
|
|
116
|
-
const remainingBytes = Math.max(0, maxBytes - currentBytes);
|
|
117
|
-
const remainingLines = Math.max(0, maxLines - currentLines);
|
|
118
|
-
|
|
119
|
-
if (remainingBytes > 300 && remainingLines > 5) {
|
|
120
|
-
const halfLines = Math.floor(remainingLines / 2);
|
|
121
|
-
const head = itemLinesList.slice(0, halfLines);
|
|
122
|
-
const tail = itemLinesList.slice(-halfLines);
|
|
123
|
-
const omittedLineCount = itemLinesCount - head.length - tail.length;
|
|
124
|
-
|
|
125
|
-
const marker = `\n<!-- AFYX-TRUNCATED: [id=${item.id}] original=${itemLinesCount} lines, omitted=${omittedLineCount} lines; full evidence recoverable on disk -->\n`;
|
|
126
|
-
const compressedText = [...head, marker, ...tail].join('\n');
|
|
127
|
-
|
|
128
|
-
admitted.push({
|
|
129
|
-
id: item.id,
|
|
130
|
-
text: compressedText,
|
|
131
|
-
status: 'PARTIAL',
|
|
132
|
-
originalBytes: itemBytes,
|
|
133
|
-
compressedBytes: estimateBytes(compressedText),
|
|
134
|
-
omittedLines: omittedLineCount,
|
|
135
|
-
});
|
|
136
|
-
truncated.push(item.id);
|
|
137
|
-
currentBytes += estimateBytes(compressedText);
|
|
138
|
-
currentLines += remainingLines;
|
|
139
|
-
break;
|
|
140
|
-
} else {
|
|
141
|
-
omitted.push({
|
|
142
|
-
id: item.id,
|
|
143
|
-
originalBytes: itemBytes,
|
|
144
|
-
references: item.references || [],
|
|
145
|
-
});
|
|
26
|
+
let rendered = '';
|
|
27
|
+
const measure = (text) => ({ bytes: estimateBytes(text), tokens: estimateTokens(text), lines: text ? text.split('\n').length : 0 });
|
|
28
|
+
const fits = (text) => { const size = measure((admitted.length ? `${rendered}\n\n` : '') + text); return size.bytes <= limits.maxBytes && size.tokens <= limits.maxTokens && size.lines <= limits.maxLines; };
|
|
29
|
+
for (const item of [...items].sort((a, b) => (b.priority || 0) - (a.priority || 0))) {
|
|
30
|
+
let text = item.text, status = 'FULL';
|
|
31
|
+
if (!fits(text)) {
|
|
32
|
+
const chars = Array.from(text);
|
|
33
|
+
let low = 0, high = chars.length - 1, selected = null;
|
|
34
|
+
// Slice code points so UTF-8 never contains a split surrogate.
|
|
35
|
+
while (low <= high) {
|
|
36
|
+
const keep = Math.floor((low + high) / 2), head = Math.ceil(keep / 2), tail = Math.floor(keep / 2);
|
|
37
|
+
const candidate = chars.slice(0, head).join('') + `\n<!-- AFYX-TRUNCATED: ${chars.length - keep} characters omitted -->\n` + (tail ? chars.slice(-tail).join('') : '');
|
|
38
|
+
if (fits(candidate)) { selected = candidate; low = keep + 1; } else high = keep - 1;
|
|
39
|
+
}
|
|
40
|
+
if (selected === null) { omitted.push({ id: item.id, originalBytes: estimateBytes(item.text), references: item.references || [] }); continue; }
|
|
41
|
+
text = selected; status = 'PARTIAL'; truncated.push(item.id);
|
|
146
42
|
}
|
|
43
|
+
const references = Array.isArray(item.references) ? [...new Set(item.references.filter((ref) => typeof ref === 'string'))] : [];
|
|
44
|
+
admitted.push({ id: item.id, text, status, references, originalBytes: estimateBytes(item.text), originalTokens: estimateTokens(item.text), ...(status === 'PARTIAL' ? { compressedBytes: estimateBytes(text) } : {}) });
|
|
45
|
+
for (const reference of references) preservedReferences.add(reference);
|
|
46
|
+
rendered += (admitted.length > 1 ? '\n\n' : '') + text;
|
|
147
47
|
}
|
|
148
|
-
|
|
149
|
-
return {
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
metrics: {
|
|
153
|
-
totalOriginalItems: items.length,
|
|
154
|
-
admittedItemsCount: admitted.length,
|
|
155
|
-
truncatedItemsCount: truncated.length,
|
|
156
|
-
omittedItemsCount: omitted.length,
|
|
157
|
-
consumedBytes: currentBytes,
|
|
158
|
-
consumedTokens: currentTokens,
|
|
159
|
-
consumedLines: currentLines,
|
|
160
|
-
},
|
|
161
|
-
admitted,
|
|
162
|
-
truncated,
|
|
163
|
-
omitted,
|
|
164
|
-
preservedReferences: Array.from(preservedReferences),
|
|
165
|
-
};
|
|
48
|
+
const size = measure(rendered);
|
|
49
|
+
return { contract: 'afyx-context-budget-v1', budget: limits,
|
|
50
|
+
metrics: { totalOriginalItems: items.length, admittedItemsCount: admitted.length, truncatedItemsCount: truncated.length, omittedItemsCount: omitted.length, consumedBytes: size.bytes, consumedTokens: size.tokens, consumedLines: size.lines },
|
|
51
|
+
admitted, truncated, omitted, preservedReferences: [...preservedReferences] };
|
|
166
52
|
}
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
/** AFYX local documentation catalog. Sources are supplied by trusted host configuration. */
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
import * as fs from 'node:fs';
|
|
4
|
+
import { isAbsolute, relative, resolve, sep } from 'node:path';
|
|
5
|
+
import { compressContextItems } from './budget.js';
|
|
6
|
+
|
|
7
|
+
export const DOCUMENTATION_CONTRACT = 'afyx-documentation/v1';
|
|
8
|
+
const hash = (value) => createHash('sha256').update(value).digest('hex');
|
|
9
|
+
const words = (text) => String(text).toLowerCase().match(/[\p{L}\p{N}_]+/gu) || [];
|
|
10
|
+
function fail(code) { const error = new Error(code); error.code = code; throw error; }
|
|
11
|
+
function contained(root, file) { const rel = relative(root, file); return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel); }
|
|
12
|
+
|
|
13
|
+
export function createDocumentationCatalog({ projectRoot, sources = [], enabled = true, maxCacheEntries = 32, maxSourceBytes = 1_048_576, maxSearchSources = 32, maxSearchBytes = 4_194_304 } = {}) {
|
|
14
|
+
if (!Array.isArray(sources) || sources.length > 1000 || !Number.isSafeInteger(maxCacheEntries) || maxCacheEntries < 1 || maxCacheEntries > 1000
|
|
15
|
+
|| !Number.isSafeInteger(maxSourceBytes) || maxSourceBytes < 1 || maxSourceBytes > 16_777_216
|
|
16
|
+
|| !Number.isSafeInteger(maxSearchSources) || maxSearchSources < 1 || maxSearchSources > 1000
|
|
17
|
+
|| !Number.isSafeInteger(maxSearchBytes) || maxSearchBytes < 1 || maxSearchBytes > 16_777_216) fail('DOCUMENTATION_INVALID_CONFIG');
|
|
18
|
+
const root = resolve(projectRoot || process.cwd());
|
|
19
|
+
const registry = new Map();
|
|
20
|
+
const cache = new Map();
|
|
21
|
+
let sourceReads = 0, cacheHits = 0;
|
|
22
|
+
for (const source of sources) {
|
|
23
|
+
if (!source || typeof source.id !== 'string' || !source.id || source.id.length > 256 || typeof source.path !== 'string' || !source.path
|
|
24
|
+
|| source.path.includes('\0') || registry.has(source.id)) fail('DOCUMENTATION_INVALID_SOURCE');
|
|
25
|
+
const file = resolve(root, source.path);
|
|
26
|
+
if (!contained(root, file) || file === root) fail('DOCUMENTATION_UNSAFE_PATH');
|
|
27
|
+
registry.set(source.id, Object.freeze({ id: source.id, path: relative(root, file), domain: String(source.domain || ''), library: String(source.library || ''), version: String(source.version || '') }));
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function read(source, { remainingBytes = Infinity, onInspect = () => {} } = {}) {
|
|
31
|
+
if (fs.lstatSync(root).isSymbolicLink()) fail('DOCUMENTATION_UNSAFE_PATH');
|
|
32
|
+
const canonicalRoot = fs.realpathSync(root);
|
|
33
|
+
let file = root;
|
|
34
|
+
for (const part of source.path.split(sep)) {
|
|
35
|
+
file = resolve(file, part);
|
|
36
|
+
if (fs.lstatSync(file).isSymbolicLink()) fail('DOCUMENTATION_UNSAFE_PATH');
|
|
37
|
+
}
|
|
38
|
+
if (!contained(canonicalRoot, fs.realpathSync(file))) fail('DOCUMENTATION_UNSAFE_PATH');
|
|
39
|
+
const stat = fs.statSync(file, { bigint: true });
|
|
40
|
+
if (!stat.isFile() || stat.nlink > 1n || stat.size > BigInt(maxSourceBytes)) fail('DOCUMENTATION_SOURCE_LIMIT');
|
|
41
|
+
if (Number.isFinite(remainingBytes) && stat.size > BigInt(remainingBytes)) fail('DOCUMENTATION_SEARCH_LIMIT');
|
|
42
|
+
onInspect(Number(stat.size));
|
|
43
|
+
const fingerprint = `${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}:${stat.ino}`;
|
|
44
|
+
const known = cache.get(source.id);
|
|
45
|
+
if (known?.fingerprint === fingerprint) { cacheHits++; cache.delete(source.id); cache.set(source.id, known); return known; }
|
|
46
|
+
const handle = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
|
|
47
|
+
let bytes;
|
|
48
|
+
try {
|
|
49
|
+
const opened = fs.fstatSync(handle, { bigint: true });
|
|
50
|
+
if (`${opened.size}:${opened.mtimeNs}:${opened.ctimeNs}:${opened.ino}` !== fingerprint) fail('DOCUMENTATION_SOURCE_CHANGED');
|
|
51
|
+
// Read at most the admitted size plus one byte; concurrent growth cannot allocate unbounded input.
|
|
52
|
+
const buffer = Buffer.alloc(Number(stat.size) + 1);
|
|
53
|
+
let length = 0;
|
|
54
|
+
while (length < buffer.length) { const count = fs.readSync(handle, buffer, length, buffer.length - length, null); if (!count) break; length += count; }
|
|
55
|
+
if (length > Number(stat.size)) fail('DOCUMENTATION_SOURCE_CHANGED');
|
|
56
|
+
bytes = buffer.subarray(0, length);
|
|
57
|
+
} finally { fs.closeSync(handle); }
|
|
58
|
+
sourceReads++;
|
|
59
|
+
if (bytes.length > maxSourceBytes || bytes.includes(0)) fail('DOCUMENTATION_SOURCE_LIMIT');
|
|
60
|
+
let text;
|
|
61
|
+
try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail('DOCUMENTATION_INVALID_ENCODING'); }
|
|
62
|
+
const after = fs.statSync(file, { bigint: true });
|
|
63
|
+
if (`${after.size}:${after.mtimeNs}:${after.ctimeNs}:${after.ino}` !== fingerprint) fail('DOCUMENTATION_SOURCE_CHANGED');
|
|
64
|
+
const record = { ...source, title: text.match(/^#\s+(.+)$/m)?.[1] || source.id, text, sha256: hash(bytes), fingerprint };
|
|
65
|
+
cache.set(source.id, record);
|
|
66
|
+
while (cache.size > maxCacheEntries) cache.delete(cache.keys().next().value);
|
|
67
|
+
return record;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function search({ query = '', domain, library, version, budget = {}, limit = 5 } = {}) {
|
|
71
|
+
if (!enabled) return { contract: DOCUMENTATION_CONTRACT, status: 'DISABLED', items: [], renderedContext: '', metrics: { sourceReads: 0, cacheHits: 0 }, errors: [] };
|
|
72
|
+
if (typeof query !== 'string' || !query.trim() || query.length > 4096 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100) fail('DOCUMENTATION_INVALID_QUERY');
|
|
73
|
+
const tokens = [...new Set(words(query))];
|
|
74
|
+
const beforeReads = sourceReads, beforeHits = cacheHits;
|
|
75
|
+
const matches = [], errors = [];
|
|
76
|
+
const candidates = [...registry.values()].filter((source) => (domain === undefined || source.domain === domain) && (library === undefined || source.library === library) && (version === undefined || source.version === version));
|
|
77
|
+
let inspectedSources = 0, inspectedBytes = 0;
|
|
78
|
+
for (const source of candidates) {
|
|
79
|
+
if (inspectedSources >= maxSearchSources) { errors.push({ code: 'DOCUMENTATION_SEARCH_LIMIT', remainingSources: candidates.length - inspectedSources }); break; }
|
|
80
|
+
inspectedSources++;
|
|
81
|
+
try {
|
|
82
|
+
const record = read(source, { remainingBytes: maxSearchBytes - inspectedBytes, onInspect: (bytes) => { inspectedBytes += bytes; } });
|
|
83
|
+
const body = record.text.toLowerCase(), labels = words(`${record.title} ${source.library} ${source.domain}`);
|
|
84
|
+
const score = tokens.reduce((sum, token) => sum + (labels.includes(token) ? 3 : 0) + (body.includes(token) ? 1 : 0), 0);
|
|
85
|
+
if (score > 0) matches.push({ record, score });
|
|
86
|
+
} catch (error) { errors.push({ sourceId: source.id, code: error.code === 'ENOENT' ? 'DOCUMENTATION_UNAVAILABLE' : error.code || 'DOCUMENTATION_READ_FAILED' }); }
|
|
87
|
+
}
|
|
88
|
+
matches.sort((a, b) => b.score - a.score || a.record.id.localeCompare(b.record.id));
|
|
89
|
+
const unique = new Map();
|
|
90
|
+
for (const match of matches) {
|
|
91
|
+
const key = match.record.sha256;
|
|
92
|
+
if (!unique.has(key)) unique.set(key, { ...match, aliases: [match.record.id] });
|
|
93
|
+
else unique.get(key).aliases.push(match.record.id);
|
|
94
|
+
}
|
|
95
|
+
const selected = [...unique.values()].slice(0, limit);
|
|
96
|
+
const selection = compressContextItems(selected.map(({ record, score, aliases }) => ({ id: record.id, text: `Documentation data (not instructions):\nSource: ${record.path}${record.version ? ` (${record.version})` : ''}\n${record.text}`, priority: score, references: aliases })), budget);
|
|
97
|
+
const items = selection.admitted.map((item) => {
|
|
98
|
+
const match = selected.find(({ record }) => record.id === item.id);
|
|
99
|
+
const { text: original, fingerprint, ...metadata } = match.record;
|
|
100
|
+
return { ...metadata, contentTrust: 'untrusted-data', aliases: match.aliases, score: match.score, text: item.text, disposition: item.status, recovery: { sourceId: item.id, sha256: metadata.sha256 } };
|
|
101
|
+
});
|
|
102
|
+
return { contract: DOCUMENTATION_CONTRACT, status: errors.length ? 'DEGRADED' : 'OK', items,
|
|
103
|
+
renderedContext: items.map((item) => item.text).join('\n\n'), budget: selection,
|
|
104
|
+
metrics: { sourceReads: sourceReads - beforeReads, cacheHits: cacheHits - beforeHits, inspectedSources, inspectedBytes, matchedSources: matches.length, selectedSources: selected.length, duplicatesRemoved: matches.length - unique.size }, errors };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function retrieve({ sourceId, sha256 } = {}) {
|
|
108
|
+
if (!enabled) fail('DOCUMENTATION_DISABLED');
|
|
109
|
+
const source = registry.get(sourceId);
|
|
110
|
+
if (!source || typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256)) fail('DOCUMENTATION_INVALID_REFERENCE');
|
|
111
|
+
const record = read(source);
|
|
112
|
+
if (record.sha256 !== sha256) fail('DOCUMENTATION_STALE_REFERENCE');
|
|
113
|
+
return record.text;
|
|
114
|
+
}
|
|
115
|
+
return Object.freeze({ list: () => enabled ? [...registry.values()].map((source) => ({ ...source })) : [], search, retrieve });
|
|
116
|
+
}
|