@modelprofile.com/flexharness 18.9.0 → 18.10.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 (35) hide show
  1. package/dist_ts/00_commitinfo_data.js +2 -2
  2. package/dist_ts/classes.flexharness.core.d.ts +15 -3
  3. package/dist_ts/classes.flexharness.core.js +211 -18
  4. package/dist_ts/classes.flexharness.d.ts +3 -1
  5. package/dist_ts/classes.flexharness.js +5 -1
  6. package/dist_ts/classes.flexharness.lifecycle.js +4 -1
  7. package/dist_ts/classes.flexharness.reversions.d.ts +2 -1
  8. package/dist_ts/classes.flexharness.reversions.js +15 -75
  9. package/dist_ts/classes.flexharness.sessions.js +9 -6
  10. package/dist_ts/classes.recoverygate.d.ts +1 -0
  11. package/dist_ts/classes.recoverygate.js +4 -1
  12. package/dist_ts/index.d.ts +1 -0
  13. package/dist_ts/index.js +2 -1
  14. package/dist_ts/interfaces.d.ts +20 -0
  15. package/dist_ts/interfaces.js +1 -1
  16. package/dist_ts/utils.reversionpresentation.d.ts +12 -0
  17. package/dist_ts/utils.reversionpresentation.js +219 -0
  18. package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +76 -4
  19. package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +1 -1
  20. package/dist_ts_stores_nosqldb/classes.recordstore.js +1 -1
  21. package/package.json +3 -3
  22. package/readme.md +5 -1
  23. package/ts/00_commitinfo_data.ts +1 -1
  24. package/ts/classes.flexharness.core.ts +239 -36
  25. package/ts/classes.flexharness.lifecycle.ts +3 -0
  26. package/ts/classes.flexharness.reversions.ts +19 -69
  27. package/ts/classes.flexharness.sessions.ts +6 -5
  28. package/ts/classes.flexharness.ts +10 -0
  29. package/ts/classes.recoverygate.ts +4 -0
  30. package/ts/index.ts +4 -0
  31. package/ts/interfaces.ts +32 -0
  32. package/ts/readme.md +5 -1
  33. package/ts/utils.reversionpresentation.ts +227 -0
  34. package/ts_stores_nosqldb/classes.nosqldbstores.ts +101 -2
  35. package/ts_stores_nosqldb/classes.recordstore.ts +1 -0
package/ts/readme.md CHANGED
@@ -699,6 +699,8 @@ await harness.reconcileToolExecution(scopeId, sessionId, intentId, {
699
699
  });
700
700
  const reversion = await harness.getSessionReversionInfo(scopeId, sessionId);
701
701
  console.log(reversion.undoAvailable, reversion.redoAvailable, reversion.groups);
702
+ const reversionPresentation = await harness.getSessionReversionPresentation(scopeId, sessionId);
703
+ console.log(reversionPresentation.affectedWorkspaces, reversionPresentation.barrierCauses);
702
704
  const undone = await harness.undoSession(scopeId, sessionId);
703
705
  console.log(undone.revertedRunId);
704
706
  const redone = await harness.redoSession(scopeId, sessionId);
@@ -746,7 +748,7 @@ The reservation save is the admission point. A save failure produces no start ev
746
748
 
747
749
  The default `sessionLoading: 'eager'` preserves existing store behavior. Opt into `sessionLoading: 'session-local'` to load a complete metadata catalogue and hydrate only the session a request uses. Concurrent requests, including scope aliases of one storage key, join that session's hydration and repair. Creating an empty session reads none of the unrelated sessions' projections, permissions, events or jobs. `listSessions()` deliberately requests every session's repaired metadata; use `getScopeCatalogue()` or `listSessionIdentities()` for metadata-only enumeration.
748
750
 
749
- Clean recovery admission is a separate rollout. The default `recoveryFrontier: 'compatibility'` fully recovers schema-2 sessions on restart. To enable bounded clean reads, set `recoveryFrontier: { mode: 'clean-read' }` with `sessionLoading: 'session-local'`, a versioned recovery sidecar, and bounded projection and provider-level Agent-event heads. Use `storageKeys: ['exact-storage-key']` to enable selected namespaces; an empty list is rejected. Scope aliases share one storage key and therefore one setting. A valid clean proof whose head has changed is durably marked dirty before full hydration and repair; absent or unrooted heads take that same recovery path, and malformed evidence fails closed.
751
+ Clean recovery admission is a separate rollout. The default `recoveryFrontier: 'compatibility'` clears settled schema-1 obligations after the session's producers drain. With schema 2 it marks inherited clean entries dirty, recovers them once per runtime, and retains their durable marks for the next cold restart. To enable bounded clean reads, set `recoveryFrontier: { mode: 'clean-read' }` with `sessionLoading: 'session-local'`, a versioned recovery sidecar, and bounded projection and provider-level Agent-event heads. Use `storageKeys: ['exact-storage-key']` to enable selected namespaces; an empty list is rejected. Scope aliases share one storage key and therefore one setting. A valid clean proof whose head has changed is durably marked dirty before full hydration and repair; absent or unrooted heads take that same recovery path, and malformed evidence fails closed.
750
752
 
751
753
  ```typescript
752
754
  const harness = new FlexHarness({
@@ -1057,6 +1059,8 @@ for (const group of info.groups) {
1057
1059
 
1058
1060
  The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. `barrierCauses` states why a barrier blocks traversal, each cause once in this order: `pending` while a capture runs or its outcome is not final, `nonrevertible` for a workspace outcome that cannot be reverted, `transcript-only` for legacy transcript history without a workspace capture; it is empty for candidate and no-change groups (`FLEX_SESSION_REVERSION_BARRIER_CAUSES` lists the order). `reasonCodes` lists the distinct `reasonCode`s of the group's nonrevertible segments in segment order, so an application can say why a turn is not revertible even when its provider named no affected workspace. It never includes capture IDs or provider references.
1059
1061
 
1062
+ `getSessionReversionPresentation(scopeId, sessionId, signal?)` returns one immutable bounded union for a Git reversion strip without per-turn groups or undo/redo availability. It keeps the first 64 distinct affected workspaces and first 64 distinct nonrevertible reason codes in historical group order, with separate `affectedWorkspacesTruncated` and `reasonCodesTruncated` flags. `barrierCauses` uses the same policy and fixed order as the full group view. A settled clean session can serve this view and `getSessionMetrics()` from one optional auxiliary summary bound to the exact rooted projection head and policy flag; the guarded read also checks the clean sidecar and Agent-event head through completion. Missing or stale summaries hydrate only that session, repair it, and backfill the current summary. Custom stores without the summary capability retain the same hydrated results. The NoSQL store keeps one summary slot per session and policy, separate from the projection head, so older readers' strict head schema is unchanged.
1063
+
1060
1064
  `workspaceSnapshots` is application-owned. Every context contains `scopeId`, `scope`, `storageKey`, `sessionId`, the required canonical `sessionGenerationId` and `sessionGenerationSequence`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, per-segment `operationId`, and `direction`; release contexts contain the reference. Deleted-session recovery retains the same generation from the durable tombstone, so providers can reject callbacks from an older same-ID generation.
1061
1065
 
1062
1066
  The protocol is durable and inspectable:
@@ -0,0 +1,227 @@
1
+ import {
2
+ FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
3
+ FLEX_REVERSION_REASON_CODE_MAX_BYTES,
4
+ FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
5
+ FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
6
+ FLEX_SESSION_REVERSION_BARRIER_CAUSES,
7
+ type IFlexAffectedWorkspace,
8
+ type IFlexReversionSegment,
9
+ type IFlexSessionAuxiliarySummary,
10
+ type IFlexSessionMetricsState,
11
+ type IFlexSessionReversionGroup,
12
+ type IFlexSessionReversionPresentation,
13
+ type TFlexReversionPolicy,
14
+ type TFlexSessionReversionBarrierCause,
15
+ } from './interfaces.js';
16
+ import type { IReversionGroup } from './interfaces.flexharness.js';
17
+ import { FlexHarnessStoreFormatError } from './errors.js';
18
+ import { assertSessionMetrics, canonicalJson, cloneSerializable } from './utils.json.js';
19
+ import { sessionMetricsView } from './utils.sessionmetrics.js';
20
+
21
+ /** The aggregate has fixed limits regardless of the number of turns in a session. */
22
+ export const FLEX_REVERSION_PRESENTATION_MAX_REASON_CODES = 64;
23
+ export const FLEX_REVERSION_PRESENTATION_MAX_BYTES = 256 * 1024;
24
+ export const FLEX_SESSION_AUXILIARY_SUMMARY_MAX_BYTES = FLEX_REVERSION_PRESENTATION_MAX_BYTES + 4096;
25
+
26
+ export function assertFlexSessionAuxiliarySummary(value: unknown): IFlexSessionAuxiliarySummary {
27
+ const invalid = () => new FlexHarnessStoreFormatError('Invalid session auxiliary summary.');
28
+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalid();
29
+ const record = value as Record<string, unknown>;
30
+ if (JSON.stringify(Object.keys(record).sort()) !== JSON.stringify([
31
+ 'reversionPresentation', 'sessionMetrics',
32
+ ])) throw invalid();
33
+ assertFlexSessionReversionPresentation(record.reversionPresentation);
34
+ if (!record.sessionMetrics || typeof record.sessionMetrics !== 'object'
35
+ || Array.isArray(record.sessionMetrics)) throw invalid();
36
+ const metrics = record.sessionMetrics as Record<string, unknown>;
37
+ if (metrics.inFlight !== false) throw invalid();
38
+ const metricsState = { ...metrics };
39
+ delete metricsState.inFlight;
40
+ delete metricsState.lifetimeUsedTokens;
41
+ delete metricsState.lastObservedInputTokensFreshness;
42
+ assertSessionMetrics(metricsState);
43
+ if (canonicalJson(sessionMetricsView(metricsState as unknown as IFlexSessionMetricsState))
44
+ !== canonicalJson(metrics)) throw invalid();
45
+ if (Buffer.byteLength(JSON.stringify(value), 'utf8') > FLEX_SESSION_AUXILIARY_SUMMARY_MAX_BYTES) {
46
+ throw invalid();
47
+ }
48
+ return value as IFlexSessionAuxiliarySummary;
49
+ }
50
+
51
+ /** Checks an untrusted stored summary without opening its source projection. */
52
+ export function assertFlexSessionReversionPresentation(value: unknown): IFlexSessionReversionPresentation {
53
+ const invalid = () => new FlexHarnessStoreFormatError('Invalid session reversion presentation.');
54
+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalid();
55
+ const record = value as Record<string, unknown>;
56
+ const keys = Object.keys(record).sort();
57
+ if (JSON.stringify(keys) !== JSON.stringify([
58
+ 'affectedWorkspaces', 'affectedWorkspacesTruncated', 'barrierCauses',
59
+ 'reasonCodes', 'reasonCodesTruncated',
60
+ ])) throw invalid();
61
+ if (!Array.isArray(record.affectedWorkspaces)
62
+ || record.affectedWorkspaces.length > FLEX_REVERSION_MAX_AFFECTED_WORKSPACES
63
+ || !Array.isArray(record.barrierCauses)
64
+ || !Array.isArray(record.reasonCodes)
65
+ || record.reasonCodes.length > FLEX_REVERSION_PRESENTATION_MAX_REASON_CODES
66
+ || typeof record.affectedWorkspacesTruncated !== 'boolean'
67
+ || typeof record.reasonCodesTruncated !== 'boolean') throw invalid();
68
+ const workspaceIds = new Set<string>();
69
+ for (const workspace of record.affectedWorkspaces) {
70
+ if (!workspace || typeof workspace !== 'object' || Array.isArray(workspace)) throw invalid();
71
+ if (JSON.stringify(Object.keys(workspace).sort()) !== JSON.stringify(['id', 'label'])) throw invalid();
72
+ if (typeof workspace.id !== 'string' || !workspace.id.trim()
73
+ || typeof workspace.label !== 'string' || !workspace.label.trim()
74
+ || Buffer.byteLength(workspace.id, 'utf8') > FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES
75
+ || Buffer.byteLength(workspace.label, 'utf8') > FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES
76
+ || workspaceIds.has(workspace.id)) throw invalid();
77
+ workspaceIds.add(workspace.id);
78
+ }
79
+ const barrierCauses = record.barrierCauses;
80
+ if (JSON.stringify(barrierCauses) !== JSON.stringify(
81
+ FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => barrierCauses.includes(cause)),
82
+ )) throw invalid();
83
+ const reasonCodes = new Set<string>();
84
+ for (const reason of record.reasonCodes) {
85
+ if (typeof reason !== 'string'
86
+ || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(reason)
87
+ || Buffer.byteLength(reason, 'utf8') > FLEX_REVERSION_REASON_CODE_MAX_BYTES
88
+ || reasonCodes.has(reason)) throw invalid();
89
+ reasonCodes.add(reason);
90
+ }
91
+ if ((record.affectedWorkspacesTruncated && workspaceIds.size !== FLEX_REVERSION_MAX_AFFECTED_WORKSPACES)
92
+ || (record.reasonCodesTruncated && reasonCodes.size !== FLEX_REVERSION_PRESENTATION_MAX_REASON_CODES)) {
93
+ throw invalid();
94
+ }
95
+ if (Buffer.byteLength(JSON.stringify(value), 'utf8') > FLEX_REVERSION_PRESENTATION_MAX_BYTES) {
96
+ throw invalid();
97
+ }
98
+ return value as IFlexSessionReversionPresentation;
99
+ }
100
+
101
+ export function deriveReversionGroups(
102
+ reversionSegments: readonly IFlexReversionSegment[],
103
+ reversionPolicy: TFlexReversionPolicy,
104
+ ): IReversionGroup[] {
105
+ const groups: IReversionGroup[] = [];
106
+ let leading: IFlexReversionSegment[] = [];
107
+ for (const segment of reversionSegments) {
108
+ if (segment.status === 'completed') {
109
+ const segments = groups.length === 0 ? [...leading, segment] : [segment];
110
+ leading = [];
111
+ groups.push({
112
+ target: segment,
113
+ segments,
114
+ kind: 'candidate',
115
+ affectedWorkspaces: [],
116
+ affectedWorkspacesTruncated: false,
117
+ barrierCauses: [],
118
+ reasonCodes: [],
119
+ });
120
+ } else if (groups.length > 0) {
121
+ groups[groups.length - 1].segments.push(segment);
122
+ } else {
123
+ leading.push(segment);
124
+ }
125
+ }
126
+ for (const group of groups) {
127
+ const affected = new Map<string, IFlexAffectedWorkspace>();
128
+ for (const workspace of group.segments.flatMap((segment) =>
129
+ segment.affectedWorkspaces ?? [])) {
130
+ if (affected.has(workspace.id)) continue;
131
+ if (affected.size < FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
132
+ affected.set(workspace.id, cloneSerializable(workspace));
133
+ } else {
134
+ group.affectedWorkspacesTruncated = true;
135
+ }
136
+ }
137
+ group.affectedWorkspaces = [...affected.values()];
138
+ group.reasonCodes = [...new Set(group.segments.flatMap((segment) => (
139
+ segment.disposition === 'nonrevertible' && segment.reasonCode !== undefined
140
+ ? [segment.reasonCode]
141
+ : []
142
+ )))];
143
+ if (reversionPolicy === 'transcript-optional') continue;
144
+ const causes = new Set<TFlexSessionReversionBarrierCause>();
145
+ for (const segment of group.segments) {
146
+ if (segment.status === 'capturing' || segment.disposition === 'pending') causes.add('pending');
147
+ if (segment.disposition === 'nonrevertible') causes.add('nonrevertible');
148
+ if (segment.protocolVersion === 1 && segment.provenance === 'transcript') {
149
+ causes.add('transcript-only');
150
+ }
151
+ }
152
+ if (causes.size > 0) {
153
+ group.kind = 'barrier';
154
+ group.barrierCauses = FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => causes.has(cause));
155
+ } else if (group.segments.some((segment) => segment.disposition === 'revertible')) {
156
+ group.kind = 'candidate';
157
+ } else {
158
+ group.kind = 'no-change';
159
+ }
160
+ }
161
+ return groups;
162
+ }
163
+
164
+ export function presentReversionGroups(
165
+ groups: readonly IReversionGroup[],
166
+ revertCursor: number,
167
+ ): IFlexSessionReversionGroup[] {
168
+ return groups.map((group, index): IFlexSessionReversionGroup => ({
169
+ runId: group.target.runId,
170
+ kind: group.kind,
171
+ visibility: index < revertCursor ? 'visible' : 'hidden',
172
+ affectedWorkspaces: cloneSerializable(group.affectedWorkspaces),
173
+ affectedWorkspacesTruncated: group.affectedWorkspacesTruncated,
174
+ barrierCauses: [...group.barrierCauses],
175
+ reasonCodes: [...group.reasonCodes],
176
+ }));
177
+ }
178
+
179
+ export function deriveReversionPresentation(
180
+ reversionSegments: readonly IFlexReversionSegment[],
181
+ reversionPolicy: TFlexReversionPolicy,
182
+ ): IFlexSessionReversionPresentation | undefined {
183
+ const affectedWorkspaces = new Map<string, IFlexAffectedWorkspace>();
184
+ const reasonCodes = new Set<string>();
185
+ const causes = new Set<TFlexSessionReversionBarrierCause>();
186
+ let affectedWorkspacesTruncated = false;
187
+ let reasonCodesTruncated = false;
188
+ for (const group of deriveReversionGroups(reversionSegments, reversionPolicy)) {
189
+ for (const segment of group.segments) {
190
+ for (const workspace of segment.affectedWorkspaces ?? []) {
191
+ if (
192
+ Buffer.byteLength(workspace.id, 'utf8') > FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES
193
+ || Buffer.byteLength(workspace.label, 'utf8') > FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES
194
+ ) return undefined;
195
+ if (affectedWorkspaces.has(workspace.id)) continue;
196
+ if (affectedWorkspaces.size >= FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
197
+ affectedWorkspacesTruncated = true;
198
+ } else {
199
+ affectedWorkspaces.set(workspace.id, cloneSerializable(workspace));
200
+ }
201
+ }
202
+ }
203
+ for (const cause of group.barrierCauses) causes.add(cause);
204
+ for (const reasonCode of group.reasonCodes) {
205
+ if (Buffer.byteLength(reasonCode, 'utf8') > FLEX_REVERSION_REASON_CODE_MAX_BYTES) {
206
+ return undefined;
207
+ }
208
+ if (reasonCodes.has(reasonCode)) continue;
209
+ if (reasonCodes.size >= FLEX_REVERSION_PRESENTATION_MAX_REASON_CODES) {
210
+ reasonCodesTruncated = true;
211
+ } else {
212
+ reasonCodes.add(reasonCode);
213
+ }
214
+ }
215
+ }
216
+ const presentation: IFlexSessionReversionPresentation = {
217
+ affectedWorkspaces: [...affectedWorkspaces.values()],
218
+ affectedWorkspacesTruncated,
219
+ barrierCauses: FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => causes.has(cause)),
220
+ reasonCodes: [...reasonCodes],
221
+ reasonCodesTruncated,
222
+ };
223
+ if (Buffer.byteLength(JSON.stringify(presentation), 'utf8') > FLEX_REVERSION_PRESENTATION_MAX_BYTES) {
224
+ return undefined;
225
+ }
226
+ return presentation;
227
+ }
@@ -4,7 +4,7 @@ import {
4
4
  RecoverableFlexScopeStore,
5
5
  validateFlexScopeRecoverySave,
6
6
  } from '../ts/classes.scoperecovery.js';
7
- import { FlexHarnessStoreConflictError, FlexHarnessValidationError } from '../ts/errors.js';
7
+ import { FlexHarnessStoreConflictError, FlexHarnessStoreFormatError, FlexHarnessValidationError } from '../ts/errors.js';
8
8
  import type {
9
9
  IFlexAgentEventStoreProvider,
10
10
  IFlexHarnessStores,
@@ -15,7 +15,9 @@ import type {
15
15
  IFlexProjectManagementTombstone,
16
16
  IFlexProjectManagementWriteContext,
17
17
  IFlexProjectionChange,
18
+ IFlexProjectionHead,
18
19
  IFlexProjectionStore,
20
+ IFlexSessionAuxiliarySummary,
19
21
  IFlexResultStore,
20
22
  TFlexScopeRecoverySnapshot,
21
23
  IFlexScopeRecoveryStoreV2,
@@ -31,6 +33,7 @@ import {
31
33
  assertFlexProjectionSnapshot,
32
34
  assertFlexScopeSnapshot,
33
35
  assertJsonSerializable,
36
+ canonicalJson,
34
37
  } from '../ts/utils.json.js';
35
38
  import {
36
39
  assertFlexProjectManagementRecord,
@@ -42,6 +45,7 @@ import {
42
45
  assertFlexProjectionChange,
43
46
  validateProjectionChangeSave,
44
47
  } from '../ts/utils.projectionchange.js';
48
+ import { assertFlexSessionAuxiliarySummary } from '../ts/utils.reversionpresentation.js';
45
49
  import {
46
50
  assertFlexToolJobSnapshot,
47
51
  createChangedAgentEventSnapshot,
@@ -171,10 +175,105 @@ class NoSqlScopeRecoveryStore implements IFlexScopeRecoveryStoreV2 {
171
175
  }
172
176
  }
173
177
 
178
+ interface ISessionAuxiliarySummarySlot {
179
+ revision: number;
180
+ projection: IFlexProjectionHead;
181
+ summary: IFlexSessionAuxiliarySummary;
182
+ }
183
+
174
184
  /** A projection is a log record: a save writes its change, checked in form. */
175
185
  class NoSqlProjectionStore implements IFlexProjectionStore {
176
186
  constructor(private readonly records: FlexRecordStore) {}
177
187
 
188
+ private auxiliarySummaryAddress(
189
+ storageKey: string,
190
+ sessionId: string,
191
+ workspaceRequired: boolean,
192
+ ) {
193
+ return {
194
+ domain: 'sessionAuxiliarySummary' as const,
195
+ storageKey,
196
+ sessionId,
197
+ entryId: workspaceRequired ? 'workspace-required' : 'transcript-optional',
198
+ };
199
+ }
200
+
201
+ private assertAuxiliarySummarySlot(value: unknown): ISessionAuxiliarySummarySlot {
202
+ const invalid = () => new FlexHarnessStoreFormatError('Invalid auxiliary summary slot.');
203
+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalid();
204
+ const slot = value as Record<string, unknown>;
205
+ if (JSON.stringify(Object.keys(slot).sort()) !== JSON.stringify(['projection', 'revision', 'summary'])
206
+ || !Number.isSafeInteger(slot.revision) || Number(slot.revision) < 1
207
+ || !slot.projection || typeof slot.projection !== 'object' || Array.isArray(slot.projection)) {
208
+ throw invalid();
209
+ }
210
+ const projection = slot.projection as Record<string, unknown>;
211
+ if (JSON.stringify(Object.keys(projection).sort())
212
+ !== JSON.stringify(['contentRoot', 'incarnationId', 'revision'])
213
+ || typeof projection.incarnationId !== 'string' || !projection.incarnationId
214
+ || typeof projection.contentRoot !== 'string' || !/^[a-f0-9]{64}$/u.test(projection.contentRoot)
215
+ || !Number.isSafeInteger(projection.revision) || Number(projection.revision) < 1) throw invalid();
216
+ assertFlexSessionAuxiliarySummary(slot.summary);
217
+ return value as ISessionAuxiliarySummarySlot;
218
+ }
219
+
220
+ private matchesProjection(left: IFlexProjectionHead, right: IFlexProjectionHead): boolean {
221
+ return left.incarnationId === right.incarnationId
222
+ && left.revision === right.revision
223
+ && left.contentRoot === right.contentRoot;
224
+ }
225
+
226
+ public async loadAuxiliarySummaryHead(
227
+ storageKey: string,
228
+ sessionId: string,
229
+ workspaceRequired: boolean,
230
+ ): Promise<{ projection: IFlexProjectionHead; summary: IFlexSessionAuxiliarySummary } | undefined> {
231
+ providerKey(storageKey, sessionId);
232
+ const projection = await this.loadHead(storageKey, sessionId);
233
+ if (!projection?.incarnationId) return undefined;
234
+ const slot = await this.records.read(
235
+ this.auxiliarySummaryAddress(storageKey, sessionId, workspaceRequired),
236
+ (value) => this.assertAuxiliarySummarySlot(value),
237
+ );
238
+ return slot && this.matchesProjection(slot.projection, projection)
239
+ ? { projection: slot.projection, summary: slot.summary }
240
+ : undefined;
241
+ }
242
+
243
+ public async saveAuxiliarySummaryHead(
244
+ storageKey: string,
245
+ sessionId: string,
246
+ expectedProjection: IFlexProjectionHead,
247
+ workspaceRequired: boolean,
248
+ summary: IFlexSessionAuxiliarySummary,
249
+ ): Promise<void> {
250
+ providerKey(storageKey, sessionId);
251
+ const address = this.auxiliarySummaryAddress(storageKey, sessionId, workspaceRequired);
252
+ if (!expectedProjection.incarnationId || !/^[a-f0-9]{64}$/u.test(expectedProjection.contentRoot)
253
+ || !Number.isSafeInteger(expectedProjection.revision) || expectedProjection.revision < 1) {
254
+ throw new FlexHarnessValidationError('A session auxiliary summary requires a rooted projection head.');
255
+ }
256
+ const validated = assertFlexSessionAuxiliarySummary(summary);
257
+ await this.records.mutate(address, {
258
+ validate: (value) => this.assertAuxiliarySummarySlot(value),
259
+ decide: (current) => {
260
+ if (current) {
261
+ if (this.matchesProjection(current.projection, expectedProjection)) {
262
+ if (canonicalJson(current.summary) !== canonicalJson(validated)) {
263
+ throw new FlexHarnessStoreFormatError('Conflicting auxiliary summary for one projection head.');
264
+ }
265
+ return undefined;
266
+ }
267
+ if (current.projection.incarnationId === expectedProjection.incarnationId
268
+ && current.projection.revision > expectedProjection.revision) return undefined;
269
+ }
270
+ const revision = (current?.revision ?? 0) + 1;
271
+ return { revision, value: { revision, projection: expectedProjection, summary: validated } };
272
+ },
273
+ contention: () => new FlexHarnessStoreFormatError('Contended auxiliary summary record.'),
274
+ });
275
+ }
276
+
178
277
  private log(sessionId: string): IFlexRecordLog<TFlexProjectionSnapshot, IFlexProjectionChange> {
179
278
  return {
180
279
  validate: (value) => {
@@ -217,7 +316,7 @@ class NoSqlProjectionStore implements IFlexProjectionStore {
217
316
 
218
317
  public deleteSession(storageKey: string, sessionId: string): Promise<void> {
219
318
  providerKey(storageKey, sessionId);
220
- return this.records.deleteOwner(storageKey, sessionId, ['projection']);
319
+ return this.records.deleteOwner(storageKey, sessionId, ['projection', 'sessionAuxiliarySummary']);
221
320
  }
222
321
  }
223
322
 
@@ -10,6 +10,7 @@ export type TFlexRecordDomain =
10
10
  | 'scope'
11
11
  | 'scopeRecovery'
12
12
  | 'projection'
13
+ | 'sessionAuxiliarySummary'
13
14
  | 'permission'
14
15
  | 'projectManagement'
15
16
  | 'agentEvents'