@modelprofile.com/flexharness 9.10.0 → 10.1.0

package/ts_stores_nosqldb/classes.nosqldbstores.ts

@@ -0,0 +1,465 @@
+import * as plugins from './plugins.js';
+import { FlexHarnessStoreConflictError, FlexHarnessValidationError } from '../ts/errors.js';
+import type {
+  IFlexAgentEventStoreProvider,
+  IFlexHarnessStores,
+  IFlexPermissionSnapshot,
+  IFlexPermissionStore,
+  IFlexProjectManagementSnapshot,
+  IFlexProjectManagementStore,
+  IFlexProjectManagementTombstone,
+  IFlexProjectManagementWriteContext,
+  IFlexProjectionSnapshotV3,
+  IFlexProjectionStore,
+  IFlexScopeSnapshot,
+  IFlexScopeStore,
+  IFlexToolJobStoreProvider,
+  TFlexProjectionSnapshot,
+  TFlexProjectManagementRecord,
+} from '../ts/interfaces.js';
+import {
+  assertFlexPermissionSnapshot,
+  assertFlexProjectionSnapshot,
+  assertFlexScopeSnapshot,
+} from '../ts/utils.json.js';
+import {
+  assertFlexProjectManagementRecord,
+  assertFlexProjectManagementSnapshot,
+  assertFlexProjectManagementTombstone,
+} from '../ts/utils.projectmanagement.js';
+import {
+  createAgentEventSnapshot,
+  createToolJobSnapshot,
+  normalizeJsonObjectUndefined,
+  validateAgentEventArchive,
+  validateAgentEventSnapshot,
+  validateToolJobSnapshot,
+} from '../ts/utils.storecodecs.js';
+import {
+  assertProjectionSession,
+  assertProjectManagementSaveAdmitted,
+  assertSameArchiveEvents,
+  isProjectManagementTombstoneAdmitted,
+  providerKey,
+  validateExpectedRevision,
+  validateIdentifier,
+  validateProjectManagementWriteContext,
+  validateSnapshotSave,
+} from '../ts/utils.storerules.js';
+import { FlexRecordStore, type IFlexRecordWrite } from './classes.recordstore.js';
+
+function revisionWrite<TSnapshot extends { revision: number }>(
+  current: { revision: number } | undefined,
+  snapshot: TSnapshot,
+  expectedRevision: number,
+  conflict: (actualRevision: number) => Error,
+): IFlexRecordWrite {
+  const actualRevision = current?.revision ?? 0;
+  if (actualRevision !== expectedRevision) throw conflict(actualRevision);
+  return { revision: snapshot.revision, value: snapshot };
+}
+
+function validateScope(value: unknown): IFlexScopeSnapshot {
+  assertFlexScopeSnapshot(value);
+  return value;
+}
+
+function validatePermission(value: unknown): IFlexPermissionSnapshot {
+  assertFlexPermissionSnapshot(value);
+  return value;
+}
+
+function validateProjectManagement(value: unknown): TFlexProjectManagementRecord {
+  assertFlexProjectManagementRecord(value);
+  return value;
+}
+
+class NoSqlScopeStore implements IFlexScopeStore {
+  constructor(private readonly records: FlexRecordStore) {}
+
+  public load(storageKey: string): Promise<IFlexScopeSnapshot | undefined> {
+    validateIdentifier(storageKey, 'storageKey');
+    return this.records.read({ domain: 'scope', storageKey }, validateScope);
+  }
+
+  public async save(
+    storageKey: string,
+    snapshot: IFlexScopeSnapshot,
+    expectedRevision: number,
+  ): Promise<void> {
+    validateIdentifier(storageKey, 'storageKey');
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexScopeSnapshot);
+    const conflict = (actualRevision: number) =>
+      new FlexHarnessStoreConflictError(storageKey, expectedRevision, actualRevision);
+    await this.records.mutate({ domain: 'scope', storageKey }, {
+      validate: validateScope,
+      decide: (current) => revisionWrite(current, validated, expectedRevision, conflict),
+      contention: conflict,
+    });
+  }
+}
+
+class NoSqlProjectionStore implements IFlexProjectionStore {
+  constructor(private readonly records: FlexRecordStore) {}
+
+  private validator(sessionId: string): (value: unknown) => TFlexProjectionSnapshot {
+    return (value) => {
+      assertFlexProjectionSnapshot(value);
+      assertProjectionSession(value, sessionId);
+      return value;
+    };
+  }
+
+  public load(storageKey: string, sessionId: string): Promise<TFlexProjectionSnapshot | undefined> {
+    providerKey(storageKey, sessionId);
+    return this.records.read(
+      { domain: 'projection', storageKey, sessionId },
+      this.validator(sessionId),
+    );
+  }
+
+  public async save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexProjectionSnapshotV3,
+    expectedRevision: number,
+  ): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexProjectionSnapshot);
+    assertProjectionSession(validated, sessionId);
+    const conflict = (actualRevision: number) =>
+      new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    await this.records.mutate({ domain: 'projection', storageKey, sessionId }, {
+      validate: this.validator(sessionId),
+      decide: (current) => revisionWrite(current, validated, expectedRevision, conflict),
+      contention: conflict,
+    });
+  }
+
+  public deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    providerKey(storageKey, sessionId);
+    return this.records.deleteOwner(storageKey, sessionId, ['projection']);
+  }
+}
+
+class NoSqlPermissionStore implements IFlexPermissionStore {
+  constructor(private readonly records: FlexRecordStore) {}
+
+  public load(storageKey: string, sessionId: string): Promise<IFlexPermissionSnapshot | undefined> {
+    providerKey(storageKey, sessionId);
+    return this.records.read({ domain: 'permission', storageKey, sessionId }, validatePermission);
+  }
+
+  public async save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexPermissionSnapshot,
+    expectedRevision: number,
+  ): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const validated = validateSnapshotSave(snapshot, expectedRevision, assertFlexPermissionSnapshot);
+    const conflict = (actualRevision: number) =>
+      new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    await this.records.mutate({ domain: 'permission', storageKey, sessionId }, {
+      validate: validatePermission,
+      decide: (current) => revisionWrite(current, validated, expectedRevision, conflict),
+      contention: conflict,
+    });
+  }
+
+  public deleteSession(storageKey: string, sessionId: string): Promise<void> {
+    providerKey(storageKey, sessionId);
+    return this.records.deleteOwner(storageKey, sessionId, ['permission']);
+  }
+}
+
+class NoSqlProjectManagementStore implements IFlexProjectManagementStore {
+  constructor(private readonly records: FlexRecordStore) {}
+
+  public load(
+    storageKey: string,
+    sessionId: string,
+  ): Promise<TFlexProjectManagementRecord | undefined> {
+    providerKey(storageKey, sessionId);
+    return this.records.read(
+      { domain: 'projectManagement', storageKey, sessionId },
+      validateProjectManagement,
+    );
+  }
+
+  public async save(
+    storageKey: string,
+    sessionId: string,
+    snapshot: IFlexProjectManagementSnapshot,
+    expectedRevision: number,
+    writeContext: IFlexProjectManagementWriteContext,
+  ): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    validateProjectManagementWriteContext(writeContext);
+    const validated = validateSnapshotSave(
+      snapshot,
+      expectedRevision,
+      assertFlexProjectManagementSnapshot,
+    );
+    await this.records.mutate({ domain: 'projectManagement', storageKey, sessionId }, {
+      validate: validateProjectManagement,
+      decide: (current) => {
+        assertProjectManagementSaveAdmitted(key, current, validated, expectedRevision);
+        return { revision: validated.revision, value: validated };
+      },
+      contention: (actualRevision) =>
+        new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision),
+    });
+  }
+
+  public async tombstoneSession(
+    storageKey: string,
+    sessionId: string,
+    tombstone: IFlexProjectManagementTombstone,
+    expectedRevision: number,
+  ): Promise<void> {
+    const key = providerKey(storageKey, sessionId);
+    const validated = validateSnapshotSave(
+      tombstone,
+      expectedRevision,
+      assertFlexProjectManagementTombstone,
+    );
+    await this.records.mutate({ domain: 'projectManagement', storageKey, sessionId }, {
+      validate: validateProjectManagement,
+      decide: (current) => (
+        isProjectManagementTombstoneAdmitted(key, current, validated, expectedRevision)
+          ? { revision: validated.revision, value: validated }
+          : undefined
+      ),
+      contention: (actualRevision) =>
+        new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision),
+    });
+  }
+
+  public purgeNamespace(storageKey: string): Promise<void> {
+    validateIdentifier(storageKey, 'storageKey');
+    return this.records.purgeNamespace(storageKey, 'projectManagement');
+  }
+}
+
+class NoSqlAgentEventStore implements plugins.IAgentEventStoreV2 {
+  public readonly eventSchemaVersion = 2 as const;
+
+  constructor(
+    private readonly records: FlexRecordStore,
+    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}".`,
+      );
+    }
+  }
+
+  private readonly validateSnapshot = (value: unknown): plugins.IAgentEventSnapshotV2 =>
+    validateAgentEventSnapshot(value, this.sessionId);
+
+  public load(sessionId: string): Promise<plugins.IAgentEventSnapshotV2 | undefined> {
+    this.assertSession(sessionId);
+    return this.records.read(
+      { domain: 'agentEvents', storageKey: this.storageKey, sessionId },
+      this.validateSnapshot,
+    );
+  }
+
+  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 conflict = (actualRevision: number) =>
+      new plugins.AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
+    await this.records.mutate({ domain: 'agentEvents', storageKey: this.storageKey, sessionId }, {
+      validate: this.validateSnapshot,
+      decide: (current) => revisionWrite(current, snapshot, expectedRevision, conflict),
+      contention: conflict,
+    });
+    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 address = {
+      domain: 'agentEventArchive' as const,
+      storageKey: this.storageKey,
+      sessionId: this.sessionId,
+      archiveId: archive.archiveId,
+    };
+    await this.records.mutate(address, {
+      validate: (value) => validateAgentEventArchive(value, this.sessionId, archive.archiveId),
+      decide: (current) => {
+        if (!current) return { revision: 0, value: validated };
+        assertSameArchiveEvents(current, validated);
+        return undefined;
+      },
+      contention: () =>
+        new Error(`Archive "${archive.archiveId}" is contended by concurrent writers.`),
+    });
+  }
+
+  public loadArchive(
+    sessionId: string,
+    archiveId: string,
+  ): Promise<plugins.IAgentEventArchiveV2 | undefined> {
+    this.assertSession(sessionId);
+    validateIdentifier(archiveId, 'archiveId');
+    return this.records.read(
+      { domain: 'agentEventArchive', storageKey: this.storageKey, sessionId, archiveId },
+      (value) => validateAgentEventArchive(value, this.sessionId, archiveId),
+    );
+  }
+}
+
+class NoSqlAgentEventStoreProvider implements IFlexAgentEventStoreProvider {
+  private readonly stores = new Map<string, NoSqlAgentEventStore>();
+
+  constructor(private readonly records: FlexRecordStore) {}
+
+  public getStore(storageKey: string, sessionId: string): NoSqlAgentEventStore {
+    const key = providerKey(storageKey, sessionId);
+    let store = this.stores.get(key);
+    if (!store) {
+      store = new NoSqlAgentEventStore(this.records, 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);
+    await this.records.deleteOwner(storageKey, sessionId, ['agentEvents', 'agentEventArchive']);
+    this.stores.delete(key);
+  }
+}
+
+class NoSqlToolJobStore implements plugins.IToolJobStore {
+  constructor(
+    private readonly records: FlexRecordStore,
+    private readonly storageKey: string,
+    private readonly sessionId: string,
+  ) {}
+
+  public async load(abortSignal?: AbortSignal): Promise<plugins.IToolJobSnapshot | undefined> {
+    abortSignal?.throwIfAborted();
+    const snapshot = await this.records.read(
+      { domain: 'jobs', storageKey: this.storageKey, sessionId: this.sessionId },
+      validateToolJobSnapshot,
+    );
+    abortSignal?.throwIfAborted();
+    return snapshot;
+  }
+
+  public async save(
+    jobs: readonly plugins.IToolJobState[],
+    expectedRevision: number,
+    abortSignal?: AbortSignal,
+  ): Promise<number> {
+    abortSignal?.throwIfAborted();
+    validateExpectedRevision(expectedRevision);
+    const snapshot = createToolJobSnapshot(jobs, expectedRevision + 1);
+    const conflict = (actualRevision: number) =>
+      new plugins.ToolJobStoreConflictError(expectedRevision, actualRevision);
+    await this.records.mutate(
+      { domain: 'jobs', storageKey: this.storageKey, sessionId: this.sessionId },
+      {
+        validate: validateToolJobSnapshot,
+        decide: (current) => {
+          abortSignal?.throwIfAborted();
+          return revisionWrite(current, snapshot, expectedRevision, conflict);
+        },
+        contention: conflict,
+      },
+    );
+    return snapshot.revision;
+  }
+}
+
+class NoSqlToolJobStoreProvider implements IFlexToolJobStoreProvider {
+  private readonly stores = new Map<string, NoSqlToolJobStore>();
+
+  constructor(private readonly records: FlexRecordStore) {}
+
+  public getStore(storageKey: string, sessionId: string): NoSqlToolJobStore {
+    const key = providerKey(storageKey, sessionId);
+    let store = this.stores.get(key);
+    if (!store) {
+      store = new NoSqlToolJobStore(this.records, 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);
+    await this.records.deleteOwner(storageKey, sessionId, ['jobs']);
+    this.stores.delete(key);
+  }
+}
+
+export interface INoSqlFlexHarnessStoresOptions {
+  /**
+   * An initialized database the application owns, on NoSQLDB or a MongoDB deployment with
+   * transactions. The stores never close it.
+   */
+  db: plugins.SmartdataDb;
+  /** Client deadline of every database call and transaction, 1 to 120000 ms. Defaults to 30000. */
+  operationTimeoutMs?: number;
+}
+
+/**
+ * Every FlexHarness persistence domain on `@lossless.org/client/nosqldb`, with compare-and-swap
+ * that holds across processes. Records live in `flexharness_records`; payloads longer than one
+ * chunk live in `flexharness_chunks`.
+ */
+export class NoSqlFlexHarnessStores implements IFlexHarnessStores {
+  public readonly scopes: IFlexScopeStore;
+  public readonly projections: IFlexProjectionStore;
+  public readonly permissions: IFlexPermissionStore;
+  public readonly projectManagement: IFlexProjectManagementStore;
+  public readonly agentEvents: IFlexAgentEventStoreProvider;
+  public readonly jobs: IFlexToolJobStoreProvider;
+  private readonly records: FlexRecordStore;
+
+  constructor(options: INoSqlFlexHarnessStoresOptions) {
+    if (!(options?.db instanceof plugins.SmartdataDb)) {
+      throw new FlexHarnessValidationError('NoSqlFlexHarnessStores requires a SmartdataDb.');
+    }
+    this.records = new FlexRecordStore(options);
+    this.scopes = new NoSqlScopeStore(this.records);
+    this.projections = new NoSqlProjectionStore(this.records);
+    this.permissions = new NoSqlPermissionStore(this.records);
+    this.projectManagement = new NoSqlProjectManagementStore(this.records);
+    this.agentEvents = new NoSqlAgentEventStoreProvider(this.records);
+    this.jobs = new NoSqlToolJobStoreProvider(this.records);
+  }
+
+  /**
+   * Creates or verifies the two collections and their indexes. Every store operation awaits the
+   * same preparation, so calling it at startup only moves that work, and its failure, forward.
+   */
+  public prepare(): Promise<void> {
+    return this.records.prepare();
+  }
+}