@modelprofile.com/flexharness 18.7.0 → 18.8.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.
@@ -6,15 +6,21 @@ import {
6
6
  FlexHarnessValidationError,
7
7
  } from './errors.js';
8
8
  import type {
9
+ IFlexSession,
10
+ IFlexSessionRecoveryCleanState,
11
+ TFlexSessionRecoveryState,
9
12
  IFlexScopeRecoverySnapshot,
10
13
  IFlexScopeRecoveryStore,
14
+ IFlexScopeRecoveryStoreV2,
11
15
  IFlexScopeSnapshot,
12
16
  IFlexScopeStore,
13
17
  IFlexSessionLocalScopeStore,
18
+ TFlexScopeRecoverySnapshot,
14
19
  } from './interfaces.js';
15
20
  import {
16
21
  assertFlexScopeSnapshot,
17
22
  assertJsonSerializable,
23
+ canonicalJson,
18
24
  cloneSerializable,
19
25
  } from './utils.json.js';
20
26
  import { assertExactKeys, assertRecord } from './utils.storecodecs.js';
@@ -34,35 +40,100 @@ function assertRecoverySessionIds(value: unknown): asserts value is string[] {
34
40
  }
35
41
  }
36
42
 
37
- /** Strict sidecar validation shared by recovery-store adapters; scope snapshots stay schema 1. */
38
- export function assertFlexScopeRecoverySnapshot(
43
+ const isDigest = (value: unknown): value is string =>
44
+ typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
45
+
46
+ function assertRecoveryHead(value: unknown, path: string): void {
47
+ assertRecord(value, path);
48
+ assertExactKeys(value, ['incarnationId', 'revision', 'contentRoot'], path);
49
+ if (typeof value.incarnationId !== 'string' || !value.incarnationId.trim()
50
+ || !Number.isSafeInteger(value.revision) || Number(value.revision) < 1
51
+ || !isDigest(value.contentRoot)) {
52
+ throw new FlexHarnessStoreFormatError(`${path} must identify one rooted log incarnation and revision.`);
53
+ }
54
+ }
55
+
56
+ function assertSessionRecoveryState(value: unknown, path: string): asserts value is TFlexSessionRecoveryState {
57
+ assertRecord(value, path);
58
+ if (typeof value.sessionId !== 'string' || !value.sessionId.trim()) {
59
+ throw new FlexHarnessStoreFormatError(`${path}.sessionId must be a non-empty string.`);
60
+ }
61
+ if (value.state === 'dirty') {
62
+ assertExactKeys(value, ['sessionId', 'state'], path);
63
+ return;
64
+ }
65
+ if (value.state !== 'clean') {
66
+ throw new FlexHarnessStoreFormatError(`${path}.state must be dirty or clean.`);
67
+ }
68
+ assertExactKeys(value, [
69
+ 'sessionId', 'state', 'sessionGenerationId', 'sessionGenerationSequence',
70
+ 'sessionDigest', 'projection', 'agentEvents',
71
+ ], path);
72
+ if (typeof value.sessionGenerationId !== 'string' || !value.sessionGenerationId.trim()
73
+ || !Number.isSafeInteger(value.sessionGenerationSequence)
74
+ || Number(value.sessionGenerationSequence) < 1
75
+ || !isDigest(value.sessionDigest)) {
76
+ throw new FlexHarnessStoreFormatError(`${path} must bind an exact session generation and digest.`);
77
+ }
78
+ assertRecoveryHead(value.projection, `${path}.projection`);
79
+ assertRecoveryHead(value.agentEvents, `${path}.agentEvents`);
80
+ }
81
+
82
+ /** Strict validation for the explicit versioned sidecar capability. */
83
+ export function assertFlexScopeRecoverySnapshotVersioned(
39
84
  value: unknown,
40
- ): asserts value is IFlexScopeRecoverySnapshot {
85
+ ): asserts value is TFlexScopeRecoverySnapshot {
41
86
  assertJsonSerializable(value, '$scopeRecovery');
42
87
  assertRecord(value, '$scopeRecovery');
43
- assertExactKeys(value, [
44
- 'schemaVersion', 'revision', 'catalogueRevision', 'catalogueDigest', 'recoverySessionIds',
45
- ], '$scopeRecovery');
46
- if (value.schemaVersion !== 1) {
47
- throw new FlexHarnessStoreFormatError('Scope recovery schemaVersion must be 1.');
88
+ if (value.schemaVersion === 1) {
89
+ assertExactKeys(value, [
90
+ 'schemaVersion', 'revision', 'catalogueRevision', 'catalogueDigest', 'recoverySessionIds',
91
+ ], '$scopeRecovery');
92
+ assertRecoverySessionIds(value.recoverySessionIds);
93
+ } else if (value.schemaVersion === 2) {
94
+ assertExactKeys(value, [
95
+ 'schemaVersion', 'revision', 'catalogueRevision', 'catalogueDigest', 'sessionStates',
96
+ ], '$scopeRecovery');
97
+ if (!Array.isArray(value.sessionStates)) {
98
+ throw new FlexHarnessStoreFormatError('Scope recovery sessionStates must be an array.');
99
+ }
100
+ let previous = '';
101
+ for (const [index, state] of value.sessionStates.entries()) {
102
+ assertSessionRecoveryState(state, `$scopeRecovery.sessionStates[${index}]`);
103
+ if (state.sessionId <= previous) {
104
+ throw new FlexHarnessStoreFormatError('Scope recovery sessionStates must have unique, sorted session ids.');
105
+ }
106
+ previous = state.sessionId;
107
+ }
108
+ } else {
109
+ throw new FlexHarnessStoreFormatError('Scope recovery schemaVersion must be 1 or 2.');
48
110
  }
49
111
  for (const key of ['revision', 'catalogueRevision'] as const) {
50
112
  if (!Number.isSafeInteger(value[key]) || Number(value[key]) < 0) {
51
113
  throw new FlexHarnessStoreFormatError(`Scope recovery ${key} must be a non-negative safe integer.`);
52
114
  }
53
115
  }
54
- if (typeof value.catalogueDigest !== 'string' || !/^[a-f0-9]{64}$/.test(value.catalogueDigest)) {
116
+ if (!isDigest(value.catalogueDigest)) {
55
117
  throw new FlexHarnessStoreFormatError('Scope recovery catalogueDigest must be a lowercase SHA-256 digest.');
56
118
  }
57
- assertRecoverySessionIds(value.recoverySessionIds);
119
+ }
120
+
121
+ /** Strict schema-1 validation for the original recovery-store contract. */
122
+ export function assertFlexScopeRecoverySnapshot(
123
+ value: unknown,
124
+ ): asserts value is IFlexScopeRecoverySnapshot {
125
+ assertFlexScopeRecoverySnapshotVersioned(value);
126
+ if (value.schemaVersion !== 1) {
127
+ throw new FlexHarnessStoreFormatError('Scope recovery schemaVersion must be 1.');
128
+ }
58
129
  }
59
130
 
60
131
  /** Checks the sidecar CAS admission rule and copies the caller-owned value before a backend awaits. */
61
- export function validateFlexScopeRecoverySave(
62
- snapshot: IFlexScopeRecoverySnapshot,
132
+ export function validateFlexScopeRecoverySave<TSnapshot extends TFlexScopeRecoverySnapshot>(
133
+ snapshot: TSnapshot,
63
134
  expectedRevision: number,
64
- ): IFlexScopeRecoverySnapshot {
65
- assertFlexScopeRecoverySnapshot(snapshot);
135
+ ): TSnapshot {
136
+ assertFlexScopeRecoverySnapshotVersioned(snapshot);
66
137
  validateExpectedRevision(expectedRevision);
67
138
  if (snapshot.revision !== expectedRevision + 1) {
68
139
  throw new FlexHarnessStoreFormatError(
@@ -72,6 +143,30 @@ export function validateFlexScopeRecoverySave(
72
143
  return cloneSerializable(snapshot);
73
144
  }
74
145
 
146
+ /** SHA-256 of one canonical IFlexSession, independent of object-key insertion order. */
147
+ export function flexSessionDigest(session: IFlexSession): string {
148
+ const json = canonicalJson(session);
149
+ if (json === undefined) throw new FlexHarnessStoreFormatError('Session metadata is not canonical JSON.');
150
+ return plugins.crypto.createHash('sha256').update(json).digest('hex');
151
+ }
152
+
153
+ function recoveryStates(recovery: TFlexScopeRecoverySnapshot | undefined): TFlexSessionRecoveryState[] {
154
+ return recovery?.schemaVersion === 2
155
+ ? cloneSerializable(recovery.sessionStates)
156
+ : (recovery?.recoverySessionIds ?? []).map((sessionId) => ({ sessionId, state: 'dirty' as const }));
157
+ }
158
+
159
+ function sortedStates(states: TFlexSessionRecoveryState[]): TFlexSessionRecoveryState[] {
160
+ return states.sort((left, right) => left.sessionId < right.sessionId ? -1 : left.sessionId > right.sessionId ? 1 : 0);
161
+ }
162
+
163
+ function cleanMatchesSession(clean: IFlexSessionRecoveryCleanState, session: IFlexSession | undefined): boolean {
164
+ return session !== undefined
165
+ && clean.sessionGenerationId === session.sessionGenerationId
166
+ && clean.sessionGenerationSequence === session.sessionGenerationSequence
167
+ && clean.sessionDigest === flexSessionDigest(session);
168
+ }
169
+
75
170
  function canonicalCatalogueJson(value: unknown): string {
76
171
  if (Array.isArray(value)) return `[${value.map(canonicalCatalogueJson).join(',')}]`;
77
172
  if (value !== null && typeof value === 'object') {
@@ -97,10 +192,16 @@ function catalogueDigest(snapshot: IFlexScopeSnapshot | undefined): string {
97
192
 
98
193
  interface IRecoveryEvidence {
99
194
  snapshot: IFlexScopeSnapshot | undefined;
100
- recovery: IFlexScopeRecoverySnapshot | undefined;
195
+ recovery: TFlexScopeRecoverySnapshot | undefined;
101
196
  qualified: boolean;
102
197
  }
103
198
 
199
+ function isVersionedRecoveryStore(
200
+ store: IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2,
201
+ ): store is IFlexScopeRecoveryStoreV2 {
202
+ return 'recoverySchemaVersion' in store && store.recoverySchemaVersion === 2;
203
+ }
204
+
104
205
  /**
105
206
  * Adds session-local recovery to any durable scope CAS store without changing its snapshots.
106
207
  *
@@ -117,7 +218,7 @@ interface IRecoveryEvidence {
117
218
  * a failure in that gap is CommitUncertain and never implicitly qualifies the resulting catalogue.
118
219
  */
119
220
  export class RecoverableFlexScopeStore implements IFlexScopeStore {
120
- private static readonly lanes = new WeakMap<IFlexScopeRecoveryStore, Map<string, Promise<void>>>();
221
+ private static readonly lanes = new WeakMap<IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2, Map<string, Promise<void>>>();
121
222
 
122
223
  public readonly sessionLocal: IFlexSessionLocalScopeStore = {
123
224
  releaseOwnership: (storageKey) => this.recoveryStore.deactivateWriteProvenance(storageKey),
@@ -132,7 +233,7 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
132
233
 
133
234
  constructor(
134
235
  private readonly scopes: IFlexScopeStore,
135
- private readonly recoveryStore: IFlexScopeRecoveryStore,
236
+ private readonly recoveryStore: IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2,
136
237
  ) {}
137
238
 
138
239
  private inLane<T>(storageKey: string, operation: () => Promise<T>): Promise<T> {
@@ -163,21 +264,42 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
163
264
  }
164
265
 
165
266
  private async readEvidence(storageKey: string): Promise<IRecoveryEvidence> {
166
- const provenance = await this.recoveryStore.loadWriteProvenance(storageKey);
167
- const snapshot = await this.scopes.load(storageKey);
168
- if (snapshot !== undefined) assertFlexScopeSnapshot(snapshot);
169
- const recovery = await this.recoveryStore.load(storageKey);
170
- if (recovery !== undefined) assertFlexScopeRecoverySnapshot(recovery);
171
- const qualified = provenance && (recovery === undefined
172
- ? snapshot === undefined
173
- : recovery.catalogueRevision === (snapshot?.revision ?? 0)
174
- && recovery.catalogueDigest === catalogueDigest(snapshot));
175
- if (!qualified) this.recoveryStore.deactivateWriteProvenance(storageKey);
176
- return {
177
- snapshot: snapshot === undefined ? undefined : cloneSerializable(snapshot),
178
- recovery: recovery === undefined ? undefined : cloneSerializable(recovery),
179
- qualified,
180
- };
267
+ try {
268
+ const provenance = await this.recoveryStore.loadWriteProvenance(storageKey);
269
+ const snapshot = await this.scopes.load(storageKey);
270
+ if (snapshot !== undefined) assertFlexScopeSnapshot(snapshot);
271
+ let recovery = await this.recoveryStore.load(storageKey);
272
+ if (recovery !== undefined) {
273
+ assertFlexScopeRecoverySnapshotVersioned(recovery);
274
+ if (recovery.schemaVersion === 2 && !isVersionedRecoveryStore(this.recoveryStore)) {
275
+ throw new FlexHarnessStoreFormatError('A schema-2 sidecar requires a versioned recovery store.');
276
+ }
277
+ if (recovery.schemaVersion === 2 && recovery.sessionStates.some((entry) => entry.state === 'clean')) {
278
+ // This compatibility writer cannot mark every producer before its effect. Retire every
279
+ // inherited clean claim before a session-local scope can admit work after a rollback.
280
+ const demoted: TFlexScopeRecoverySnapshot = {
281
+ ...recovery,
282
+ revision: recovery.revision + 1,
283
+ sessionStates: recovery.sessionStates.map((entry) => ({ sessionId: entry.sessionId, state: 'dirty' })),
284
+ };
285
+ await this.saveRecovery(storageKey, demoted, recovery.revision);
286
+ recovery = demoted;
287
+ }
288
+ }
289
+ const qualified = provenance && (recovery === undefined
290
+ ? snapshot === undefined
291
+ : recovery.catalogueRevision === (snapshot?.revision ?? 0)
292
+ && recovery.catalogueDigest === catalogueDigest(snapshot));
293
+ if (!qualified) this.recoveryStore.deactivateWriteProvenance(storageKey);
294
+ return {
295
+ snapshot: snapshot === undefined ? undefined : cloneSerializable(snapshot),
296
+ recovery: recovery === undefined ? undefined : cloneSerializable(recovery),
297
+ qualified,
298
+ };
299
+ } catch (error) {
300
+ this.recoveryStore.deactivateWriteProvenance(storageKey);
301
+ throw error;
302
+ }
181
303
  }
182
304
 
183
305
  private loadCatalogue(storageKey: string): ReturnType<IFlexSessionLocalScopeStore['loadCatalogue']> {
@@ -186,7 +308,15 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
186
308
  return {
187
309
  snapshot: evidence.snapshot,
188
310
  qualified: evidence.qualified,
189
- recoverySessionIds: evidence.recovery?.recoverySessionIds ?? [],
311
+ // readEvidence has retired schema-2 clean claims. Until the complete producer gate is
312
+ // activated, every session in that sidecar takes normal recovery.
313
+ recoverySessionIds: evidence.recovery?.schemaVersion === 2
314
+ ? [...new Set([
315
+ ...(evidence.snapshot?.sessions.map((session) => session.sessionId) ?? []),
316
+ ...(evidence.snapshot?.tombstones.map((tombstone) => tombstone.sessionId) ?? []),
317
+ ...evidence.recovery.sessionStates.map((entry) => entry.sessionId),
318
+ ])].sort()
319
+ : evidence.recovery?.recoverySessionIds ?? [],
190
320
  };
191
321
  });
192
322
  }
@@ -199,20 +329,37 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
199
329
  }
200
330
  }
201
331
 
332
+ private saveRecovery(
333
+ storageKey: string,
334
+ snapshot: TFlexScopeRecoverySnapshot,
335
+ expectedRevision: number,
336
+ ): Promise<void> {
337
+ if (isVersionedRecoveryStore(this.recoveryStore)) {
338
+ return this.recoveryStore.save(storageKey, snapshot, expectedRevision);
339
+ }
340
+ if (snapshot.schemaVersion !== 1) {
341
+ throw new FlexHarnessStoreFormatError('A schema-2 sidecar requires a versioned recovery store.');
342
+ }
343
+ return this.recoveryStore.save(storageKey, snapshot, expectedRevision);
344
+ }
345
+
202
346
  private saveProof(
203
347
  storageKey: string,
204
348
  snapshot: IFlexScopeSnapshot | undefined,
205
- recovery: IFlexScopeRecoverySnapshot | undefined,
206
- recoverySessionIds: string[],
349
+ recovery: TFlexScopeRecoverySnapshot | undefined,
350
+ states: TFlexSessionRecoveryState[],
207
351
  ): Promise<void> {
208
352
  const expectedRevision = recovery?.revision ?? 0;
209
- return this.recoveryStore.save(storageKey, {
210
- schemaVersion: 1,
353
+ const common = {
211
354
  revision: expectedRevision + 1,
212
355
  catalogueRevision: snapshot?.revision ?? 0,
213
356
  catalogueDigest: catalogueDigest(snapshot),
214
- recoverySessionIds,
215
- }, expectedRevision);
357
+ };
358
+ return this.saveRecovery(storageKey, recovery?.schemaVersion === 2
359
+ ? { schemaVersion: 2, ...common, sessionStates: sortedStates(states) }
360
+ : { schemaVersion: 1, ...common,
361
+ recoverySessionIds: sortedStates(states).filter((entry) => entry.state === 'dirty')
362
+ .map((entry) => entry.sessionId) }, expectedRevision);
216
363
  }
217
364
 
218
365
  private async saveCatalogue(
@@ -226,8 +373,13 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
226
373
  this.assertQualified(storageKey, evidence);
227
374
  await this.scopes.save(storageKey, validated, expectedRevision);
228
375
  try {
376
+ const sessions = new Map(validated.sessions.map((session) => [session.sessionId, session]));
377
+ const states = recoveryStates(evidence.recovery).map((entry): TFlexSessionRecoveryState =>
378
+ entry.state === 'clean' && !cleanMatchesSession(entry, sessions.get(entry.sessionId))
379
+ ? { sessionId: entry.sessionId, state: 'dirty' }
380
+ : entry);
229
381
  await this.saveProof(
230
- storageKey, validated, evidence.recovery, evidence.recovery?.recoverySessionIds ?? [],
382
+ storageKey, validated, evidence.recovery, states,
231
383
  );
232
384
  } catch (cause) {
233
385
  throw new FlexHarnessStoreCommitUncertainError(storageKey, 'write', { cause });
@@ -243,22 +395,32 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
243
395
  return this.inLane(storageKey, async () => {
244
396
  const evidence = await this.readEvidence(storageKey);
245
397
  if (!required) this.assertQualified(storageKey, evidence);
246
- const ids = evidence.recovery?.recoverySessionIds ?? [];
247
- if (ids.includes(sessionId) === required) return;
248
- const recoverySessionIds = required ? [...ids, sessionId] : ids.filter((id) => id !== sessionId);
398
+ if (!required && evidence.recovery?.schemaVersion === 2
399
+ && evidence.snapshot?.sessions.some((session) => session.sessionId === sessionId)) {
400
+ throw new FlexHarnessValidationError('A live schema-2 session requires an exact clean publication.');
401
+ }
402
+ const states = recoveryStates(evidence.recovery);
403
+ const current = states.find((entry) => entry.sessionId === sessionId);
404
+ if (required && current?.state === 'dirty') return;
405
+ if (!required && current === undefined) return;
406
+ const next = states.filter((entry) => entry.sessionId !== sessionId);
407
+ if (required) next.push({ sessionId, state: 'dirty' });
249
408
  if (evidence.qualified) {
250
- await this.saveProof(storageKey, evidence.snapshot, evidence.recovery, recoverySessionIds);
409
+ await this.saveProof(storageKey, evidence.snapshot, evidence.recovery, next);
251
410
  } else {
252
411
  // Adding an obligation is safe without qualification, but it must not create a proof of
253
412
  // the unqualified snapshot. An absent proof remains the proof of an absent catalogue.
254
413
  const expectedRevision = evidence.recovery?.revision ?? 0;
255
- await this.recoveryStore.save(storageKey, {
256
- schemaVersion: 1,
414
+ const common = {
257
415
  revision: expectedRevision + 1,
258
416
  catalogueRevision: evidence.recovery?.catalogueRevision ?? 0,
259
417
  catalogueDigest: evidence.recovery?.catalogueDigest ?? catalogueDigest(undefined),
260
- recoverySessionIds,
261
- }, expectedRevision);
418
+ };
419
+ await this.saveRecovery(storageKey, evidence.recovery?.schemaVersion === 2
420
+ ? { schemaVersion: 2, ...common, sessionStates: sortedStates(next) }
421
+ : { schemaVersion: 1, ...common,
422
+ recoverySessionIds: sortedStates(next).filter((entry) => entry.state === 'dirty')
423
+ .map((entry) => entry.sessionId) }, expectedRevision);
262
424
  }
263
425
  });
264
426
  }
@@ -281,7 +443,16 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
281
443
  // Publish the proof inactive: a crash/failure before witness qualification cannot bless it.
282
444
  this.recoveryStore.deactivateWriteProvenance(storageKey);
283
445
  try {
284
- await this.saveProof(storageKey, validated, evidence.recovery, ids);
446
+ const previous = recoveryStates(evidence.recovery);
447
+ const sessions = new Map(validated.sessions.map((session) => [session.sessionId, session]));
448
+ const states: TFlexSessionRecoveryState[] = ids.map((sessionId) => ({ sessionId, state: 'dirty' }));
449
+ if (evidence.recovery?.schemaVersion === 2) {
450
+ for (const entry of previous) {
451
+ if (entry.state === 'clean' && !ids.includes(entry.sessionId)
452
+ && cleanMatchesSession(entry, sessions.get(entry.sessionId))) states.push(entry);
453
+ }
454
+ }
455
+ await this.saveProof(storageKey, validated, evidence.recovery, states);
285
456
  await this.recoveryStore.qualifyWriteProvenance(storageKey);
286
457
  } catch (cause) {
287
458
  throw new FlexHarnessStoreCommitUncertainError(storageKey, 'write', { cause });
package/ts/interfaces.ts CHANGED
@@ -1726,6 +1726,45 @@ export interface IFlexScopeRecoverySnapshot {
1726
1726
  recoverySessionIds: string[];
1727
1727
  }
1728
1728
 
1729
+ /** An unresolved session. A clean publication must replace this state through an exact CAS. */
1730
+ export interface IFlexSessionRecoveryDirtyState {
1731
+ sessionId: string;
1732
+ state: 'dirty';
1733
+ }
1734
+
1735
+ /** A bounded commitment to one incarnation of a persistent session log. */
1736
+ export interface IFlexSessionRecoveryHead {
1737
+ incarnationId: string;
1738
+ revision: number;
1739
+ contentRoot: string;
1740
+ }
1741
+
1742
+ /** The exact producer identity and authenticated histories certified by a clean publication. */
1743
+ export interface IFlexSessionRecoveryCleanState {
1744
+ sessionId: string;
1745
+ state: 'clean';
1746
+ sessionGenerationId: string;
1747
+ sessionGenerationSequence: number;
1748
+ sessionDigest: string;
1749
+ projection: IFlexSessionRecoveryHead;
1750
+ agentEvents: IFlexSessionRecoveryHead;
1751
+ }
1752
+
1753
+ export type TFlexSessionRecoveryState =
1754
+ | IFlexSessionRecoveryDirtyState
1755
+ | IFlexSessionRecoveryCleanState;
1756
+
1757
+ /** Additive sidecar schema; strict schema-1 scope snapshots remain unchanged. */
1758
+ export interface IFlexScopeRecoverySnapshotV2 {
1759
+ schemaVersion: 2;
1760
+ revision: number;
1761
+ catalogueRevision: number;
1762
+ catalogueDigest: string;
1763
+ sessionStates: TFlexSessionRecoveryState[];
1764
+ }
1765
+
1766
+ export type TFlexScopeRecoverySnapshot = IFlexScopeRecoverySnapshot | IFlexScopeRecoverySnapshotV2;
1767
+
1729
1768
  /**
1730
1769
  * Additive sidecar persistence for `RecoverableFlexScopeStore`: the recovery proof and the
1731
1770
  * namespace's write provenance. A scope snapshot cannot show that nothing needs recovery: a writer
@@ -1775,6 +1814,13 @@ export interface IFlexScopeRecoveryStore {
1775
1814
  save(storageKey: string, snapshot: IFlexScopeRecoverySnapshot, expectedRevision: number): Promise<void>;
1776
1815
  }
1777
1816
 
1817
+ /** Explicit schema-2 storage capability; schema-1 recovery stores retain their original contract. */
1818
+ export interface IFlexScopeRecoveryStoreV2 extends Omit<IFlexScopeRecoveryStore, 'load' | 'save'> {
1819
+ readonly recoverySchemaVersion: 2;
1820
+ load(storageKey: string): Promise<TFlexScopeRecoverySnapshot | undefined>;
1821
+ save(storageKey: string, snapshot: TFlexScopeRecoverySnapshot, expectedRevision: number): Promise<void>;
1822
+ }
1823
+
1778
1824
  /** Requires exclusive namespace ownership, like the harness itself. */
1779
1825
  export interface IFlexSessionLocalScopeStore {
1780
1826
  /** Releases local writer activation only, not a distributed namespace lock. */
@@ -1829,6 +1875,8 @@ export interface IFlexProjectionStore {
1829
1875
  }
1830
1876
 
1831
1877
  export interface IFlexProjectionHead {
1878
+ /** Present on stores that can prove the log was not deleted and recreated at this revision. */
1879
+ incarnationId?: string;
1832
1880
  revision: number;
1833
1881
  contentRoot: string;
1834
1882
  }
package/ts/readme.md CHANGED
@@ -778,7 +778,9 @@ When the older releases of a host change no such witness, the host cannot detect
778
778
 
779
779
  In-memory and NoSQL stores implement the additive capability. Existing custom stores and `JsonFileFlexHarnessStores` keep their eager behavior; the JSON store creates no new recovery files and cannot opt into session-local loading without a separate capable backend.
780
780
 
781
- The NoSQL projection store's optional `loadHead(storageKey, sessionId)` and Agent event store's optional `loadHead(sessionId)` return `{ revision, contentRoot }` from the record head without reading the base, change pages or event bodies. The SHA-256 root commits to the serialized log base and each ordered change; its stored revision and write-token binding advance in the same compare-and-swap as the head. A missing record, legacy unrooted log or head whose revision or write token an older writer advanced without renewing the root returns `undefined`; its next save validates and rewrites the complete log before it can supply a root. Malformed commitment fields fail closed. A full load verifies a current root against the stored base and changes. These heads are content commitments for a future recovery frontier; by themselves they do not make a catalogue session safe for a cold `getSession()` read. Other stores do not advertise bounded heads.
781
+ The NoSQL projection store's optional `loadHead(storageKey, sessionId)` and Agent event store's optional `loadHead(sessionId)` return `{ incarnationId, revision, contentRoot }` from the record head without reading the base, change pages or event bodies. The SHA-256 root commits to the serialized log base and each ordered change; its stored revision and write-token binding advance in the same compare-and-swap as the head. A missing record, legacy unrooted log or head whose revision or write token an older writer advanced without renewing the root returns `undefined`; its next save validates and rewrites the complete log before it can supply a root. Malformed commitment fields fail closed. A full load verifies a current root against the stored base and changes. These heads are content commitments for a future recovery frontier; by themselves they do not make a catalogue session safe for a cold `getSession()` read. Other stores do not advertise bounded heads.
782
+
783
+ The existing `IFlexScopeRecoveryStore` contract remains schema 1. A store that can read schema-2 sidecars explicitly implements `IFlexScopeRecoveryStoreV2`; the built-in NoSQL store does. `RecoverableFlexScopeStore` accepts either contract. New sidecars start at schema 1, and no production path promotes them to schema 2. On a session-local open, this compatibility version durably turns every inherited schema-2 clean state dirty before returning the catalogue; a failed sidecar write refuses the open. The sidecar stays schema 2, and cold loading performs normal recovery.
782
784
 
783
785
  ### Continuing Without New Input
784
786
 
@@ -1,6 +1,6 @@
1
1
  import * as plugins from './plugins.js';
2
2
  import {
3
- assertFlexScopeRecoverySnapshot,
3
+ assertFlexScopeRecoverySnapshotVersioned,
4
4
  RecoverableFlexScopeStore,
5
5
  validateFlexScopeRecoverySave,
6
6
  } from '../ts/classes.scoperecovery.js';
@@ -17,8 +17,8 @@ import type {
17
17
  IFlexProjectionChange,
18
18
  IFlexProjectionStore,
19
19
  IFlexResultStore,
20
- IFlexScopeRecoverySnapshot,
21
- IFlexScopeRecoveryStore,
20
+ TFlexScopeRecoverySnapshot,
21
+ IFlexScopeRecoveryStoreV2,
22
22
  IFlexScopeSnapshot,
23
23
  IFlexScopeStore,
24
24
  IFlexToolJobStoreProvider,
@@ -129,7 +129,8 @@ class NoSqlScopeStore implements IFlexScopeStore {
129
129
  }
130
130
  }
131
131
 
132
- class NoSqlScopeRecoveryStore implements IFlexScopeRecoveryStore {
132
+ class NoSqlScopeRecoveryStore implements IFlexScopeRecoveryStoreV2 {
133
+ public readonly recoverySchemaVersion = 2;
133
134
  constructor(private readonly records: FlexRecordStore) {}
134
135
 
135
136
  public deactivateWriteProvenance(storageKey: string): void {
@@ -146,17 +147,17 @@ class NoSqlScopeRecoveryStore implements IFlexScopeRecoveryStore {
146
147
  return this.records.qualifyWriteProvenance(storageKey);
147
148
  }
148
149
 
149
- public load(storageKey: string): Promise<IFlexScopeRecoverySnapshot | undefined> {
150
+ public load(storageKey: string): Promise<TFlexScopeRecoverySnapshot | undefined> {
150
151
  validateIdentifier(storageKey, 'storageKey');
151
152
  return this.records.read({ domain: 'scopeRecovery', storageKey }, (value) => {
152
- assertFlexScopeRecoverySnapshot(value);
153
+ assertFlexScopeRecoverySnapshotVersioned(value);
153
154
  return value;
154
155
  });
155
156
  }
156
157
 
157
158
  public async save(
158
159
  storageKey: string,
159
- snapshot: IFlexScopeRecoverySnapshot,
160
+ snapshot: TFlexScopeRecoverySnapshot,
160
161
  expectedRevision: number,
161
162
  ): Promise<void> {
162
163
  validateIdentifier(storageKey, 'storageKey');
@@ -324,6 +324,7 @@ interface IStoredLog<TSnapshot> {
324
324
 
325
325
  /** A content commitment read from one bounded log head, without its base or change pages. */
326
326
  export interface IFlexRecordLogHead {
327
+ incarnationId: string;
327
328
  revision: number;
328
329
  contentRoot: string;
329
330
  }
@@ -573,7 +574,11 @@ export class FlexRecordStore {
573
574
  > FLEX_RECORD_INLINE_CHANGE_CODE_UNITS) {
574
575
  throw new FlexHarnessStoreFormatError(`Invalid content commitment at ${resolved.path}.`);
575
576
  }
576
- return root === undefined ? undefined : { revision: head.revision, contentRoot: root };
577
+ return root === undefined ? undefined : {
578
+ incarnationId: head.logId,
579
+ revision: head.revision,
580
+ contentRoot: root,
581
+ };
577
582
  });
578
583
  }
579
584
 
@@ -27,6 +27,8 @@ Scope snapshots retain exactly schema 1's `{ schemaVersion, revision, sessions,
27
27
 
28
28
  Qualification publishes its proof while inactive, then explicitly qualifies the namespace witness. A failure between those steps remains unqualified. Disposal, retirement and eager activation release local known-writer activation, including when a bundle is reused. Neither those hooks nor cross-process CAS replace the host's exclusive namespace lifecycle ownership. All namespace header access uses the public document-model APIs of `@lossless.org/client/nosqldb`.
29
29
 
30
+ On a session-local open, the compatibility harness converts every inherited schema-2 clean state to dirty in one sidecar CAS before it can hydrate a session or admit work. A failed CAS refuses the open. The schema-2 format and session IDs remain intact, so a later version must recover those sessions even if this version wrote only a projection or Agent event after the open.
31
+
30
32
  Engine qualification follows the store's client, `@lossless.org/client` ^1.17.0, which qualifies NoSQLDB 8.0.2 and 10.7.2; the store's tests run on NoSQLDB 10.x (10.11.0). NoSQLDB 11 is not qualified: on 11.1.2, two connections that create the same new collection at the same time can fail `prepare()` with `Created collection is not observable.` (one connection is told the collection exists while another still lists it as absent), and a fenced purge racing record creations can leave a record behind.
31
33
 
32
34
  The database is the application's. The stores never close it, and they need NoSQLDB or a MongoDB deployment with transactions. `prepare()` creates or verifies the `flexharness_records`, `flexharness_chunks`, `flexharness_changes` and `flexharness_namespaces` collections and their indexes; every store operation awaits the same preparation, so calling it at startup only moves that work and its failure forward. `operationTimeoutMs` (1 to 120000, default 30000) bounds every database call and transaction.
@@ -56,7 +58,7 @@ All writes in one namespace now contend on its namespace document, not only crea
56
58
 
57
59
  A projection and an Agent event history are each stored as a base plus the changes saved since. FlexHarness saves a projection as an `IFlexProjectionChange` and an Agent event history as an `IAgentEventChange`, which carry only the entries that changed, and the store appends the change to the record's head in the compare-and-swap that commits it, so a save reads and writes the head alone and costs the change rather than the whole session. The head holds the latest changes up to 16 Ki characters of JSON; the save that would exceed that first writes them, with its own change, as one page in `flexharness_changes`, and empties them in its swap. The base lives in chunks whatever its length, so the head each change swaps holds no payload; a session's first save creates the record together with a base of up to one chunk in one transaction. The changes are kept while together they stay no longer than the base, or than 64 Ki characters of JSON while the base is shorter, and no single change is longer than one chunk. The save that would exceed that compacts the record instead: it reads the record, applies the change, checks the resulting snapshot in full and writes it as the new base. The earlier base and its pages are removed like unreferenced chunks, by the record's next compaction, which finds those pages by their log instead of scanning the current one. A record therefore holds its base and changes no longer than it or that minimum, plus the earlier base and its pages until the next compaction. A session whose history shrank, after an undo branch for example, keeps its larger base until its changes outgrow it. A read applies every change to the base and checks the result in full, so it costs the base and every change since, and a record whose pages are incomplete fails with `FlexHarnessStoreFormatError`. A page a crashed writer left behind without swapping the head onto it is removed with the rest of its log, or by the record's deletion.
58
60
 
59
- The projection store and each Agent event store also expose `loadHead`, an optional bounded read of `{ revision, contentRoot }`. A rooted log's head commits to its serialized base and ordered changes; each append advances that SHA-256 root and binds it to the new revision and write token in the head CAS. A full read verifies a current root. Missing and older unrooted logs return no head. An older writer that advances a rooted head but preserves fields it does not know leaves a well-formed stale binding: `loadHead` returns no root, and the next save validates and rewrites the whole log. Malformed commitment fields fail closed. This commitment does not certify a repaired session or replace recovery evidence.
61
+ The projection store and each Agent event store also expose `loadHead`, an optional bounded read of `{ incarnationId, revision, contentRoot }`. `incarnationId` identifies the log record so a deleted and recreated log cannot match an earlier head at the same revision. A rooted log's head commits to its serialized base and ordered changes; each append advances that SHA-256 root and binds it to the new revision and write token in the head CAS. A full read verifies a current root. Missing and older unrooted logs return no head. An older writer that advances a rooted head but preserves fields it does not know leaves a well-formed stale binding: `loadHead` returns no root, and the next save validates and rewrites the whole log. Malformed commitment fields fail closed. This commitment does not certify a repaired session or replace recovery evidence.
60
62
 
61
63
  A save of a scope, permission or job snapshot checks its expected revision against the record's head alone: it never reads the stored snapshot or its chunks, which it replaces whole. A projection or Agent event change checks it against the head in the same way and checks only its own form; the store reads the record only when it compacts. A record swap that loses to a concurrent writer is decided again against the newer record, up to eight times, with a bounded exponential backoff between attempts; a writer that still loses gets the domain's conflict error.
62
64