@modelprofile.com/flexharness 11.3.1 → 12.0.0

package/ts_stores_testing/contract.ts

@@ -0,0 +1,776 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessStoreConflictError,
+  FlexHarnessStoreFormatError,
+  FlexHarnessValidationError,
+} from '../ts/errors.js';
+import type {
+  IFlexHarnessStores,
+  IFlexProjectManagementSnapshot,
+  IFlexProjectManagementTombstone,
+  IFlexProjectionChange,
+  IFlexProjectionSnapshotCurrent,
+  IFlexScopeSnapshot,
+} from '../ts/interfaces.js';
+import { createWholeProjectionChange } from '../ts/utils.projectionchange.js';
+import {
+  agentEvent,
+  appendEvents,
+  finishedJob,
+  permissionSnapshot,
+  projectionSnapshot,
+  projectionWithRuns,
+  runMessages,
+  runSegment,
+  scopeSnapshot,
+} from './fixtures.js';
+
+/** One store bundle over an isolated, initially empty backing store. */
+export interface IFlexStoreContractFixture {
+  stores: IFlexHarnessStores;
+  /**
+   * Opens another bundle over the same backing store, as a second process would. Required when
+   * the backend declares `sharedBackingStore`.
+   */
+  openPeer?(): Promise<IFlexHarnessStores>;
+  /** Releases every bundle and removes the backing store. */
+  close(): Promise<void>;
+}
+
+export interface IFlexStoreContractBackend {
+  /** Names the backend in every test title. */
+  name: string;
+  /** Several bundles can open one backing store, as separate processes would. */
+  sharedBackingStore: boolean;
+  /** The Agent event and tool job providers implement `releaseSession`. */
+  releasesSessions: boolean;
+  /** The bundle provides `results`. */
+  storesResults: boolean;
+  open(): Promise<IFlexStoreContractFixture>;
+}
+
+/** One case of the store contract. It opens and closes its own fixture and throws when it fails. */
+export interface IFlexStoreContractTest {
+  title: string;
+  run(): Promise<void>;
+}
+
+type TErrorClass = abstract new (...args: never[]) => Error;
+
+function liveProjectState(
+  generation: string,
+  revision = 1,
+  sequence = 1,
+): IFlexProjectManagementSnapshot {
+  return {
+    schemaVersion: 1,
+    revision,
+    sessionGenerationId: generation,
+    sessionGenerationSequence: sequence,
+    scratchpad: '',
+    tasks: [],
+  };
+}
+
+function projectTombstone(
+  generation: string,
+  revision = 1,
+  sequence = 1,
+): IFlexProjectManagementTombstone {
+  return {
+    schemaVersion: 1,
+    revision,
+    sessionGenerationId: generation,
+    sessionGenerationSequence: sequence,
+    deletedAt: '2026-08-14T00:00:00.000Z',
+  };
+}
+
+/** 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);
+  const rejection = attempts.find((result): result is PromiseRejectedResult => result.status === 'rejected');
+  plugins.assert.ok(rejection?.reason instanceof errorClass, `expected a ${errorClass.name}, got ${String(rejection?.reason)}`);
+}
+
+/**
+ * `operation` fails as an awaiting caller sees it: FlexHarness awaits every store call, so a store
+ * may reject or throw.
+ */
+function assertRejects(
+  operation: () => unknown,
+  expected?: plugins.assert.AssertPredicate,
+): Promise<void> {
+  return expected === undefined
+    ? plugins.assert.rejects(async () => operation())
+    : plugins.assert.rejects(async () => operation(), expected);
+}
+
+/** `operation` rejects with `errorClass` and a message that contains `text`. */
+async function assertRejectsWith(
+  operation: () => Promise<unknown>,
+  errorClass: TErrorClass,
+  text: string,
+): Promise<void> {
+  await assertRejects(operation, (error: unknown) => {
+    plugins.assert.ok(error instanceof errorClass, `expected a ${errorClass.name}, got ${String(error)}`);
+    plugins.assert.ok(error.message.includes(text), `expected "${text}" in: ${error.message}`);
+    return true;
+  });
+}
+
+/**
+ * A store may check a change against the stored value when it saves it or when it next loads the
+ * value; either way the change must not load. Returns which of the two rejected it.
+ */
+async function assertChangeRejected(
+  save: () => Promise<unknown>,
+  load: () => Promise<unknown>,
+): Promise<'save' | 'load'> {
+  try {
+    await save();
+  } catch (error) {
+    plugins.assert.ok(error instanceof FlexHarnessStoreFormatError, `expected a format error, got ${String(error)}`);
+    return 'save';
+  }
+  await assertRejects(load, FlexHarnessStoreFormatError);
+  return 'load';
+}
+
+/**
+ * The behaviour every `IFlexHarnessStores` implementation shares, as test cases for any runner.
+ * Each case opens its own fixture, so backends need no cleanup between cases.
+ */
+export function createFlexStoreContractTests(
+  backend: IFlexStoreContractBackend,
+): IFlexStoreContractTest[] {
+  const tests: IFlexStoreContractTest[] = [];
+  const contractTest = (
+    title: string,
+    body: (fixture: IFlexStoreContractFixture) => Promise<void>,
+  ): void => {
+    tests.push({
+      title: `${backend.name}: ${title}`,
+      async run() {
+        const fixture = await backend.open();
+        try {
+          await body(fixture);
+        } finally {
+          await fixture.close();
+        }
+      },
+    });
+  };
+
+  contractTest('scope store clones snapshots and enforces CAS', async ({ stores }) => {
+    plugins.assert.equal(await stores.scopes.load('scope'), undefined);
+    const first = scopeSnapshot(1);
+    await stores.scopes.save('scope', first, 0);
+    first.sessions[0].status = 'failed';
+    const loaded = await stores.scopes.load('scope');
+    plugins.assert.ok(loaded);
+    plugins.assert.equal(loaded.sessions[0].status, 'idle');
+    loaded.sessions[0].status = 'failed';
+    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),
+    ]), 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);
+    plugins.assert.equal(await stores.scopes.load('scope'), undefined);
+
+    const saveProjection = (revision: number, expectedRevision: number) => stores.projections.save(
+      'scope',
+      'session-1',
+      createWholeProjectionChange(projectionSnapshot(revision)),
+      expectedRevision,
+    );
+    await saveProjection(1, 0);
+    await saveProjection(2, 1);
+    await assertRejects(() => saveProjection(4, 2), FlexHarnessStoreFormatError);
+    await assertRejects(() => saveProjection(2, 1), (error: unknown) => {
+      plugins.assert.ok(error instanceof FlexHarnessStoreConflictError);
+      plugins.assert.equal(error.expectedRevision, 1);
+      plugins.assert.equal(error.actualRevision, 2);
+      return true;
+    });
+    plugins.assert.equal((await stores.projections.load('scope', 'session-1'))?.revision, 2);
+
+    await stores.permissions.save('scope', 'session-1', permissionSnapshot(1), 0);
+    await assertRejects(
+      () => stores.permissions.save('scope', 'session-1', permissionSnapshot(1), 0),
+      FlexHarnessStoreConflictError,
+    );
+  });
+
+  contractTest('session records are exact per storage key and session', async ({ stores }) => {
+    const projection = createWholeProjectionChange(projectionSnapshot(1));
+    await stores.projections.save('namespace-a', 'session', projection, 0);
+    await stores.permissions.save('namespace-a', 'session', permissionSnapshot(1), 0);
+    plugins.assert.equal(await stores.projections.load('namespace-b', 'session'), undefined);
+    plugins.assert.equal(await stores.permissions.load('namespace-b', 'session'), undefined);
+    plugins.assert.equal(await stores.projections.load('namespace-a', 'other'), undefined);
+    await stores.projections.save('namespace-b', 'session', projection, 0);
+
+    const eventsA = await stores.agentEvents.getStore('namespace-a', 'session');
+    const eventsB = await stores.agentEvents.getStore('namespace-b', 'session');
+    await eventsA.save('session', appendEvents(agentEvent('event-a')), 0);
+    plugins.assert.equal(await eventsB.load('session'), undefined);
+    await stores.projections.deleteSession('namespace-a', 'session');
+    plugins.assert.equal(await stores.projections.load('namespace-a', 'session'), undefined);
+    plugins.assert.equal((await stores.projections.load('namespace-b', 'session'))?.revision, 1);
+  });
+
+  contractTest('split session domains stay independent', async ({ stores }) => {
+    await stores.scopes.save('scope', scopeSnapshot(1), 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');
+    const jobStore = await stores.jobs.getStore('scope', 'session-1');
+    plugins.assert.equal(await eventStore.save('session-1', appendEvents(), 0), 1);
+    plugins.assert.equal(await jobStore.save([], 0), 1);
+
+    plugins.assert.equal((await stores.scopes.load('scope'))?.sessions.length, 1);
+    plugins.assert.equal((await stores.projections.load('scope', 'session-1'))?.revision, 1);
+    plugins.assert.deepEqual(
+      (await stores.permissions.load('scope', 'session-1'))?.rememberedPermissionKeys,
+      ['shell:approved'],
+    );
+    plugins.assert.equal((await eventStore.load('session-1'))?.revision, 1);
+    plugins.assert.equal((await jobStore.load())?.revision, 1);
+    plugins.assert.equal(await stores.projections.load('scope', 'another-session'), undefined);
+
+    await Promise.all([
+      stores.projections.deleteSession('scope', 'session-1'),
+      stores.permissions.deleteSession('scope', 'session-1'),
+      stores.agentEvents.deleteSession('scope', 'session-1'),
+      stores.jobs.deleteSession('scope', 'session-1'),
+    ]);
+    plugins.assert.equal(await stores.projections.load('scope', 'session-1'), undefined);
+    plugins.assert.equal(await stores.permissions.load('scope', 'session-1'), undefined);
+    plugins.assert.equal(await eventStore.load('session-1'), undefined);
+    plugins.assert.equal(await jobStore.load(), undefined);
+    plugins.assert.notEqual(await stores.agentEvents.getStore('scope', 'session-1'), eventStore);
+    plugins.assert.notEqual(await stores.jobs.getStore('scope', 'session-1'), jobStore);
+    plugins.assert.equal((await stores.scopes.load('scope'))?.sessions.length, 1);
+
+    await stores.agentEvents.deleteSession('scope', 'unknown');
+    await stores.jobs.deleteSession('scope', 'unknown');
+    const unknownEventStore = await stores.agentEvents.getStore('scope', 'unknown');
+    const unknownJobStore = await stores.jobs.getStore('scope', 'unknown');
+    await stores.agentEvents.deleteSession('scope', 'unknown');
+    await stores.jobs.deleteSession('scope', 'unknown');
+    plugins.assert.notEqual(await stores.agentEvents.getStore('scope', 'unknown'), unknownEventStore);
+    plugins.assert.notEqual(await stores.jobs.getStore('scope', 'unknown'), unknownJobStore);
+  });
+
+  contractTest('stores reject non-serializable snapshots at their boundary', async ({ stores }) => {
+    const invalid = scopeSnapshot(1) as unknown as Record<string, unknown>;
+    invalid.nonJson = new Date();
+    await assertRejects(
+      () => stores.scopes.save('scope', invalid as unknown as IFlexScopeSnapshot, 0),
+      FlexHarnessStoreFormatError,
+    );
+  });
+
+  contractTest('projection saves apply list changes to the stored lists', async ({ stores }) => {
+    const save = (change: IFlexProjectionChange, expectedRevision: number) =>
+      stores.projections.save('scope', 'session-1', change, expectedRevision);
+    const load = () => stores.projections.load('scope', 'session-1');
+    await save(createWholeProjectionChange(projectionWithRuns(1, ['run-1'])), 0);
+
+    const appended = projectionWithRuns(2, ['run-1', 'run-2']);
+    await save({
+      ...appended,
+      messages: { start: 0, end: 2, items: runMessages('run-2') },
+      reversionSegments: { start: 0, end: 1, items: [runSegment('run-2')] },
+    }, 1);
+    plugins.assert.deepEqual(await load(), appended);
+
+    const trimmed = projectionWithRuns(3, ['run-2', 'run-3']);
+    await save({
+      ...trimmed,
+      messages: { start: 2, end: 4, items: runMessages('run-3') },
+      reversionSegments: { start: 1, end: 2, items: [runSegment('run-3')] },
+    }, 2);
+    plugins.assert.deepEqual(await load(), trimmed);
+
+    const replaced = projectionWithRuns(4, ['run-4']);
+    await save(createWholeProjectionChange(replaced), 3);
+    plugins.assert.deepEqual(await load(), replaced);
+
+    const emptied = projectionSnapshot(5);
+    await save(createWholeProjectionChange(emptied), 4);
+    plugins.assert.deepEqual(await load(), emptied);
+  });
+
+  contractTest('projection changes are checked in form and against the stored lists', async ({ stores }) => {
+    const save = (change: IFlexProjectionChange, expectedRevision: number) =>
+      stores.projections.save('scope', 'session-1', change, expectedRevision);
+    await save(createWholeProjectionChange(projectionWithRuns(1, ['run-1'])), 0);
+    const next = projectionWithRuns(2, ['run-1', 'run-2']);
+    const whole = createWholeProjectionChange(next);
+    const malformed: IFlexProjectionChange[] = [
+      { ...whole, messages: { start: 1, end: 0, items: next.messages } },
+      { ...whole, messages: { start: -1, end: 0, items: next.messages } },
+      { ...whole, reversionSegments: { start: 0, end: 0, items: 'segments' as never } },
+      { ...whole, schemaVersion: 2 as never },
+    ];
+    for (const change of malformed) {
+      await assertRejects(() => save(change, 1), FlexHarnessStoreFormatError);
+    }
+    plugins.assert.equal((await stores.projections.load('scope', 'session-1'))?.revision, 1);
+
+    const rejectedBy = await assertChangeRejected(
+      () => save({
+        ...next,
+        messages: { start: 0, end: 4, items: [] },
+        reversionSegments: { start: 0, end: 2, items: [] },
+      }, 1),
+      () => stores.projections.load('scope', 'session-1'),
+    );
+    if (rejectedBy === 'save') {
+      plugins.assert.equal((await stores.projections.load('scope', 'session-1'))?.revision, 1);
+    }
+  });
+
+  contractTest('projection validation rejects public attachment payload fields', async ({ stores }) => {
+    const invalid: IFlexProjectionSnapshotCurrent = {
+      ...projectionSnapshot(1),
+      messages: [
+        {
+          messageId: 'message',
+          sessionId: 'session-1',
+          runId: 'run',
+          role: 'user',
+          status: 'completed',
+          createdAt: '2026-08-05T00:00:00.000Z',
+          parts: [
+            {
+              partId: 'attachment',
+              type: 'attachment',
+              attachmentType: 'file',
+              source: 'inline-base64',
+              data: 'c2VjcmV0',
+            } as never,
+          ],
+        },
+      ],
+    };
+    await assertRejects(
+      () => stores.projections.save('scope', 'session-1', createWholeProjectionChange(invalid), 0),
+      FlexHarnessStoreFormatError,
+    );
+  });
+
+  contractTest('projection validation rejects malformed reversion ownership and correlation', async ({ stores }) => {
+    const base = projectionWithRuns(1, ['run']);
+    const segment = base.reversionSegments[0];
+    const invalidSnapshots: IFlexProjectionSnapshotCurrent[] = [
+      {
+        ...structuredClone(base),
+        reversionSegments: [{ ...segment, workspaceCaptured: true, captureId: 'capture' }],
+      },
+      {
+        ...structuredClone(base),
+        reversionSegments: [{
+          ...segment,
+          status: 'capturing',
+          workspaceCaptured: true,
+          captureId: 'capture',
+        }],
+        revertCursor: 0,
+      },
+      {
+        ...structuredClone(base),
+        messages: [...runMessages('failed'), ...runMessages('run')],
+        reversionSegments: [
+          { ...runSegment('failed'), status: 'failed', eventIds: ['event-shared'] },
+          { ...segment, eventIds: ['event-shared'] },
+        ],
+      },
+      {
+        ...structuredClone(base),
+        messages: [...runMessages('failed'), ...runMessages('run')],
+        reversionSegments: [{ ...runSegment('failed'), status: 'failed' }, segment],
+        pendingReversion: {
+          kind: 'apply',
+          operationId: 'apply',
+          direction: 'undo',
+          fromCursor: 1,
+          toCursor: 0,
+          segmentRunIds: ['failed', 'run'],
+          appliedRunIds: ['failed'],
+        },
+      },
+    ];
+    for (let index = 0; index < invalidSnapshots.length; index++) {
+      await assertRejects(() => stores.projections.save(
+        `invalid-reversion-${index}`,
+        'session-1',
+        createWholeProjectionChange(invalidSnapshots[index]),
+        0,
+      ), FlexHarnessStoreFormatError);
+    }
+  });
+
+  contractTest('projection schema 3 validates protocol-2 metadata, dispositions, and release ownership', async ({ stores }) => {
+    const valid: IFlexProjectionSnapshotCurrent = {
+      ...projectionWithRuns(1, ['run']),
+      reversionSegments: [{
+        ...runSegment('run'),
+        workspaceCaptured: true,
+        protocolVersion: 2,
+        provenance: 'workspace',
+        disposition: 'no-change',
+        affectedWorkspaces: [],
+      }],
+    };
+    await stores.projections.save('valid-schema-3', 'session-1', createWholeProjectionChange(valid), 0);
+    plugins.assert.deepEqual(await stores.projections.load('valid-schema-3', 'session-1'), valid);
+
+    const segment = valid.reversionSegments[0];
+    const invalid: IFlexProjectionSnapshotCurrent[] = [
+      { ...structuredClone(valid), reversionSegments: [{ ...segment, disposition: 'pending' }] },
+      { ...structuredClone(valid), reversionSegments: [{ ...segment, disposition: 'nonrevertible' }] },
+      {
+        ...structuredClone(valid),
+        reversionSegments: [{
+          ...segment,
+          affectedWorkspaces: [{ id: 'workspace', label: 'Workspace' }],
+        }],
+      },
+      {
+        ...structuredClone(valid),
+        reversionSegments: [{
+          ...segment,
+          disposition: 'revertible',
+          captureId: 'capture',
+          workspaceReference: { capture: true },
+          affectedWorkspaces: [{ id: 'workspace', label: 'Workspace' }],
+        }],
+        pendingReversionReleases: [{
+          runId: 'run',
+          captureId: 'capture',
+          reference: { capture: true },
+          protocolVersion: 2,
+        }],
+      },
+      {
+        ...structuredClone(valid),
+        reversionSegments: [{
+          ...segment,
+          disposition: 'revertible',
+          captureId: 'capture-whitespace-id',
+          workspaceReference: { capture: true },
+          affectedWorkspaces: [{ id: '   ', label: 'Workspace' }],
+        }],
+      },
+      {
+        ...structuredClone(valid),
+        reversionSegments: [{
+          ...segment,
+          disposition: 'revertible',
+          captureId: 'capture-whitespace-label',
+          workspaceReference: { capture: true },
+          affectedWorkspaces: [{ id: 'workspace', label: '\t' }],
+        }],
+      },
+      {
+        ...structuredClone(valid),
+        reversionSegments: [{ ...segment, disposition: 'nonrevertible', reasonCode: 'git conflict' }],
+      },
+    ];
+    for (let index = 0; index < invalid.length; index++) {
+      await assertRejects(() => stores.projections.save(
+        `invalid-schema-3-${index}`,
+        'session-1',
+        createWholeProjectionChange(invalid[index]),
+        0,
+      ), FlexHarnessStoreFormatError);
+    }
+  });
+
+  contractTest('Agent event saves apply removals, replacements and appends', async ({ stores }) => {
+    const eventStore = await stores.agentEvents.getStore('scope', 'session');
+    plugins.assert.equal(await eventStore.save('session', appendEvents(agentEvent('first'), agentEvent('second')), 0), 1);
+    const replacement = agentEvent('second', 'Replaced prompt');
+    plugins.assert.equal(await eventStore.save('session', {
+      remove: ['first'],
+      replace: [replacement],
+      append: [agentEvent('third')],
+    }, 1), 2);
+    const snapshot = await eventStore.load('session');
+    plugins.assert.ok(snapshot);
+    plugins.assert.equal(snapshot.revision, 2);
+    plugins.assert.deepEqual(snapshot.events, [replacement, agentEvent('third')]);
+
+    const rejectedBy = await assertChangeRejected(
+      () => eventStore.save('session', { remove: ['first'], replace: [], append: [] }, 2),
+      () => eventStore.load('session'),
+    );
+    if (rejectedBy === 'save') plugins.assert.equal((await eventStore.load('session'))?.revision, 2);
+  });
+
+  contractTest('Agent stores validate every change after strict JSON safety', async ({ stores }) => {
+    const eventStore = await stores.agentEvents.getStore('scope', 'session');
+    plugins.assert.ok(eventStore.archive, `${backend.name} Agent event stores must archive.`);
+    const canonicalEvent = agentEvent();
+
+    plugins.assert.equal(canonicalEvent.sequence, undefined);
+    plugins.assert.equal(await eventStore.save('session', appendEvents(canonicalEvent), 0), 1);
+    await eventStore.archive({
+      schemaVersion: 2,
+      sessionId: 'session',
+      archiveId: 'archive',
+      createdAt: 1,
+      events: [canonicalEvent],
+    });
+
+    const malformedEvent = { ...canonicalEvent, id: 'malformed', content: 42 } as unknown as plugins.TAgentEvent;
+    await assertRejectsWith(
+      () => eventStore.save('session', appendEvents(malformedEvent), 1),
+      FlexHarnessStoreFormatError,
+      'append[0].content',
+    );
+    await assertRejectsWith(() => eventStore.archive!({
+      schemaVersion: 2,
+      sessionId: 'session',
+      archiveId: 'malformed',
+      createdAt: 1,
+      events: [malformedEvent],
+    }), FlexHarnessStoreFormatError, 'Agent event archive events[0].content');
+
+    const unsafeEvent = { ...canonicalEvent, id: 'unsafe', content: new Date() } as unknown as plugins.TAgentEvent;
+    await assertRejectsWith(
+      () => eventStore.save('session', appendEvents(unsafeEvent), 1),
+      FlexHarnessStoreFormatError,
+      '$change.append[0].content',
+    );
+    plugins.assert.equal((await eventStore.load('session'))?.revision, 1);
+  });
+
+  contractTest('Agent event stores are session-bound, CAS-safe, and archive once', async ({ stores }) => {
+    const eventStore = await stores.agentEvents.getStore('scope', 'session');
+    plugins.assert.ok(eventStore.archive && eventStore.loadArchive, `${backend.name} Agent event stores must archive.`);
+    await assertRejects(() => eventStore.load('other-session'), FlexHarnessValidationError);
+    plugins.assert.equal(await eventStore.save('session', appendEvents(agentEvent('first')), 0), 1);
+    await assertRejects(
+      () => eventStore.save('session', appendEvents(agentEvent('second')), 0),
+      (error: unknown) => {
+        plugins.assert.ok(error instanceof plugins.AgentEventStoreConflictError);
+        plugins.assert.equal(error.actualRevision, 1);
+        return true;
+      },
+    );
+    plugins.assert.equal(await eventStore.save('session', appendEvents(agentEvent('second')), 1), 2);
+    const snapshot = await eventStore.load('session');
+    plugins.assert.ok(snapshot);
+    plugins.assert.equal(snapshot.schemaVersion, 2);
+    plugins.assert.equal(snapshot.revision, 2);
+    plugins.assert.deepEqual(snapshot.events.map((event) => event.id), ['first', 'second']);
+
+    const archive: plugins.IAgentEventArchive = {
+      schemaVersion: 2,
+      sessionId: 'session',
+      archiveId: 'archive',
+      createdAt: 1,
+      events: [agentEvent('first')],
+    };
+    plugins.assert.equal(await eventStore.loadArchive('session', 'archive'), undefined);
+    await eventStore.archive(archive);
+    await eventStore.archive(structuredClone(archive));
+    plugins.assert.deepEqual(await eventStore.loadArchive('session', 'archive'), archive);
+    await assertRejects(() => eventStore.archive!({ ...archive, events: [agentEvent('second')] }));
+    plugins.assert.equal((await eventStore.loadArchive('session', 'archive'))?.events[0].id, 'first');
+
+    await stores.agentEvents.deleteSession('scope', 'session');
+    const reopened = await stores.agentEvents.getStore('scope', 'session');
+    plugins.assert.equal(await reopened.load('session'), undefined);
+    plugins.assert.equal(await reopened.loadArchive?.('session', 'archive'), undefined);
+  });
+
+  contractTest('tool job stores are CAS-safe and honour abort signals', async ({ stores }) => {
+    const jobStore = await stores.jobs.getStore('scope', 'session');
+    plugins.assert.equal(await jobStore.save([finishedJob()], 0), 1);
+    await assertRejects(() => jobStore.save([], 0), (error: unknown) => {
+      plugins.assert.ok(error instanceof plugins.ToolJobStoreConflictError);
+      plugins.assert.equal(error.actualRevision, 1);
+      return true;
+    });
+    const snapshot = await jobStore.load();
+    plugins.assert.ok(snapshot);
+    plugins.assert.equal(snapshot.revision, 1);
+    plugins.assert.deepEqual(snapshot.jobs, [finishedJob()]);
+
+    const aborted = AbortSignal.abort(new Error('caller aborted'));
+    await assertRejects(() => jobStore.load(aborted), { message: 'caller aborted' });
+    await assertRejects(() => jobStore.save([], 1, aborted), { message: 'caller aborted' });
+    plugins.assert.equal((await jobStore.load())?.revision, 1);
+  });
+
+  contractTest('project stores fence session generations and tombstones', async ({ stores }) => {
+    const store = stores.projectManagement;
+    const application = { actor: 'application' as const };
+    await store.save('namespace', 'session', liveProjectState('generation-a'), 0, application);
+    await assertRejects(
+      () => store.save('namespace', 'session', liveProjectState('generation-a'), 0, application),
+      FlexHarnessStoreConflictError,
+    );
+    await store.save('namespace', 'session', liveProjectState('generation-a', 2), 1, {
+      actor: 'agent',
+      runId: 'run',
+      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 assertRejects(
+      () => store.save('namespace', 'session', liveProjectState('generation-a', 4), 3, application),
+      FlexHarnessStoreConflictError,
+    );
+
+    const replacement = liveProjectState('generation-b', 1, 2);
+    await store.save('namespace', 'session', replacement, 0, application);
+    plugins.assert.deepEqual(await store.load('namespace', 'session'), replacement);
+    await assertRejects(
+      () => store.save('namespace', 'session', liveProjectState('generation-c'), 0, application),
+      FlexHarnessStoreConflictError,
+    );
+    await assertRejects(
+      () => store.tombstoneSession('namespace', 'session', projectTombstone('generation-a'), 0),
+      FlexHarnessStoreConflictError,
+    );
+  });
+
+  contractTest('project stores purge one exact namespace without affecting another', async ({ stores }) => {
+    const store = stores.projectManagement;
+    const application = { actor: 'application' as const };
+    await store.save('namespace-a', 'same-id', liveProjectState('a-live'), 0, application);
+    await store.tombstoneSession('namespace-a', 'tombstoned', projectTombstone('a-tombstone'), 0);
+    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',
+      'generation-fence',
+      projectTombstone('old-generation'),
+      0,
+    );
+    await store.save(
+      'namespace-b',
+      'generation-fence',
+      liveProjectState('new-generation', 1, 2),
+      0,
+      application,
+    );
+    await assertRejects(() => store.tombstoneSession(
+      'namespace-b',
+      'generation-fence',
+      projectTombstone('old-generation'),
+      0,
+    ), 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);
+  });
+
+  if (backend.storesResults) contractTest('result stores write each handle once, clone values, list and delete them', async ({ stores }) => {
+    const results = stores.results;
+    plugins.assert.ok(results, `${backend.name} declares storesResults without a result store.`);
+    const large = { items: Array.from({ length: 2000 }, (_, index) => ({ index, text: 'x'.repeat(600) })) };
+    plugins.assert.equal(await results.load('scope', 'session-1', 'res_1'), undefined);
+    await results.save('scope', 'session-1', 'res_1', large);
+    await results.save('scope', 'session-2', 'res_1', 'other session');
+    const loaded = (await results.load('scope', 'session-1', 'res_1')) as typeof large;
+    plugins.assert.deepEqual(loaded, large);
+    loaded.items[0].text = 'changed';
+    plugins.assert.equal(
+      ((await results.load('scope', 'session-1', 'res_1')) as typeof large).items[0].text,
+      'x'.repeat(600),
+    );
+    await assertRejects(() => results.save('scope', 'session-1', 'res_1', 'again'), FlexHarnessStoreConflictError);
+    await results.save('scope', 'session-1', 'res_2', 2);
+    await results.save('scope', 'session-1', 'res_3', 3);
+    plugins.assert.deepEqual(await results.list('scope', 'session-1'), ['res_1', 'res_2', 'res_3']);
+    await results.delete('scope', 'session-1', 'res_2');
+    plugins.assert.deepEqual(await results.list('scope', 'session-1'), ['res_1', 'res_3']);
+    plugins.assert.equal(await results.load('scope', 'session-1', 'res_2'), undefined);
+    plugins.assert.equal(await results.load('scope', 'session-1', 'res_3'), 3);
+    await results.deleteSession('scope', 'session-1');
+    plugins.assert.equal(await results.load('scope', 'session-1', 'res_1'), undefined);
+    plugins.assert.deepEqual(await results.list('scope', 'session-1'), []);
+    plugins.assert.equal(await results.load('scope', 'session-2', 'res_1'), 'other session');
+    plugins.assert.deepEqual(await results.list('scope', 'session-2'), ['res_1']);
+  });
+
+  if (backend.releasesSessions) contractTest('provider release evicts wrappers without deleting persisted session data', async ({ stores }) => {
+    const eventStore = await stores.agentEvents.getStore('release', 'session');
+    const jobStore = await stores.jobs.getStore('release', 'session');
+    await eventStore.save('session', appendEvents(agentEvent()), 0);
+    await jobStore.save([], 0);
+    plugins.assert.ok(
+      stores.agentEvents.releaseSession && stores.jobs.releaseSession,
+      `${backend.name} declares releasesSessions without releaseSession hooks.`,
+    );
+
+    await stores.agentEvents.releaseSession('release', 'session');
+    await stores.jobs.releaseSession('release', 'session');
+    const reloadedEventStore = await stores.agentEvents.getStore('release', 'session');
+    const reloadedJobStore = await stores.jobs.getStore('release', 'session');
+    plugins.assert.notEqual(reloadedEventStore, eventStore);
+    plugins.assert.notEqual(reloadedJobStore, jobStore);
+    plugins.assert.equal((await reloadedEventStore.load('session'))?.revision, 1);
+    plugins.assert.equal((await reloadedJobStore.load())?.revision, 1);
+  });
+
+  if (backend.sharedBackingStore) contractTest('bundles over one backing store share CAS revisions', async (fixture) => {
+    plugins.assert.ok(fixture.openPeer, `${backend.name} declares sharedBackingStore without openPeer.`);
+    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),
+    ]), FlexHarnessStoreConflictError);
+    plugins.assert.deepEqual(await first.scopes.load('shared'), await second.scopes.load('shared'));
+
+    const firstEvents = await first.agentEvents.getStore('shared', 'session');
+    const secondEvents = await second.agentEvents.getStore('shared', 'session');
+    await firstEvents.save('session', appendEvents(agentEvent('from-first')), 0);
+    plugins.assert.equal((await secondEvents.load('session'))?.events[0].id, 'from-first');
+    await assertRejects(
+      () => secondEvents.save('session', appendEvents(agentEvent('stale')), 0),
+      plugins.AgentEventStoreConflictError,
+    );
+    await secondEvents.save('session', appendEvents(agentEvent('from-second')), 1);
+    plugins.assert.deepEqual(
+      (await firstEvents.load('session'))?.events.map((event) => event.id),
+      ['from-first', 'from-second'],
+    );
+
+    const projection = projectionWithRuns(1, ['run-1']);
+    await first.projections.save('shared', 'session-1', createWholeProjectionChange(projection), 0);
+    const appended = projectionWithRuns(2, ['run-1', 'run-2']);
+    await second.projections.save('shared', 'session-1', {
+      ...appended,
+      messages: { start: 0, end: 2, items: runMessages('run-2') },
+      reversionSegments: { start: 0, end: 1, items: [runSegment('run-2')] },
+    }, 1);
+    plugins.assert.deepEqual(await first.projections.load('shared', 'session-1'), appended);
+
+    await first.permissions.save('shared', 'session', permissionSnapshot(1), 0);
+    await second.permissions.deleteSession('shared', 'session');
+    plugins.assert.equal(await first.permissions.load('shared', 'session'), undefined);
+  });
+
+  return tests;
+}