@modelprofile.com/flexharness 18.0.0 → 18.1.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.flexharness.core.d.ts +58 -2
- package/dist_ts/classes.flexharness.core.js +391 -177
- package/dist_ts/classes.flexharness.d.ts +6 -1
- package/dist_ts/classes.flexharness.js +8 -1
- package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
- package/dist_ts/classes.flexharness.sessions.js +27 -1
- package/dist_ts/classes.timeslicer.d.ts +21 -0
- package/dist_ts/classes.timeslicer.js +31 -0
- package/dist_ts/interfaces.d.ts +36 -0
- package/dist_ts/interfaces.flexharness.d.ts +20 -1
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/plugins.d.ts +2 -2
- package/dist_ts/plugins.js +3 -3
- package/dist_ts/utils.json.d.ts +6 -0
- package/dist_ts/utils.json.js +75 -20
- package/dist_ts/utils.scopesnapshot.d.ts +14 -0
- package/dist_ts/utils.scopesnapshot.js +58 -0
- package/package.json +3 -3
- package/readme.md +5 -0
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +451 -207
- package/ts/classes.flexharness.sessions.ts +30 -0
- package/ts/classes.flexharness.ts +9 -0
- package/ts/classes.timeslicer.ts +32 -0
- package/ts/interfaces.flexharness.ts +22 -0
- package/ts/interfaces.ts +40 -0
- package/ts/plugins.ts +2 -0
- package/ts/readme.md +5 -0
- package/ts/utils.json.ts +70 -18
- package/ts/utils.scopesnapshot.ts +75 -0
|
@@ -14,6 +14,7 @@ import {
|
|
|
14
14
|
type IFlexMessagePageOptions,
|
|
15
15
|
type IFlexMessageReadOptions,
|
|
16
16
|
type IFlexSession,
|
|
17
|
+
type IFlexSessionIdentity,
|
|
17
18
|
type IFlexSessionView,
|
|
18
19
|
type IFlexSessionMetrics,
|
|
19
20
|
type IFlexSessionTombstone,
|
|
@@ -48,6 +49,7 @@ import {
|
|
|
48
49
|
combineErrors,
|
|
49
50
|
} from './utils.flexharness.js';
|
|
50
51
|
import type { FlexHarnessCore } from './classes.flexharness.core.js';
|
|
52
|
+
import { liveScopeSessions, normalizeScopeSnapshot, sessionIdentities } from './utils.scopesnapshot.js';
|
|
51
53
|
|
|
52
54
|
/**
|
|
53
55
|
* Consecutive waits a session view makes for queued writes and open sections to settle. Each wait
|
|
@@ -84,6 +86,34 @@ export class FlexHarnessSessions<TScope> {
|
|
|
84
86
|
.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)));
|
|
85
87
|
}
|
|
86
88
|
|
|
89
|
+
/**
|
|
90
|
+
* The identities of a scope's live sessions, sorted by session id. Until the scope's load has
|
|
91
|
+
* settled they are read from its stored scope snapshot, normalized as the load normalizes it:
|
|
92
|
+
* they neither wait for the load nor read a session's projection, events or jobs, and nothing
|
|
93
|
+
* changes a scope before its load settles. Once it has, they are its loaded sessions'.
|
|
94
|
+
*/
|
|
95
|
+
public async listSessionIdentities(scopeId: string): Promise<IFlexSessionIdentity[]> {
|
|
96
|
+
return this.core.withScopeAdmission(scopeId, async (scope, admitted) => {
|
|
97
|
+
const stateLoad = this.core.stateLoads.get(scope.storageKey);
|
|
98
|
+
if (stateLoad && this.core.isStateLoaded(stateLoad)) {
|
|
99
|
+
const state = await this.core.admittedState(scopeId, scope, stateLoad, admitted);
|
|
100
|
+
await state.scopeQueue;
|
|
101
|
+
this.core.assertOpen();
|
|
102
|
+
this.core.assertStateAcceptingWork(state);
|
|
103
|
+
return sessionIdentities([...state.sessions.values()]
|
|
104
|
+
.filter((stored) => !state.initializingSessions.has(stored.session.sessionId))
|
|
105
|
+
.map((stored) => stored.session));
|
|
106
|
+
}
|
|
107
|
+
const { snapshot } = normalizeScopeSnapshot(
|
|
108
|
+
scope.storageKey,
|
|
109
|
+
await this.core.stores.scopes.load(scope.storageKey),
|
|
110
|
+
);
|
|
111
|
+
this.core.assertOpen();
|
|
112
|
+
if (!admitted()) throw this.core.createScopeRetirementError();
|
|
113
|
+
return sessionIdentities(liveScopeSessions(snapshot));
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
|
|
87
117
|
public async createSession(
|
|
88
118
|
scopeId: string,
|
|
89
119
|
options: IFlexCreateSessionOptions = {},
|
|
@@ -35,6 +35,7 @@ import type {
|
|
|
35
35
|
IFlexScheduledPromptAdmission,
|
|
36
36
|
IFlexSchedulePromptOptions,
|
|
37
37
|
IFlexSession,
|
|
38
|
+
IFlexSessionIdentity,
|
|
38
39
|
IFlexSessionView,
|
|
39
40
|
IFlexSessionMetrics,
|
|
40
41
|
IFlexSessionImportHandle,
|
|
@@ -73,6 +74,14 @@ export class FlexHarness<TScope = unknown> {
|
|
|
73
74
|
return this.core.sessions.listSessions(scopeId);
|
|
74
75
|
}
|
|
75
76
|
|
|
77
|
+
/**
|
|
78
|
+
* The identities of a scope's live sessions, sorted by session id. Before the scope is loaded
|
|
79
|
+
* they come from its stored scope metadata alone, without loading any session.
|
|
80
|
+
*/
|
|
81
|
+
public listSessionIdentities(scopeId: string): Promise<IFlexSessionIdentity[]> {
|
|
82
|
+
return this.core.sessions.listSessionIdentities(scopeId);
|
|
83
|
+
}
|
|
84
|
+
|
|
76
85
|
public createSession(
|
|
77
86
|
scopeId: string,
|
|
78
87
|
options?: IFlexCreateSessionOptions,
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The longest stretch of scope-load work between two turns of the event loop. Timers, I/O and a
|
|
3
|
+
* caller's cancellation wait at most this long behind the load; at about 0.1 ms per turn the
|
|
4
|
+
* pauses cost well under 1% of the load's time.
|
|
5
|
+
*/
|
|
6
|
+
export const scopeLoadSliceMs = 25;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Cuts long synchronous work into slices of elapsed time. Work checks `due` between steps and
|
|
10
|
+
* awaits `pause()` when it is: the event loop runs whatever waits behind the work, and the work
|
|
11
|
+
* stops with the signal's reason once the signal is aborted.
|
|
12
|
+
*/
|
|
13
|
+
export class FlexTimeSlicer {
|
|
14
|
+
private sliceStartedAt = performance.now();
|
|
15
|
+
|
|
16
|
+
constructor(
|
|
17
|
+
private readonly signal: AbortSignal,
|
|
18
|
+
private readonly sliceMs = scopeLoadSliceMs,
|
|
19
|
+
) {}
|
|
20
|
+
|
|
21
|
+
/** Whether the current slice has used its time. */
|
|
22
|
+
public get due(): boolean {
|
|
23
|
+
return performance.now() - this.sliceStartedAt >= this.sliceMs;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Lets the event loop run, then fails with the signal's reason if it was aborted. */
|
|
27
|
+
public async pause(): Promise<void> {
|
|
28
|
+
await new Promise<void>((resolve) => setImmediate(resolve));
|
|
29
|
+
this.signal.throwIfAborted();
|
|
30
|
+
this.sliceStartedAt = performance.now();
|
|
31
|
+
}
|
|
32
|
+
}
|
|
@@ -2,6 +2,7 @@ import type * as plugins from './plugins.js';
|
|
|
2
2
|
import type { FlexHarnessAbortError } from './errors.js';
|
|
3
3
|
import type { FlexToolCatalog } from './classes.toolcatalog.js';
|
|
4
4
|
import type { FlexCodeSandbox } from './classes.codesandbox.js';
|
|
5
|
+
import type { FlexTimeSlicer } from './classes.timeslicer.js';
|
|
5
6
|
import type { IFlexProjectionLists } from './utils.projectionchange.js';
|
|
6
7
|
import type {
|
|
7
8
|
IFlexAgentContextInvocation,
|
|
@@ -20,6 +21,7 @@ import type {
|
|
|
20
21
|
IFlexPendingReversionRelease,
|
|
21
22
|
IFlexResolvedModel,
|
|
22
23
|
IFlexResolvedSessionConfiguration,
|
|
24
|
+
IFlexScopeLoadMetrics,
|
|
23
25
|
IFlexSession,
|
|
24
26
|
IFlexSessionMetricsState,
|
|
25
27
|
IFlexSessionTombstone,
|
|
@@ -53,6 +55,26 @@ export type TRunPhase =
|
|
|
53
55
|
| 'finalizing'
|
|
54
56
|
| 'promoting';
|
|
55
57
|
|
|
58
|
+
/** One scope load: the slicer that cuts its work, and what it took so far. */
|
|
59
|
+
export interface IScopeLoadPass {
|
|
60
|
+
readonly slicer: FlexTimeSlicer;
|
|
61
|
+
readonly metrics: Omit<IFlexScopeLoadMetrics, 'totalMs' | 'outcome'>;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* A session's projection content as a repair found it: the message and reversion segment lists
|
|
66
|
+
* with their frozen entries, the other fields encoded.
|
|
67
|
+
*/
|
|
68
|
+
export interface IProjectionContent {
|
|
69
|
+
readonly messages: readonly IFlexMessage[];
|
|
70
|
+
readonly reversionSegments: readonly IFlexReversionSegment[];
|
|
71
|
+
readonly stagedTerminals: string;
|
|
72
|
+
readonly revertCursor: number;
|
|
73
|
+
readonly excludedRunIds: string;
|
|
74
|
+
readonly pendingReversion: string | undefined;
|
|
75
|
+
readonly pendingReversionReleases: string;
|
|
76
|
+
}
|
|
77
|
+
|
|
56
78
|
/** The invocation a compaction runs under; a manual compaction also carries its requested model hint. */
|
|
57
79
|
export interface ICompactorInvocation<TScope> extends IFlexAgentContextInvocation<TScope> {
|
|
58
80
|
readonly modelHint?: string;
|
package/ts/interfaces.ts
CHANGED
|
@@ -1510,6 +1510,12 @@ export interface IFlexSessionGeneration {
|
|
|
1510
1510
|
sessionGenerationSequence: number;
|
|
1511
1511
|
}
|
|
1512
1512
|
|
|
1513
|
+
/** A live session of a scope as `listSessionIdentities()` names it. */
|
|
1514
|
+
export interface IFlexSessionIdentity extends IFlexSessionGeneration {
|
|
1515
|
+
sessionId: string;
|
|
1516
|
+
parentSessionId?: string;
|
|
1517
|
+
}
|
|
1518
|
+
|
|
1513
1519
|
export const FLEX_SESSION_CONFIGURATION_REF_MAX_BYTES = 1024;
|
|
1514
1520
|
|
|
1515
1521
|
export interface IFlexSessionConfigurationResolverContext<TScope> extends IFlexSessionGeneration {
|
|
@@ -2216,8 +2222,42 @@ export interface IFlexHarnessOptions<TScope> {
|
|
|
2216
2222
|
maxSubagentCallsPerRun?: number;
|
|
2217
2223
|
/** Bounds and the clock of the cache keeper; see `keepCacheWarm()`. */
|
|
2218
2224
|
cacheWarm?: IFlexCacheWarmOptions;
|
|
2225
|
+
/**
|
|
2226
|
+
* Called once each scope load ends, with what it took. An exception it throws, or a promise it
|
|
2227
|
+
* rejects, is ignored.
|
|
2228
|
+
*/
|
|
2229
|
+
scopeLoadObserver?: TFlexScopeLoadObserver;
|
|
2230
|
+
}
|
|
2231
|
+
|
|
2232
|
+
/** How a scope load ended: loaded, failed, or stopped by disposal or the scope's retirement. */
|
|
2233
|
+
export type TFlexScopeLoadOutcome = 'loaded' | 'failed' | 'aborted';
|
|
2234
|
+
|
|
2235
|
+
/**
|
|
2236
|
+
* What one scope load took. A load reads the scope's sessions, their projections, permissions,
|
|
2237
|
+
* event logs and job stores, and repairs what a stopped process left behind; the first request of
|
|
2238
|
+
* a scope waits for it. Times are wall-clock milliseconds, which include the turns the load gives
|
|
2239
|
+
* the event loop.
|
|
2240
|
+
*/
|
|
2241
|
+
export interface IFlexScopeLoadMetrics {
|
|
2242
|
+
scopeId: string;
|
|
2243
|
+
storageKey: string;
|
|
2244
|
+
/** The live sessions the load read, up to where it ended. */
|
|
2245
|
+
sessions: number;
|
|
2246
|
+
/**
|
|
2247
|
+
* The time spent waiting for the stores: the scope snapshot, and each session's projection,
|
|
2248
|
+
* permissions, agent event store and job store. The event log itself is read in `agentSessionMs`.
|
|
2249
|
+
*/
|
|
2250
|
+
storeReadMs: number;
|
|
2251
|
+
/** The time spent creating the sessions' agent sessions: each reads and checks its event log. */
|
|
2252
|
+
agentSessionMs: number;
|
|
2253
|
+
/** The time spent repairing the sessions, their saves included. */
|
|
2254
|
+
repairMs: number;
|
|
2255
|
+
totalMs: number;
|
|
2256
|
+
outcome: TFlexScopeLoadOutcome;
|
|
2219
2257
|
}
|
|
2220
2258
|
|
|
2259
|
+
export type TFlexScopeLoadObserver = (metricsArg: IFlexScopeLoadMetrics) => void;
|
|
2260
|
+
|
|
2221
2261
|
export interface IFlexUncertainToolExecution {
|
|
2222
2262
|
intentId: string;
|
|
2223
2263
|
generationId: string;
|
package/ts/plugins.ts
CHANGED
|
@@ -108,6 +108,7 @@ import {
|
|
|
108
108
|
createAgentEvent,
|
|
109
109
|
filterModelVisibleAgentEvents,
|
|
110
110
|
getAgentGenerationTransactions,
|
|
111
|
+
getGenerationsInModelContext,
|
|
111
112
|
isGenerationInModelContext,
|
|
112
113
|
modelMessagesToAgentEvents,
|
|
113
114
|
resolveAgentContextCompactionPoint,
|
|
@@ -134,6 +135,7 @@ export {
|
|
|
134
135
|
createAgentEvent,
|
|
135
136
|
filterModelVisibleAgentEvents,
|
|
136
137
|
getAgentGenerationTransactions,
|
|
138
|
+
getGenerationsInModelContext,
|
|
137
139
|
isGenerationInModelContext,
|
|
138
140
|
modelMessagesToAgentEvents,
|
|
139
141
|
resolveAgentContextCompactionPoint,
|
package/ts/readme.md
CHANGED
|
@@ -639,6 +639,7 @@ The main session methods are:
|
|
|
639
639
|
|
|
640
640
|
```typescript
|
|
641
641
|
await harness.listSessions(scopeId);
|
|
642
|
+
await harness.listSessionIdentities(scopeId);
|
|
642
643
|
await harness.createSession(scopeId, { sessionId, sessionGenerationId, title });
|
|
643
644
|
await harness.getSession(scopeId, sessionId);
|
|
644
645
|
await harness.getMessages(scopeId, sessionId);
|
|
@@ -708,6 +709,10 @@ await harness.dispose();
|
|
|
708
709
|
|
|
709
710
|
`getSession()` returns the session as saved after every queued write that may change it; it does not wait for queued writes of the scope's other sessions, so a slow save of one session never holds a read of another. `listSessions()` waits for every queued write.
|
|
710
711
|
|
|
712
|
+
`listSessionIdentities(scopeId)` lists a scope's live sessions as `IFlexSessionIdentity` (`sessionId`, `sessionGenerationId`, `sessionGenerationSequence`, `parentSessionId` when set), sorted by session id. The first request of a scope loads it: every session's projection, permissions, event log and job store, and the repair of what a stopped process left behind. `listSessions()` waits for that load; `listSessionIdentities()` does not. Until the load has settled it reads the stored scope snapshot alone, normalized as the load normalizes it (a session stored before session generations existed gets the generation the load derives for it, a deleted session is left out), and never reads a projection, an event log or a job store; nothing can change a scope before its load settles. Once the load has settled it answers from the loaded sessions. It gives the same answer before and after the load.
|
|
713
|
+
|
|
714
|
+
The load gives the event loop a turn about every 25 ms of work, so timers, I/O and a caller's cancellation keep running beside it, and its repair takes time linear in a session's size. A request that stops waiting for the load leaves it running, and the next request of the scope joins it; `dispose()` and `retireScope()` stop it at its next turn, and the requests waiting for it fail with `FlexHarnessAbortError`. The `scopeLoadObserver` option is called once each load ends, with `IFlexScopeLoadMetrics`: `scopeId`, `storageKey`, the live `sessions` it read, `storeReadMs` (waiting for the scope snapshot and each session's projection, permissions, agent event store and job store), `agentSessionMs` (creating the sessions' agent sessions, each of which reads and checks its event log), `repairMs`, `totalMs`, all wall-clock milliseconds, and `outcome` (`'loaded'`, `'failed'`, or `'aborted'` by disposal or retirement). An exception the observer throws, or a promise it rejects, is ignored.
|
|
715
|
+
|
|
711
716
|
Only one run may be active in a session. Additional prompts enter a bounded FIFO owned by FlexHarness, while different sessions can run concurrently. `enqueuePrompt()` resolves with `{ queueId, generation, completion }` after the immutable prompt and options have been accepted into that runtime queue and `prompt.queued` has been emitted. `startPrompt()` keeps its durable-admission behavior: it waits for its FIFO turn and resolves with `{ queueId, generation, runId, completion }` only after the canonical generation claim, run ID, and initial public audit messages have been durably reserved and the corresponding start events have been emitted. `prompt()` preserves the simpler behavior by awaiting completion internally.
|
|
712
717
|
|
|
713
718
|
Every admission names the session generation that admitted it: `generation` (`IFlexPromptAdmissionGeneration`) holds `sessionGenerationId`, `sessionGenerationSequence`, `depth` (0 for a root session, also a legacy root that stored none) and `configurationRef` when the session has one, as `getSession()` reports them. None of them changes while the generation lives, and the prompt only ever runs on that generation. The harness reads it from the session in memory, so a caller that needs it for the run it started does not call `getSession()`: that read waits for the session's queued writes, which queue behind every other session's write queued before them in the scope's one write FIFO.
|
package/ts/utils.json.ts
CHANGED
|
@@ -23,6 +23,7 @@ import type {
|
|
|
23
23
|
TJsonValue,
|
|
24
24
|
} from './interfaces.js';
|
|
25
25
|
import { sliceUtf16 } from './utils.text.js';
|
|
26
|
+
import type { FlexTimeSlicer } from './classes.timeslicer.js';
|
|
26
27
|
import { isValidSessionConfigurationRef } from './utils.validation.js';
|
|
27
28
|
|
|
28
29
|
const DEFAULT_MAX_DEPTH = 12;
|
|
@@ -346,22 +347,8 @@ function failJsonWalk(walk: IJsonWalk, message: string): never {
|
|
|
346
347
|
throw new FlexHarnessStoreFormatError(`${path} ${message}`);
|
|
347
348
|
}
|
|
348
349
|
|
|
349
|
-
/**
|
|
350
|
-
|
|
351
|
-
* `JSON.parse(JSON.stringify(value))` would return, built in the same pass.
|
|
352
|
-
*/
|
|
353
|
-
function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
|
|
354
|
-
if (value === null || typeof value === 'string' || typeof value === 'boolean') {
|
|
355
|
-
return value;
|
|
356
|
-
}
|
|
357
|
-
if (typeof value === 'number') {
|
|
358
|
-
if (!Number.isFinite(value)) failJsonWalk(walk, 'contains a non-finite number.');
|
|
359
|
-
// JSON writes -0 as 0.
|
|
360
|
-
return value === 0 ? 0 : value;
|
|
361
|
-
}
|
|
362
|
-
if (typeof value !== 'object') {
|
|
363
|
-
failJsonWalk(walk, `contains ${typeof value}, which is not JSON-safe.`);
|
|
364
|
-
}
|
|
350
|
+
/** Rejects an object or array that is not a JSON container where the walk stands. */
|
|
351
|
+
function assertJsonContainer(walk: IJsonWalk, value: object): void {
|
|
365
352
|
if (walk.ancestors.includes(value)) {
|
|
366
353
|
failJsonWalk(walk, 'contains a circular reference.');
|
|
367
354
|
}
|
|
@@ -371,8 +358,6 @@ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
|
|
|
371
358
|
if (Object.getOwnPropertySymbols(value).length > 0) {
|
|
372
359
|
failJsonWalk(walk, 'contains a symbol-keyed property.');
|
|
373
360
|
}
|
|
374
|
-
walk.ancestors.push(value);
|
|
375
|
-
let copy: unknown;
|
|
376
361
|
if (Array.isArray(value)) {
|
|
377
362
|
const length = value.length;
|
|
378
363
|
// Own names list array indices in ascending order, then `length`, then any other keys, so a
|
|
@@ -392,6 +377,30 @@ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
|
|
|
392
377
|
failJsonWalk(walk, 'is not JSON-visible.');
|
|
393
378
|
}
|
|
394
379
|
}
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
/**
|
|
384
|
+
* Rejects anything a JSON round trip would not preserve. With `walk.copy` it also returns the copy
|
|
385
|
+
* `JSON.parse(JSON.stringify(value))` would return, built in the same pass.
|
|
386
|
+
*/
|
|
387
|
+
function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
|
|
388
|
+
if (value === null || typeof value === 'string' || typeof value === 'boolean') {
|
|
389
|
+
return value;
|
|
390
|
+
}
|
|
391
|
+
if (typeof value === 'number') {
|
|
392
|
+
if (!Number.isFinite(value)) failJsonWalk(walk, 'contains a non-finite number.');
|
|
393
|
+
// JSON writes -0 as 0.
|
|
394
|
+
return value === 0 ? 0 : value;
|
|
395
|
+
}
|
|
396
|
+
if (typeof value !== 'object') {
|
|
397
|
+
failJsonWalk(walk, `contains ${typeof value}, which is not JSON-safe.`);
|
|
398
|
+
}
|
|
399
|
+
assertJsonContainer(walk, value);
|
|
400
|
+
walk.ancestors.push(value);
|
|
401
|
+
let copy: unknown;
|
|
402
|
+
if (Array.isArray(value)) {
|
|
403
|
+
const length = value.length;
|
|
395
404
|
const items: unknown[] | undefined = walk.copy ? [] : undefined;
|
|
396
405
|
const known = walk.knownEntries?.get(value) ?? 0;
|
|
397
406
|
for (let index = 0; index < length; index++) {
|
|
@@ -2292,6 +2301,49 @@ export function cloneSerializable<T>(value: T): T {
|
|
|
2292
2301
|
return walkJsonValue({ root: '$', segments: [], ancestors: [], copy: true }, value) as T;
|
|
2293
2302
|
}
|
|
2294
2303
|
|
|
2304
|
+
/**
|
|
2305
|
+
* `cloneSerializable(value)` in slices: the same copy and the same error for a value that is not
|
|
2306
|
+
* JSON, pausing through `slicer` between the entries of `value`. Each entry is copied whole.
|
|
2307
|
+
*/
|
|
2308
|
+
export async function cloneSerializableSliced<T>(value: T, slicer: FlexTimeSlicer): Promise<T> {
|
|
2309
|
+
const walk: IJsonWalk = { root: '$', segments: [], ancestors: [], copy: true };
|
|
2310
|
+
if (value === null || typeof value !== 'object') return walkJsonValue(walk, value) as T;
|
|
2311
|
+
assertJsonContainer(walk, value);
|
|
2312
|
+
walk.ancestors.push(value);
|
|
2313
|
+
let copy: unknown;
|
|
2314
|
+
if (Array.isArray(value)) {
|
|
2315
|
+
const items: unknown[] = [];
|
|
2316
|
+
for (let index = 0; index < value.length; index++) {
|
|
2317
|
+
walk.segments.push(index);
|
|
2318
|
+
if (!(index in value)) failJsonWalk(walk, 'is a sparse array entry.');
|
|
2319
|
+
items.push(walkJsonValue(walk, value[index]));
|
|
2320
|
+
walk.segments.pop();
|
|
2321
|
+
if (slicer.due) await slicer.pause();
|
|
2322
|
+
}
|
|
2323
|
+
copy = items;
|
|
2324
|
+
} else {
|
|
2325
|
+
const fields: Record<string, unknown> = {};
|
|
2326
|
+
for (const key of Object.getOwnPropertyNames(value)) {
|
|
2327
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
|
|
2328
|
+
walk.segments.push(key);
|
|
2329
|
+
if (!descriptor.enumerable || !('value' in descriptor)) {
|
|
2330
|
+
failJsonWalk(walk, 'is not a plain JSON property.');
|
|
2331
|
+
}
|
|
2332
|
+
const field = walkJsonValue(walk, descriptor.value);
|
|
2333
|
+
if (key in fields) {
|
|
2334
|
+
Object.defineProperty(fields, key, { value: field, enumerable: true, writable: true, configurable: true });
|
|
2335
|
+
} else {
|
|
2336
|
+
fields[key] = field;
|
|
2337
|
+
}
|
|
2338
|
+
walk.segments.pop();
|
|
2339
|
+
if (slicer.due) await slicer.pause();
|
|
2340
|
+
}
|
|
2341
|
+
copy = fields;
|
|
2342
|
+
}
|
|
2343
|
+
walk.ancestors.pop();
|
|
2344
|
+
return copy as T;
|
|
2345
|
+
}
|
|
2346
|
+
|
|
2295
2347
|
export function deepFreeze<T>(value: T): T {
|
|
2296
2348
|
if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
|
|
2297
2349
|
return value;
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import * as plugins from './plugins.js';
|
|
2
|
+
import type { IFlexScopeSnapshot, IFlexSession, IFlexSessionIdentity } from './interfaces.js';
|
|
3
|
+
import { cloneSerializable } from './utils.json.js';
|
|
4
|
+
import { requireSessionGeneration } from './utils.flexharness.js';
|
|
5
|
+
|
|
6
|
+
function deriveLegacySessionGenerationId(
|
|
7
|
+
storageKey: string,
|
|
8
|
+
sessionId: string,
|
|
9
|
+
createdAt: string,
|
|
10
|
+
): string {
|
|
11
|
+
const digest = plugins.crypto.createHash('sha256').update(JSON.stringify([
|
|
12
|
+
'flexharness-legacy-session-generation-v1',
|
|
13
|
+
storageKey,
|
|
14
|
+
sessionId,
|
|
15
|
+
createdAt,
|
|
16
|
+
])).digest('hex');
|
|
17
|
+
return `legacy_${digest}`;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* The scope a store holds as the harness works with it: a copy of `stored`, or the empty scope,
|
|
22
|
+
* whose sessions and tombstones stored before session generations existed carry the generation
|
|
23
|
+
* derived for them. `changed` says whether any did; the scope load then saves the copy.
|
|
24
|
+
*/
|
|
25
|
+
export function normalizeScopeSnapshot(
|
|
26
|
+
storageKey: string,
|
|
27
|
+
stored: IFlexScopeSnapshot | undefined,
|
|
28
|
+
): { snapshot: IFlexScopeSnapshot; changed: boolean } {
|
|
29
|
+
const snapshot = cloneSerializable(stored ?? {
|
|
30
|
+
schemaVersion: 1,
|
|
31
|
+
revision: 0,
|
|
32
|
+
sessions: [],
|
|
33
|
+
tombstones: [],
|
|
34
|
+
} satisfies IFlexScopeSnapshot);
|
|
35
|
+
let changed = false;
|
|
36
|
+
const repairedGenerationSequence = snapshot.revision + 1;
|
|
37
|
+
for (const session of snapshot.sessions) {
|
|
38
|
+
if (session.sessionGenerationId !== undefined) continue;
|
|
39
|
+
session.sessionGenerationId = deriveLegacySessionGenerationId(
|
|
40
|
+
storageKey,
|
|
41
|
+
session.sessionId,
|
|
42
|
+
session.createdAt,
|
|
43
|
+
);
|
|
44
|
+
session.sessionGenerationSequence = repairedGenerationSequence;
|
|
45
|
+
changed = true;
|
|
46
|
+
}
|
|
47
|
+
for (const tombstone of snapshot.tombstones) {
|
|
48
|
+
if (tombstone.sessionGenerationId !== undefined) continue;
|
|
49
|
+
tombstone.sessionGenerationId = deriveLegacySessionGenerationId(
|
|
50
|
+
storageKey,
|
|
51
|
+
tombstone.sessionId,
|
|
52
|
+
tombstone.deletedAt,
|
|
53
|
+
);
|
|
54
|
+
tombstone.sessionGenerationSequence = repairedGenerationSequence;
|
|
55
|
+
changed = true;
|
|
56
|
+
}
|
|
57
|
+
return { snapshot, changed };
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** The sessions of a scope snapshot that no tombstone deletes, in snapshot order. */
|
|
61
|
+
export function liveScopeSessions(snapshot: IFlexScopeSnapshot): IFlexSession[] {
|
|
62
|
+
const tombstoned = new Set(snapshot.tombstones.map((tombstone) => tombstone.sessionId));
|
|
63
|
+
return snapshot.sessions.filter((session) => !tombstoned.has(session.sessionId));
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The identities of `sessions`, sorted by session id as scope snapshots are. */
|
|
67
|
+
export function sessionIdentities(sessions: Iterable<IFlexSession>): IFlexSessionIdentity[] {
|
|
68
|
+
return [...sessions]
|
|
69
|
+
.map((session): IFlexSessionIdentity => ({
|
|
70
|
+
sessionId: session.sessionId,
|
|
71
|
+
...requireSessionGeneration(session),
|
|
72
|
+
...(session.parentSessionId === undefined ? {} : { parentSessionId: session.parentSessionId }),
|
|
73
|
+
}))
|
|
74
|
+
.sort((left, right) => left.sessionId.localeCompare(right.sessionId));
|
|
75
|
+
}
|