@modelprofile.com/flexharness 18.8.0 → 18.9.1
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 +19 -0
- package/dist_ts/classes.flexharness.core.js +358 -67
- package/dist_ts/classes.flexharness.deletion.d.ts +1 -1
- package/dist_ts/classes.flexharness.deletion.js +147 -141
- package/dist_ts/classes.flexharness.imports.js +3 -3
- package/dist_ts/classes.flexharness.lifecycle.js +4 -1
- package/dist_ts/classes.flexharness.permissions.js +5 -5
- package/dist_ts/classes.flexharness.prompts.js +5 -6
- package/dist_ts/classes.flexharness.results.js +3 -3
- package/dist_ts/classes.flexharness.reversions.js +320 -316
- package/dist_ts/classes.flexharness.sessions.js +19 -3
- package/dist_ts/classes.flexharness.subagents.js +2 -2
- package/dist_ts/classes.recoverygate.d.ts +30 -0
- package/dist_ts/classes.recoverygate.js +105 -0
- package/dist_ts/classes.scoperecovery.d.ts +9 -1
- package/dist_ts/classes.scoperecovery.js +94 -26
- package/dist_ts/interfaces.d.ts +22 -0
- package/dist_ts/interfaces.flexharness.d.ts +5 -0
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/plugins.d.ts +1 -1
- package/dist_ts/plugins.js +1 -1
- package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +5 -1
- package/package.json +3 -3
- package/readme.md +5 -3
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +337 -34
- package/ts/classes.flexharness.deletion.ts +24 -15
- package/ts/classes.flexharness.imports.ts +3 -2
- package/ts/classes.flexharness.lifecycle.ts +3 -0
- package/ts/classes.flexharness.permissions.ts +8 -4
- package/ts/classes.flexharness.prompts.ts +10 -8
- package/ts/classes.flexharness.results.ts +3 -2
- package/ts/classes.flexharness.reversions.ts +13 -6
- package/ts/classes.flexharness.sessions.ts +18 -2
- package/ts/classes.flexharness.subagents.ts +5 -4
- package/ts/classes.recoverygate.ts +111 -0
- package/ts/classes.scoperecovery.ts +102 -25
- package/ts/interfaces.flexharness.ts +5 -0
- package/ts/interfaces.ts +23 -0
- package/ts/plugins.ts +1 -0
- package/ts/readme.md +5 -3
- package/ts_stores_nosqldb/classes.nosqldbstores.ts +5 -0
- package/ts_stores_nosqldb/readme.md +1 -3
|
@@ -220,21 +220,31 @@ function isVersionedRecoveryStore(
|
|
|
220
220
|
export class RecoverableFlexScopeStore implements IFlexScopeStore {
|
|
221
221
|
private static readonly lanes = new WeakMap<IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2, Map<string, Promise<void>>>();
|
|
222
222
|
|
|
223
|
-
public readonly sessionLocal: IFlexSessionLocalScopeStore
|
|
223
|
+
public readonly sessionLocal: IFlexSessionLocalScopeStore;
|
|
224
|
+
|
|
225
|
+
constructor(
|
|
226
|
+
private readonly scopes: IFlexScopeStore,
|
|
227
|
+
private readonly recoveryStore: IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2,
|
|
228
|
+
) {
|
|
229
|
+
this.sessionLocal = {
|
|
224
230
|
releaseOwnership: (storageKey) => this.recoveryStore.deactivateWriteProvenance(storageKey),
|
|
225
231
|
loadCatalogue: (storageKey) => this.loadCatalogue(storageKey),
|
|
226
232
|
saveCatalogue: (storageKey, snapshot, expectedRevision) =>
|
|
227
233
|
this.saveCatalogue(storageKey, snapshot, expectedRevision),
|
|
228
234
|
setRecoveryRequired: (storageKey, sessionId, required) =>
|
|
229
235
|
this.setRecoveryRequired(storageKey, sessionId, required),
|
|
236
|
+
readCleanSessionMetadata: (storageKey, sessionId) =>
|
|
237
|
+
this.readCleanSessionMetadata(storageKey, sessionId),
|
|
238
|
+
...(isVersionedRecoveryStore(this.recoveryStore) ? {
|
|
239
|
+
readCleanSessionProof: (storageKey: string, sessionId: string) =>
|
|
240
|
+
this.readCleanSessionProof(storageKey, sessionId),
|
|
241
|
+
publishSessionClean: (storageKey: string, expectedRecoveryRevision: number, clean: IFlexSessionRecoveryCleanState) =>
|
|
242
|
+
this.publishSessionClean(storageKey, expectedRecoveryRevision, clean),
|
|
243
|
+
} : {}),
|
|
230
244
|
qualifyCatalogue: (storageKey, snapshot, recoverySessionIds) =>
|
|
231
245
|
this.qualifyCatalogue(storageKey, snapshot, recoverySessionIds),
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
constructor(
|
|
235
|
-
private readonly scopes: IFlexScopeStore,
|
|
236
|
-
private readonly recoveryStore: IFlexScopeRecoveryStore | IFlexScopeRecoveryStoreV2,
|
|
237
|
-
) {}
|
|
246
|
+
};
|
|
247
|
+
}
|
|
238
248
|
|
|
239
249
|
private inLane<T>(storageKey: string, operation: () => Promise<T>): Promise<T> {
|
|
240
250
|
validateIdentifier(storageKey, 'storageKey');
|
|
@@ -268,23 +278,12 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
|
|
|
268
278
|
const provenance = await this.recoveryStore.loadWriteProvenance(storageKey);
|
|
269
279
|
const snapshot = await this.scopes.load(storageKey);
|
|
270
280
|
if (snapshot !== undefined) assertFlexScopeSnapshot(snapshot);
|
|
271
|
-
|
|
281
|
+
const recovery = await this.recoveryStore.load(storageKey);
|
|
272
282
|
if (recovery !== undefined) {
|
|
273
283
|
assertFlexScopeRecoverySnapshotVersioned(recovery);
|
|
274
284
|
if (recovery.schemaVersion === 2 && !isVersionedRecoveryStore(this.recoveryStore)) {
|
|
275
285
|
throw new FlexHarnessStoreFormatError('A schema-2 sidecar requires a versioned recovery store.');
|
|
276
286
|
}
|
|
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
287
|
}
|
|
289
288
|
const qualified = provenance && (recovery === undefined
|
|
290
289
|
? snapshot === undefined
|
|
@@ -305,22 +304,60 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
|
|
|
305
304
|
private loadCatalogue(storageKey: string): ReturnType<IFlexSessionLocalScopeStore['loadCatalogue']> {
|
|
306
305
|
return this.inLane(storageKey, async () => {
|
|
307
306
|
const evidence = await this.readEvidence(storageKey);
|
|
307
|
+
const recovery = evidence.recovery;
|
|
308
308
|
return {
|
|
309
309
|
snapshot: evidence.snapshot,
|
|
310
310
|
qualified: evidence.qualified,
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
311
|
+
recoveryRevision: recovery?.revision ?? 0,
|
|
312
|
+
recoverySchemaVersion: recovery?.schemaVersion ?? 1,
|
|
313
|
+
// Missing, dirty and generation-mismatched entries require full recovery. A clean
|
|
314
|
+
// entry is only a candidate; the admission reader also checks both bounded log heads.
|
|
315
|
+
recoverySessionIds: recovery?.schemaVersion === 2
|
|
314
316
|
? [...new Set([
|
|
315
|
-
...(evidence.snapshot?.sessions
|
|
317
|
+
...(evidence.snapshot?.sessions
|
|
318
|
+
.filter((session) => !recovery.sessionStates.some((entry) =>
|
|
319
|
+
entry.sessionId === session.sessionId && entry.state === 'clean'
|
|
320
|
+
&& cleanMatchesSession(entry, session)))
|
|
321
|
+
.map((session) => session.sessionId) ?? []),
|
|
316
322
|
...(evidence.snapshot?.tombstones.map((tombstone) => tombstone.sessionId) ?? []),
|
|
317
|
-
...
|
|
323
|
+
...recovery.sessionStates.filter((entry) => entry.state === 'dirty')
|
|
324
|
+
.map((entry) => entry.sessionId),
|
|
318
325
|
])].sort()
|
|
319
|
-
:
|
|
326
|
+
: recovery?.schemaVersion === 1 ? recovery.recoverySessionIds : [],
|
|
320
327
|
};
|
|
321
328
|
});
|
|
322
329
|
}
|
|
323
330
|
|
|
331
|
+
/** Scope/sidecar-only proof read; cold admission still takes normal recovery. */
|
|
332
|
+
public readCleanSessionMetadata(storageKey: string, sessionId: string): Promise<IFlexSession | undefined> {
|
|
333
|
+
validateIdentifier(sessionId, 'sessionId');
|
|
334
|
+
return this.inLane(storageKey, async () => {
|
|
335
|
+
const evidence = await this.readEvidence(storageKey);
|
|
336
|
+
if (!evidence.qualified || evidence.recovery?.schemaVersion !== 2) return undefined;
|
|
337
|
+
const clean = evidence.recovery.sessionStates.find((entry) => entry.sessionId === sessionId);
|
|
338
|
+
if (clean?.state !== 'clean') return undefined;
|
|
339
|
+
const session = evidence.snapshot?.sessions.find((entry) => entry.sessionId === sessionId);
|
|
340
|
+
if (!cleanMatchesSession(clean, session)) return undefined;
|
|
341
|
+
return cloneSerializable(session);
|
|
342
|
+
});
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
public readCleanSessionProof(storageKey: string, sessionId: string): Promise<{
|
|
346
|
+
session: IFlexSession;
|
|
347
|
+
clean: IFlexSessionRecoveryCleanState;
|
|
348
|
+
} | undefined> {
|
|
349
|
+
validateIdentifier(sessionId, 'sessionId');
|
|
350
|
+
return this.inLane(storageKey, async () => {
|
|
351
|
+
const evidence = await this.readEvidence(storageKey);
|
|
352
|
+
if (!evidence.qualified || evidence.recovery?.schemaVersion !== 2) return undefined;
|
|
353
|
+
const clean = evidence.recovery.sessionStates.find((entry) => entry.sessionId === sessionId);
|
|
354
|
+
if (clean?.state !== 'clean') return undefined;
|
|
355
|
+
const session = evidence.snapshot?.sessions.find((entry) => entry.sessionId === sessionId);
|
|
356
|
+
if (!session || !cleanMatchesSession(clean, session)) return undefined;
|
|
357
|
+
return { session: cloneSerializable(session), clean: cloneSerializable(clean) };
|
|
358
|
+
});
|
|
359
|
+
}
|
|
360
|
+
|
|
324
361
|
private assertQualified(storageKey: string, evidence: IRecoveryEvidence): void {
|
|
325
362
|
if (!evidence.qualified) {
|
|
326
363
|
throw new FlexHarnessStoreFormatError(
|
|
@@ -425,6 +462,46 @@ export class RecoverableFlexScopeStore implements IFlexScopeStore {
|
|
|
425
462
|
});
|
|
426
463
|
}
|
|
427
464
|
|
|
465
|
+
/** Explicit CAS primitive. Callers must establish complete producer quiescence first. */
|
|
466
|
+
private publishSessionClean(
|
|
467
|
+
storageKey: string,
|
|
468
|
+
expectedRecoveryRevision: number,
|
|
469
|
+
clean: IFlexSessionRecoveryCleanState,
|
|
470
|
+
): Promise<void> {
|
|
471
|
+
assertJsonSerializable(clean, '$clean');
|
|
472
|
+
assertSessionRecoveryState(clean, '$clean');
|
|
473
|
+
if (clean.state !== 'clean') {
|
|
474
|
+
throw new FlexHarnessValidationError('Clean publication requires a clean state.');
|
|
475
|
+
}
|
|
476
|
+
validateExpectedRevision(expectedRecoveryRevision);
|
|
477
|
+
const validated = cloneSerializable(clean);
|
|
478
|
+
return this.inLane(storageKey, async () => {
|
|
479
|
+
const evidence = await this.readEvidence(storageKey);
|
|
480
|
+
this.assertQualified(storageKey, evidence);
|
|
481
|
+
const actualRevision = evidence.recovery?.revision ?? 0;
|
|
482
|
+
if (actualRevision !== expectedRecoveryRevision) {
|
|
483
|
+
throw new FlexHarnessStoreConflictError(storageKey, expectedRecoveryRevision, actualRevision);
|
|
484
|
+
}
|
|
485
|
+
const session = evidence.snapshot?.sessions.find((entry) => entry.sessionId === validated.sessionId);
|
|
486
|
+
if (!cleanMatchesSession(validated, session)) {
|
|
487
|
+
throw new FlexHarnessValidationError('Clean publication does not match the current session generation and metadata.');
|
|
488
|
+
}
|
|
489
|
+
const states = recoveryStates(evidence.recovery);
|
|
490
|
+
if (states.find((entry) => entry.sessionId === validated.sessionId)?.state !== 'dirty') {
|
|
491
|
+
throw new FlexHarnessValidationError('Clean publication requires an existing dirty session.');
|
|
492
|
+
}
|
|
493
|
+
const next = states.filter((entry) => entry.sessionId !== validated.sessionId);
|
|
494
|
+
next.push(validated);
|
|
495
|
+
await this.saveRecovery(storageKey, {
|
|
496
|
+
schemaVersion: 2,
|
|
497
|
+
revision: actualRevision + 1,
|
|
498
|
+
catalogueRevision: evidence.snapshot?.revision ?? 0,
|
|
499
|
+
catalogueDigest: catalogueDigest(evidence.snapshot),
|
|
500
|
+
sessionStates: sortedStates(next),
|
|
501
|
+
}, actualRevision);
|
|
502
|
+
});
|
|
503
|
+
}
|
|
504
|
+
|
|
428
505
|
private async qualifyCatalogue(
|
|
429
506
|
storageKey: string,
|
|
430
507
|
snapshot: IFlexScopeSnapshot,
|
|
@@ -3,6 +3,7 @@ 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
5
|
import type { FlexTimeSlicer } from './classes.timeslicer.js';
|
|
6
|
+
import type { FlexRecoveryProducerGate } from './classes.recoverygate.js';
|
|
6
7
|
import type { IFlexProjectionLists } from './utils.projectionchange.js';
|
|
7
8
|
import type {
|
|
8
9
|
IFlexAgentContextInvocation,
|
|
@@ -248,6 +249,10 @@ export interface IStorageState {
|
|
|
248
249
|
sessionLocal: boolean;
|
|
249
250
|
qualifyingLegacy: boolean;
|
|
250
251
|
recoverySessionIds: Set<string>;
|
|
252
|
+
/** One durable mark per session for this state lifetime; failed marks are never cached. */
|
|
253
|
+
recoveryMarks: Map<string, Promise<void>>;
|
|
254
|
+
/** Session producer/publication exclusion; never shared across storage-state lifetimes. */
|
|
255
|
+
recoveryProducerGates: Map<string, FlexRecoveryProducerGate>;
|
|
251
256
|
sessionLoads: Map<string, Promise<IStoredSessionState>>;
|
|
252
257
|
sharedRecovery?: Promise<void>;
|
|
253
258
|
sessions: Map<string, IStoredSessionState>;
|
package/ts/interfaces.ts
CHANGED
|
@@ -1830,9 +1830,26 @@ export interface IFlexSessionLocalScopeStore {
|
|
|
1830
1830
|
snapshot: IFlexScopeSnapshot | undefined;
|
|
1831
1831
|
qualified: boolean;
|
|
1832
1832
|
recoverySessionIds: string[];
|
|
1833
|
+
/** Exact sidecar CAS revision, when the store supports clean publication. */
|
|
1834
|
+
recoveryRevision?: number;
|
|
1835
|
+
/** Sidecar schema, when the adapter can distinguish compatibility recovery. */
|
|
1836
|
+
recoverySchemaVersion?: 1 | 2;
|
|
1833
1837
|
}>;
|
|
1834
1838
|
saveCatalogue(storageKey: string, snapshot: IFlexScopeSnapshot, expectedRevision: number): Promise<void>;
|
|
1835
1839
|
setRecoveryRequired(storageKey: string, sessionId: string, required: boolean): Promise<void>;
|
|
1840
|
+
/** Optional scope/sidecar-only read; undefined means no exact clean metadata proof. */
|
|
1841
|
+
readCleanSessionMetadata?(storageKey: string, sessionId: string): Promise<IFlexSession | undefined>;
|
|
1842
|
+
/** One exact catalogue and sidecar read, without opening any session runtime store. */
|
|
1843
|
+
readCleanSessionProof?(storageKey: string, sessionId: string): Promise<{
|
|
1844
|
+
session: IFlexSession;
|
|
1845
|
+
clean: IFlexSessionRecoveryCleanState;
|
|
1846
|
+
} | undefined>;
|
|
1847
|
+
/** Optional schema-2 CAS; legacy session-local stores may continue to implement schema 1. */
|
|
1848
|
+
publishSessionClean?(
|
|
1849
|
+
storageKey: string,
|
|
1850
|
+
expectedRecoveryRevision: number,
|
|
1851
|
+
clean: IFlexSessionRecoveryCleanState,
|
|
1852
|
+
): Promise<void>;
|
|
1836
1853
|
/** Called only after explicit complete legacy qualification under namespace ownership. */
|
|
1837
1854
|
qualifyCatalogue(storageKey: string, snapshot: IFlexScopeSnapshot, recoverySessionIds: string[]): Promise<void>;
|
|
1838
1855
|
}
|
|
@@ -1893,6 +1910,8 @@ export interface IFlexPermissionStore {
|
|
|
1893
1910
|
}
|
|
1894
1911
|
|
|
1895
1912
|
export interface IFlexAgentEventStoreProvider {
|
|
1913
|
+
/** Optional bounded head read that does not acquire a session event store. */
|
|
1914
|
+
loadHead?(storageKey: string, sessionId: string): Promise<plugins.IAgentEventHead | undefined>;
|
|
1896
1915
|
getStore(
|
|
1897
1916
|
storageKey: string,
|
|
1898
1917
|
sessionId: string,
|
|
@@ -2200,6 +2219,7 @@ export interface IFlexExecutionContextProviderContext<TScope> {
|
|
|
2200
2219
|
scope: TScope;
|
|
2201
2220
|
storageKey: string;
|
|
2202
2221
|
sessionId: string;
|
|
2222
|
+
/** The only durable job-state writer for this session; saves await its recovery fence. */
|
|
2203
2223
|
jobStore: plugins.IToolJobStore;
|
|
2204
2224
|
}
|
|
2205
2225
|
|
|
@@ -2209,6 +2229,7 @@ export interface IFlexExecutionContextHandle {
|
|
|
2209
2229
|
}
|
|
2210
2230
|
|
|
2211
2231
|
export interface IFlexExecutionContextProvider<TScope> {
|
|
2232
|
+
/** Context construction must not start an external effect; `jobs.start` and `jobs.abort` are fenced. */
|
|
2212
2233
|
provideExecutionContext(
|
|
2213
2234
|
context: IFlexExecutionContextProviderContext<TScope>,
|
|
2214
2235
|
): Promise<IFlexExecutionContextHandle | undefined> | IFlexExecutionContextHandle | undefined;
|
|
@@ -2368,6 +2389,8 @@ export interface IFlexHarnessOptions<TScope> {
|
|
|
2368
2389
|
stores?: IFlexHarnessStores;
|
|
2369
2390
|
/** Opt-in: requires scopes.sessionLocal; never falls back to an implicit complete load. */
|
|
2370
2391
|
sessionLoading?: 'eager' | 'session-local';
|
|
2392
|
+
/** Explicit clean-read rollout. Omitted keeps schema-2 sessions on compatibility recovery. */
|
|
2393
|
+
recoveryFrontier?: 'compatibility' | { mode: 'clean-read'; storageKeys?: readonly string[] };
|
|
2371
2394
|
agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;
|
|
2372
2395
|
toolOutputLimits?: IFlexJsonLimits;
|
|
2373
2396
|
callbackLimits?: IFlexCallbackLimits;
|
package/ts/plugins.ts
CHANGED
package/ts/readme.md
CHANGED
|
@@ -746,6 +746,8 @@ The reservation save is the admission point. A save failure produces no start ev
|
|
|
746
746
|
|
|
747
747
|
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
748
|
|
|
749
|
+
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
|
+
|
|
749
751
|
```typescript
|
|
750
752
|
const harness = new FlexHarness({
|
|
751
753
|
scopeResolver,
|
|
@@ -778,9 +780,9 @@ When the older releases of a host change no such witness, the host cannot detect
|
|
|
778
780
|
|
|
779
781
|
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
782
|
|
|
781
|
-
The NoSQL projection store's
|
|
783
|
+
The NoSQL projection store's `loadHead(storageKey, sessionId)` and Agent event provider's `loadHead(storageKey, sessionId)` return `{ incarnationId, revision, contentRoot }` from the record head without reading the base, change pages or event bodies or acquiring an Agent event store. The Agent event store also offers its own `loadHead(sessionId)`. 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. A cold clean read requires both provider-level bounded heads and matching catalogue and sidecar proof; otherwise it hydrates and repairs normally.
|
|
782
784
|
|
|
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
|
|
785
|
+
The existing `IFlexScopeRecoveryStore` contract remains schema 1. A store that can read and preserve schema-2 sidecars explicitly implements `IFlexScopeRecoveryStoreV2`; the built-in NoSQL store does. `RecoverableFlexScopeStore` accepts either contract and advertises `publishSessionClean` only for schema-2 stores. That CAS binds an existing dirty session to its exact generation, canonical metadata digest and both rooted log heads. New sidecars start at schema 1 until clean publication promotes them. `readCleanSessionProof()` reads only scope and sidecar evidence, returning the exact clean metadata and head commitments or `undefined` when proof is absent or stale. Malformed evidence fails closed. `getSession()` compares both bounded heads to that proof under a per-session producer gate and returns the metadata without acquiring runtime stores when they match. Publication waits until producers, the generation and background jobs have settled; a new producer durably marks the session dirty before its effect.
|
|
784
786
|
|
|
785
787
|
### Continuing Without New Input
|
|
786
788
|
|
|
@@ -1228,7 +1230,7 @@ For a bounded inspection view, call `pageUncertainToolExecutions(scopeId, sessio
|
|
|
1228
1230
|
|
|
1229
1231
|
`agentSessionPolicy` forwards bounded AgentSession session controls for context building, compaction, event retention, change-listener pressure, lease cleanup, archived transaction tombstones, and context-overflow retries. A configured `contextCompactor` receives the projected model messages, only the filtered model-visible covered events, AgentSession's existing `reason` and `abortSignal`, and the exact resolved `scopeId`, `scope`, `storageKey`, and `sessionId` for the invocation causing compaction. The invocation context remains isolated when aliases share one storage key, so integrations can resolve the correct model without global mutable state. If no events are eligible for compaction, `compactSession()` returns without calling the compactor or writing a compaction event; otherwise it writes the canonical event. `archiveSessionEvents()` moves events covered by that compaction into the configured Agent event archive store and returns public archive metadata.
|
|
1230
1232
|
|
|
1231
|
-
`executionContextProvider` can construct a AgentSession execution context for each session. FlexHarness supplies the resolved scope, storage key, and the session's private job store. The public background APIs expose only execution ID, type, state, exit code, and timestamps; command payloads, stdout, and stderr remain private. The provider's optional `close()` is owned by session deletion, scope retirement, and harness disposal.
|
|
1233
|
+
`executionContextProvider` can construct a AgentSession execution context for each session. FlexHarness supplies the resolved scope, storage key, and the session's private job store. The provider must persist all job state through that supplied store and must not start external effects while constructing the context; FlexHarness fences `jobs.start` and `jobs.abort` before invoking them. The public background APIs expose only execution ID, type, state, exit code, and timestamps; command payloads, stdout, and stderr remain private. The provider's optional `close()` is owned by session deletion, scope retirement, and harness disposal.
|
|
1232
1234
|
|
|
1233
1235
|
### Compaction Point
|
|
1234
1236
|
|
|
@@ -414,6 +414,11 @@ class NoSqlAgentEventStoreProvider implements IFlexAgentEventStoreProvider {
|
|
|
414
414
|
|
|
415
415
|
constructor(private readonly records: FlexRecordStore) {}
|
|
416
416
|
|
|
417
|
+
public loadHead(storageKey: string, sessionId: string) {
|
|
418
|
+
providerKey(storageKey, sessionId);
|
|
419
|
+
return this.records.readLogHead({ domain: 'agentEvents', storageKey, sessionId });
|
|
420
|
+
}
|
|
421
|
+
|
|
417
422
|
public getStore(storageKey: string, sessionId: string): NoSqlAgentEventStore {
|
|
418
423
|
const key = providerKey(storageKey, sessionId);
|
|
419
424
|
let store = this.stores.get(key);
|
|
@@ -27,8 +27,6 @@ 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
|
-
|
|
32
30
|
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.
|
|
33
31
|
|
|
34
32
|
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.
|
|
@@ -58,7 +56,7 @@ All writes in one namespace now contend on its namespace document, not only crea
|
|
|
58
56
|
|
|
59
57
|
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.
|
|
60
58
|
|
|
61
|
-
The projection store and each Agent event store
|
|
59
|
+
The projection store, Agent event provider and each Agent event store expose `loadHead`, a bounded read of `{ incarnationId, revision, contentRoot }`. The provider method reads the Agent event head without acquiring a session store. `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. A clean cold `getSession()` also requires matching catalogue metadata and schema-2 sidecar proof.
|
|
62
60
|
|
|
63
61
|
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.
|
|
64
62
|
|