@modelprofile.com/flexharness 12.1.0 → 12.1.2

package/ts_stores_testing/contract.ts

@@ -6,6 +6,7 @@ import {
 } from '../ts/errors.js';
 import type {
   IFlexHarnessStores,
+  IFlexProjectManagementSessionContext,
   IFlexProjectManagementSnapshot,
   IFlexProjectManagementTombstone,
   IFlexProjectionChange,
@@ -46,6 +47,11 @@ export interface IFlexStoreContractBackend {
   releasesSessions: boolean;
   /** The bundle provides `results`. */
   storesResults: boolean;
+  /**
+   * The scope store keeps a session whose `scopeId` differs from the storage key it is saved under,
+   * as a resolver that maps several scope IDs to one storage key saves it. Defaults to `true`.
+   */
+  storesScopeAliases?: boolean;
   open(): Promise<IFlexStoreContractFixture>;
 }
 
@@ -86,6 +92,17 @@ function projectTombstone(
   };
 }
 
+/**
+ * The session context FlexHarness passes with every project-management `load` and
+ * `tombstoneSession` of the session generation `generation`.
+ */
+function projectSessionContext(
+  generation: string,
+  sequence = 1,
+): Readonly<IFlexProjectManagementSessionContext> {
+  return Object.freeze({ sessionGenerationId: generation, sessionGenerationSequence: sequence });
+}
+
 /** Exactly one of `attempts` succeeded and another was rejected with `errorClass`. */
 function assertOneWinner(attempts: PromiseSettledResult<unknown>[], errorClass: TErrorClass): void {
   plugins.assert.equal(attempts.filter((result) => result.status === 'fulfilled').length, 1);
@@ -164,7 +181,7 @@ export function createFlexStoreContractTests(
 
   contractTest('scope store clones snapshots and enforces CAS', async ({ stores }) => {
     plugins.assert.equal(await stores.scopes.load('scope'), undefined);
-    const first = scopeSnapshot(1);
+    const first = scopeSnapshot(1, 'session-1', 'scope');
     await stores.scopes.save('scope', first, 0);
     first.sessions[0].status = 'failed';
     const loaded = await stores.scopes.load('scope');
@@ -174,15 +191,15 @@ export function createFlexStoreContractTests(
     plugins.assert.equal((await stores.scopes.load('scope'))?.sessions[0].status, 'idle');
 
     assertOneWinner(await Promise.allSettled([
-      stores.scopes.save('scope', scopeSnapshot(2, 'session-a'), 1),
-      stores.scopes.save('scope', scopeSnapshot(2, 'session-b'), 1),
+      stores.scopes.save('scope', scopeSnapshot(2, 'session-a', 'scope'), 1),
+      stores.scopes.save('scope', scopeSnapshot(2, 'session-b', 'scope'), 1),
     ]), FlexHarnessStoreConflictError);
     plugins.assert.equal((await stores.scopes.load('scope'))?.revision, 2);
   });
 
   contractTest('saves require the next revision and report the stored one', async ({ stores }) => {
-    await assertRejects(() => stores.scopes.save('scope', scopeSnapshot(2), 0), FlexHarnessStoreFormatError);
-    await assertRejects(() => stores.scopes.save('scope', scopeSnapshot(0), -1), FlexHarnessValidationError);
+    await assertRejects(() => stores.scopes.save('scope', scopeSnapshot(2, 'session-1', 'scope'), 0), FlexHarnessStoreFormatError);
+    await assertRejects(() => stores.scopes.save('scope', scopeSnapshot(0, 'session-1', 'scope'), -1), FlexHarnessValidationError);
     plugins.assert.equal(await stores.scopes.load('scope'), undefined);
 
     const saveProjection = (revision: number, expectedRevision: number) => stores.projections.save(
@@ -228,7 +245,7 @@ export function createFlexStoreContractTests(
   });
 
   contractTest('split session domains stay independent', async ({ stores }) => {
-    await stores.scopes.save('scope', scopeSnapshot(1), 0);
+    await stores.scopes.save('scope', scopeSnapshot(1, 'session-1', 'scope'), 0);
     await stores.projections.save('scope', 'session-1', createWholeProjectionChange(projectionSnapshot(1)), 0);
     await stores.permissions.save('scope', 'session-1', permissionSnapshot(1), 0);
     const eventStore = await stores.agentEvents.getStore('scope', 'session-1');
@@ -271,7 +288,7 @@ export function createFlexStoreContractTests(
   });
 
   contractTest('stores reject non-serializable snapshots at their boundary', async ({ stores }) => {
-    const invalid = scopeSnapshot(1) as unknown as Record<string, unknown>;
+    const invalid = scopeSnapshot(1, 'session-1', 'scope') as unknown as Record<string, unknown>;
     invalid.nonJson = new Date();
     await assertRejects(
       () => stores.scopes.save('scope', invalid as unknown as IFlexScopeSnapshot, 0),
@@ -618,6 +635,8 @@ export function createFlexStoreContractTests(
   contractTest('project stores fence session generations and tombstones', async ({ stores }) => {
     const store = stores.projectManagement;
     const application = { actor: 'application' as const };
+    const generationA = projectSessionContext('generation-a');
+    const generationB = projectSessionContext('generation-b', 2);
     await store.save('namespace', 'session', liveProjectState('generation-a'), 0, application);
     await assertRejects(
       () => store.save('namespace', 'session', liveProjectState('generation-a'), 0, application),
@@ -629,9 +648,12 @@ export function createFlexStoreContractTests(
       toolCallId: 'tool-call',
     });
 
-    await store.tombstoneSession('namespace', 'session', projectTombstone('generation-a', 3), 2);
-    await store.tombstoneSession('namespace', 'session', projectTombstone('generation-a', 3), 2);
-    plugins.assert.deepEqual(await store.load('namespace', 'session'), projectTombstone('generation-a', 3));
+    await store.tombstoneSession('namespace', 'session', projectTombstone('generation-a', 3), 2, generationA);
+    await store.tombstoneSession('namespace', 'session', projectTombstone('generation-a', 3), 2, generationA);
+    plugins.assert.deepEqual(
+      await store.load('namespace', 'session', generationA),
+      projectTombstone('generation-a', 3),
+    );
     await assertRejects(
       () => store.save('namespace', 'session', liveProjectState('generation-a', 4), 3, application),
       FlexHarnessStoreConflictError,
@@ -639,13 +661,13 @@ export function createFlexStoreContractTests(
 
     const replacement = liveProjectState('generation-b', 1, 2);
     await store.save('namespace', 'session', replacement, 0, application);
-    plugins.assert.deepEqual(await store.load('namespace', 'session'), replacement);
+    plugins.assert.deepEqual(await store.load('namespace', 'session', generationB), replacement);
     await assertRejects(
       () => store.save('namespace', 'session', liveProjectState('generation-c'), 0, application),
       FlexHarnessStoreConflictError,
     );
     await assertRejects(
-      () => store.tombstoneSession('namespace', 'session', projectTombstone('generation-a'), 0),
+      () => store.tombstoneSession('namespace', 'session', projectTombstone('generation-a'), 0, generationA),
       FlexHarnessStoreConflictError,
     );
   });
@@ -653,15 +675,21 @@ export function createFlexStoreContractTests(
   contractTest('project stores purge one exact namespace without affecting another', async ({ stores }) => {
     const store = stores.projectManagement;
     const application = { actor: 'application' as const };
+    const aLive = projectSessionContext('a-live');
+    const aTombstone = projectSessionContext('a-tombstone');
+    const bLive = projectSessionContext('b-live');
+    const bTombstone = projectSessionContext('b-tombstone');
+    const oldGeneration = projectSessionContext('old-generation');
     await store.save('namespace-a', 'same-id', liveProjectState('a-live'), 0, application);
-    await store.tombstoneSession('namespace-a', 'tombstoned', projectTombstone('a-tombstone'), 0);
+    await store.tombstoneSession('namespace-a', 'tombstoned', projectTombstone('a-tombstone'), 0, aTombstone);
     await store.save('namespace-b', 'same-id', liveProjectState('b-live'), 0, application);
-    await store.tombstoneSession('namespace-b', 'tombstoned', projectTombstone('b-tombstone'), 0);
+    await store.tombstoneSession('namespace-b', 'tombstoned', projectTombstone('b-tombstone'), 0, bTombstone);
     await store.tombstoneSession(
       'namespace-b',
       'generation-fence',
       projectTombstone('old-generation'),
       0,
+      oldGeneration,
     );
     await store.save(
       'namespace-b',
@@ -675,13 +703,19 @@ export function createFlexStoreContractTests(
       'generation-fence',
       projectTombstone('old-generation'),
       0,
+      oldGeneration,
     ), FlexHarnessStoreConflictError);
 
     await store.purgeNamespace('namespace-a');
-    plugins.assert.equal(await store.load('namespace-a', 'same-id'), undefined);
-    plugins.assert.equal(await store.load('namespace-a', 'tombstoned'), undefined);
-    plugins.assert.notEqual(await store.load('namespace-b', 'same-id'), undefined);
-    plugins.assert.notEqual(await store.load('namespace-b', 'tombstoned'), undefined);
+    plugins.assert.equal(await store.load('namespace-a', 'same-id', aLive), undefined);
+    plugins.assert.equal(await store.load('namespace-a', 'tombstoned', aTombstone), undefined);
+    plugins.assert.notEqual(await store.load('namespace-b', 'same-id', bLive), undefined);
+    plugins.assert.notEqual(await store.load('namespace-b', 'tombstoned', bTombstone), undefined);
+  });
+
+  if (backend.storesScopeAliases ?? true) contractTest('scope store keeps the sessions of scope aliases sharing its storage key', async ({ stores }) => {
+    await stores.scopes.save('scope', scopeSnapshot(1, 'session-1', 'alias'), 0);
+    plugins.assert.equal((await stores.scopes.load('scope'))?.sessions[0].scopeId, 'alias');
   });
 
   if (backend.storesResults) contractTest('result stores write each handle once, clone values, list and delete them', async ({ stores }) => {
@@ -738,8 +772,8 @@ export function createFlexStoreContractTests(
     const first = fixture.stores;
     const second = await fixture.openPeer();
     assertOneWinner(await Promise.allSettled([
-      first.scopes.save('shared', scopeSnapshot(1, 'first'), 0),
-      second.scopes.save('shared', scopeSnapshot(1, 'second'), 0),
+      first.scopes.save('shared', scopeSnapshot(1, 'first', 'shared'), 0),
+      second.scopes.save('shared', scopeSnapshot(1, 'second', 'shared'), 0),
     ]), FlexHarnessStoreConflictError);
     plugins.assert.deepEqual(await first.scopes.load('shared'), await second.scopes.load('shared'));
 

package/ts_stores_testing/fixtures.ts

@@ -7,14 +7,14 @@ import type {
   IFlexScopeSnapshot,
 } from '../ts/interfaces.js';
 
-/** A scope snapshot with one idle session. */
-export function scopeSnapshot(revision: number, sessionId = 'session-1'): IFlexScopeSnapshot {
+/** A scope snapshot with one idle session of `scopeId`. */
+export function scopeSnapshot(revision: number, sessionId = 'session-1', scopeId = 'scope-1'): IFlexScopeSnapshot {
   return {
     schemaVersion: 1,
     revision,
     sessions: [
       {
-        scopeId: 'scope-1',
+        scopeId,
         sessionId,
         createdAt: '2026-08-05T00:00:00.000Z',
         updatedAt: '2026-08-05T00:00:00.000Z',

package/ts_stores_testing/readme.md

@@ -31,6 +31,7 @@ for (const contractTest of createFlexStoreContractTests({
 - `sharedBackingStore`: several bundles can open one backing store, as separate processes would. The fixture's `openPeer()` opens another, and a case checks that the bundles share compare-and-swap revisions.
 - `releasesSessions`: the Agent event and tool job providers implement `releaseSession`, which must evict their session wrappers without deleting stored data.
 - `storesResults`: the bundle provides the optional `results` store.
+- `storesScopeAliases` (optional, `true` when left out): the scope store keeps a session whose `scopeId` differs from the storage key it is saved under, as a scope resolver that maps several scope IDs to one storage key saves it. A store behind a resolver whose storage key always equals the scope ID may refuse such a session and declare `false`; every other case saves each session under its own scope ID.
 
 The cases cover compare-and-swap revisions and the conflict errors that report them, cloning at the store boundary, session and storage key isolation, the snapshot validation every domain applies, and the change-based saves of projections and Agent events: a projection change keeps the stored entries its list changes name and appends the rest, an Agent event change removes, replaces and appends events, and a change that does not fit the stored value never loads, whether the store rejects it when it saves the change or when it next loads the value. The cases await every store call, as FlexHarness does, so a store method may reject or throw.