@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.
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/classes.scoperecovery.d.ts +9 -4
- package/dist_ts/classes.scoperecovery.js +196 -45
- package/dist_ts/interfaces.d.ts +39 -0
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +4 -3
- package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +1 -0
- package/dist_ts_stores_nosqldb/classes.recordstore.js +6 -2
- package/package.json +3 -3
- package/readme.md +3 -1
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.scoperecovery.ts +220 -49
- package/ts/interfaces.ts +48 -0
- package/ts/readme.md +3 -1
- package/ts_stores_nosqldb/classes.nosqldbstores.ts +8 -7
- package/ts_stores_nosqldb/classes.recordstore.ts +6 -1
- package/ts_stores_nosqldb/readme.md +3 -1
|
@@ -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
|
-
|
|
38
|
-
|
|
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
|
|
85
|
+
): asserts value is TFlexScopeRecoverySnapshot {
|
|
41
86
|
assertJsonSerializable(value, '$scopeRecovery');
|
|
42
87
|
assertRecord(value, '$scopeRecovery');
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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 (
|
|
116
|
+
if (!isDigest(value.catalogueDigest)) {
|
|
55
117
|
throw new FlexHarnessStoreFormatError('Scope recovery catalogueDigest must be a lowercase SHA-256 digest.');
|
|
56
118
|
}
|
|
57
|
-
|
|
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:
|
|
132
|
+
export function validateFlexScopeRecoverySave<TSnapshot extends TFlexScopeRecoverySnapshot>(
|
|
133
|
+
snapshot: TSnapshot,
|
|
63
134
|
expectedRevision: number,
|
|
64
|
-
):
|
|
65
|
-
|
|
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:
|
|
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
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
|
|
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:
|
|
206
|
-
|
|
349
|
+
recovery: TFlexScopeRecoverySnapshot | undefined,
|
|
350
|
+
states: TFlexSessionRecoveryState[],
|
|
207
351
|
): Promise<void> {
|
|
208
352
|
const expectedRevision = recovery?.revision ?? 0;
|
|
209
|
-
|
|
210
|
-
schemaVersion: 1,
|
|
353
|
+
const common = {
|
|
211
354
|
revision: expectedRevision + 1,
|
|
212
355
|
catalogueRevision: snapshot?.revision ?? 0,
|
|
213
356
|
catalogueDigest: catalogueDigest(snapshot),
|
|
214
|
-
|
|
215
|
-
|
|
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,
|
|
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
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
261
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
21
|
-
|
|
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
|
|
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<
|
|
150
|
+
public load(storageKey: string): Promise<TFlexScopeRecoverySnapshot | undefined> {
|
|
150
151
|
validateIdentifier(storageKey, 'storageKey');
|
|
151
152
|
return this.records.read({ domain: 'scopeRecovery', storageKey }, (value) => {
|
|
152
|
-
|
|
153
|
+
assertFlexScopeRecoverySnapshotVersioned(value);
|
|
153
154
|
return value;
|
|
154
155
|
});
|
|
155
156
|
}
|
|
156
157
|
|
|
157
158
|
public async save(
|
|
158
159
|
storageKey: string,
|
|
159
|
-
snapshot:
|
|
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 : {
|
|
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
|
|