@modelprofile.com/flexharness 18.3.1 → 18.5.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,328 @@
1
+ import * as plugins from './plugins.js';
2
+ import { FlexHarnessStoreFormatError } from './errors.js';
3
+ import { assertJsonSerializable } from './utils.json.js';
4
+
5
+ /** A content address is the SHA-256 of the canonical JSON node, including its domain tag. */
6
+ export interface IProjectionIndexNodeWrite {
7
+ readonly hash: string;
8
+ readonly node: IProjectionIndexTreeNode;
9
+ }
10
+
11
+ export type TProjectionIndexTree =
12
+ | 'messages'
13
+ | 'messageIds'
14
+ | 'runs'
15
+ | 'staged'
16
+ | 'segments'
17
+ | 'segmentRuns'
18
+ | 'events'
19
+ | 'captures';
20
+
21
+ export interface IProjectionIndexTreeNode {
22
+ readonly kind: 'projection-index-tree-v1';
23
+ readonly tree: TProjectionIndexTree;
24
+ readonly key: string;
25
+ readonly value: unknown;
26
+ readonly left?: string;
27
+ readonly right?: string;
28
+ readonly height: number;
29
+ readonly size: number;
30
+ /** Completed segment count, populated only by the ordered segment tree. */
31
+ readonly completed: number;
32
+ readonly capturing: number;
33
+ }
34
+
35
+ export interface IProjectionIndexTreeReader {
36
+ readNode(hash: string): Promise<unknown>;
37
+ }
38
+
39
+ function canonicalJson(value: unknown): string {
40
+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
41
+ if (value !== null && typeof value === 'object') {
42
+ const record = value as Record<string, unknown>;
43
+ return `{${Object.keys(record).sort().map((key) =>
44
+ `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
45
+ }
46
+ const primitive = JSON.stringify(value);
47
+ if (primitive === undefined) throw new FlexHarnessStoreFormatError('Projection index node is not JSON.');
48
+ return primitive;
49
+ }
50
+
51
+ export function projectionIndexHash(node: unknown): string {
52
+ assertJsonSerializable(node, '$indexNode');
53
+ return plugins.crypto.createHash('sha256').update(canonicalJson(node)).digest('hex');
54
+ }
55
+
56
+ function assertHash(hash: string): void {
57
+ if (!/^[a-f0-9]{64}$/.test(hash)) {
58
+ throw new FlexHarnessStoreFormatError('Projection index node hash is invalid.');
59
+ }
60
+ }
61
+
62
+ function isRecord(value: unknown): value is Record<string, unknown> {
63
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
64
+ }
65
+
66
+ function assertTreeNode(value: unknown, tree: TProjectionIndexTree): asserts value is IProjectionIndexTreeNode {
67
+ if (!isRecord(value) || value.kind !== 'projection-index-tree-v1' || value.tree !== tree
68
+ || typeof value.key !== 'string' || !Object.hasOwn(value, 'value')
69
+ || !Number.isSafeInteger(value.height) || Number(value.height) < 1
70
+ || !Number.isSafeInteger(value.size) || Number(value.size) < 1
71
+ || !Number.isSafeInteger(value.completed) || Number(value.completed) < 0
72
+ || !Number.isSafeInteger(value.capturing) || Number(value.capturing) < 0
73
+ || (value.left !== undefined && (typeof value.left !== 'string' || !/^[a-f0-9]{64}$/.test(value.left)))
74
+ || (value.right !== undefined && (typeof value.right !== 'string' || !/^[a-f0-9]{64}$/.test(value.right)))) {
75
+ throw new FlexHarnessStoreFormatError('Projection index tree node is malformed.');
76
+ }
77
+ const keys = Object.keys(value);
78
+ if (keys.some((key) => !['kind', 'tree', 'key', 'value', 'left', 'right', 'height', 'size', 'completed', 'capturing'].includes(key))) {
79
+ throw new FlexHarnessStoreFormatError('Projection index tree node has an unknown field.');
80
+ }
81
+ }
82
+
83
+ /** One invocation's authenticated, immutable AVL nodes and staged replacements. */
84
+ export class ProjectionIndexTree {
85
+ private readonly cached = new Map<string, IProjectionIndexTreeNode>();
86
+ private readonly staged = new Map<string, IProjectionIndexTreeNode>();
87
+
88
+ public constructor(
89
+ private readonly tree: TProjectionIndexTree,
90
+ private readonly reader?: IProjectionIndexTreeReader,
91
+ ) {}
92
+
93
+ private async read(hash: string | undefined): Promise<IProjectionIndexTreeNode | undefined> {
94
+ if (hash === undefined) return undefined;
95
+ assertHash(hash);
96
+ const cached = this.cached.get(hash);
97
+ if (cached) return cached;
98
+ if (!this.reader) throw new FlexHarnessStoreFormatError('Projection index node is missing.');
99
+ const value = await this.reader.readNode(hash);
100
+ assertTreeNode(value, this.tree);
101
+ if (projectionIndexHash(value) !== hash) {
102
+ throw new FlexHarnessStoreFormatError('Projection index node digest does not match its address.');
103
+ }
104
+ this.cached.set(hash, value);
105
+ return value;
106
+ }
107
+
108
+ private async write(
109
+ key: string,
110
+ value: unknown,
111
+ left: string | undefined,
112
+ right: string | undefined,
113
+ ): Promise<string> {
114
+ const [leftNode, rightNode] = await Promise.all([this.read(left), this.read(right)]);
115
+ const node: IProjectionIndexTreeNode = {
116
+ kind: 'projection-index-tree-v1',
117
+ tree: this.tree,
118
+ key,
119
+ value,
120
+ ...(left === undefined ? {} : { left }),
121
+ ...(right === undefined ? {} : { right }),
122
+ height: 1 + Math.max(leftNode?.height ?? 0, rightNode?.height ?? 0),
123
+ size: 1 + (leftNode?.size ?? 0) + (rightNode?.size ?? 0),
124
+ completed: (this.tree === 'segments' && isRecord(value) && value.status === 'completed' ? 1 : 0)
125
+ + (leftNode?.completed ?? 0) + (rightNode?.completed ?? 0),
126
+ capturing: (this.tree === 'segments' && isRecord(value) && value.status === 'capturing' && value.captureId !== undefined ? 1 : 0)
127
+ + (leftNode?.capturing ?? 0) + (rightNode?.capturing ?? 0),
128
+ };
129
+ const hash = projectionIndexHash(node);
130
+ this.cached.set(hash, node);
131
+ this.staged.set(hash, node);
132
+ return hash;
133
+ }
134
+
135
+ private async rotateLeft(hash: string): Promise<string> {
136
+ const node = await this.read(hash);
137
+ const right = await this.read(node?.right);
138
+ if (!node || !right) throw new FlexHarnessStoreFormatError('Projection index rotation is invalid.');
139
+ const newLeft = await this.write(node.key, node.value, node.left, right.left);
140
+ return this.write(right.key, right.value, newLeft, right.right);
141
+ }
142
+
143
+ private async rotateRight(hash: string): Promise<string> {
144
+ const node = await this.read(hash);
145
+ const left = await this.read(node?.left);
146
+ if (!node || !left) throw new FlexHarnessStoreFormatError('Projection index rotation is invalid.');
147
+ const newRight = await this.write(node.key, node.value, left.right, node.right);
148
+ return this.write(left.key, left.value, left.left, newRight);
149
+ }
150
+
151
+ private async balance(hash: string): Promise<string> {
152
+ const node = await this.read(hash);
153
+ if (!node) throw new FlexHarnessStoreFormatError('Projection index node is missing.');
154
+ const [left, right] = await Promise.all([this.read(node.left), this.read(node.right)]);
155
+ const difference = (left?.height ?? 0) - (right?.height ?? 0);
156
+ if (difference > 1) {
157
+ if (!left) throw new FlexHarnessStoreFormatError('Projection index left branch is missing.');
158
+ const [inner, outer] = await Promise.all([this.read(left.right), this.read(left.left)]);
159
+ const leftHash = (inner?.height ?? 0) > (outer?.height ?? 0)
160
+ ? await this.rotateLeft(node.left as string) : node.left as string;
161
+ return this.rotateRight(await this.write(node.key, node.value, leftHash, node.right));
162
+ }
163
+ if (difference < -1) {
164
+ if (!right) throw new FlexHarnessStoreFormatError('Projection index right branch is missing.');
165
+ const [inner, outer] = await Promise.all([this.read(right.left), this.read(right.right)]);
166
+ const rightHash = (inner?.height ?? 0) > (outer?.height ?? 0)
167
+ ? await this.rotateRight(node.right as string) : node.right as string;
168
+ return this.rotateLeft(await this.write(node.key, node.value, node.left, rightHash));
169
+ }
170
+ return hash;
171
+ }
172
+
173
+ public async get(root: string | undefined, key: string): Promise<unknown> {
174
+ let cursor = root;
175
+ while (cursor !== undefined) {
176
+ const node = await this.read(cursor);
177
+ if (!node) break;
178
+ if (key === node.key) return node.value;
179
+ cursor = key < node.key ? node.left : node.right;
180
+ }
181
+ return undefined;
182
+ }
183
+
184
+ public async set(root: string | undefined, key: string, value: unknown): Promise<string> {
185
+ if (root === undefined) return this.write(key, value, undefined, undefined);
186
+ const node = await this.read(root);
187
+ if (!node) throw new FlexHarnessStoreFormatError('Projection index node is missing.');
188
+ if (key === node.key) return this.write(key, value, node.left, node.right);
189
+ const left = key < node.key ? await this.set(node.left, key, value) : node.left;
190
+ const right = key > node.key ? await this.set(node.right, key, value) : node.right;
191
+ return this.balance(await this.write(node.key, node.value, left, right));
192
+ }
193
+
194
+ /** Builds a canonical balanced tree in linear work from entries sorted by unique key. */
195
+ public async build(entries: readonly { key: string; value: unknown }[]): Promise<string | undefined> {
196
+ for (let index = 1; index < entries.length; index++) {
197
+ if (entries[index - 1].key >= entries[index].key) {
198
+ throw new FlexHarnessStoreFormatError('Projection index bootstrap keys must be unique and sorted.');
199
+ }
200
+ }
201
+ const visit = async (start: number, end: number): Promise<string | undefined> => {
202
+ if (start === end) return undefined;
203
+ const middle = Math.floor((start + end) / 2);
204
+ const left = await visit(start, middle);
205
+ const right = await visit(middle + 1, end);
206
+ return this.write(entries[middle].key, entries[middle].value, left, right);
207
+ };
208
+ return visit(0, entries.length);
209
+ }
210
+
211
+ private async removeMin(root: string): Promise<{ root: string | undefined; node: IProjectionIndexTreeNode }> {
212
+ const node = await this.read(root);
213
+ if (!node) throw new FlexHarnessStoreFormatError('Projection index node is missing.');
214
+ if (!node.left) return { root: node.right, node };
215
+ const result = await this.removeMin(node.left);
216
+ return {
217
+ root: await this.balance(await this.write(node.key, node.value, result.root, node.right)),
218
+ node: result.node,
219
+ };
220
+ }
221
+
222
+ public async delete(root: string | undefined, key: string): Promise<string | undefined> {
223
+ if (root === undefined) return undefined;
224
+ const node = await this.read(root);
225
+ if (!node) throw new FlexHarnessStoreFormatError('Projection index node is missing.');
226
+ if (key < node.key) {
227
+ if (!node.left) return root;
228
+ return this.balance(await this.write(node.key, node.value, await this.delete(node.left, key), node.right));
229
+ }
230
+ if (key > node.key) {
231
+ if (!node.right) return root;
232
+ return this.balance(await this.write(node.key, node.value, node.left, await this.delete(node.right, key)));
233
+ }
234
+ if (!node.left) return node.right;
235
+ if (!node.right) return node.left;
236
+ const next = await this.removeMin(node.right);
237
+ return this.balance(await this.write(next.node.key, next.node.value, node.left, next.root));
238
+ }
239
+
240
+ public async size(root: string | undefined): Promise<number> {
241
+ return (await this.read(root))?.size ?? 0;
242
+ }
243
+
244
+ public async completed(root: string | undefined): Promise<number> {
245
+ return (await this.read(root))?.completed ?? 0;
246
+ }
247
+
248
+ public async capturing(root: string | undefined): Promise<number> {
249
+ return (await this.read(root))?.capturing ?? 0;
250
+ }
251
+
252
+ public async select(root: string | undefined, index: number): Promise<{ key: string; value: unknown } | undefined> {
253
+ let cursor = root;
254
+ let offset = index;
255
+ while (cursor !== undefined) {
256
+ const node = await this.read(cursor);
257
+ if (!node) break;
258
+ const leftSize = (await this.read(node.left))?.size ?? 0;
259
+ if (offset === leftSize) return { key: node.key, value: node.value };
260
+ if (offset < leftSize) cursor = node.left;
261
+ else { offset -= leftSize + 1; cursor = node.right; }
262
+ }
263
+ return undefined;
264
+ }
265
+
266
+ public async rank(root: string | undefined, key: string): Promise<number | undefined> {
267
+ let cursor = root;
268
+ let before = 0;
269
+ while (cursor !== undefined) {
270
+ const node = await this.read(cursor);
271
+ if (!node) break;
272
+ const leftSize = (await this.read(node.left))?.size ?? 0;
273
+ if (key === node.key) return before + leftSize;
274
+ if (key < node.key) cursor = node.left;
275
+ else { before += leftSize + 1; cursor = node.right; }
276
+ }
277
+ return undefined;
278
+ }
279
+
280
+ public async selectCompleted(root: string | undefined, index: number): Promise<{ key: string; value: unknown } | undefined> {
281
+ let cursor = root;
282
+ let offset = index;
283
+ while (cursor !== undefined) {
284
+ const node = await this.read(cursor);
285
+ if (!node) break;
286
+ const leftCompleted = (await this.read(node.left))?.completed ?? 0;
287
+ if (offset < leftCompleted) { cursor = node.left; continue; }
288
+ offset -= leftCompleted;
289
+ const self = this.tree === 'segments' && isRecord(node.value) && node.value.status === 'completed';
290
+ if (self && offset === 0) return { key: node.key, value: node.value };
291
+ if (self) offset--;
292
+ cursor = node.right;
293
+ }
294
+ return undefined;
295
+ }
296
+
297
+ public async range(root: string | undefined, start: number, end: number): Promise<Array<{ key: string; value: unknown }>> {
298
+ const result: Array<{ key: string; value: unknown }> = [];
299
+ const visit = async (hash: string | undefined, base: number): Promise<void> => {
300
+ const node = await this.read(hash);
301
+ if (!node) return;
302
+ const leftSize = (await this.read(node.left))?.size ?? 0;
303
+ const position = base + leftSize;
304
+ if (start < position) await visit(node.left, base);
305
+ if (start <= position && position < end) result.push({ key: node.key, value: node.value });
306
+ if (position + 1 < end) await visit(node.right, position + 1);
307
+ };
308
+ await visit(root, 0);
309
+ return result;
310
+ }
311
+
312
+ /** Only nodes reachable from a returned root need to be persisted. */
313
+ public writes(root: string | undefined): IProjectionIndexNodeWrite[] {
314
+ const result: IProjectionIndexNodeWrite[] = [];
315
+ const visited = new Set<string>();
316
+ const visit = (hash: string | undefined): void => {
317
+ if (hash === undefined || visited.has(hash)) return;
318
+ visited.add(hash);
319
+ const node = this.staged.get(hash);
320
+ if (!node) return;
321
+ result.push({ hash, node });
322
+ visit(node.left);
323
+ visit(node.right);
324
+ };
325
+ visit(root);
326
+ return result;
327
+ }
328
+ }