@modelprofile.com/flexharness 10.0.0 → 10.1.0

package/ts/classes.stores.ts

@@ -35,8 +35,6 @@ import {
   assertFlexProjectManagementTombstone,
 } from './utils.projectmanagement.js';
 import {
-  assertExactKeys,
-  assertRecord,
   createAgentEventSnapshot,
   createToolJobSnapshot,
   normalizeJsonObjectUndefined,
@@ -44,101 +42,17 @@ import {
   validateAgentEventSnapshot,
   validateToolJobSnapshot,
 } from './utils.storecodecs.js';
-
-type TSnapshot =
-  | IFlexScopeSnapshot
-  | TFlexProjectionSnapshot
-  | IFlexPermissionSnapshot
-  | TFlexProjectManagementRecord;
-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 validateProjectManagementWriteContext(
-  writeContext: IFlexProjectManagementWriteContext,
-): void {
-  assertJsonSerializable(writeContext, '$writeContext');
-  assertRecord(writeContext, 'writeContext');
-  assertExactKeys(writeContext, ['actor', 'runId', 'agent', 'toolCallId'], 'writeContext');
-  if (writeContext.actor !== 'agent' && writeContext.actor !== 'application') {
-    throw new FlexHarnessValidationError('writeContext.actor must be agent or application.');
-  }
-  for (const key of ['runId', 'agent', 'toolCallId'] as const) {
-    if (writeContext[key] !== undefined) validateIdentifier(writeContext[key], `writeContext.${key}`);
-  }
-}
-
-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.`,
-    );
-  }
-  return cloneSerializable(snapshot);
-}
-
-function providerKey(storageKey: string, sessionId: string): string {
-  validateIdentifier(storageKey, 'storageKey');
-  validateIdentifier(sessionId, 'sessionId');
-  return JSON.stringify([storageKey, sessionId]);
-}
-
-function sameProjectManagementGeneration(
-  left: TFlexProjectManagementRecord,
-  right: TFlexProjectManagementRecord,
-): boolean {
-  return left.sessionGenerationId === right.sessionGenerationId
-    && left.sessionGenerationSequence === right.sessionGenerationSequence;
-}
-
-function canInitializeProjectManagementGeneration(
-  current: TFlexProjectManagementRecord,
-  next: TFlexProjectManagementRecord,
-  expectedRevision: number,
-): boolean {
-  return 'deletedAt' in current
-    && expectedRevision === 0
-    && next.sessionGenerationId !== current.sessionGenerationId
-    && next.sessionGenerationSequence > current.sessionGenerationSequence;
-}
-
-function assertProjectionSession(snapshot: TFlexProjectionSnapshot, 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}".`,
-      );
-    }
-  }
-}
+import {
+  assertProjectionSession,
+  assertProjectManagementSaveAdmitted,
+  assertSameArchiveEvents,
+  isProjectManagementTombstoneAdmitted,
+  providerKey,
+  validateExpectedRevision,
+  validateIdentifier,
+  validateProjectManagementWriteContext,
+  validateSnapshotSave,
+} from './utils.storerules.js';
 
 class InMemoryScopeStore implements IFlexScopeStore {
   private readonly snapshots = new Map<string, IFlexScopeSnapshot>();
@@ -253,15 +167,7 @@ export class InMemoryFlexProjectManagementStore implements IFlexProjectManagemen
       expectedRevision,
       assertFlexProjectManagementSnapshot,
     );
-    const current = this.snapshots.get(key);
-    const actualRevision = current?.revision ?? 0;
-    if (current && !sameProjectManagementGeneration(current, validated)) {
-      if (!canInitializeProjectManagementGeneration(current, validated, expectedRevision)) {
-        throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
-      }
-    } else if ((current && 'deletedAt' in current) || actualRevision !== expectedRevision) {
-      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
-    }
+    assertProjectManagementSaveAdmitted(key, this.snapshots.get(key), validated, expectedRevision);
     this.snapshots.set(key, validated);
   }
 
@@ -277,19 +183,8 @@ export class InMemoryFlexProjectManagementStore implements IFlexProjectManagemen
       expectedRevision,
       assertFlexProjectManagementTombstone,
     );
-    const current = this.snapshots.get(key);
-    const actualRevision = current?.revision ?? 0;
-    if (current && sameProjectManagementGeneration(current, validated)) {
-      if ('deletedAt' in current) return;
-      if (actualRevision !== expectedRevision) {
-        throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
-      }
-    } else if (current) {
-      if (!canInitializeProjectManagementGeneration(current, validated, expectedRevision)) {
-        throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
-      }
-    } else if (actualRevision !== expectedRevision) {
-      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    if (!isProjectManagementTombstoneAdmitted(key, this.snapshots.get(key), validated, expectedRevision)) {
+      return;
     }
     this.snapshots.set(key, validated);
   }
@@ -346,12 +241,7 @@ class InMemoryAgentEventStore implements plugins.IAgentEventStoreV2 {
     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.`);
-      }
+      assertSameArchiveEvents(existing, validated);
       return;
     }
     this.archives.set(archive.archiveId, cloneSerializable(validated));
@@ -1007,22 +897,12 @@ class JsonProjectManagementStore implements IFlexProjectManagementStore {
           assertFlexProjectManagementRecord(value);
           return value;
         });
-        const actualRevision = current?.revision ?? 0;
-        if (current && !sameProjectManagementGeneration(current, validated)) {
-          if (!canInitializeProjectManagementGeneration(current, validated, expectedRevision)) {
-            throw new FlexHarnessStoreConflictError(
-              providerKey(storageKey, sessionId),
-              expectedRevision,
-              actualRevision,
-            );
-          }
-        } else if ((current && 'deletedAt' in current) || actualRevision !== expectedRevision) {
-          throw new FlexHarnessStoreConflictError(
-            providerKey(storageKey, sessionId),
-            expectedRevision,
-            actualRevision,
-          );
-        }
+        assertProjectManagementSaveAdmitted(
+          providerKey(storageKey, sessionId),
+          current,
+          validated,
+          expectedRevision,
+        );
         await this.root.write(filePath, validated);
       }),
     );
@@ -1046,31 +926,12 @@ class JsonProjectManagementStore implements IFlexProjectManagementStore {
           assertFlexProjectManagementRecord(value);
           return value;
         });
-        const actualRevision = current?.revision ?? 0;
-        if (current && sameProjectManagementGeneration(current, validated)) {
-          if ('deletedAt' in current) return;
-          if (actualRevision !== expectedRevision) {
-            throw new FlexHarnessStoreConflictError(
-              providerKey(storageKey, sessionId),
-              expectedRevision,
-              actualRevision,
-            );
-          }
-        } else if (current) {
-          if (!canInitializeProjectManagementGeneration(current, validated, expectedRevision)) {
-            throw new FlexHarnessStoreConflictError(
-              providerKey(storageKey, sessionId),
-              expectedRevision,
-              actualRevision,
-            );
-          }
-        } else if (actualRevision !== expectedRevision) {
-          throw new FlexHarnessStoreConflictError(
-            providerKey(storageKey, sessionId),
-            expectedRevision,
-            actualRevision,
-          );
-        }
+        if (!isProjectManagementTombstoneAdmitted(
+          providerKey(storageKey, sessionId),
+          current,
+          validated,
+          expectedRevision,
+        )) return;
         await this.root.write(filePath, validated);
       }),
     );
@@ -1163,12 +1024,7 @@ class JsonAgentEventStore implements plugins.IAgentEventStoreV2 {
         (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.`);
-        }
+        assertSameArchiveEvents(current, validated);
         return;
       }
       await this.root.write(filePath, validated);

package/ts/errors.ts

@@ -173,13 +173,19 @@ export class FlexHarnessStoreFormatError extends FlexHarnessError {
   }
 }
 
+/**
+ * What a store was doing when it could not confirm the outcome: `write` and `delete` name a
+ * database record, `delete-file` and `delete-directory` a file-system path.
+ */
+export type TFlexStoreCommitOperation = 'write' | 'delete' | 'delete-file' | 'delete-directory';
+
 export class FlexHarnessStoreCommitUncertainError extends FlexHarnessError {
   public readonly path: string;
-  public readonly operation: 'write' | 'delete-file' | 'delete-directory';
+  public readonly operation: TFlexStoreCommitOperation;
 
   constructor(
     path: string,
-    operation: 'write' | 'delete-file' | 'delete-directory',
+    operation: TFlexStoreCommitOperation,
     options: ErrorOptions,
   ) {
     super(

package/ts/readme.md

@@ -61,10 +61,12 @@ or provider SDKs.
 | `/chat` | Portable streaming `ChatSession`, history and usage | None |
 | `/chat/cli` | Ink/React terminal chat | `ink ink-text-input react`; TypeScript: `@types/react` |
 | `/chat/web` | Lit `flexchat-window`, `flexchat-message`, `flexchat-input` | `lit` |
+| `/chat/harness` | `FlexHarnessTranscript` and intents for the `@design.estate/dees-catalog` harness components, browser-safe | `@design.estate/dees-catalog` (types only) |
 | `/kvm` | Browser control, terminal framing and OCR observation | `puppeteer` |
 | `/documents` | PDF and image documents, `extractTextFromPdf` | `@push.rocks/smartpdf`; for image documents `sharp` |
 | `/mcp` | MCP clients and AI SDK tool conversion | `@modelcontextprotocol/sdk` |
 | `/migration` | Existing versioned harness migrations | None |
+| `/stores/nosqldb` | `NoSqlFlexHarnessStores`: cross-process CAS stores on `@lossless.org/client/nosqldb` | `@lossless.org/client` |
 
 The integrations in the last column use optional peer dependencies. Install them
 only for the entrypoints your project imports, for example:
@@ -1068,6 +1070,8 @@ After every harness using a `JsonFileFlexHarnessStores` instance has been dispos
 
 The JSON stores are explicitly not cross-process safe. When several processes can access the same storage namespace, every core `IFlexHarnessStores` domain and `stores.projectManagement` must use database-backed or equivalent cross-process CAS. Process-local CAS for the core stores or for PM alone is insufficient: session generation creation, cleanup tombstones, PM replacement, and stale-writer rejection must all retain their respective atomic preconditions across processes.
 
+`NoSqlFlexHarnessStores` from `/stores/nosqldb` is that database-backed bundle for every domain. Pass it an initialized `SmartdataDb` and `await stores.prepare()` at startup, before the first harness uses it; the subpath readme describes chunked snapshots and failure reporting.
+
 Direct store operations and non-run session mutations surface conflicts as `FlexHarnessStoreConflictError` or the corresponding AgentSession store conflict. Malformed, wrong-schema, or non-JSON snapshots are surfaced as `FlexHarnessStoreFormatError`. A write or deletion that changed its target but cannot confirm parent-directory durability surfaces `FlexHarnessStoreCommitUncertainError` with the affected path, operation, and cause. Run persistence failures cross the external error boundary and therefore become `FlexHarnessExternalError`. FlexHarness does not merge conflicts.
 
 Each domain serializes its own mutations. A successful run first persists a hidden completed projection, then finalizes the canonical Agent generation as `accepted`, then promotes the hidden projection publicly. Recovery uses the canonical generation outcome to promote an accepted stage or publish a failed/cancelled projection. Failed and cancelled generations remain auditable but never enter future model context.

package/ts/utils.storerules.ts

@@ -0,0 +1,177 @@
+import type * as plugins from './plugins.js';
+import {
+  FlexHarnessStoreConflictError,
+  FlexHarnessStoreFormatError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import type {
+  IFlexPermissionSnapshot,
+  IFlexProjectManagementSnapshot,
+  IFlexProjectManagementTombstone,
+  IFlexProjectManagementWriteContext,
+  IFlexScopeSnapshot,
+  TFlexProjectionSnapshot,
+  TFlexProjectManagementRecord,
+} from './interfaces.js';
+import { assertJsonSerializable, cloneSerializable } from './utils.json.js';
+import { assertExactKeys, assertRecord } from './utils.storecodecs.js';
+
+/**
+ * Store-independent admission rules every `IFlexHarnessStores` implementation applies: argument
+ * validation, the next-revision rule, exact session keys, and the project-management generation
+ * fence. Backends own only how they read, compare and write.
+ */
+
+type TSnapshot =
+  | IFlexScopeSnapshot
+  | TFlexProjectionSnapshot
+  | IFlexPermissionSnapshot
+  | TFlexProjectManagementRecord;
+type TSnapshotValidator<TSnapshotValue extends TSnapshot> = (
+  value: unknown,
+) => asserts value is TSnapshotValue;
+
+export function validateIdentifier(value: string, name: string): void {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new FlexHarnessValidationError(`${name} must be a non-empty string.`);
+  }
+}
+
+export function validateExpectedRevision(expectedRevision: number): void {
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+    throw new FlexHarnessValidationError('expectedRevision must be a non-negative integer.');
+  }
+}
+
+export function validateProjectManagementWriteContext(
+  writeContext: IFlexProjectManagementWriteContext,
+): void {
+  assertJsonSerializable(writeContext, '$writeContext');
+  assertRecord(writeContext, 'writeContext');
+  assertExactKeys(writeContext, ['actor', 'runId', 'agent', 'toolCallId'], 'writeContext');
+  if (writeContext.actor !== 'agent' && writeContext.actor !== 'application') {
+    throw new FlexHarnessValidationError('writeContext.actor must be agent or application.');
+  }
+  for (const key of ['runId', 'agent', 'toolCallId'] as const) {
+    if (writeContext[key] !== undefined) validateIdentifier(writeContext[key], `writeContext.${key}`);
+  }
+}
+
+export 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.`,
+    );
+  }
+  return cloneSerializable(snapshot);
+}
+
+export function providerKey(storageKey: string, sessionId: string): string {
+  validateIdentifier(storageKey, 'storageKey');
+  validateIdentifier(sessionId, 'sessionId');
+  return JSON.stringify([storageKey, sessionId]);
+}
+
+export function assertProjectionSession(snapshot: TFlexProjectionSnapshot, 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 sameProjectManagementGeneration(
+  left: TFlexProjectManagementRecord,
+  right: TFlexProjectManagementRecord,
+): boolean {
+  return left.sessionGenerationId === right.sessionGenerationId
+    && left.sessionGenerationSequence === right.sessionGenerationSequence;
+}
+
+function canInitializeProjectManagementGeneration(
+  current: TFlexProjectManagementRecord,
+  next: TFlexProjectManagementRecord,
+  expectedRevision: number,
+): boolean {
+  return 'deletedAt' in current
+    && expectedRevision === 0
+    && next.sessionGenerationId !== current.sessionGenerationId
+    && next.sessionGenerationSequence > current.sessionGenerationSequence;
+}
+
+/**
+ * Admits a live project-management save over the stored record: a CAS save within the stored
+ * generation, or a newer generation that replaces a tombstone at expected revision 0.
+ */
+export function assertProjectManagementSaveAdmitted(
+  key: string,
+  current: TFlexProjectManagementRecord | undefined,
+  snapshot: IFlexProjectManagementSnapshot,
+  expectedRevision: number,
+): void {
+  const actualRevision = current?.revision ?? 0;
+  if (current && !sameProjectManagementGeneration(current, snapshot)) {
+    if (!canInitializeProjectManagementGeneration(current, snapshot, expectedRevision)) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+  } else if ((current && 'deletedAt' in current) || actualRevision !== expectedRevision) {
+    throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+  }
+}
+
+/**
+ * Admits a project-management tombstone over the stored record. Returns false when the same
+ * generation is already tombstoned, which makes a repeated cleanup idempotent.
+ */
+export function isProjectManagementTombstoneAdmitted(
+  key: string,
+  current: TFlexProjectManagementRecord | undefined,
+  tombstone: IFlexProjectManagementTombstone,
+  expectedRevision: number,
+): boolean {
+  const actualRevision = current?.revision ?? 0;
+  if (current && sameProjectManagementGeneration(current, tombstone)) {
+    if ('deletedAt' in current) return false;
+    if (actualRevision !== expectedRevision) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+  } else if (current) {
+    if (!canInitializeProjectManagementGeneration(current, tombstone, expectedRevision)) {
+      throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+    }
+  } else if (actualRevision !== expectedRevision) {
+    throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
+  }
+  return true;
+}
+
+/** An archive is written once; repeating it with the same events is a no-op. */
+export function assertSameArchiveEvents(
+  existing: plugins.IAgentEventArchiveV2,
+  next: plugins.IAgentEventArchiveV2,
+): void {
+  if (
+    JSON.stringify(existing.events.map((event) => event.id))
+    !== JSON.stringify(next.events.map((event) => event.id))
+  ) {
+    throw new Error(`Archive "${next.archiveId}" already exists with different events.`);
+  }
+}