@modelprofile.com/flexharness 2.1.0 → 3.0.1

package/ts/classes.stores.ts

@@ -1,20 +1,53 @@
 import * as plugins from './plugins.js';
 import {
+  FlexHarnessStoreCommitUncertainError,
   FlexHarnessStoreConflictError,
   FlexHarnessStoreFormatError,
   FlexHarnessValidationError,
 } from './errors.js';
-import type { IFlexHarnessSnapshot, IFlexHarnessStore } from './interfaces.js';
-import { assertFlexHarnessSnapshot, cloneSerializable } from './utils.json.js';
+import type {
+  IFlexAgentEventStoreProvider,
+  IFlexHarnessStores,
+  IFlexPermissionSnapshot,
+  IFlexPermissionStore,
+  IFlexProjectionSnapshot,
+  IFlexProjectionStore,
+  IFlexScopeSnapshot,
+  IFlexScopeStore,
+  IFlexToolJobStoreProvider,
+} from './interfaces.js';
+import {
+  assertFlexPermissionSnapshot,
+  assertFlexProjectionSnapshot,
+  assertFlexScopeSnapshot,
+  assertJsonSerializable,
+  cloneSerializable,
+} from './utils.json.js';
 
-function validateSave(
-  snapshot: IFlexHarnessSnapshot,
-  expectedRevision: number,
-): IFlexHarnessSnapshot {
-  assertFlexHarnessSnapshot(snapshot);
+type TSnapshot = IFlexScopeSnapshot | IFlexProjectionSnapshot | IFlexPermissionSnapshot;
+type TSnapshotValidator<TSnapshotValue extends TSnapshot> = (
+  value: unknown,
+) => asserts value is TSnapshotValue;
+
+function validateIdentifier(value: string, name: string): void {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new FlexHarnessValidationError(`${name} must be a non-empty string.`);
+  }
+}
+
+function validateExpectedRevision(expectedRevision: number): void {
   if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
     throw new FlexHarnessValidationError('expectedRevision must be a non-negative integer.');
   }
+}
+
+function validateSnapshotSave<TSnapshotValue extends TSnapshot>(
+  snapshot: TSnapshotValue,
+  expectedRevision: number,
+  validator: TSnapshotValidator<TSnapshotValue>,
+): TSnapshotValue {
+  validator(snapshot);
+  validateExpectedRevision(expectedRevision);
   if (snapshot.revision !== expectedRevision + 1) {
     throw new FlexHarnessStoreFormatError(
       `Snapshot revision ${snapshot.revision} must equal expected revision ${expectedRevision} plus one.`,
@@ -23,20 +56,291 @@ function validateSave(
   return cloneSerializable(snapshot);
 }
 
-export class InMemoryFlexHarnessStore implements IFlexHarnessStore {
-  private readonly snapshots = new Map<string, IFlexHarnessSnapshot>();
+function providerKey(storageKey: string, sessionId: string): string {
+  validateIdentifier(storageKey, 'storageKey');
+  validateIdentifier(sessionId, 'sessionId');
+  return JSON.stringify([storageKey, sessionId]);
+}
+
+function assertProjectionSession(snapshot: IFlexProjectionSnapshot, sessionId: string): void {
+  for (const message of snapshot.messages) {
+    if (message.sessionId !== sessionId) {
+      throw new FlexHarnessStoreFormatError(
+        `Projection message "${message.messageId}" does not belong to session "${sessionId}".`,
+      );
+    }
+  }
+  for (const terminal of snapshot.stagedTerminals) {
+    if (
+      terminal.userMessage.sessionId !== sessionId
+      || terminal.assistantMessage.sessionId !== sessionId
+    ) {
+      throw new FlexHarnessStoreFormatError(
+        `Staged terminal "${terminal.runId}" does not belong to session "${sessionId}".`,
+      );
+    }
+  }
+}
+
+function normalizeJsonObjectUndefined<TValue>(value: TValue, path = '$'): TValue {
+  const seen = new WeakSet<object>();
+  const visit = (current: unknown, currentPath: string): unknown => {
+    if (
+      current === null
+      || typeof current === 'string'
+      || typeof current === 'boolean'
+    ) return current;
+    if (typeof current === 'number') {
+      if (!Number.isFinite(current)) {
+        throw new FlexHarnessStoreFormatError(`${currentPath} contains a non-finite number.`);
+      }
+      return current;
+    }
+    if (typeof current !== 'object') {
+      throw new FlexHarnessStoreFormatError(
+        `${currentPath} contains ${typeof current}, which is not JSON-safe.`,
+      );
+    }
+    if (seen.has(current)) {
+      throw new FlexHarnessStoreFormatError(`${currentPath} contains a circular reference.`);
+    }
+    const prototype = Object.getPrototypeOf(current);
+    if (!Array.isArray(current) && prototype !== Object.prototype && prototype !== null) {
+      throw new FlexHarnessStoreFormatError(`${currentPath} contains a non-plain object.`);
+    }
+    if (Object.getOwnPropertySymbols(current).length > 0) {
+      throw new FlexHarnessStoreFormatError(`${currentPath} contains a symbol-keyed property.`);
+    }
+    seen.add(current);
+    if (Array.isArray(current)) {
+      const result = current.map((entry, index) => {
+        if (!(index in current) || entry === undefined) {
+          throw new FlexHarnessStoreFormatError(`${currentPath}[${index}] is not JSON-safe.`);
+        }
+        return visit(entry, `${currentPath}[${index}]`);
+      });
+      seen.delete(current);
+      return result;
+    }
+    const result: Record<string, unknown> = {};
+    for (const key of Object.getOwnPropertyNames(current)) {
+      const descriptor = Object.getOwnPropertyDescriptor(current, key)!;
+      if (!descriptor.enumerable || !('value' in descriptor)) {
+        throw new FlexHarnessStoreFormatError(`${currentPath}.${key} is not a plain JSON property.`);
+      }
+      if (descriptor.value !== undefined) {
+        result[key] = visit(descriptor.value, `${currentPath}.${key}`);
+      }
+    }
+    seen.delete(current);
+    return result;
+  };
+  const normalized = visit(value, path);
+  assertJsonSerializable(normalized, path);
+  return normalized as TValue;
+}
+
+function assertNonEmptyString(value: unknown, path: string): asserts value is string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a non-empty string.`);
+  }
+}
+
+function assertNonNegativeInteger(value: unknown, path: string): asserts value is number {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a non-negative integer.`);
+  }
+}
+
+function assertExactKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  path: string,
+): void {
+  const invalidKey = Object.keys(value).find((key) => !keys.includes(key));
+  if (invalidKey) {
+    throw new FlexHarnessStoreFormatError(`${path}.${invalidKey} is not supported.`);
+  }
+}
+
+function assertRecord(value: unknown, path: string): asserts value is Record<string, unknown> {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+  ) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a plain object.`);
+  }
+}
+
+function createAgentEventSnapshot(
+  sessionId: string,
+  events: readonly plugins.TAgentEvent[],
+  revision: number,
+): plugins.IAgentEventSnapshotV2 {
+  return {
+    schemaVersion: 2,
+    sessionId,
+    revision,
+    updatedAt: events.reduce((latest, event) => Math.max(latest, event.timestamp), 0),
+    events: normalizeJsonObjectUndefined([...events], '$events'),
+  };
+}
+
+function validateAgentEventSnapshot(
+  value: unknown,
+  sessionId: string,
+): plugins.IAgentEventSnapshotV2 {
+  assertJsonSerializable(value, '$snapshot');
+  try {
+    return plugins.validateAgentEventSnapshotV2(value, sessionId);
+  } catch (error) {
+    throw new FlexHarnessStoreFormatError(
+      `$snapshot is not a canonical schema-2 Agent event snapshot: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}
 
-  public async load(storageKey: string): Promise<IFlexHarnessSnapshot | undefined> {
+function validateAgentEventArchive(
+  value: unknown,
+  sessionId: string,
+  archiveId: string,
+): plugins.IAgentEventArchiveV2 {
+  assertJsonSerializable(value, '$archive');
+  try {
+    return plugins.validateAgentEventArchiveV2(value, sessionId, archiveId);
+  } catch (error) {
+    throw new FlexHarnessStoreFormatError(
+      `$archive is not a canonical schema-2 Agent event archive: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+function validateToolJobSnapshot(value: unknown): plugins.IToolJobSnapshot {
+  assertJsonSerializable(value, '$snapshot');
+  assertRecord(value, '$snapshot');
+  assertExactKeys(value, ['schemaVersion', 'revision', 'updatedAt', 'jobs'], '$snapshot');
+  if (value.schemaVersion !== 1) {
+    throw new FlexHarnessStoreFormatError('Tool job snapshot schemaVersion must be 1.');
+  }
+  assertNonNegativeInteger(value.revision, '$snapshot.revision');
+  assertNonNegativeInteger(value.updatedAt, '$snapshot.updatedAt');
+  if (!Array.isArray(value.jobs)) {
+    throw new FlexHarnessStoreFormatError('$snapshot.jobs must be an array.');
+  }
+  const executionIds = new Set<string>();
+  for (let index = 0; index < value.jobs.length; index++) {
+    const path = `$snapshot.jobs[${index}]`;
+    assertRecord(value.jobs[index], path);
+    const job = value.jobs[index];
+    assertExactKeys(
+      job,
+      [
+        'executionId',
+        'type',
+        'state',
+        'request',
+        'exitCode',
+        'stdout',
+        'stderr',
+        'signal',
+        'startedAt',
+        'updatedAt',
+        'finishedAt',
+      ],
+      path,
+    );
+    assertNonEmptyString(job.executionId, `${path}.executionId`);
+    if (executionIds.has(job.executionId)) {
+      throw new FlexHarnessStoreFormatError(`$snapshot.jobs contains duplicate job "${job.executionId}".`);
+    }
+    executionIds.add(job.executionId);
+    assertNonEmptyString(job.type, `${path}.type`);
+    if (!['running', 'finished', 'failed', 'aborted'].includes(String(job.state))) {
+      throw new FlexHarnessStoreFormatError(`${path}.state is invalid.`);
+    }
+    if (job.request !== undefined) {
+      const requestPath = `${path}.request`;
+      assertRecord(job.request, requestPath);
+      assertExactKeys(
+        job.request,
+        ['type', 'command', 'cwd', 'timeoutMs', 'metadata'],
+        requestPath,
+      );
+      assertNonEmptyString(job.request.type, `${requestPath}.type`);
+      if (job.request.command !== undefined) {
+        const commandPath = `${requestPath}.command`;
+        assertRecord(job.request.command, commandPath);
+        assertExactKeys(job.request.command, ['executable', 'args'], commandPath);
+        assertNonEmptyString(job.request.command.executable, `${commandPath}.executable`);
+        if (!Array.isArray(job.request.command.args)) {
+          throw new FlexHarnessStoreFormatError(`${commandPath}.args must be an array.`);
+        }
+        for (let argumentIndex = 0; argumentIndex < job.request.command.args.length; argumentIndex++) {
+          if (typeof job.request.command.args[argumentIndex] !== 'string') {
+            throw new FlexHarnessStoreFormatError(
+              `${commandPath}.args[${argumentIndex}] must be a string.`,
+            );
+          }
+        }
+      }
+      if (job.request.cwd !== undefined && typeof job.request.cwd !== 'string') {
+        throw new FlexHarnessStoreFormatError(`${requestPath}.cwd must be a string.`);
+      }
+      if (job.request.timeoutMs !== undefined) {
+        assertNonNegativeInteger(job.request.timeoutMs, `${requestPath}.timeoutMs`);
+      }
+      if (job.request.metadata !== undefined) {
+        assertRecord(job.request.metadata, `${requestPath}.metadata`);
+      }
+    }
+    if (job.exitCode !== undefined && job.exitCode !== null && !Number.isSafeInteger(job.exitCode)) {
+      throw new FlexHarnessStoreFormatError(`${path}.exitCode must be an integer or null.`);
+    }
+    for (const key of ['stdout', 'stderr', 'signal'] as const) {
+      if (job[key] !== undefined && typeof job[key] !== 'string') {
+        throw new FlexHarnessStoreFormatError(`${path}.${key} must be a string.`);
+      }
+    }
+    for (const key of ['startedAt', 'updatedAt', 'finishedAt'] as const) {
+      if (job[key] !== undefined) assertNonNegativeInteger(job[key], `${path}.${key}`);
+    }
+  }
+  return value as unknown as plugins.IToolJobSnapshot;
+}
+
+function createToolJobSnapshot(
+  jobs: readonly plugins.IToolJobState[],
+  revision: number,
+): plugins.IToolJobSnapshot {
+  const snapshot: plugins.IToolJobSnapshot = {
+    schemaVersion: 1,
+    revision,
+    updatedAt: Date.now(),
+    jobs: normalizeJsonObjectUndefined([...jobs], '$jobs'),
+  };
+  return validateToolJobSnapshot(snapshot);
+}
+
+class InMemoryScopeStore implements IFlexScopeStore {
+  private readonly snapshots = new Map<string, IFlexScopeSnapshot>();
+
+  public async load(storageKey: string): Promise<IFlexScopeSnapshot | undefined> {
+    validateIdentifier(storageKey, 'storageKey');
     const snapshot = this.snapshots.get(storageKey);
     return snapshot ? cloneSerializable(snapshot) : undefined;
   }
 
   public async save(
     storageKey: string,
-    snapshot: IFlexHarnessSnapshot,
+    snapshot: IFlexScopeSnapshot,
     expectedRevision: number,
   ): Promise<void> {
-    const validated = validateSave(snapshot, expectedRevision);
+    validateIdentifier(storageKey, 'storageKey');
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexScopeSnapshot);
     const actualRevision = this.snapshots.get(storageKey)?.revision ?? 0;
     if (actualRevision !== expectedRevision) {
       throw new FlexHarnessStoreConflictError(storageKey, expectedRevision, actualRevision);
@@ -45,151 +349,976 @@ export class InMemoryFlexHarnessStore implements IFlexHarnessStore {
   }
 }
 
-export interface IJsonFileFlexHarnessStoreOptions {
-  directory: string;
-}
+class InMemoryProjectionStore implements IFlexProjectionStore {
+  private readonly snapshots = new Map<string, IFlexProjectionSnapshot>();
 
-/**
- * Atomic and CAS-safe across instances in this process. It intentionally does not
- * claim cross-process safety because no operating-system lock is held.
- */
-export class JsonFileFlexHarnessStore implements IFlexHarnessStore {
-  private static readonly fileQueues = new Map<string, Promise<void>>();
-  private readonly directory: string;
+  public async load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<IFlexProjectionSnapshot | undefined> {
+    const key = providerKey(storageKey, sessionId);
+    const snapshot = this.snapshots.get(key);
+    return snapshot ? cloneSerializable(snapshot) : undefined;
+  }
 
-  constructor(options: IJsonFileFlexHarnessStoreOptions) {
-    if (!options.directory) {
-      throw new FlexHarnessValidationError('JsonFileFlexHarnessStore requires a directory.');
+  public async save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexProjectionSnapshot,
+    expectedRevision: number,
+  ): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexProjectionSnapshot);
+    assertProjectionSession(validated, sessionId);
+    const actualRevision = this.snapshots.get(key)?.revision ?? 0;
+    if (actualRevision !== expectedRevision) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
     }
-    this.directory = plugins.path.resolve(options.directory);
+    this.snapshots.set(key, validated);
   }
 
-  public async load(storageKey: string): Promise<IFlexHarnessSnapshot | undefined> {
-    const filePath = this.filePath(storageKey);
-    return JsonFileFlexHarnessStore.inFileQueue(filePath, async () => {
-      await this.preparePath(filePath);
-      return this.readSnapshot(filePath);
-    });
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    this.snapshots.delete(providerKey(storageKey, sessionId));
+  }
+}
+
+class InMemoryPermissionStore implements IFlexPermissionStore {
+  private readonly snapshots = new Map<string, IFlexPermissionSnapshot>();
+
+  public async load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<IFlexPermissionSnapshot | undefined> {
+    const snapshot = this.snapshots.get(providerKey(storageKey, sessionId));
+    return snapshot ? cloneSerializable(snapshot) : undefined;
   }
 
   public async save(
     storageKey: string,
-    snapshot: IFlexHarnessSnapshot,
+    sessionId: string,
+    snapshot: IFlexPermissionSnapshot,
     expectedRevision: number,
   ): Promise<void> {
-    const validated = validateSave(snapshot, expectedRevision);
-    const filePath = this.filePath(storageKey);
-    await JsonFileFlexHarnessStore.inFileQueue(filePath, async () => {
-      await this.preparePath(filePath);
-      const current = await this.readSnapshot(filePath);
-      const actualRevision = current?.revision ?? 0;
-      if (actualRevision !== expectedRevision) {
-        throw new FlexHarnessStoreConflictError(storageKey, expectedRevision, actualRevision);
+    const key = providerKey(storageKey, sessionId);
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexPermissionSnapshot);
+    const actualRevision = this.snapshots.get(key)?.revision ?? 0;
+    if (actualRevision !== expectedRevision) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+    this.snapshots.set(key, validated);
+  }
+
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    this.snapshots.delete(providerKey(storageKey, sessionId));
+  }
+}
+
+class InMemoryAgentEventStore implements plugins.IAgentEventStoreV2 {
+  public readonly eventSchemaVersion = 2 as const;
+  private snapshot: plugins.IAgentEventSnapshotV2 | undefined;
+  private readonly archives = new Map<string, plugins.IAgentEventArchiveV2>();
+
+  constructor(private readonly sessionId: string) {}
+
+  private assertSession(sessionId: string): void {
+    if (sessionId !== this.sessionId) {
+      throw new FlexHarnessValidationError(
+        `Agent event store is bound to session "${this.sessionId}", not "${sessionId}".`,
+      );
+    }
+  }
+
+  public async load(sessionId: string): Promise<plugins.IAgentEventSnapshotV2 | undefined> {
+    this.assertSession(sessionId);
+    return this.snapshot ? cloneSerializable(this.snapshot) : undefined;
+  }
+
+  public async save(
+    sessionId: string,
+    events: readonly plugins.TAgentEvent[],
+    expectedRevision: number,
+  ): Promise<number> {
+    this.assertSession(sessionId);
+    validateExpectedRevision(expectedRevision);
+    const snapshot = createAgentEventSnapshot(sessionId, events, expectedRevision + 1);
+    validateAgentEventSnapshot(snapshot, sessionId);
+    const actualRevision = this.snapshot?.revision ?? 0;
+    if (actualRevision !== expectedRevision) {
+      throw new plugins.AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
+    }
+    this.snapshot = cloneSerializable(snapshot);
+    return snapshot.revision;
+  }
+
+  public async archive(archive: plugins.IAgentEventArchiveV2): Promise<void> {
+    this.assertSession(archive.sessionId);
+    const normalized = normalizeJsonObjectUndefined(archive, '$archive');
+    const validated = validateAgentEventArchive(normalized, this.sessionId, archive.archiveId);
+    const existing = this.archives.get(archive.archiveId);
+    if (existing) {
+      if (
+        JSON.stringify(existing.events.map((event) => event.id))
+        !== JSON.stringify(validated.events.map((event) => event.id))
+      ) {
+        throw new Error(`Archive "${archive.archiveId}" already exists with different events.`);
       }
-      await this.writeSnapshot(filePath, validated);
-    });
+      return;
+    }
+    this.archives.set(archive.archiveId, cloneSerializable(validated));
+  }
+
+  public async loadArchive(
+    sessionId: string,
+    archiveId: string,
+  ): Promise<plugins.IAgentEventArchiveV2 | undefined> {
+    this.assertSession(sessionId);
+    validateIdentifier(archiveId, 'archiveId');
+    const archive = this.archives.get(archiveId);
+    return archive ? cloneSerializable(archive) : undefined;
+  }
+
+  public clear(): void {
+    this.snapshot = undefined;
+    this.archives.clear();
+  }
+}
+
+class InMemoryAgentEventStoreProvider implements IFlexAgentEventStoreProvider {
+  private readonly stores = new Map<string, InMemoryAgentEventStore>();
+
+  public getStore(storageKey: string, sessionId: string): InMemoryAgentEventStore {
+    const key = providerKey(storageKey, sessionId);
+    let store = this.stores.get(key);
+    if (!store) {
+      store = new InMemoryAgentEventStore(sessionId);
+      this.stores.set(key, store);
+    }
+    return store;
+  }
+
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const store = this.stores.get(key);
+    if (!store) return;
+    store.clear();
+    this.stores.delete(key);
+  }
+}
+
+class InMemoryToolJobStore implements plugins.IToolJobStore {
+  private snapshot: plugins.IToolJobSnapshot | undefined;
+
+  public async load(abortSignal?: AbortSignal): Promise<plugins.IToolJobSnapshot | undefined> {
+    abortSignal?.throwIfAborted();
+    return this.snapshot ? cloneSerializable(this.snapshot) : undefined;
+  }
+
+  public async save(
+    jobs: readonly plugins.IToolJobState[],
+    expectedRevision: number,
+    abortSignal?: AbortSignal,
+  ): Promise<number> {
+    abortSignal?.throwIfAborted();
+    validateExpectedRevision(expectedRevision);
+    const snapshot = createToolJobSnapshot(jobs, expectedRevision + 1);
+    const actualRevision = this.snapshot?.revision ?? 0;
+    if (actualRevision !== expectedRevision) {
+      throw new plugins.ToolJobStoreConflictError(expectedRevision, actualRevision);
+    }
+    this.snapshot = cloneSerializable(snapshot);
+    return snapshot.revision;
+  }
+
+  public clear(): void {
+    this.snapshot = undefined;
+  }
+}
+
+class InMemoryToolJobStoreProvider implements IFlexToolJobStoreProvider {
+  private readonly stores = new Map<string, InMemoryToolJobStore>();
+
+  public getStore(storageKey: string, sessionId: string): InMemoryToolJobStore {
+    const key = providerKey(storageKey, sessionId);
+    let store = this.stores.get(key);
+    if (!store) {
+      store = new InMemoryToolJobStore();
+      this.stores.set(key, store);
+    }
+    return store;
   }
 
-  private static inFileQueue<T>(filePath: string, operation: () => Promise<T>): Promise<T> {
-    const previous = JsonFileFlexHarnessStore.fileQueues.get(filePath) ?? Promise.resolve();
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const store = this.stores.get(key);
+    if (!store) return;
+    store.clear();
+    this.stores.delete(key);
+  }
+}
+
+export class InMemoryFlexHarnessStores implements IFlexHarnessStores {
+  public readonly scopes: IFlexScopeStore = new InMemoryScopeStore();
+  public readonly projections: IFlexProjectionStore = new InMemoryProjectionStore();
+  public readonly permissions: IFlexPermissionStore = new InMemoryPermissionStore();
+  public readonly agentEvents: IFlexAgentEventStoreProvider = new InMemoryAgentEventStoreProvider();
+  public readonly jobs: IFlexToolJobStoreProvider = new InMemoryToolJobStoreProvider();
+}
+
+const jsonDomains = ['scopes', 'projections', 'permissions', 'events', 'archives', 'jobs'] as const;
+type TJsonDomain = (typeof jsonDomains)[number];
+
+interface IDirectorySyncAttempt {
+  syncError?: unknown;
+  closeError?: unknown;
+}
+
+function aggregateStoreErrors(errors: unknown[], message: string): unknown {
+  return errors.length === 1 ? errors[0] : new AggregateError(errors, message);
+}
+
+class JsonFileRoot {
+  private static readonly fileQueues = new Map<string, Promise<void>>();
+  public readonly directory: string;
+  private readonly retainedFileHandles = new Set<plugins.fs.FileHandle>();
+  private readonly fileHandleClosures = new Map<plugins.fs.FileHandle, Promise<void>>();
+
+  constructor(directory: string) {
+    this.directory = plugins.path.resolve(directory);
+  }
+
+  public static inQueue<T>(key: string, operation: () => Promise<T>): Promise<T> {
+    const previous = JsonFileRoot.fileQueues.get(key) ?? Promise.resolve();
     const result = previous.catch(() => undefined).then(operation);
     const barrier = result.then(
       () => undefined,
       () => undefined,
     );
-    JsonFileFlexHarnessStore.fileQueues.set(filePath, barrier);
+    JsonFileRoot.fileQueues.set(key, barrier);
     void barrier.then(() => {
-      if (JsonFileFlexHarnessStore.fileQueues.get(filePath) === barrier) {
-        JsonFileFlexHarnessStore.fileQueues.delete(filePath);
-      }
+      if (JsonFileRoot.fileQueues.get(key) === barrier) JsonFileRoot.fileQueues.delete(key);
     });
     return result;
   }
 
-  private filePath(storageKey: string): string {
-    const digest = plugins.crypto.createHash('sha256').update(storageKey).digest('hex');
-    return plugins.path.join(this.directory, `${digest}.json`);
+  public digest(value: string): string {
+    return plugins.crypto.createHash('sha256').update(value).digest('hex');
+  }
+
+  public scopePath(domain: TJsonDomain, storageKey: string): string {
+    validateIdentifier(storageKey, 'storageKey');
+    return plugins.path.join(this.directory, domain, `${this.digest(storageKey)}.json`);
+  }
+
+  public sessionPath(domain: TJsonDomain, storageKey: string, sessionId: string): string {
+    validateIdentifier(storageKey, 'storageKey');
+    validateIdentifier(sessionId, 'sessionId');
+    return plugins.path.join(
+      this.directory,
+      domain,
+      this.digest(storageKey),
+      `${this.digest(sessionId)}.json`,
+    );
   }
 
-  private async preparePath(filePath: string): Promise<void> {
+  public archivePath(storageKey: string, sessionId: string, archiveId: string): string {
+    validateIdentifier(archiveId, 'archiveId');
+    return plugins.path.join(
+      this.archiveSessionPath(storageKey, sessionId),
+      `${this.digest(archiveId)}.json`,
+    );
+  }
+
+  public archiveSessionPath(storageKey: string, sessionId: string): string {
+    validateIdentifier(storageKey, 'storageKey');
+    validateIdentifier(sessionId, 'sessionId');
+    return plugins.path.join(
+      this.directory,
+      'archives',
+      this.digest(storageKey),
+      this.digest(sessionId),
+    );
+  }
+
+  public eventQueueKey(storageKey: string, sessionId: string): string {
+    return `event:${this.sessionPath('events', storageKey, sessionId)}`;
+  }
+
+  private async prepareRoot(): Promise<void> {
+    await this.retryRetainedFileHandles();
     await plugins.fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
     await plugins.fs.chmod(this.directory, 0o700);
-    await this.cleanupTemps(filePath);
+    await Promise.all(jsonDomains.map(async (domain) => {
+      const path = plugins.path.join(this.directory, domain);
+      await plugins.fs.mkdir(path, { recursive: true, mode: 0o700 });
+      await plugins.fs.chmod(path, 0o700);
+    }));
+  }
+
+  private closeFileHandle(handle: plugins.fs.FileHandle): Promise<void> {
+    const existing = this.fileHandleClosures.get(handle);
+    if (existing) return existing;
+    let closure!: Promise<void>;
+    closure = handle.close().then(() => {
+      this.retainedFileHandles.delete(handle);
+    }, (error: unknown) => {
+      this.retainedFileHandles.add(handle);
+      throw error;
+    }).finally(() => {
+      if (this.fileHandleClosures.get(handle) === closure) {
+        this.fileHandleClosures.delete(handle);
+      }
+    });
+    this.fileHandleClosures.set(handle, closure);
+    return closure;
+  }
+
+  private async retryRetainedFileHandles(): Promise<void> {
+    const results = await Promise.allSettled(
+      [...this.retainedFileHandles].map((handle) => this.closeFileHandle(handle)),
+    );
+    const errors = results
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (errors.length > 0) {
+      throw aggregateStoreErrors(errors, 'Failed to close retained JSON store file handles.');
+    }
+  }
+
+  public async dispose(): Promise<void> {
+    await Promise.allSettled([...this.fileHandleClosures.values()]);
+    await this.retryRetainedFileHandles();
+  }
+
+  private async prepareDirectory(directory: string): Promise<void> {
+    await this.prepareRoot();
+    await plugins.fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    let current = directory;
+    while (current !== this.directory && current.startsWith(`${this.directory}${plugins.path.sep}`)) {
+      await plugins.fs.chmod(current, 0o700);
+      current = plugins.path.dirname(current);
+    }
   }
 
   private async cleanupTemps(filePath: string): Promise<void> {
+    const directory = plugins.path.dirname(filePath);
     const prefix = `${plugins.path.basename(filePath)}.`;
-    const entries = await plugins.fs.readdir(this.directory, { withFileTypes: true });
-    await Promise.all(
-      entries
-        .filter((entry) => entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith('.tmp'))
-        .map(async (entry) => {
-          try {
-            await plugins.fs.unlink(plugins.path.join(this.directory, entry.name));
-          } catch (error) {
-            if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-              throw error;
-            }
-          }
-        }),
-    );
+    const entries = await plugins.fs.readdir(directory, { withFileTypes: true });
+    const cleanupResults = await Promise.allSettled(entries
+      .filter((entry) => entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith('.tmp'))
+      .map(async (entry) => {
+        try {
+          await plugins.fs.unlink(plugins.path.join(directory, entry.name));
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+        }
+      }));
+    const cleanupErrors = cleanupResults
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (cleanupErrors.length > 0) {
+      throw aggregateStoreErrors(cleanupErrors, `Failed to clean temporary files for ${filePath}.`);
+    }
   }
 
-  private async readSnapshot(filePath: string): Promise<IFlexHarnessSnapshot | undefined> {
+  private async attemptDirectorySync(directory: string): Promise<IDirectorySyncAttempt> {
+    let handle: plugins.fs.FileHandle | undefined;
+    let syncError: unknown;
+    let closeError: unknown;
+    try {
+      handle = await plugins.fs.open(directory, 'r');
+      await handle.sync();
+    } catch (error) {
+      syncError = error;
+    }
+    if (handle) {
+      try {
+        await this.closeFileHandle(handle);
+      } catch (error) {
+        closeError = error;
+      }
+    }
+    return { syncError, closeError };
+  }
+
+  private async writeExact(handle: plugins.fs.FileHandle, serialized: Buffer): Promise<void> {
+    let offset = 0;
+    while (offset < serialized.length) {
+      const { bytesWritten } = await handle.write(
+        serialized,
+        offset,
+        serialized.length - offset,
+        offset,
+      );
+      if (bytesWritten === 0) {
+        throw new Error('Writing the store temporary file made no progress.');
+      }
+      offset += bytesWritten;
+    }
+  }
+
+  private async syncParentAfterWrite(filePath: string, serialized: Buffer): Promise<void> {
+    const directory = plugins.path.dirname(filePath);
+    const firstAttempt = await this.attemptDirectorySync(directory);
+    if (firstAttempt.syncError === undefined && firstAttempt.closeError === undefined) return;
+
+    let comparisonError: unknown;
+    try {
+      const persisted = await plugins.fs.readFile(filePath);
+      if (!persisted.equals(serialized)) {
+        throw new Error(`Destination bytes at ${filePath} do not match the committed write.`);
+      }
+    } catch (error) {
+      comparisonError = error;
+    }
+    const retryAttempt = await this.attemptDirectorySync(directory);
+    if (
+      comparisonError === undefined
+      && retryAttempt.syncError === undefined
+      && firstAttempt.closeError === undefined
+      && retryAttempt.closeError === undefined
+    ) return;
+
+    const errors = [
+      firstAttempt.syncError,
+      firstAttempt.closeError,
+      comparisonError,
+      retryAttempt.syncError,
+      retryAttempt.closeError,
+    ].filter((error) => error !== undefined);
+    throw new FlexHarnessStoreCommitUncertainError(filePath, 'write', {
+      cause: aggregateStoreErrors(errors, `Could not confirm the store write at ${filePath}.`),
+    });
+  }
+
+  private async syncParentAfterDelete(
+    deletedPath: string,
+    operation: 'delete-file' | 'delete-directory',
+  ): Promise<void> {
+    const directory = plugins.path.dirname(deletedPath);
+    const firstAttempt = await this.attemptDirectorySync(directory);
+    if (firstAttempt.syncError === undefined && firstAttempt.closeError === undefined) return;
+
+    let comparisonError: unknown;
+    try {
+      await plugins.fs.stat(deletedPath);
+      comparisonError = new Error(`Deleted path ${deletedPath} still exists.`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') comparisonError = error;
+    }
+    const retryAttempt = await this.attemptDirectorySync(directory);
+    if (
+      comparisonError === undefined
+      && retryAttempt.syncError === undefined
+      && firstAttempt.closeError === undefined
+      && retryAttempt.closeError === undefined
+    ) return;
+
+    const errors = [
+      firstAttempt.syncError,
+      firstAttempt.closeError,
+      comparisonError,
+      retryAttempt.syncError,
+      retryAttempt.closeError,
+    ]
+      .filter((error) => error !== undefined);
+    throw new FlexHarnessStoreCommitUncertainError(deletedPath, operation, {
+      cause: aggregateStoreErrors(errors, `Could not confirm the store deletion at ${deletedPath}.`),
+    });
+  }
+
+  public async read<TValue>(
+    filePath: string,
+    validate: (value: unknown) => TValue,
+  ): Promise<TValue | undefined> {
+    await this.prepareDirectory(plugins.path.dirname(filePath));
     let serialized: string;
     try {
       await plugins.fs.chmod(filePath, 0o600);
       serialized = await plugins.fs.readFile(filePath, 'utf8');
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-        return undefined;
-      }
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
       throw error;
     }
-
     let parsed: unknown;
     try {
       parsed = JSON.parse(serialized);
     } catch (error) {
-      throw new FlexHarnessStoreFormatError(`Malformed JSON snapshot at ${filePath}.`, {
-        cause: error,
-      });
+      throw new FlexHarnessStoreFormatError(`Malformed JSON at ${filePath}.`, { cause: error });
     }
     try {
-      assertFlexHarnessSnapshot(parsed);
+      return validate(parsed);
     } catch (error) {
       if (error instanceof FlexHarnessStoreFormatError) {
-        throw new FlexHarnessStoreFormatError(`Invalid snapshot at ${filePath}: ${error.message}`, {
+        throw new FlexHarnessStoreFormatError(`Invalid JSON at ${filePath}: ${error.message}`, {
           cause: error,
         });
       }
       throw error;
     }
-    return cloneSerializable(parsed);
   }
 
-  private async writeSnapshot(
-    filePath: string,
-    snapshot: IFlexHarnessSnapshot,
-  ): Promise<void> {
+  public async write(filePath: string, value: unknown): Promise<void> {
+    assertJsonSerializable(value);
+    const serialized = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    const directory = plugins.path.dirname(filePath);
+    await this.prepareDirectory(directory);
+    await this.cleanupTemps(filePath);
     const tempPath = `${filePath}.${process.pid}.${plugins.crypto.randomUUID()}.tmp`;
-    let fileHandle: plugins.fs.FileHandle | undefined;
+    let handle: plugins.fs.FileHandle | undefined;
+    let operationError: unknown;
+    let operationFailed = false;
+    let renamed = false;
     try {
-      fileHandle = await plugins.fs.open(tempPath, 'wx', 0o600);
-      await fileHandle.writeFile(`${JSON.stringify(snapshot, null, 2)}\n`, 'utf8');
-      await fileHandle.sync();
-      await fileHandle.close();
-      fileHandle = undefined;
-      await plugins.fs.chmod(tempPath, 0o600);
+      handle = await plugins.fs.open(tempPath, 'wx', 0o600);
+      await this.writeExact(handle, serialized);
+      await handle.sync();
+      await this.closeFileHandle(handle);
+      handle = undefined;
       await plugins.fs.rename(tempPath, filePath);
-      await plugins.fs.chmod(filePath, 0o600);
-    } finally {
-      await fileHandle?.close().catch(() => undefined);
-      await plugins.fs.unlink(tempPath).catch((error: NodeJS.ErrnoException) => {
-        if (error.code !== 'ENOENT') {
-          throw error;
-        }
+      renamed = true;
+      await this.syncParentAfterWrite(filePath, serialized);
+    } catch (error) {
+      operationError = error;
+      operationFailed = true;
+    }
+
+    const cleanupErrors: unknown[] = [];
+    if (handle) {
+      try {
+        await this.closeFileHandle(handle);
+      } catch (error) {
+        cleanupErrors.push(error);
+      }
+    }
+    try {
+      await plugins.fs.unlink(tempPath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') cleanupErrors.push(error);
+    }
+
+    if (!operationFailed && cleanupErrors.length === 0) return;
+    if (
+      renamed
+      && operationError instanceof FlexHarnessStoreCommitUncertainError
+      && cleanupErrors.length === 0
+    ) {
+      throw operationError;
+    }
+    const errors: unknown[] = [];
+    if (operationFailed) errors.push(operationError);
+    errors.push(...cleanupErrors);
+    const cause = aggregateStoreErrors(errors, `Store write or cleanup failed at ${filePath}.`);
+    if (renamed) {
+      throw new FlexHarnessStoreCommitUncertainError(filePath, 'write', { cause });
+    }
+    throw cause;
+  }
+
+  public async deleteFile(filePath: string): Promise<void> {
+    await this.prepareDirectory(plugins.path.dirname(filePath));
+    try {
+      await plugins.fs.unlink(filePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    await this.syncParentAfterDelete(filePath, 'delete-file');
+  }
+
+  public async deleteDirectory(directory: string): Promise<void> {
+    await this.prepareDirectory(plugins.path.dirname(directory));
+    await plugins.fs.rm(directory, { recursive: true, force: true });
+    await this.syncParentAfterDelete(directory, 'delete-directory');
+  }
+}
+
+class JsonScopeStore implements IFlexScopeStore {
+  constructor(private readonly root: JsonFileRoot) {}
+
+  public async load(storageKey: string): Promise<IFlexScopeSnapshot | undefined> {
+    const filePath = this.root.scopePath('scopes', storageKey);
+    return JsonFileRoot.inQueue(filePath, async () => {
+      const snapshot = await this.root.read(filePath, (value) => {
+        assertFlexScopeSnapshot(value);
+        return value;
+      });
+      return snapshot ? cloneSerializable(snapshot) : undefined;
+    });
+  }
+
+  public async save(
+    storageKey: string,
+    snapshot: IFlexScopeSnapshot,
+    expectedRevision: number,
+  ): Promise<void> {
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexScopeSnapshot);
+    const filePath = this.root.scopePath('scopes', storageKey);
+    await JsonFileRoot.inQueue(filePath, async () => {
+      const current = await this.root.read(filePath, (value) => {
+        assertFlexScopeSnapshot(value);
+        return value;
+      });
+      const actualRevision = current?.revision ?? 0;
+      if (actualRevision !== expectedRevision) {
+        throw new FlexHarnessStoreConflictError(storageKey, expectedRevision, actualRevision);
+      }
+      await this.root.write(filePath, validated);
+    });
+  }
+}
+
+class JsonProjectionStore implements IFlexProjectionStore {
+  constructor(private readonly root: JsonFileRoot) {}
+
+  public async load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<IFlexProjectionSnapshot | undefined> {
+    const filePath = this.root.sessionPath('projections', storageKey, sessionId);
+    return JsonFileRoot.inQueue(filePath, async () => {
+      const snapshot = await this.root.read(filePath, (value) => {
+        assertFlexProjectionSnapshot(value);
+        assertProjectionSession(value, sessionId);
+        return value;
+      });
+      return snapshot ? cloneSerializable(snapshot) : undefined;
+    });
+  }
+
+  public async save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexProjectionSnapshot,
+    expectedRevision: number,
+  ): Promise<void> {
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexProjectionSnapshot);
+    assertProjectionSession(validated, sessionId);
+    const filePath = this.root.sessionPath('projections', storageKey, sessionId);
+    await JsonFileRoot.inQueue(filePath, async () => {
+      const current = await this.root.read(filePath, (value) => {
+        assertFlexProjectionSnapshot(value);
+        assertProjectionSession(value, sessionId);
+        return value;
+      });
+      const actualRevision = current?.revision ?? 0;
+      if (actualRevision !== expectedRevision) {
+        throw new FlexHarnessStoreConflictError(providerKey(storageKey, sessionId), expectedRevision, actualRevision);
+      }
+      await this.root.write(filePath, validated);
+    });
+  }
+
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    const filePath = this.root.sessionPath('projections', storageKey, sessionId);
+    await JsonFileRoot.inQueue(filePath, () => this.root.deleteFile(filePath));
+  }
+}
+
+class JsonPermissionStore implements IFlexPermissionStore {
+  constructor(private readonly root: JsonFileRoot) {}
+
+  public async load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<IFlexPermissionSnapshot | undefined> {
+    const filePath = this.root.sessionPath('permissions', storageKey, sessionId);
+    return JsonFileRoot.inQueue(filePath, async () => {
+      const snapshot = await this.root.read(filePath, (value) => {
+        assertFlexPermissionSnapshot(value);
+        return value;
       });
+      return snapshot ? cloneSerializable(snapshot) : undefined;
+    });
+  }
+
+  public async save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexPermissionSnapshot,
+    expectedRevision: number,
+  ): Promise<void> {
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexPermissionSnapshot);
+    const filePath = this.root.sessionPath('permissions', storageKey, sessionId);
+    await JsonFileRoot.inQueue(filePath, async () => {
+      const current = await this.root.read(filePath, (value) => {
+        assertFlexPermissionSnapshot(value);
+        return value;
+      });
+      const actualRevision = current?.revision ?? 0;
+      if (actualRevision !== expectedRevision) {
+        throw new FlexHarnessStoreConflictError(providerKey(storageKey, sessionId), expectedRevision, actualRevision);
+      }
+      await this.root.write(filePath, validated);
+    });
+  }
+
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    const filePath = this.root.sessionPath('permissions', storageKey, sessionId);
+    await JsonFileRoot.inQueue(filePath, () => this.root.deleteFile(filePath));
+  }
+}
+
+async function clearJsonAgentEventSession(
+  root: JsonFileRoot,
+  storageKey: string,
+  sessionId: string,
+): Promise<void> {
+  const filePath = root.sessionPath('events', storageKey, sessionId);
+  const archiveDirectory = root.archiveSessionPath(storageKey, sessionId);
+  await JsonFileRoot.inQueue(root.eventQueueKey(storageKey, sessionId), async () => {
+    await root.deleteFile(filePath);
+    await root.deleteDirectory(archiveDirectory);
+  });
+}
+
+class JsonAgentEventStore implements plugins.IAgentEventStoreV2 {
+  public readonly eventSchemaVersion = 2 as const;
+
+  constructor(
+    private readonly root: JsonFileRoot,
+    private readonly storageKey: string,
+    private readonly sessionId: string,
+  ) {}
+
+  private assertSession(sessionId: string): void {
+    if (sessionId !== this.sessionId) {
+      throw new FlexHarnessValidationError(
+        `Agent event store is bound to session "${this.sessionId}", not "${sessionId}".`,
+      );
+    }
+  }
+
+  public async load(sessionId: string): Promise<plugins.IAgentEventSnapshotV2 | undefined> {
+    this.assertSession(sessionId);
+    const filePath = this.root.sessionPath('events', this.storageKey, this.sessionId);
+    return JsonFileRoot.inQueue(this.root.eventQueueKey(this.storageKey, this.sessionId), async () => {
+      const snapshot = await this.root.read(
+        filePath,
+        (value) => validateAgentEventSnapshot(value, this.sessionId),
+      );
+      return snapshot ? cloneSerializable(snapshot) : undefined;
+    });
+  }
+
+  public async save(
+    sessionId: string,
+    events: readonly plugins.TAgentEvent[],
+    expectedRevision: number,
+  ): Promise<number> {
+    this.assertSession(sessionId);
+    validateExpectedRevision(expectedRevision);
+    const snapshot = createAgentEventSnapshot(sessionId, events, expectedRevision + 1);
+    validateAgentEventSnapshot(snapshot, sessionId);
+    const filePath = this.root.sessionPath('events', this.storageKey, this.sessionId);
+    return JsonFileRoot.inQueue(this.root.eventQueueKey(this.storageKey, this.sessionId), async () => {
+      const current = await this.root.read(
+        filePath,
+        (value) => validateAgentEventSnapshot(value, this.sessionId),
+      );
+      const actualRevision = current?.revision ?? 0;
+      if (actualRevision !== expectedRevision) {
+        throw new plugins.AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
+      }
+      await this.root.write(filePath, snapshot);
+      return snapshot.revision;
+    });
+  }
+
+  public async archive(archive: plugins.IAgentEventArchiveV2): Promise<void> {
+    this.assertSession(archive.sessionId);
+    const normalized = normalizeJsonObjectUndefined(archive, '$archive');
+    const validated = validateAgentEventArchive(normalized, this.sessionId, archive.archiveId);
+    const filePath = this.root.archivePath(
+      this.storageKey,
+      this.sessionId,
+      archive.archiveId,
+    );
+    await JsonFileRoot.inQueue(this.root.eventQueueKey(this.storageKey, this.sessionId), async () => {
+      const current = await this.root.read(
+        filePath,
+        (value) => validateAgentEventArchive(value, this.sessionId, archive.archiveId),
+      );
+      if (current) {
+        if (
+          JSON.stringify(current.events.map((event) => event.id))
+          !== JSON.stringify(validated.events.map((event) => event.id))
+        ) {
+          throw new Error(`Archive "${archive.archiveId}" already exists with different events.`);
+        }
+        return;
+      }
+      await this.root.write(filePath, validated);
+    });
+  }
+
+  public async loadArchive(
+    sessionId: string,
+    archiveId: string,
+  ): Promise<plugins.IAgentEventArchiveV2 | undefined> {
+    this.assertSession(sessionId);
+    const filePath = this.root.archivePath(this.storageKey, this.sessionId, archiveId);
+    return JsonFileRoot.inQueue(this.root.eventQueueKey(this.storageKey, this.sessionId), async () => {
+      const archive = await this.root.read(
+        filePath,
+        (value) => validateAgentEventArchive(value, this.sessionId, archiveId),
+      );
+      return archive ? cloneSerializable(archive) : undefined;
+    });
+  }
+
+  public async clear(): Promise<void> {
+    await clearJsonAgentEventSession(this.root, this.storageKey, this.sessionId);
+  }
+}
+
+class JsonAgentEventStoreProvider implements IFlexAgentEventStoreProvider {
+  private readonly stores = new Map<string, JsonAgentEventStore>();
+
+  constructor(private readonly root: JsonFileRoot) {}
+
+  public getStore(storageKey: string, sessionId: string): JsonAgentEventStore {
+    const key = providerKey(storageKey, sessionId);
+    let store = this.stores.get(key);
+    if (!store) {
+      store = new JsonAgentEventStore(this.root, storageKey, sessionId);
+      this.stores.set(key, store);
+    }
+    return store;
+  }
+
+  public releaseSession(storageKey: string, sessionId: string): void {
+    this.stores.delete(providerKey(storageKey, sessionId));
+  }
+
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const store = this.stores.get(key);
+    if (store) {
+      await store.clear();
+    } else {
+      await clearJsonAgentEventSession(this.root, storageKey, sessionId);
     }
+    this.stores.delete(key);
+  }
+}
+
+async function clearJsonToolJobSession(
+  root: JsonFileRoot,
+  storageKey: string,
+  sessionId: string,
+): Promise<void> {
+  const filePath = root.sessionPath('jobs', storageKey, sessionId);
+  await JsonFileRoot.inQueue(filePath, () => root.deleteFile(filePath));
+}
+
+class JsonToolJobStore implements plugins.IToolJobStore {
+  constructor(
+    private readonly root: JsonFileRoot,
+    private readonly storageKey: string,
+    private readonly sessionId: string,
+  ) {}
+
+  private filePath(): string {
+    return this.root.sessionPath('jobs', this.storageKey, this.sessionId);
+  }
+
+  public async load(abortSignal?: AbortSignal): Promise<plugins.IToolJobSnapshot | undefined> {
+    abortSignal?.throwIfAborted();
+    const filePath = this.filePath();
+    return JsonFileRoot.inQueue(filePath, async () => {
+      abortSignal?.throwIfAborted();
+      const snapshot = await this.root.read(filePath, validateToolJobSnapshot);
+      abortSignal?.throwIfAborted();
+      return snapshot ? cloneSerializable(snapshot) : undefined;
+    });
+  }
+
+  public async save(
+    jobs: readonly plugins.IToolJobState[],
+    expectedRevision: number,
+    abortSignal?: AbortSignal,
+  ): Promise<number> {
+    abortSignal?.throwIfAborted();
+    validateExpectedRevision(expectedRevision);
+    const snapshot = createToolJobSnapshot(jobs, expectedRevision + 1);
+    const filePath = this.filePath();
+    return JsonFileRoot.inQueue(filePath, async () => {
+      abortSignal?.throwIfAborted();
+      const current = await this.root.read(filePath, validateToolJobSnapshot);
+      const actualRevision = current?.revision ?? 0;
+      if (actualRevision !== expectedRevision) {
+        throw new plugins.ToolJobStoreConflictError(expectedRevision, actualRevision);
+      }
+      abortSignal?.throwIfAborted();
+      await this.root.write(filePath, snapshot);
+      return snapshot.revision;
+    });
+  }
+
+  public async clear(): Promise<void> {
+    await clearJsonToolJobSession(this.root, this.storageKey, this.sessionId);
+  }
+}
+
+class JsonToolJobStoreProvider implements IFlexToolJobStoreProvider {
+  private readonly stores = new Map<string, JsonToolJobStore>();
+
+  constructor(private readonly root: JsonFileRoot) {}
+
+  public getStore(storageKey: string, sessionId: string): JsonToolJobStore {
+    const key = providerKey(storageKey, sessionId);
+    let store = this.stores.get(key);
+    if (!store) {
+      store = new JsonToolJobStore(this.root, storageKey, sessionId);
+      this.stores.set(key, store);
+    }
+    return store;
+  }
+
+  public releaseSession(storageKey: string, sessionId: string): void {
+    this.stores.delete(providerKey(storageKey, sessionId));
+  }
+
+  public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const store = this.stores.get(key);
+    if (store) {
+      await store.clear();
+    } else {
+      await clearJsonToolJobSession(this.root, storageKey, sessionId);
+    }
+    this.stores.delete(key);
+  }
+}
+
+export interface IJsonFileFlexHarnessStoresOptions {
+  directory: string;
+}
+
+/**
+ * Atomic and CAS-safe across instances in this process. No operating-system lock
+ * is held, so this store intentionally does not claim cross-process safety.
+ */
+export class JsonFileFlexHarnessStores implements IFlexHarnessStores {
+  public readonly scopes: IFlexScopeStore;
+  public readonly projections: IFlexProjectionStore;
+  public readonly permissions: IFlexPermissionStore;
+  public readonly agentEvents: IFlexAgentEventStoreProvider;
+  public readonly jobs: IFlexToolJobStoreProvider;
+  private readonly root: JsonFileRoot;
+
+  constructor(options: IJsonFileFlexHarnessStoresOptions) {
+    if (!options?.directory?.trim()) {
+      throw new FlexHarnessValidationError('JsonFileFlexHarnessStores requires a directory.');
+    }
+    this.root = new JsonFileRoot(options.directory);
+    this.scopes = new JsonScopeStore(this.root);
+    this.projections = new JsonProjectionStore(this.root);
+    this.permissions = new JsonPermissionStore(this.root);
+    this.agentEvents = new JsonAgentEventStoreProvider(this.root);
+    this.jobs = new JsonToolJobStoreProvider(this.root);
+  }
+
+  public dispose(): Promise<void> {
+    return this.root.dispose();
   }
 }