@modelprofile.com/flexharness 18.1.0 → 18.3.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.
Files changed (68) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/classes.flexharness.cachewarm.js +3 -3
  3. package/dist_ts/classes.flexharness.callbacks.d.ts +37 -0
  4. package/dist_ts/classes.flexharness.callbacks.js +129 -2
  5. package/dist_ts/classes.flexharness.compaction.js +2 -2
  6. package/dist_ts/classes.flexharness.configurations.js +4 -4
  7. package/dist_ts/classes.flexharness.core.d.ts +39 -4
  8. package/dist_ts/classes.flexharness.core.js +467 -134
  9. package/dist_ts/classes.flexharness.d.ts +4 -0
  10. package/dist_ts/classes.flexharness.deletion.d.ts +13 -0
  11. package/dist_ts/classes.flexharness.deletion.js +132 -48
  12. package/dist_ts/classes.flexharness.imports.js +26 -21
  13. package/dist_ts/classes.flexharness.js +9 -1
  14. package/dist_ts/classes.flexharness.lifecycle.js +9 -3
  15. package/dist_ts/classes.flexharness.projects.js +2 -2
  16. package/dist_ts/classes.flexharness.prompts.js +14 -8
  17. package/dist_ts/classes.flexharness.reversions.js +3 -3
  18. package/dist_ts/classes.flexharness.runs.js +18 -2
  19. package/dist_ts/classes.flexharness.sessions.d.ts +1 -1
  20. package/dist_ts/classes.flexharness.sessions.js +18 -18
  21. package/dist_ts/classes.flexharness.slashcommands.js +3 -3
  22. package/dist_ts/classes.flexharness.subagents.js +37 -16
  23. package/dist_ts/classes.flexharness.tooldispatch.js +3 -3
  24. package/dist_ts/classes.scoperecovery.d.ts +37 -0
  25. package/dist_ts/classes.scoperecovery.js +229 -0
  26. package/dist_ts/classes.stores.d.ts +14 -1
  27. package/dist_ts/classes.stores.js +150 -17
  28. package/dist_ts/index.d.ts +1 -0
  29. package/dist_ts/index.js +2 -1
  30. package/dist_ts/interfaces.d.ts +113 -2
  31. package/dist_ts/interfaces.flexharness.d.ts +41 -5
  32. package/dist_ts/interfaces.js +1 -1
  33. package/dist_ts/utils.harnessoptions.d.ts +2 -0
  34. package/dist_ts/utils.harnessoptions.js +16 -11
  35. package/dist_ts_stores_nosqldb/classes.nosqldbstores.d.ts +3 -2
  36. package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +33 -2
  37. package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +10 -1
  38. package/dist_ts_stores_nosqldb/classes.recordstore.js +75 -7
  39. package/package.json +3 -3
  40. package/readme.md +43 -5
  41. package/ts/00_commitinfo_data.ts +1 -1
  42. package/ts/classes.flexharness.cachewarm.ts +2 -2
  43. package/ts/classes.flexharness.callbacks.ts +142 -1
  44. package/ts/classes.flexharness.compaction.ts +1 -1
  45. package/ts/classes.flexharness.configurations.ts +3 -3
  46. package/ts/classes.flexharness.core.ts +463 -133
  47. package/ts/classes.flexharness.deletion.ts +178 -62
  48. package/ts/classes.flexharness.imports.ts +26 -21
  49. package/ts/classes.flexharness.lifecycle.ts +8 -2
  50. package/ts/classes.flexharness.projects.ts +1 -1
  51. package/ts/classes.flexharness.prompts.ts +11 -7
  52. package/ts/classes.flexharness.reversions.ts +2 -2
  53. package/ts/classes.flexharness.runs.ts +16 -1
  54. package/ts/classes.flexharness.sessions.ts +17 -17
  55. package/ts/classes.flexharness.slashcommands.ts +2 -2
  56. package/ts/classes.flexharness.subagents.ts +40 -15
  57. package/ts/classes.flexharness.tooldispatch.ts +2 -2
  58. package/ts/classes.flexharness.ts +13 -0
  59. package/ts/classes.scoperecovery.ts +291 -0
  60. package/ts/classes.stores.ts +150 -16
  61. package/ts/index.ts +2 -0
  62. package/ts/interfaces.flexharness.ts +44 -4
  63. package/ts/interfaces.ts +124 -2
  64. package/ts/readme.md +43 -5
  65. package/ts/utils.harnessoptions.ts +18 -12
  66. package/ts_stores_nosqldb/classes.nosqldbstores.ts +52 -2
  67. package/ts_stores_nosqldb/classes.recordstore.ts +78 -8
  68. package/ts_stores_nosqldb/readme.md +10 -0
@@ -0,0 +1,291 @@
1
+ import * as plugins from './plugins.js';
2
+ import {
3
+ FlexHarnessStoreCommitUncertainError,
4
+ FlexHarnessStoreConflictError,
5
+ FlexHarnessStoreFormatError,
6
+ FlexHarnessValidationError,
7
+ } from './errors.js';
8
+ import type {
9
+ IFlexScopeRecoverySnapshot,
10
+ IFlexScopeRecoveryStore,
11
+ IFlexScopeSnapshot,
12
+ IFlexScopeStore,
13
+ IFlexSessionLocalScopeStore,
14
+ } from './interfaces.js';
15
+ import {
16
+ assertFlexScopeSnapshot,
17
+ assertJsonSerializable,
18
+ cloneSerializable,
19
+ } from './utils.json.js';
20
+ import { assertExactKeys, assertRecord } from './utils.storecodecs.js';
21
+ import {
22
+ validateExpectedRevision,
23
+ validateIdentifier,
24
+ validateSnapshotSave,
25
+ } from './utils.storerules.js';
26
+
27
+ function assertRecoverySessionIds(value: unknown): asserts value is string[] {
28
+ if (
29
+ !Array.isArray(value)
30
+ || value.some((id) => typeof id !== 'string' || !id.trim())
31
+ || new Set(value).size !== value.length
32
+ ) {
33
+ throw new FlexHarnessStoreFormatError('recoverySessionIds must contain unique non-empty string ids.');
34
+ }
35
+ }
36
+
37
+ /** Strict sidecar validation shared by recovery-store adapters; scope snapshots stay schema 1. */
38
+ export function assertFlexScopeRecoverySnapshot(
39
+ value: unknown,
40
+ ): asserts value is IFlexScopeRecoverySnapshot {
41
+ assertJsonSerializable(value, '$scopeRecovery');
42
+ 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.');
48
+ }
49
+ for (const key of ['revision', 'catalogueRevision'] as const) {
50
+ if (!Number.isSafeInteger(value[key]) || Number(value[key]) < 0) {
51
+ throw new FlexHarnessStoreFormatError(`Scope recovery ${key} must be a non-negative safe integer.`);
52
+ }
53
+ }
54
+ if (typeof value.catalogueDigest !== 'string' || !/^[a-f0-9]{64}$/.test(value.catalogueDigest)) {
55
+ throw new FlexHarnessStoreFormatError('Scope recovery catalogueDigest must be a lowercase SHA-256 digest.');
56
+ }
57
+ assertRecoverySessionIds(value.recoverySessionIds);
58
+ }
59
+
60
+ /** Checks the sidecar CAS admission rule and copies the caller-owned value before a backend awaits. */
61
+ export function validateFlexScopeRecoverySave(
62
+ snapshot: IFlexScopeRecoverySnapshot,
63
+ expectedRevision: number,
64
+ ): IFlexScopeRecoverySnapshot {
65
+ assertFlexScopeRecoverySnapshot(snapshot);
66
+ validateExpectedRevision(expectedRevision);
67
+ if (snapshot.revision !== expectedRevision + 1) {
68
+ throw new FlexHarnessStoreFormatError(
69
+ `Scope recovery revision ${snapshot.revision} must equal expected revision ${expectedRevision} plus one.`,
70
+ );
71
+ }
72
+ return cloneSerializable(snapshot);
73
+ }
74
+
75
+ function canonicalCatalogueJson(value: unknown): string {
76
+ if (Array.isArray(value)) return `[${value.map(canonicalCatalogueJson).join(',')}]`;
77
+ if (value !== null && typeof value === 'object') {
78
+ const fields = value as Record<string, unknown>;
79
+ return `{${Object.keys(fields).sort().map((key) =>
80
+ `${JSON.stringify(key)}:${canonicalCatalogueJson(fields[key])}`,
81
+ ).join(',')}}`;
82
+ }
83
+ const serialized = JSON.stringify(value);
84
+ if (serialized === undefined) {
85
+ throw new FlexHarnessStoreFormatError('Scope catalogue is not canonical JSON.');
86
+ }
87
+ return serialized;
88
+ }
89
+
90
+ function catalogueDigest(snapshot: IFlexScopeSnapshot | undefined): string {
91
+ const canonical = canonicalCatalogueJson({
92
+ catalogueRevision: snapshot?.revision ?? 0,
93
+ snapshot: snapshot ?? null,
94
+ });
95
+ return plugins.crypto.createHash('sha256').update(canonical).digest('hex');
96
+ }
97
+
98
+ interface IRecoveryEvidence {
99
+ snapshot: IFlexScopeSnapshot | undefined;
100
+ recovery: IFlexScopeRecoverySnapshot | undefined;
101
+ qualified: boolean;
102
+ }
103
+
104
+ /**
105
+ * Adds session-local recovery to any durable scope CAS store without changing its snapshots.
106
+ *
107
+ * The host must exclusively own the namespace, including qualification and every legacy writer;
108
+ * there must be no simultaneous legacy writer, even through another wrapper/process. The helper
109
+ * lane serializes this sidecar adapter's operations per storage key, not distributed ownership.
110
+ * Clear an obligation only after the session effects/recovery are conclusively durable; an
111
+ * uncertain session operation must retain its obligation, never attempt a clear.
112
+ * Qualification requires both the snapshot proof and authoritative write provenance of every
113
+ * recovery-bearing domain (project management is not one); a legacy projection/event/job write can
114
+ * invalidate provenance without changing the scope.
115
+ * Normal load/save keep the legacy contract: a legacy save leaves the old proof stale by revision.
116
+ * A catalogue save commits the scope first and its matching proof second, preserving obligations;
117
+ * a failure in that gap is CommitUncertain and never implicitly qualifies the resulting catalogue.
118
+ */
119
+ export class RecoverableFlexScopeStore implements IFlexScopeStore {
120
+ private static readonly lanes = new WeakMap<IFlexScopeRecoveryStore, Map<string, Promise<void>>>();
121
+
122
+ public readonly sessionLocal: IFlexSessionLocalScopeStore = {
123
+ releaseOwnership: (storageKey) => this.recoveryStore.deactivateWriteProvenance(storageKey),
124
+ loadCatalogue: (storageKey) => this.loadCatalogue(storageKey),
125
+ saveCatalogue: (storageKey, snapshot, expectedRevision) =>
126
+ this.saveCatalogue(storageKey, snapshot, expectedRevision),
127
+ setRecoveryRequired: (storageKey, sessionId, required) =>
128
+ this.setRecoveryRequired(storageKey, sessionId, required),
129
+ qualifyCatalogue: (storageKey, snapshot, recoverySessionIds) =>
130
+ this.qualifyCatalogue(storageKey, snapshot, recoverySessionIds),
131
+ };
132
+
133
+ constructor(
134
+ private readonly scopes: IFlexScopeStore,
135
+ private readonly recoveryStore: IFlexScopeRecoveryStore,
136
+ ) {}
137
+
138
+ private inLane<T>(storageKey: string, operation: () => Promise<T>): Promise<T> {
139
+ validateIdentifier(storageKey, 'storageKey');
140
+ let lanes = RecoverableFlexScopeStore.lanes.get(this.recoveryStore);
141
+ if (!lanes) {
142
+ lanes = new Map();
143
+ RecoverableFlexScopeStore.lanes.set(this.recoveryStore, lanes);
144
+ }
145
+ const result = (lanes.get(storageKey) ?? Promise.resolve()).then(operation);
146
+ const barrier = result.then(() => undefined, () => undefined);
147
+ lanes.set(storageKey, barrier);
148
+ void barrier.then(() => {
149
+ if (lanes.get(storageKey) === barrier) lanes.delete(storageKey);
150
+ });
151
+ return result;
152
+ }
153
+
154
+ public load(storageKey: string): Promise<IFlexScopeSnapshot | undefined> {
155
+ return this.scopes.load(storageKey);
156
+ }
157
+
158
+ public save(storageKey: string, snapshot: IFlexScopeSnapshot, expectedRevision: number): Promise<void> {
159
+ return this.inLane(storageKey, () => {
160
+ this.recoveryStore.deactivateWriteProvenance(storageKey);
161
+ return this.scopes.save(storageKey, snapshot, expectedRevision);
162
+ });
163
+ }
164
+
165
+ 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
+ };
181
+ }
182
+
183
+ private loadCatalogue(storageKey: string): ReturnType<IFlexSessionLocalScopeStore['loadCatalogue']> {
184
+ return this.inLane(storageKey, async () => {
185
+ const evidence = await this.readEvidence(storageKey);
186
+ return {
187
+ snapshot: evidence.snapshot,
188
+ qualified: evidence.qualified,
189
+ recoverySessionIds: evidence.recovery?.recoverySessionIds ?? [],
190
+ };
191
+ });
192
+ }
193
+
194
+ private assertQualified(storageKey: string, evidence: IRecoveryEvidence): void {
195
+ if (!evidence.qualified) {
196
+ throw new FlexHarnessStoreFormatError(
197
+ `Scope catalogue "${storageKey}" requires explicit qualification before catalogue writes or recovery clears.`,
198
+ );
199
+ }
200
+ }
201
+
202
+ private saveProof(
203
+ storageKey: string,
204
+ snapshot: IFlexScopeSnapshot | undefined,
205
+ recovery: IFlexScopeRecoverySnapshot | undefined,
206
+ recoverySessionIds: string[],
207
+ ): Promise<void> {
208
+ const expectedRevision = recovery?.revision ?? 0;
209
+ return this.recoveryStore.save(storageKey, {
210
+ schemaVersion: 1,
211
+ revision: expectedRevision + 1,
212
+ catalogueRevision: snapshot?.revision ?? 0,
213
+ catalogueDigest: catalogueDigest(snapshot),
214
+ recoverySessionIds,
215
+ }, expectedRevision);
216
+ }
217
+
218
+ private async saveCatalogue(
219
+ storageKey: string,
220
+ snapshot: IFlexScopeSnapshot,
221
+ expectedRevision: number,
222
+ ): Promise<void> {
223
+ const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexScopeSnapshot);
224
+ return this.inLane(storageKey, async () => {
225
+ const evidence = await this.readEvidence(storageKey);
226
+ this.assertQualified(storageKey, evidence);
227
+ await this.scopes.save(storageKey, validated, expectedRevision);
228
+ try {
229
+ await this.saveProof(
230
+ storageKey, validated, evidence.recovery, evidence.recovery?.recoverySessionIds ?? [],
231
+ );
232
+ } catch (cause) {
233
+ throw new FlexHarnessStoreCommitUncertainError(storageKey, 'write', { cause });
234
+ }
235
+ });
236
+ }
237
+
238
+ private async setRecoveryRequired(storageKey: string, sessionId: string, required: boolean): Promise<void> {
239
+ validateIdentifier(sessionId, 'sessionId');
240
+ if (typeof required !== 'boolean') {
241
+ throw new FlexHarnessValidationError('required must be a boolean.');
242
+ }
243
+ return this.inLane(storageKey, async () => {
244
+ const evidence = await this.readEvidence(storageKey);
245
+ 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);
249
+ if (evidence.qualified) {
250
+ await this.saveProof(storageKey, evidence.snapshot, evidence.recovery, recoverySessionIds);
251
+ } else {
252
+ // Adding an obligation is safe without qualification, but it must not create a proof of
253
+ // the unqualified snapshot. An absent proof remains the proof of an absent catalogue.
254
+ const expectedRevision = evidence.recovery?.revision ?? 0;
255
+ await this.recoveryStore.save(storageKey, {
256
+ schemaVersion: 1,
257
+ revision: expectedRevision + 1,
258
+ catalogueRevision: evidence.recovery?.catalogueRevision ?? 0,
259
+ catalogueDigest: evidence.recovery?.catalogueDigest ?? catalogueDigest(undefined),
260
+ recoverySessionIds,
261
+ }, expectedRevision);
262
+ }
263
+ });
264
+ }
265
+
266
+ private async qualifyCatalogue(
267
+ storageKey: string,
268
+ snapshot: IFlexScopeSnapshot,
269
+ recoverySessionIds: string[],
270
+ ): Promise<void> {
271
+ assertFlexScopeSnapshot(snapshot);
272
+ assertRecoverySessionIds(recoverySessionIds);
273
+ const validated = cloneSerializable(snapshot);
274
+ const ids = [...recoverySessionIds];
275
+ return this.inLane(storageKey, async () => {
276
+ const evidence = await this.readEvidence(storageKey);
277
+ if (evidence.snapshot === undefined || catalogueDigest(evidence.snapshot) !== catalogueDigest(validated)) {
278
+ throw new FlexHarnessStoreConflictError(storageKey, validated.revision, evidence.snapshot?.revision ?? 0);
279
+ }
280
+ // The exclusive owner supplies the complete unresolved set after canonical qualification.
281
+ // Publish the proof inactive: a crash/failure before witness qualification cannot bless it.
282
+ this.recoveryStore.deactivateWriteProvenance(storageKey);
283
+ try {
284
+ await this.saveProof(storageKey, validated, evidence.recovery, ids);
285
+ await this.recoveryStore.qualifyWriteProvenance(storageKey);
286
+ } catch (cause) {
287
+ throw new FlexHarnessStoreCommitUncertainError(storageKey, 'write', { cause });
288
+ }
289
+ });
290
+ }
291
+ }
@@ -1,4 +1,5 @@
1
1
  import * as plugins from './plugins.js';
2
+ import { RecoverableFlexScopeStore, validateFlexScopeRecoverySave } from './classes.scoperecovery.js';
2
3
  import {
3
4
  FlexHarnessStoreCommitUncertainError,
4
5
  FlexHarnessStoreConflictError,
@@ -17,6 +18,8 @@ import type {
17
18
  IFlexProjectionChange,
18
19
  IFlexProjectionStore,
19
20
  IFlexResultStore,
21
+ IFlexScopeRecoverySnapshot,
22
+ IFlexScopeRecoveryStore,
20
23
  IFlexScopeSnapshot,
21
24
  IFlexScopeStore,
22
25
  IFlexToolJobStoreProvider,
@@ -61,7 +64,56 @@ import {
61
64
  validateSnapshotSave,
62
65
  } from './utils.storerules.js';
63
66
 
67
+ interface IInMemoryWriteGeneration {
68
+ generation: number;
69
+ recoveryGeneration: number;
70
+ }
71
+
72
+ class InMemoryWriteProvenance {
73
+ private readonly generations = new Map<string, IInMemoryWriteGeneration>();
74
+ private readonly active = new Set<string>();
75
+
76
+ public deactivate(storageKey: string): void {
77
+ validateIdentifier(storageKey, 'storageKey');
78
+ this.active.delete(storageKey);
79
+ }
80
+
81
+ public load(storageKey: string): boolean {
82
+ validateIdentifier(storageKey, 'storageKey');
83
+ const generation = this.generations.get(storageKey);
84
+ const current = !generation || generation.generation === generation.recoveryGeneration;
85
+ if (current) this.active.add(storageKey);
86
+ else this.active.delete(storageKey);
87
+ return current;
88
+ }
89
+
90
+ public qualify(storageKey: string): void {
91
+ validateIdentifier(storageKey, 'storageKey');
92
+ const generation = this.generations.get(storageKey) ?? { generation: 0, recoveryGeneration: 0 };
93
+ generation.recoveryGeneration = generation.generation;
94
+ this.generations.set(storageKey, generation);
95
+ this.active.add(storageKey);
96
+ }
97
+
98
+ public touch(storageKey: string): void {
99
+ validateIdentifier(storageKey, 'storageKey');
100
+ const generation = this.generations.get(storageKey) ?? { generation: 0, recoveryGeneration: 0 };
101
+ const active = this.active.has(storageKey);
102
+ if (active && generation.generation !== generation.recoveryGeneration) {
103
+ throw new FlexHarnessStoreFormatError('Namespace write provenance requires explicit qualification.');
104
+ }
105
+ if (generation.generation === Number.MAX_SAFE_INTEGER) {
106
+ throw new FlexHarnessStoreFormatError('Namespace write provenance exhausted its safe integer generation.');
107
+ }
108
+ generation.generation++;
109
+ if (active) generation.recoveryGeneration++;
110
+ this.generations.set(storageKey, generation);
111
+ }
112
+ }
113
+
64
114
  class InMemoryScopeStore implements IFlexScopeStore {
115
+ constructor(private readonly writes: InMemoryWriteProvenance) {}
116
+
65
117
  private readonly snapshots = new Map<string, IFlexScopeSnapshot>();
66
118
 
67
119
  public async load(storageKey: string): Promise<IFlexScopeSnapshot | undefined> {
@@ -81,11 +133,53 @@ class InMemoryScopeStore implements IFlexScopeStore {
81
133
  if (actualRevision !== expectedRevision) {
82
134
  throw new FlexHarnessStoreConflictError(storageKey, expectedRevision, actualRevision);
83
135
  }
136
+ this.writes.touch(storageKey);
137
+ this.snapshots.set(storageKey, validated);
138
+ }
139
+ }
140
+
141
+ class InMemoryScopeRecoveryStore implements IFlexScopeRecoveryStore {
142
+ constructor(private readonly writes: InMemoryWriteProvenance) {}
143
+
144
+ public deactivateWriteProvenance(storageKey: string): void {
145
+ this.writes.deactivate(storageKey);
146
+ }
147
+
148
+ public async loadWriteProvenance(storageKey: string): Promise<boolean> {
149
+ return this.writes.load(storageKey);
150
+ }
151
+
152
+ public async qualifyWriteProvenance(storageKey: string): Promise<void> {
153
+ this.writes.qualify(storageKey);
154
+ }
155
+
156
+ private readonly snapshots = new Map<string, IFlexScopeRecoverySnapshot>();
157
+
158
+ public async load(storageKey: string): Promise<IFlexScopeRecoverySnapshot | undefined> {
159
+ validateIdentifier(storageKey, 'storageKey');
160
+ const snapshot = this.snapshots.get(storageKey);
161
+ return snapshot ? cloneSerializable(snapshot) : undefined;
162
+ }
163
+
164
+ public async save(
165
+ storageKey: string,
166
+ snapshot: IFlexScopeRecoverySnapshot,
167
+ expectedRevision: number,
168
+ ): Promise<void> {
169
+ validateIdentifier(storageKey, 'storageKey');
170
+ const validated = validateFlexScopeRecoverySave(snapshot, expectedRevision);
171
+ const actualRevision = this.snapshots.get(storageKey)?.revision ?? 0;
172
+ if (actualRevision !== expectedRevision) {
173
+ throw new FlexHarnessStoreConflictError(storageKey, expectedRevision, actualRevision);
174
+ }
175
+ this.writes.touch(storageKey);
84
176
  this.snapshots.set(storageKey, validated);
85
177
  }
86
178
  }
87
179
 
88
180
  class InMemoryProjectionStore implements IFlexProjectionStore {
181
+ constructor(private readonly writes: InMemoryWriteProvenance) {}
182
+
89
183
  private readonly snapshots = new Map<string, TFlexProjectionSnapshot>();
90
184
 
91
185
  public async load(
@@ -110,15 +204,21 @@ class InMemoryProjectionStore implements IFlexProjectionStore {
110
204
  if (actualRevision !== expectedRevision) {
111
205
  throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
112
206
  }
113
- this.snapshots.set(key, createChangedProjectionSnapshot(current, validated, sessionId));
207
+ const next = createChangedProjectionSnapshot(current, validated, sessionId);
208
+ this.writes.touch(storageKey);
209
+ this.snapshots.set(key, next);
114
210
  }
115
211
 
116
212
  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
117
- this.snapshots.delete(providerKey(storageKey, sessionId));
213
+ const key = providerKey(storageKey, sessionId);
214
+ this.writes.touch(storageKey);
215
+ this.snapshots.delete(key);
118
216
  }
119
217
  }
120
218
 
121
219
  class InMemoryPermissionStore implements IFlexPermissionStore {
220
+ constructor(private readonly writes: InMemoryWriteProvenance) {}
221
+
122
222
  private readonly snapshots = new Map<string, IFlexPermissionSnapshot>();
123
223
 
124
224
  public async load(
@@ -141,15 +241,20 @@ class InMemoryPermissionStore implements IFlexPermissionStore {
141
241
  if (actualRevision !== expectedRevision) {
142
242
  throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
143
243
  }
244
+ this.writes.touch(storageKey);
144
245
  this.snapshots.set(key, validated);
145
246
  }
146
247
 
147
248
  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
148
- this.snapshots.delete(providerKey(storageKey, sessionId));
249
+ const key = providerKey(storageKey, sessionId);
250
+ this.writes.touch(storageKey);
251
+ this.snapshots.delete(key);
149
252
  }
150
253
  }
151
254
 
152
255
  export class InMemoryFlexProjectManagementStore implements IFlexProjectManagementStore {
256
+ constructor(private readonly writes?: InMemoryWriteProvenance) {}
257
+
153
258
  private readonly snapshots = new Map<string, TFlexProjectManagementRecord>();
154
259
 
155
260
  public async load(
@@ -175,6 +280,7 @@ export class InMemoryFlexProjectManagementStore implements IFlexProjectManagemen
175
280
  assertFlexProjectManagementSnapshot,
176
281
  );
177
282
  assertProjectManagementSaveAdmitted(key, this.snapshots.get(key), validated, expectedRevision);
283
+ this.writes?.touch(storageKey);
178
284
  this.snapshots.set(key, validated);
179
285
  }
180
286
 
@@ -193,11 +299,13 @@ export class InMemoryFlexProjectManagementStore implements IFlexProjectManagemen
193
299
  if (!isProjectManagementTombstoneAdmitted(key, this.snapshots.get(key), validated, expectedRevision)) {
194
300
  return;
195
301
  }
302
+ this.writes?.touch(storageKey);
196
303
  this.snapshots.set(key, validated);
197
304
  }
198
305
 
199
306
  public async purgeNamespace(storageKey: string): Promise<void> {
200
307
  validateIdentifier(storageKey, 'storageKey');
308
+ this.writes?.touch(storageKey);
201
309
  for (const key of this.snapshots.keys()) {
202
310
  const [recordStorageKey] = JSON.parse(key) as [string, string];
203
311
  if (recordStorageKey === storageKey) this.snapshots.delete(key);
@@ -209,7 +317,11 @@ class InMemoryAgentEventStore implements plugins.IAgentEventStore {
209
317
  private snapshot: plugins.IAgentEventSnapshot | undefined;
210
318
  private readonly archives = new Map<string, plugins.IAgentEventArchive>();
211
319
 
212
- constructor(private readonly sessionId: string) {}
320
+ constructor(
321
+ private readonly sessionId: string,
322
+ private readonly storageKey: string,
323
+ private readonly writes: InMemoryWriteProvenance,
324
+ ) {}
213
325
 
214
326
  private assertSession(sessionId: string): void {
215
327
  if (sessionId !== this.sessionId) {
@@ -240,6 +352,7 @@ class InMemoryAgentEventStore implements plugins.IAgentEventStore {
240
352
  createChangedAgentEventSnapshot(sessionId, this.snapshot, normalized),
241
353
  sessionId,
242
354
  );
355
+ this.writes.touch(this.storageKey);
243
356
  this.snapshot = snapshot;
244
357
  return snapshot.revision;
245
358
  }
@@ -253,6 +366,7 @@ class InMemoryAgentEventStore implements plugins.IAgentEventStore {
253
366
  assertSameArchiveEvents(existing, validated);
254
367
  return;
255
368
  }
369
+ this.writes.touch(this.storageKey);
256
370
  this.archives.set(archive.archiveId, cloneSerializable(validated));
257
371
  }
258
372
 
@@ -267,19 +381,22 @@ class InMemoryAgentEventStore implements plugins.IAgentEventStore {
267
381
  }
268
382
 
269
383
  public clear(): void {
384
+ this.writes.touch(this.storageKey);
270
385
  this.snapshot = undefined;
271
386
  this.archives.clear();
272
387
  }
273
388
  }
274
389
 
275
390
  class InMemoryAgentEventStoreProvider implements IFlexAgentEventStoreProvider {
391
+ constructor(private readonly writes: InMemoryWriteProvenance) {}
392
+
276
393
  private readonly stores = new Map<string, InMemoryAgentEventStore>();
277
394
 
278
395
  public getStore(storageKey: string, sessionId: string): InMemoryAgentEventStore {
279
396
  const key = providerKey(storageKey, sessionId);
280
397
  let store = this.stores.get(key);
281
398
  if (!store) {
282
- store = new InMemoryAgentEventStore(sessionId);
399
+ store = new InMemoryAgentEventStore(sessionId, storageKey, this.writes);
283
400
  this.stores.set(key, store);
284
401
  }
285
402
  return store;
@@ -295,6 +412,8 @@ class InMemoryAgentEventStoreProvider implements IFlexAgentEventStoreProvider {
295
412
  }
296
413
 
297
414
  class InMemoryToolJobStore implements plugins.IToolJobStore {
415
+ constructor(private readonly writes: InMemoryWriteProvenance, private readonly storageKey: string) {}
416
+
298
417
  private snapshot: plugins.IToolJobSnapshot | undefined;
299
418
 
300
419
  public async load(abortSignal?: AbortSignal): Promise<plugins.IToolJobSnapshot | undefined> {
@@ -314,23 +433,27 @@ class InMemoryToolJobStore implements plugins.IToolJobStore {
314
433
  if (actualRevision !== expectedRevision) {
315
434
  throw new plugins.ToolJobStoreConflictError(expectedRevision, actualRevision);
316
435
  }
436
+ this.writes.touch(this.storageKey);
317
437
  this.snapshot = cloneSerializable(snapshot);
318
438
  return snapshot.revision;
319
439
  }
320
440
 
321
441
  public clear(): void {
442
+ this.writes.touch(this.storageKey);
322
443
  this.snapshot = undefined;
323
444
  }
324
445
  }
325
446
 
326
447
  class InMemoryToolJobStoreProvider implements IFlexToolJobStoreProvider {
448
+ constructor(private readonly writes: InMemoryWriteProvenance) {}
449
+
327
450
  private readonly stores = new Map<string, InMemoryToolJobStore>();
328
451
 
329
452
  public getStore(storageKey: string, sessionId: string): InMemoryToolJobStore {
330
453
  const key = providerKey(storageKey, sessionId);
331
454
  let store = this.stores.get(key);
332
455
  if (!store) {
333
- store = new InMemoryToolJobStore();
456
+ store = new InMemoryToolJobStore(this.writes, storageKey);
334
457
  this.stores.set(key, store);
335
458
  }
336
459
  return store;
@@ -346,6 +469,8 @@ class InMemoryToolJobStoreProvider implements IFlexToolJobStoreProvider {
346
469
  }
347
470
 
348
471
  class InMemoryResultStore implements IFlexResultStore {
472
+ constructor(private readonly writes: InMemoryWriteProvenance) {}
473
+
349
474
  private readonly sessions = new Map<string, Map<string, TJsonValue>>();
350
475
 
351
476
  public async save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void> {
@@ -353,7 +478,9 @@ class InMemoryResultStore implements IFlexResultStore {
353
478
  const key = providerKey(storageKey, sessionId);
354
479
  const results = this.sessions.get(key) ?? new Map<string, TJsonValue>();
355
480
  if (results.has(handle)) throw new FlexHarnessStoreConflictError(`${key}:${handle}`, 0, 1);
356
- results.set(handle, cloneSerializable(value));
481
+ const validated = cloneSerializable(value);
482
+ this.writes.touch(storageKey);
483
+ results.set(handle, validated);
357
484
  this.sessions.set(key, results);
358
485
  }
359
486
 
@@ -367,22 +494,29 @@ class InMemoryResultStore implements IFlexResultStore {
367
494
  }
368
495
 
369
496
  public async delete(storageKey: string, sessionId: string, handle: string): Promise<void> {
370
- this.sessions.get(providerKey(storageKey, sessionId))?.delete(handle);
497
+ const key = providerKey(storageKey, sessionId);
498
+ this.writes.touch(storageKey);
499
+ this.sessions.get(key)?.delete(handle);
371
500
  }
372
501
 
373
502
  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
374
- this.sessions.delete(providerKey(storageKey, sessionId));
503
+ const key = providerKey(storageKey, sessionId);
504
+ this.writes.touch(storageKey);
505
+ this.sessions.delete(key);
375
506
  }
376
507
  }
377
508
 
378
509
  export class InMemoryFlexHarnessStores implements IFlexHarnessStores {
379
- public readonly scopes: IFlexScopeStore = new InMemoryScopeStore();
380
- public readonly projections: IFlexProjectionStore = new InMemoryProjectionStore();
381
- public readonly permissions: IFlexPermissionStore = new InMemoryPermissionStore();
382
- public readonly agentEvents: IFlexAgentEventStoreProvider = new InMemoryAgentEventStoreProvider();
383
- public readonly jobs: IFlexToolJobStoreProvider = new InMemoryToolJobStoreProvider();
384
- public readonly projectManagement = new InMemoryFlexProjectManagementStore();
385
- public readonly results: IFlexResultStore = new InMemoryResultStore();
510
+ private readonly writes = new InMemoryWriteProvenance();
511
+ public readonly scopes = new RecoverableFlexScopeStore(
512
+ new InMemoryScopeStore(this.writes), new InMemoryScopeRecoveryStore(this.writes),
513
+ );
514
+ public readonly projections: IFlexProjectionStore = new InMemoryProjectionStore(this.writes);
515
+ public readonly permissions: IFlexPermissionStore = new InMemoryPermissionStore(this.writes);
516
+ public readonly agentEvents: IFlexAgentEventStoreProvider = new InMemoryAgentEventStoreProvider(this.writes);
517
+ public readonly jobs: IFlexToolJobStoreProvider = new InMemoryToolJobStoreProvider(this.writes);
518
+ public readonly projectManagement = new InMemoryFlexProjectManagementStore(this.writes);
519
+ public readonly results: IFlexResultStore = new InMemoryResultStore(this.writes);
386
520
  }
387
521
 
388
522
  const jsonDomains = [
package/ts/index.ts CHANGED
@@ -40,3 +40,5 @@ export {
40
40
  isValidSlashCommandName,
41
41
  parseSlashCommand,
42
42
  } from './utils.slashcommands.js';
43
+
44
+ export * from './classes.scoperecovery.js';