@modelprofile.com/flexharness 18.4.0 → 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,693 @@
1
+ import { FlexHarnessStoreFormatError } from './errors.js';
2
+ import type {
3
+ IFlexMessage,
4
+ IFlexProjectionChange,
5
+ IFlexReversionSegment,
6
+ TFlexProjectionSnapshot,
7
+ } from './interfaces.js';
8
+ import { FLEX_REVERSION_MAXIMUM_LIMITS, FLEX_REVERSION_REFERENCE_MAX_BYTES } from './interfaces.js';
9
+ import {
10
+ assertFlexProjectionSnapshot,
11
+ assertPendingApplyRunIds,
12
+ assertPendingApplyRunUnit,
13
+ assertProjectionSegmentTurnRelation,
14
+ assertSessionMetrics,
15
+ deepFreeze,
16
+ validateMessage,
17
+ validateReversionSegment,
18
+ validateStagedTerminal,
19
+ } from './utils.json.js';
20
+ import { validateProjectionChangeSave } from './utils.projectionchange.js';
21
+ import {
22
+ ProjectionIndexTree,
23
+ projectionIndexHash,
24
+ type IProjectionIndexTreeNode,
25
+ type IProjectionIndexTreeReader,
26
+ type TProjectionIndexTree,
27
+ } from './utils.projectionindextree.js';
28
+
29
+ export interface IFlexProjectionMessageFact {
30
+ readonly messageId: string;
31
+ readonly sessionId: string;
32
+ readonly runId: string;
33
+ readonly role: IFlexMessage['role'];
34
+ readonly steerId?: string;
35
+ }
36
+
37
+ export interface IFlexProjectionSegmentFact {
38
+ readonly runId: string;
39
+ readonly userMessageId?: string;
40
+ readonly status: IFlexReversionSegment['status'];
41
+ readonly eventIds: readonly string[];
42
+ readonly captureId?: string;
43
+ readonly protocolVersion: IFlexReversionSegment['protocolVersion'];
44
+ readonly disposition?: IFlexReversionSegment['disposition'];
45
+ }
46
+
47
+ interface IRunFact {
48
+ readonly prompts: number;
49
+ readonly assistants: number;
50
+ }
51
+
52
+ interface IStagedFact {
53
+ readonly userMessageId?: string;
54
+ readonly userSteerId?: string;
55
+ readonly assistantMessageId: string;
56
+ }
57
+
58
+ interface IRootRefs {
59
+ readonly messages?: string;
60
+ readonly messageIds?: string;
61
+ readonly runs?: string;
62
+ readonly staged?: string;
63
+ readonly segments?: string;
64
+ readonly segmentRuns?: string;
65
+ readonly events?: string;
66
+ readonly captures?: string;
67
+ }
68
+
69
+ export interface IFlexProjectionIndexRoot {
70
+ readonly kind: 'flex-projection-validation-root-v1';
71
+ readonly sessionId: string;
72
+ readonly revision: number;
73
+ readonly projectionSchemaVersion: 0 | 1 | 2 | 3;
74
+ readonly nextMessageSerial: number;
75
+ readonly nextSegmentSerial: number;
76
+ readonly refs: IRootRefs;
77
+ }
78
+
79
+ export type TFlexProjectionIndexNode = IFlexProjectionIndexRoot | IProjectionIndexTreeNode;
80
+
81
+ export interface IFlexProjectionIndexNodeWrite {
82
+ readonly hash: string;
83
+ readonly node: TFlexProjectionIndexNode;
84
+ }
85
+
86
+ export interface IFlexProjectionIndexReader extends IProjectionIndexTreeReader {}
87
+
88
+ export interface IFlexProjectionIndexResult {
89
+ readonly rootHash: string;
90
+ readonly writes: readonly IFlexProjectionIndexNodeWrite[];
91
+ }
92
+
93
+ export interface IFlexProjectionIndexChangeResult extends IFlexProjectionIndexResult {
94
+ readonly change: IFlexProjectionChange;
95
+ }
96
+
97
+ /** Recomputes a returned node's canonical address before a store stages it. */
98
+ export function hashFlexProjectionIndexNode(node: TFlexProjectionIndexNode): string {
99
+ return projectionIndexHash(node);
100
+ }
101
+
102
+ const refNames = [
103
+ 'messages', 'messageIds', 'runs', 'staged', 'segments', 'segmentRuns', 'events', 'captures',
104
+ ] as const satisfies readonly TProjectionIndexTree[];
105
+
106
+ function isRecord(value: unknown): value is Record<string, unknown> {
107
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
108
+ }
109
+
110
+ function hashNode(node: TFlexProjectionIndexNode): string {
111
+ return hashFlexProjectionIndexNode(node);
112
+ }
113
+
114
+ function serialKey(serial: number): string {
115
+ if (!Number.isSafeInteger(serial) || serial < 0) throw new FlexHarnessStoreFormatError('Projection index serial is invalid.');
116
+ return serial.toString(16).padStart(16, '0');
117
+ }
118
+
119
+ function compareKey(left: { key: string }, right: { key: string }): number {
120
+ return left.key < right.key ? -1 : left.key > right.key ? 1 : 0;
121
+ }
122
+
123
+ function messageFact(message: IFlexMessage): IFlexProjectionMessageFact {
124
+ return {
125
+ messageId: message.messageId,
126
+ sessionId: message.sessionId,
127
+ runId: message.runId,
128
+ role: message.role,
129
+ ...(message.steerId === undefined ? {} : { steerId: message.steerId }),
130
+ };
131
+ }
132
+
133
+ function segmentFact(segment: IFlexReversionSegment): IFlexProjectionSegmentFact {
134
+ return {
135
+ runId: segment.runId,
136
+ ...(segment.userMessageId === undefined ? {} : { userMessageId: segment.userMessageId }),
137
+ status: segment.status,
138
+ eventIds: [...segment.eventIds],
139
+ ...(segment.captureId === undefined ? {} : { captureId: segment.captureId }),
140
+ protocolVersion: segment.protocolVersion,
141
+ ...(segment.disposition === undefined ? {} : { disposition: segment.disposition }),
142
+ };
143
+ }
144
+
145
+ function assertRoot(value: unknown): asserts value is IFlexProjectionIndexRoot {
146
+ if (!isRecord(value) || value.kind !== 'flex-projection-validation-root-v1'
147
+ || typeof value.sessionId !== 'string' || !value.sessionId
148
+ || !Number.isSafeInteger(value.revision) || Number(value.revision) < 0
149
+ || ![0, 1, 2, 3].includes(Number(value.projectionSchemaVersion))
150
+ || !Number.isSafeInteger(value.nextMessageSerial) || Number(value.nextMessageSerial) < 0
151
+ || !Number.isSafeInteger(value.nextSegmentSerial) || Number(value.nextSegmentSerial) < 0
152
+ || !isRecord(value.refs)) {
153
+ throw new FlexHarnessStoreFormatError('Projection validation index root is malformed.');
154
+ }
155
+ if (Object.keys(value).some((key) => ![
156
+ 'kind', 'sessionId', 'revision', 'projectionSchemaVersion', 'nextMessageSerial', 'nextSegmentSerial', 'refs',
157
+ ].includes(key))) throw new FlexHarnessStoreFormatError('Projection validation index root has unknown fields.');
158
+ if (Object.keys(value.refs).some((key) => !refNames.includes(key as TProjectionIndexTree))) {
159
+ throw new FlexHarnessStoreFormatError('Projection validation index root has an unknown tree.');
160
+ }
161
+ for (const name of refNames) {
162
+ const ref = value.refs[name];
163
+ if (ref !== undefined && (typeof ref !== 'string' || !/^[a-f0-9]{64}$/.test(ref))) {
164
+ throw new FlexHarnessStoreFormatError('Projection validation index root has an invalid tree address.');
165
+ }
166
+ }
167
+ if (value.projectionSchemaVersion !== 3 && Object.keys(value.refs).length > 0) {
168
+ throw new FlexHarnessStoreFormatError('Legacy projection validation index must have no trees.');
169
+ }
170
+ }
171
+
172
+ async function readRoot(
173
+ reader: IFlexProjectionIndexReader,
174
+ rootHash: string,
175
+ expectedRevision: number,
176
+ sessionId: string,
177
+ ): Promise<IFlexProjectionIndexRoot> {
178
+ if (!/^[a-f0-9]{64}$/.test(rootHash)) throw new FlexHarnessStoreFormatError('Projection validation index root address is invalid.');
179
+ const node = await reader.readNode(rootHash);
180
+ assertRoot(node);
181
+ if (hashNode(node) !== rootHash || node.revision !== expectedRevision || node.sessionId !== sessionId) {
182
+ throw new FlexHarnessStoreFormatError('Projection validation index is not authenticated to this session and revision.');
183
+ }
184
+ return node;
185
+ }
186
+
187
+ class IndexTrees {
188
+ public readonly messages: ProjectionIndexTree;
189
+ public readonly messageIds: ProjectionIndexTree;
190
+ public readonly runs: ProjectionIndexTree;
191
+ public readonly staged: ProjectionIndexTree;
192
+ public readonly segments: ProjectionIndexTree;
193
+ public readonly segmentRuns: ProjectionIndexTree;
194
+ public readonly events: ProjectionIndexTree;
195
+ public readonly captures: ProjectionIndexTree;
196
+
197
+ public constructor(reader?: IFlexProjectionIndexReader) {
198
+ this.messages = new ProjectionIndexTree('messages', reader);
199
+ this.messageIds = new ProjectionIndexTree('messageIds', reader);
200
+ this.runs = new ProjectionIndexTree('runs', reader);
201
+ this.staged = new ProjectionIndexTree('staged', reader);
202
+ this.segments = new ProjectionIndexTree('segments', reader);
203
+ this.segmentRuns = new ProjectionIndexTree('segmentRuns', reader);
204
+ this.events = new ProjectionIndexTree('events', reader);
205
+ this.captures = new ProjectionIndexTree('captures', reader);
206
+ }
207
+
208
+ public writes(refs: IRootRefs): IFlexProjectionIndexNodeWrite[] {
209
+ const writes = new Map<string, IFlexProjectionIndexNodeWrite>();
210
+ for (const name of refNames) {
211
+ for (const entry of this[name].writes(refs[name])) writes.set(entry.hash, entry);
212
+ }
213
+ return [...writes.values()];
214
+ }
215
+ }
216
+
217
+ function finish(root: IFlexProjectionIndexRoot, trees: IndexTrees): IFlexProjectionIndexResult {
218
+ const refs = Object.fromEntries(Object.entries(root.refs).filter((entry) => entry[1] !== undefined)) as IRootRefs;
219
+ const canonicalRoot = { ...root, refs };
220
+ const rootHash = hashNode(canonicalRoot);
221
+ return deepFreeze({
222
+ rootHash,
223
+ writes: [{ hash: rootHash, node: canonicalRoot }, ...trees.writes(refs)],
224
+ });
225
+ }
226
+
227
+ async function changeRun(
228
+ trees: IndexTrees,
229
+ root: string | undefined,
230
+ fact: IFlexProjectionMessageFact,
231
+ delta: 1 | -1,
232
+ ): Promise<string | undefined> {
233
+ const prior = await trees.runs.get(root, fact.runId) as IRunFact | undefined;
234
+ const prompts = (prior?.prompts ?? 0) + (fact.role === 'user' && fact.steerId === undefined ? delta : 0);
235
+ const assistants = (prior?.assistants ?? 0) + (fact.role === 'assistant' ? delta : 0);
236
+ if (prompts < 0 || assistants < 0) throw new FlexHarnessStoreFormatError('Projection run identity index is inconsistent.');
237
+ if (prompts === 0 && assistants === 0) return trees.runs.delete(root, fact.runId);
238
+ return trees.runs.set(root, fact.runId, { prompts, assistants } satisfies IRunFact);
239
+ }
240
+
241
+ /** Full validation and one-time construction, including legacy snapshots with empty current-schema trees. */
242
+ export async function createProjectionValidationIndex(
243
+ snapshot: TFlexProjectionSnapshot | undefined,
244
+ sessionId: string,
245
+ ): Promise<IFlexProjectionIndexResult> {
246
+ if (snapshot) assertFlexProjectionSnapshot(snapshot, sessionId);
247
+ const trees = new IndexTrees();
248
+ const refs: { -readonly [K in keyof IRootRefs]?: string } = {};
249
+ const current = snapshot?.schemaVersion === 3 ? snapshot : undefined;
250
+ if (current) {
251
+ const messageFacts = current.messages.map(messageFact);
252
+ const runCounts = new Map<string, IRunFact>();
253
+ for (const fact of messageFacts) {
254
+ const old = runCounts.get(fact.runId) ?? { prompts: 0, assistants: 0 };
255
+ runCounts.set(fact.runId, {
256
+ prompts: old.prompts + (fact.role === 'user' && fact.steerId === undefined ? 1 : 0),
257
+ assistants: old.assistants + (fact.role === 'assistant' ? 1 : 0),
258
+ });
259
+ }
260
+ refs.messages = await trees.messages.build(messageFacts.map((value, index) => ({ key: serialKey(index), value })));
261
+ refs.messageIds = await trees.messageIds.build(messageFacts
262
+ .map((fact, serial) => ({ key: fact.messageId, value: { ...fact, serial } }))
263
+ .sort(compareKey));
264
+ refs.runs = await trees.runs.build([...runCounts].map(([key, value]) => ({ key, value }))
265
+ .sort(compareKey));
266
+ refs.staged = await trees.staged.build(current.stagedTerminals.map((terminal) => ({
267
+ key: terminal.runId,
268
+ value: {
269
+ ...(terminal.userMessage ? { userMessageId: terminal.userMessage.messageId } : {}),
270
+ ...(terminal.userMessage?.steerId === undefined ? {} : { userSteerId: terminal.userMessage.steerId }),
271
+ assistantMessageId: terminal.assistantMessage.messageId,
272
+ } satisfies IStagedFact,
273
+ })).sort(compareKey));
274
+ const segmentFacts = current.reversionSegments.map(segmentFact);
275
+ refs.segments = await trees.segments.build(segmentFacts.map((value, index) => ({ key: serialKey(index), value })));
276
+ refs.segmentRuns = await trees.segmentRuns.build(segmentFacts
277
+ .map((fact, serial) => ({ key: fact.runId, value: serial }))
278
+ .sort(compareKey));
279
+ refs.events = await trees.events.build(segmentFacts.flatMap((fact, serial) =>
280
+ fact.eventIds.map((key) => ({ key, value: serial })))
281
+ .sort(compareKey));
282
+ refs.captures = await trees.captures.build(segmentFacts.flatMap((fact, serial) =>
283
+ fact.captureId === undefined ? [] : [{ key: fact.captureId, value: serial }])
284
+ .sort(compareKey));
285
+ }
286
+ return finish({
287
+ kind: 'flex-projection-validation-root-v1',
288
+ sessionId,
289
+ revision: snapshot?.revision ?? 0,
290
+ projectionSchemaVersion: snapshot?.schemaVersion ?? 0,
291
+ nextMessageSerial: current?.messages.length ?? 0,
292
+ nextSegmentSerial: current?.reversionSegments.length ?? 0,
293
+ refs,
294
+ }, trees);
295
+ }
296
+
297
+ function requireMessageFact(value: unknown): IFlexProjectionMessageFact & { serial: number } {
298
+ if (!isRecord(value) || typeof value.messageId !== 'string' || typeof value.sessionId !== 'string'
299
+ || typeof value.runId !== 'string' || (value.role !== 'user' && value.role !== 'assistant')
300
+ || !Number.isSafeInteger(value.serial) || Number(value.serial) < 0
301
+ || (value.steerId !== undefined && typeof value.steerId !== 'string')) {
302
+ throw new FlexHarnessStoreFormatError('Projection message identity index is malformed.');
303
+ }
304
+ return value as unknown as IFlexProjectionMessageFact & { serial: number };
305
+ }
306
+
307
+ function requireSegmentFact(value: unknown): IFlexProjectionSegmentFact {
308
+ if (!isRecord(value) || typeof value.runId !== 'string'
309
+ || (value.userMessageId !== undefined && typeof value.userMessageId !== 'string')
310
+ || !['capturing', 'completed', 'failed', 'cancelled'].includes(String(value.status))
311
+ || !Array.isArray(value.eventIds) || !value.eventIds.every((id: unknown) => typeof id === 'string')
312
+ || (value.captureId !== undefined && typeof value.captureId !== 'string')
313
+ || (value.protocolVersion !== 1 && value.protocolVersion !== 2)
314
+ || (value.disposition !== undefined
315
+ && !['pending', 'revertible', 'no-change', 'nonrevertible'].includes(String(value.disposition)))) {
316
+ throw new FlexHarnessStoreFormatError('Projection segment identity index is malformed.');
317
+ }
318
+ return value as unknown as IFlexProjectionSegmentFact;
319
+ }
320
+
321
+ function requireStagedFact(value: unknown): IStagedFact {
322
+ if (!isRecord(value) || typeof value.assistantMessageId !== 'string'
323
+ || (value.userMessageId !== undefined && typeof value.userMessageId !== 'string')
324
+ || (value.userSteerId !== undefined && typeof value.userSteerId !== 'string')
325
+ || (value.userSteerId !== undefined && value.userMessageId === undefined)) {
326
+ throw new FlexHarnessStoreFormatError('Projection staged identity index is malformed.');
327
+ }
328
+ return value as unknown as IStagedFact;
329
+ }
330
+
331
+ function requireSerial(value: unknown): number {
332
+ if (!Number.isSafeInteger(value) || Number(value) < 0) {
333
+ throw new FlexHarnessStoreFormatError('Projection identity serial is invalid.');
334
+ }
335
+ return value as number;
336
+ }
337
+
338
+ function requireNonNegativeInteger(value: unknown, path: string): number {
339
+ if (!Number.isSafeInteger(value) || Number(value) < 0) {
340
+ throw new FlexHarnessStoreFormatError(`${path} must be a non-negative integer.`);
341
+ }
342
+ return value as number;
343
+ }
344
+
345
+ function requireStringArray(value: unknown, path: string): string[] {
346
+ if (!Array.isArray(value) || value.some((item: unknown) => typeof item !== 'string')) {
347
+ throw new FlexHarnessStoreFormatError(`${path} must be an array of strings.`);
348
+ }
349
+ return value;
350
+ }
351
+
352
+ function assertOnlyKeys(value: Record<string, unknown>, allowed: readonly string[], path: string): void {
353
+ if (Object.keys(value).some((key) => !allowed.includes(key))) {
354
+ throw new FlexHarnessStoreFormatError(`${path} has an unknown field.`);
355
+ }
356
+ }
357
+
358
+ async function assertSegmentRelation(
359
+ trees: IndexTrees,
360
+ refs: IRootRefs,
361
+ fact: IFlexProjectionSegmentFact,
362
+ ): Promise<void> {
363
+ const visibleRun = await trees.runs.get(refs.runs, fact.runId) as IRunFact | undefined;
364
+ const staged = await trees.staged.get(refs.staged, fact.runId);
365
+ const stagedFact = staged === undefined ? undefined : requireStagedFact(staged);
366
+ const visible = fact.userMessageId === undefined ? undefined
367
+ : await trees.messageIds.get(refs.messageIds, fact.userMessageId);
368
+ const message = visible === undefined ? undefined : requireMessageFact(visible);
369
+ assertProjectionSegmentTurnRelation(fact, {
370
+ visiblePrompt: (visibleRun?.prompts ?? 0) > 0,
371
+ stagedPrompt: stagedFact?.userMessageId !== undefined && stagedFact.userSteerId === undefined,
372
+ assistant: (visibleRun?.assistants ?? 0) > 0 || stagedFact !== undefined,
373
+ matchingVisibleUser: message?.runId === fact.runId && message.role === 'user',
374
+ matchingStagedUser: stagedFact?.userMessageId !== undefined && stagedFact.userMessageId === fact.userMessageId,
375
+ }, 'Projection segment');
376
+ }
377
+
378
+ async function applyMessageEntries(
379
+ trees: IndexTrees,
380
+ refs: { -readonly [K in keyof IRootRefs]?: string },
381
+ list: IFlexProjectionChange['messages'],
382
+ sessionId: string,
383
+ nextSerial: number,
384
+ affectedRuns: Set<string>,
385
+ ): Promise<number> {
386
+ const length = await trees.messages.size(refs.messages);
387
+ if (list.end > length) {
388
+ throw new FlexHarnessStoreFormatError(`$change.messages keeps entries up to ${list.end}, but the store holds ${length}.`);
389
+ }
390
+ const discarded = [
391
+ ...await trees.messages.range(refs.messages, 0, list.start),
392
+ ...await trees.messages.range(refs.messages, list.end, length),
393
+ ];
394
+ for (const entry of discarded) {
395
+ const fact = requireMessageFact({ ...requireMessageIdentity(entry.value), serial: Number.parseInt(entry.key, 16) });
396
+ refs.messages = await trees.messages.delete(refs.messages, entry.key);
397
+ refs.messageIds = await trees.messageIds.delete(refs.messageIds, fact.messageId);
398
+ refs.runs = await changeRun(trees, refs.runs, fact, -1);
399
+ affectedRuns.add(fact.runId);
400
+ }
401
+ for (let index = 0; index < list.items.length; index++) {
402
+ const message = list.items[index];
403
+ validateMessage(message, `$snapshot.messages[${list.end - list.start + index}]`);
404
+ if (message.sessionId !== sessionId) {
405
+ throw new FlexHarnessStoreFormatError(`Projection message "${message.messageId}" does not belong to session "${sessionId}".`);
406
+ }
407
+ if (await trees.messageIds.get(refs.messageIds, message.messageId) !== undefined) {
408
+ throw new FlexHarnessStoreFormatError(`$snapshot.messages contains duplicate message "${message.messageId}".`);
409
+ }
410
+ const fact = messageFact(message);
411
+ const serial = nextSerial++;
412
+ refs.messages = await trees.messages.set(refs.messages, serialKey(serial), fact);
413
+ refs.messageIds = await trees.messageIds.set(refs.messageIds, fact.messageId, { ...fact, serial });
414
+ refs.runs = await changeRun(trees, refs.runs, fact, 1);
415
+ affectedRuns.add(fact.runId);
416
+ }
417
+ return nextSerial;
418
+ }
419
+
420
+ function requireMessageIdentity(value: unknown): IFlexProjectionMessageFact {
421
+ if (!isRecord(value) || typeof value.messageId !== 'string' || typeof value.sessionId !== 'string'
422
+ || typeof value.runId !== 'string' || (value.role !== 'user' && value.role !== 'assistant')
423
+ || (value.steerId !== undefined && typeof value.steerId !== 'string')) {
424
+ throw new FlexHarnessStoreFormatError('Projection ordered message identity is malformed.');
425
+ }
426
+ return value as unknown as IFlexProjectionMessageFact;
427
+ }
428
+
429
+ async function applyStagedTerminals(
430
+ trees: IndexTrees,
431
+ refs: { -readonly [K in keyof IRootRefs]?: string },
432
+ terminals: IFlexProjectionChange['stagedTerminals'],
433
+ sessionId: string,
434
+ affectedRuns: Set<string>,
435
+ ): Promise<void> {
436
+ const oldCount = await trees.staged.size(refs.staged);
437
+ const old = await trees.staged.range(refs.staged, 0, oldCount);
438
+ for (const entry of old) {
439
+ refs.staged = await trees.staged.delete(refs.staged, entry.key);
440
+ affectedRuns.add(entry.key);
441
+ }
442
+ if (!Array.isArray(terminals)) throw new FlexHarnessStoreFormatError('Snapshot stagedTerminals must be an array.');
443
+ const messageIds = new Set<string>();
444
+ const runIds = new Set<string>();
445
+ for (let index = 0; index < terminals.length; index++) {
446
+ const terminal = terminals[index];
447
+ const validated = validateStagedTerminal(terminal, `$snapshot.stagedTerminals[${index}]`);
448
+ if (runIds.has(validated.runId)) {
449
+ throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate staged run "${validated.runId}".`);
450
+ }
451
+ runIds.add(validated.runId);
452
+ affectedRuns.add(validated.runId);
453
+ for (const message of validated.user ? [validated.user, validated.assistant] : [validated.assistant]) {
454
+ if (message.sessionId !== sessionId) {
455
+ throw new FlexHarnessStoreFormatError(`Staged terminal "${validated.runId}" does not belong to session "${sessionId}".`);
456
+ }
457
+ if (messageIds.has(message.messageId)) {
458
+ throw new FlexHarnessStoreFormatError(`Snapshot staged terminals contain duplicate message "${message.messageId}".`);
459
+ }
460
+ messageIds.add(message.messageId);
461
+ }
462
+ const visible = await trees.runs.get(refs.runs, validated.runId) as IRunFact | undefined;
463
+ if (!validated.user && (visible?.prompts ?? 0) > 0) {
464
+ throw new FlexHarnessStoreFormatError(`$snapshot.stagedTerminals[${index}] omits its projected prompt message.`);
465
+ }
466
+ refs.staged = await trees.staged.set(refs.staged, validated.runId, {
467
+ ...(validated.user ? { userMessageId: validated.user.messageId } : {}),
468
+ ...(validated.user?.steerId === undefined ? {} : { userSteerId: validated.user.steerId }),
469
+ assistantMessageId: validated.assistant.messageId,
470
+ } satisfies IStagedFact);
471
+ }
472
+ }
473
+
474
+ async function applySegmentEntries(
475
+ trees: IndexTrees,
476
+ refs: { -readonly [K in keyof IRootRefs]?: string },
477
+ list: IFlexProjectionChange['reversionSegments'],
478
+ nextSerial: number,
479
+ affectedRuns: Set<string>,
480
+ ): Promise<number> {
481
+ const length = await trees.segments.size(refs.segments);
482
+ if (list.end > length) {
483
+ throw new FlexHarnessStoreFormatError(`$change.reversionSegments keeps entries up to ${list.end}, but the store holds ${length}.`);
484
+ }
485
+ const discarded = [
486
+ ...await trees.segments.range(refs.segments, 0, list.start),
487
+ ...await trees.segments.range(refs.segments, list.end, length),
488
+ ];
489
+ for (const entry of discarded) {
490
+ const fact = requireSegmentFact(entry.value);
491
+ refs.segments = await trees.segments.delete(refs.segments, entry.key);
492
+ refs.segmentRuns = await trees.segmentRuns.delete(refs.segmentRuns, fact.runId);
493
+ for (const eventId of fact.eventIds) refs.events = await trees.events.delete(refs.events, eventId);
494
+ if (fact.captureId !== undefined) refs.captures = await trees.captures.delete(refs.captures, fact.captureId);
495
+ affectedRuns.add(fact.runId);
496
+ }
497
+ for (let index = 0; index < list.items.length; index++) {
498
+ const segment = list.items[index];
499
+ validateReversionSegment(segment, `$snapshot.reversionSegments[${list.end - list.start + index}]`);
500
+ const fact = segmentFact(segment);
501
+ if (await trees.segmentRuns.get(refs.segmentRuns, fact.runId) !== undefined) {
502
+ throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate reversion run "${fact.runId}".`);
503
+ }
504
+ for (const eventId of fact.eventIds) {
505
+ if (await trees.events.get(refs.events, eventId) !== undefined) {
506
+ throw new FlexHarnessStoreFormatError(`Snapshot reuses reversion event "${eventId}".`);
507
+ }
508
+ }
509
+ if (fact.captureId !== undefined && await trees.captures.get(refs.captures, fact.captureId) !== undefined) {
510
+ throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate capture "${fact.captureId}".`);
511
+ }
512
+ const serial = nextSerial++;
513
+ refs.segments = await trees.segments.set(refs.segments, serialKey(serial), fact);
514
+ refs.segmentRuns = await trees.segmentRuns.set(refs.segmentRuns, fact.runId, serial);
515
+ for (const eventId of fact.eventIds) refs.events = await trees.events.set(refs.events, eventId, serial);
516
+ if (fact.captureId !== undefined) refs.captures = await trees.captures.set(refs.captures, fact.captureId, serial);
517
+ affectedRuns.add(fact.runId);
518
+ }
519
+ return nextSerial;
520
+ }
521
+
522
+ async function validateAffectedSegments(
523
+ trees: IndexTrees,
524
+ refs: IRootRefs,
525
+ affectedRuns: ReadonlySet<string>,
526
+ ): Promise<void> {
527
+ for (const runId of affectedRuns) {
528
+ const serialValue = await trees.segmentRuns.get(refs.segmentRuns, runId);
529
+ if (serialValue === undefined) continue;
530
+ const fact = requireSegmentFact(await trees.segments.get(refs.segments, serialKey(requireSerial(serialValue))));
531
+ await assertSegmentRelation(trees, refs, fact);
532
+ }
533
+ }
534
+
535
+ async function validatePendingAndReleases(
536
+ trees: IndexTrees,
537
+ refs: IRootRefs,
538
+ change: IFlexProjectionChange,
539
+ ): Promise<void> {
540
+ if (change.metrics !== undefined) assertSessionMetrics(change.metrics);
541
+ const segmentCount = await trees.segments.size(refs.segments);
542
+ if (segmentCount > FLEX_REVERSION_MAXIMUM_LIMITS.maxSegments) {
543
+ throw new FlexHarnessStoreFormatError('Snapshot reversionSegments exceeds its hard limit.');
544
+ }
545
+ const completedCount = await trees.segments.completed(refs.segments);
546
+ if (completedCount > FLEX_REVERSION_MAXIMUM_LIMITS.maxCompletedTurns) {
547
+ throw new FlexHarnessStoreFormatError('Snapshot completed reversion turns exceed their hard limit.');
548
+ }
549
+ const revertCursor = requireNonNegativeInteger(change.revertCursor, '$snapshot.revertCursor');
550
+ if (revertCursor > completedCount) {
551
+ throw new FlexHarnessStoreFormatError('Snapshot revertCursor exceeds its candidate count.');
552
+ }
553
+ const excluded = requireStringArray(change.excludedRunIds, '$snapshot.excludedRunIds');
554
+ if (excluded.some((id) => !id) || new Set(excluded).size !== excluded.length) {
555
+ throw new FlexHarnessStoreFormatError('Snapshot excludedRunIds is invalid.');
556
+ }
557
+ if (excluded.length > FLEX_REVERSION_MAXIMUM_LIMITS.maxExcludedRunIds) {
558
+ throw new FlexHarnessStoreFormatError('Snapshot excludedRunIds exceeds its hard limit.');
559
+ }
560
+
561
+ let captureOwnerRunId: string | undefined;
562
+ if (change.pendingReversion !== undefined) {
563
+ const pending = change.pendingReversion;
564
+ if (!isRecord(pending)) throw new FlexHarnessStoreFormatError('Snapshot pendingReversion is invalid.');
565
+ if (pending.kind === 'capture') {
566
+ assertOnlyKeys(pending, ['kind', 'runId', 'captureId', 'state', 'protocolVersion'], '$snapshot.pendingReversion');
567
+ if (typeof pending.runId !== 'string' || !pending.runId
568
+ || typeof pending.captureId !== 'string' || !pending.captureId
569
+ || !['preparing', 'prepared', 'finalizing'].includes(String(pending.state))
570
+ || (pending.protocolVersion !== 1 && pending.protocolVersion !== 2)) {
571
+ throw new FlexHarnessStoreFormatError('Snapshot pending capture is invalid.');
572
+ }
573
+ const serialValue = await trees.segmentRuns.get(refs.segmentRuns, pending.runId);
574
+ const segment = serialValue === undefined ? undefined
575
+ : requireSegmentFact(await trees.segments.get(refs.segments, serialKey(requireSerial(serialValue))));
576
+ if (segment === undefined || segment.captureId !== pending.captureId
577
+ || segment.protocolVersion !== pending.protocolVersion
578
+ || segment.status !== 'capturing' || segment.disposition !== 'pending') {
579
+ throw new FlexHarnessStoreFormatError('Snapshot pending capture does not match exactly one segment.');
580
+ }
581
+ captureOwnerRunId = pending.runId;
582
+ } else if (pending.kind === 'apply') {
583
+ assertOnlyKeys(pending, [
584
+ 'kind', 'operationId', 'direction', 'fromCursor', 'toCursor',
585
+ 'segmentRunIds', 'appliedRunIds', 'protocolVersion',
586
+ ], '$snapshot.pendingReversion');
587
+ if (typeof pending.operationId !== 'string' || !pending.operationId
588
+ || (pending.direction !== 'undo' && pending.direction !== 'redo')) {
589
+ throw new FlexHarnessStoreFormatError('Snapshot pending apply identity is invalid.');
590
+ }
591
+ const fromCursor = requireNonNegativeInteger(pending.fromCursor, '$snapshot.pendingReversion.fromCursor');
592
+ const toCursor = requireNonNegativeInteger(pending.toCursor, '$snapshot.pendingReversion.toCursor');
593
+ const pendingRuns = requireStringArray(pending.segmentRunIds, '$snapshot.pendingReversion.segmentRunIds');
594
+ const appliedRuns = requireStringArray(pending.appliedRunIds, '$snapshot.pendingReversion.appliedRunIds');
595
+ assertPendingApplyRunIds(pendingRuns, appliedRuns);
596
+ if (fromCursor !== revertCursor
597
+ || (pending.direction === 'undo' && !(toCursor >= 0 && toCursor < fromCursor))
598
+ || (pending.direction === 'redo' && !(toCursor > fromCursor && toCursor <= completedCount))) {
599
+ throw new FlexHarnessStoreFormatError('Snapshot pending apply cursor movement is invalid.');
600
+ }
601
+ const rangeStart = Math.min(fromCursor, toCursor);
602
+ const rangeEnd = Math.max(fromCursor, toCursor);
603
+ const first = await trees.segments.selectCompleted(refs.segments, rangeStart);
604
+ if (!first) throw new FlexHarnessStoreFormatError('Snapshot pending apply has no target candidate.');
605
+ const start = rangeStart === 0 ? 0 : await trees.segments.rank(refs.segments, first.key);
606
+ const next = await trees.segments.selectCompleted(refs.segments, rangeEnd);
607
+ const end = next ? await trees.segments.rank(refs.segments, next.key) : segmentCount;
608
+ if (start === undefined || end === undefined) {
609
+ throw new FlexHarnessStoreFormatError('Snapshot pending apply candidate index is invalid.');
610
+ }
611
+ const exactRuns = (await trees.segments.range(refs.segments, start, end))
612
+ .map((entry) => requireSegmentFact(entry.value).runId);
613
+ assertPendingApplyRunUnit(pendingRuns, appliedRuns, exactRuns, pending.direction);
614
+ } else {
615
+ throw new FlexHarnessStoreFormatError('Snapshot pendingReversion kind is invalid.');
616
+ }
617
+ }
618
+ const capturingCount = await trees.segments.capturing(refs.segments);
619
+ if (capturingCount > (captureOwnerRunId === undefined ? 0 : 1)) {
620
+ throw new FlexHarnessStoreFormatError('Snapshot contains a capture-backed capturing segment without exact pending ownership.');
621
+ }
622
+
623
+ const releases = change.pendingReversionReleases;
624
+ if (!Array.isArray(releases)) {
625
+ throw new FlexHarnessStoreFormatError('Snapshot pendingReversionReleases must be an array.');
626
+ }
627
+ if (releases.length > FLEX_REVERSION_MAXIMUM_LIMITS.maxPendingReversionReleases) {
628
+ throw new FlexHarnessStoreFormatError('Snapshot pending reversion releases exceed their hard limit.');
629
+ }
630
+ const releaseCaptureIds = new Set<string>();
631
+ for (let index = 0; index < releases.length; index++) {
632
+ const path = `$snapshot.pendingReversionReleases[${index}]`;
633
+ const release = releases[index];
634
+ if (!isRecord(release)) throw new FlexHarnessStoreFormatError(`${path} is invalid.`);
635
+ assertOnlyKeys(release, ['runId', 'captureId', 'reference', 'protocolVersion'], path);
636
+ if (typeof release.runId !== 'string' || !release.runId
637
+ || typeof release.captureId !== 'string' || !release.captureId
638
+ || (release.protocolVersion !== 1 && release.protocolVersion !== 2)) {
639
+ throw new FlexHarnessStoreFormatError(`${path} has invalid identity.`);
640
+ }
641
+ if (releaseCaptureIds.has(release.captureId)
642
+ || await trees.captures.get(refs.captures, release.captureId) !== undefined) {
643
+ throw new FlexHarnessStoreFormatError(`${path} has duplicate durable capture ownership.`);
644
+ }
645
+ releaseCaptureIds.add(release.captureId);
646
+ if (!Object.hasOwn(release, 'reference')) {
647
+ throw new FlexHarnessStoreFormatError(`${path}.reference is required.`);
648
+ }
649
+ if (Buffer.byteLength(JSON.stringify(release.reference)) > FLEX_REVERSION_REFERENCE_MAX_BYTES) {
650
+ throw new FlexHarnessStoreFormatError(`${path}.reference exceeds its byte limit.`);
651
+ }
652
+ }
653
+ }
654
+
655
+ /** Validates a change from an authenticated prior index and returns immutable nodes for one CAS publication. */
656
+ export async function validateProjectionChangeWithIndex(
657
+ rootHash: string | undefined,
658
+ reader: IFlexProjectionIndexReader,
659
+ change: IFlexProjectionChange,
660
+ expectedRevision: number,
661
+ sessionId: string,
662
+ ): Promise<IFlexProjectionIndexChangeResult> {
663
+ const validated = validateProjectionChangeSave(change, expectedRevision);
664
+ const old = rootHash === undefined
665
+ ? { kind: 'flex-projection-validation-root-v1', sessionId, revision: 0,
666
+ projectionSchemaVersion: 0, nextMessageSerial: 0, nextSegmentSerial: 0, refs: {} } as const
667
+ : await readRoot(reader, rootHash, expectedRevision, sessionId);
668
+ if (old.revision !== expectedRevision) {
669
+ throw new FlexHarnessStoreFormatError('Projection validation index revision does not match the expected revision.');
670
+ }
671
+ const trees = new IndexTrees(reader);
672
+ const refs: { -readonly [K in keyof IRootRefs]?: string } = { ...old.refs };
673
+ const affectedRuns = new Set<string>();
674
+ const nextMessageSerial = await applyMessageEntries(
675
+ trees, refs, validated.messages, sessionId, old.nextMessageSerial, affectedRuns,
676
+ );
677
+ await applyStagedTerminals(trees, refs, validated.stagedTerminals, sessionId, affectedRuns);
678
+ const nextSegmentSerial = await applySegmentEntries(
679
+ trees, refs, validated.reversionSegments, old.nextSegmentSerial, affectedRuns,
680
+ );
681
+ await validateAffectedSegments(trees, refs, affectedRuns);
682
+ await validatePendingAndReleases(trees, refs, validated);
683
+ const result = finish({
684
+ kind: 'flex-projection-validation-root-v1',
685
+ sessionId,
686
+ revision: validated.revision,
687
+ projectionSchemaVersion: 3,
688
+ nextMessageSerial,
689
+ nextSegmentSerial,
690
+ refs,
691
+ }, trees);
692
+ return deepFreeze({ ...result, change: validated });
693
+ }