@modelprofile.com/flexharness 9.10.0 → 10.1.0

package/ts_stores_nosqldb/classes.recordstore.ts

@@ -0,0 +1,560 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessStoreCommitUncertainError,
+  FlexHarnessStoreFormatError,
+  FlexHarnessValidationError,
+} from '../ts/errors.js';
+
+export type TFlexRecordDomain =
+  | 'scope'
+  | 'projection'
+  | 'permission'
+  | 'projectManagement'
+  | 'agentEvents'
+  | 'agentEventArchive'
+  | 'jobs';
+
+/** Names one record: a domain snapshot of a storage key, a session or an archive. */
+export interface IFlexRecordAddress {
+  domain: TFlexRecordDomain;
+  storageKey: string;
+  sessionId?: string;
+  archiveId?: string;
+}
+
+/** The next stored value a mutation decided on. */
+export interface IFlexRecordWrite {
+  revision: number;
+  value: unknown;
+}
+
+export interface IFlexRecordMutation<TValue> {
+  validate: (value: unknown) => TValue;
+  /** Decides on the stored value: the next value, nothing to write, or a thrown rejection. */
+  decide: (current: TValue | undefined) => IFlexRecordWrite | undefined;
+  /** The conflict to report when concurrent writers keep winning the compare-and-swap. */
+  contention: (actualRevision: number) => Error;
+}
+
+export const FLEX_RECORD_COLLECTION = 'flexharness_records';
+export const FLEX_CHUNK_COLLECTION = 'flexharness_chunks';
+
+/**
+ * UTF-16 code units a record holds inline, and the size of each chunk of a longer payload. A
+ * chunk stays below 3 MiB of UTF-8, far under the 16 MiB document limit NoSQLDB and MongoDB
+ * enforce, so a record and each of its chunks always fit one document.
+ */
+export const FLEX_RECORD_CHUNK_CODE_UNITS = 1024 * 1024;
+
+const mutationAttempts = 8;
+const mutationBackoffBaseMs = 5;
+const mutationBackoffMaxMs = 200;
+const chunkReadAttempts = 4;
+const defaultOperationTimeoutMs = 30_000;
+
+/**
+ * The head of one record. A payload up to one chunk is stored inline; a longer one lives in
+ * immutable chunks named by `blobId`. `writeToken` changes on every committed write and is the
+ * compare-and-swap fence. A head without payload or blob is a placeholder that reserves the
+ * record for a chunked first write; it reads as absent.
+ */
+export class FlexRecordDocument extends plugins.SmartDataDbDoc<FlexRecordDocument, FlexRecordDocument> {
+  public recordId!: string;
+  public domain!: TFlexRecordDomain;
+  public ownerKey!: string;
+  public namespaceKey!: string;
+  public revision!: number;
+  public writeToken!: string;
+  public payload!: string | null;
+  public blobId!: string | null;
+  public chunkCount!: number;
+  public payloadSha256!: string | null;
+  /** Set before the first chunk of this record is written; the record's writes then sweep. */
+  public chunked!: boolean;
+  public sweepCount!: number;
+}
+
+/** One immutable piece of a chunked payload, written against the head token it will replace. */
+export class FlexChunkDocument extends plugins.SmartDataDbDoc<FlexChunkDocument, FlexChunkDocument> {
+  public chunkId!: string;
+  public recordId!: string;
+  public domain!: TFlexRecordDomain;
+  public ownerKey!: string;
+  public namespaceKey!: string;
+  public blobId!: string;
+  public baseToken!: string;
+  public index!: number;
+  public data!: string;
+}
+
+type TRecordModel = typeof FlexRecordDocument;
+type TChunkModel = typeof FlexChunkDocument;
+
+function bindModels(db: plugins.SmartdataDb): { records: TRecordModel; chunks: TChunkModel } {
+  class BoundRecord extends FlexRecordDocument {}
+  class BoundChunk extends FlexChunkDocument {}
+  plugins.defineCollectionModel(BoundRecord, db, {
+    collectionName: FLEX_RECORD_COLLECTION,
+    persistedFields: [
+      'recordId',
+      'domain',
+      'ownerKey',
+      'namespaceKey',
+      'revision',
+      'writeToken',
+      'payload',
+      'blobId',
+      'chunkCount',
+      'payloadSha256',
+      'chunked',
+      'sweepCount',
+    ],
+    numericFields: ['revision', 'chunkCount', 'sweepCount'],
+    identityFields: ['recordId'],
+    indexes: [
+      { name: 'flexharness_record_id', key: { recordId: 1 }, options: { unique: true } },
+      { name: 'flexharness_record_owner', key: { ownerKey: 1, domain: 1 } },
+      { name: 'flexharness_record_namespace', key: { namespaceKey: 1, domain: 1 } },
+    ],
+  });
+  plugins.defineCollectionModel(BoundChunk, db, {
+    collectionName: FLEX_CHUNK_COLLECTION,
+    persistedFields: [
+      'chunkId',
+      'recordId',
+      'domain',
+      'ownerKey',
+      'namespaceKey',
+      'blobId',
+      'baseToken',
+      'index',
+      'data',
+    ],
+    numericFields: ['index'],
+    identityFields: ['chunkId'],
+    indexes: [
+      { name: 'flexharness_chunk_id', key: { chunkId: 1 }, options: { unique: true } },
+      { name: 'flexharness_chunk_blob', key: { blobId: 1 } },
+      { name: 'flexharness_chunk_record', key: { recordId: 1 } },
+      { name: 'flexharness_chunk_owner', key: { ownerKey: 1, domain: 1 } },
+      { name: 'flexharness_chunk_namespace', key: { namespaceKey: 1, domain: 1 } },
+    ],
+  });
+  return { records: BoundRecord, chunks: BoundChunk };
+}
+
+interface IResolvedAddress {
+  recordId: string;
+  domain: TFlexRecordDomain;
+  ownerKey: string;
+  namespaceKey: string;
+  path: string;
+}
+
+interface IStoredHead {
+  document?: FlexRecordDocument;
+  text?: string;
+}
+
+const digest = (value: string): string =>
+  plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+
+function splitPayload(text: string): string[] {
+  const chunks: string[] = [];
+  let start = 0;
+  while (start < text.length) {
+    let end = Math.min(start + FLEX_RECORD_CHUNK_CODE_UNITS, text.length);
+    const last = text.charCodeAt(end - 1);
+    if (end < text.length && last >= 0xd800 && last <= 0xdbff) end--;
+    chunks.push(text.slice(start, end));
+    start = end;
+  }
+  return chunks;
+}
+
+/** A rejection the database states before anything is written; every other failure may have applied. */
+function isDefiniteRejection(error: unknown): boolean {
+  return error instanceof plugins.SmartdataPersistenceError && [
+    'invalid_argument',
+    'invalid_configuration',
+    'invalid_document',
+    'unsupported_operation',
+    'unique_conflict',
+  ].includes(error.code);
+}
+
+/**
+ * Waits before retrying a lost head swap: exponential from 5 ms, capped at 200 ms, with full
+ * jitter over its upper half, so writers that lost the same race spread out.
+ */
+function mutationBackoff(attempt: number): Promise<void> {
+  const ceiling = Math.min(mutationBackoffMaxMs, mutationBackoffBaseMs * 2 ** (attempt - 1));
+  const delayMs = ceiling / 2 + Math.random() * (ceiling / 2);
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+function isUniqueConflict(error: unknown): boolean {
+  return error instanceof plugins.SmartdataPersistenceError && error.code === 'unique_conflict';
+}
+
+export interface IFlexRecordStoreOptions {
+  db: plugins.SmartdataDb;
+  operationTimeoutMs?: number;
+}
+
+/**
+ * Compare-and-swap records on `@lossless.org/client/nosqldb`. A write reads the head, decides,
+ * writes any chunks, and swaps the head only while its `writeToken` is unchanged. Chunks of a
+ * replaced or abandoned payload are swept in a transaction that also touches the head, so a
+ * concurrent deletion or writer can never lose chunks its head references.
+ */
+export class FlexRecordStore {
+  private readonly db: plugins.SmartdataDb;
+  private readonly timeoutMs: number;
+  private readonly records: TRecordModel;
+  private readonly chunks: TChunkModel;
+  private preparation?: Promise<void>;
+
+  constructor(options: IFlexRecordStoreOptions) {
+    const timeoutMs = options.operationTimeoutMs ?? defaultOperationTimeoutMs;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000) {
+      throw new FlexHarnessValidationError('operationTimeoutMs must be an integer from 1 to 120000.');
+    }
+    this.db = options.db;
+    this.timeoutMs = timeoutMs;
+    ({ records: this.records, chunks: this.chunks } = bindModels(options.db));
+  }
+
+  /** Creates or verifies both collections and their indexes once; a failed attempt is retried. */
+  public prepare(): Promise<void> {
+    this.preparation ??= this.prepareCollections().catch((error: unknown) => {
+      this.preparation = undefined;
+      throw error;
+    });
+    return this.preparation;
+  }
+
+  private async prepareCollections(): Promise<void> {
+    const capabilities = this.db.capabilities;
+    if (!capabilities) {
+      throw new FlexHarnessValidationError(
+        'NoSqlFlexHarnessStores requires an initialized SmartdataDb.',
+      );
+    }
+    if (capabilities.transactions === 'unsupported') {
+      throw new FlexHarnessValidationError(
+        'NoSqlFlexHarnessStores requires a database that supports transactions.',
+      );
+    }
+    const options = { mode: 'ensureCompatible' as const, timeoutMs: this.timeoutMs };
+    await this.records.prepareCollection(options);
+    await this.chunks.prepareCollection(options);
+  }
+
+  private resolve(address: IFlexRecordAddress): IResolvedAddress {
+    const recordId = digest(JSON.stringify([
+      address.domain,
+      address.storageKey,
+      address.sessionId ?? null,
+      address.archiveId ?? null,
+    ]));
+    return {
+      recordId,
+      domain: address.domain,
+      ownerKey: digest(JSON.stringify([address.storageKey, address.sessionId ?? null])),
+      namespaceKey: digest(address.storageKey),
+      path: `${FLEX_RECORD_COLLECTION}/${address.domain}/${recordId}`,
+    };
+  }
+
+  public async read<TValue>(
+    address: IFlexRecordAddress,
+    validate: (value: unknown) => TValue,
+  ): Promise<TValue | undefined> {
+    await this.prepare();
+    const resolved = this.resolve(address);
+    return this.parse(resolved, await this.readHead(resolved), validate);
+  }
+
+  public async mutate<TValue>(
+    address: IFlexRecordAddress,
+    mutation: IFlexRecordMutation<TValue>,
+  ): Promise<void> {
+    await this.prepare();
+    const resolved = this.resolve(address);
+    let actualRevision = 0;
+    for (let attempt = 0; attempt < mutationAttempts; attempt++) {
+      if (attempt > 0) await mutationBackoff(attempt);
+      const head = await this.readHead(resolved);
+      const current = this.parse(resolved, head, mutation.validate);
+      actualRevision = head.document?.revision ?? 0;
+      const write = mutation.decide(current);
+      if (!write) return;
+      if (await this.commit(resolved, head.document, write)) return;
+    }
+    throw mutation.contention(actualRevision);
+  }
+
+  /** Deletes every record and chunk one session owns in the given domains. */
+  public async deleteOwner(
+    storageKey: string,
+    sessionId: string,
+    domains: readonly TFlexRecordDomain[],
+  ): Promise<void> {
+    await this.prepare();
+    const ownerKey = digest(JSON.stringify([storageKey, sessionId]));
+    await this.deleteInTransaction(
+      `${FLEX_RECORD_COLLECTION}/${domains.join('+')}/owner/${ownerKey}`,
+      { ownerKey, domain: { $in: [...domains] } },
+    );
+  }
+
+  /** Deletes every record and chunk of one domain in a storage namespace. */
+  public async purgeNamespace(storageKey: string, domain: TFlexRecordDomain): Promise<void> {
+    await this.prepare();
+    const namespaceKey = digest(storageKey);
+    await this.deleteInTransaction(
+      `${FLEX_RECORD_COLLECTION}/${domain}/namespace/${namespaceKey}`,
+      { namespaceKey, domain },
+    );
+  }
+
+  private async deleteInTransaction(
+    path: string,
+    selector:
+      | { ownerKey: string; domain: { $in: TFlexRecordDomain[] } }
+      | { namespaceKey: string; domain: TFlexRecordDomain },
+  ): Promise<void> {
+    const session = this.db.createSession();
+    try {
+      await session.withTransaction(async (transaction) => {
+        await this.records.atomicDeleteMany(selector, { session: transaction });
+        await this.chunks.atomicDeleteMany(selector, { session: transaction });
+      }, { timeoutMS: this.timeoutMs });
+    } catch (error) {
+      if (plugins.SmartdataSession.getCommitOutcome(error) === 'not_committed') throw error;
+      throw new FlexHarnessStoreCommitUncertainError(path, 'delete', { cause: error });
+    } finally {
+      await session.close();
+    }
+  }
+
+  private parse<TValue>(
+    resolved: IResolvedAddress,
+    head: IStoredHead,
+    validate: (value: unknown) => TValue,
+  ): TValue | undefined {
+    if (head.text === undefined) return undefined;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(head.text);
+    } catch (error) {
+      throw new FlexHarnessStoreFormatError(`Malformed JSON at ${resolved.path}.`, { cause: error });
+    }
+    try {
+      return validate(parsed);
+    } catch (error) {
+      if (error instanceof FlexHarnessStoreFormatError) {
+        throw new FlexHarnessStoreFormatError(`Invalid record at ${resolved.path}: ${error.message}`, {
+          cause: error,
+        });
+      }
+      throw error;
+    }
+  }
+
+  private findHead(resolved: IResolvedAddress): Promise<FlexRecordDocument | null> {
+    return this.records.getInstance({ recordId: resolved.recordId }, { timeoutMS: this.timeoutMs });
+  }
+
+  private async readHead(resolved: IResolvedAddress): Promise<IStoredHead> {
+    for (let attempt = 0; attempt < chunkReadAttempts; attempt++) {
+      const document = await this.findHead(resolved);
+      if (!document) return {};
+      if (document.payload !== null) return { document, text: document.payload };
+      if (document.blobId === null) return { document };
+      const text = await this.readBlob(document);
+      if (text !== undefined) return { document, text };
+      const latest = await this.findHead(resolved);
+      if (latest?.writeToken === document.writeToken) {
+        throw new FlexHarnessStoreFormatError(
+          `${resolved.path} references ${document.chunkCount} chunks of blob "${document.blobId}", but they are incomplete.`,
+        );
+      }
+    }
+    throw new FlexHarnessStoreFormatError(
+      `${resolved.path} changed during ${chunkReadAttempts} consecutive reads.`,
+    );
+  }
+
+  private async readBlob(document: FlexRecordDocument): Promise<string | undefined> {
+    const stored = await this.chunks.getInstances(
+      { blobId: document.blobId! },
+      { timeoutMS: this.timeoutMs },
+    );
+    if (stored.length !== document.chunkCount) return undefined;
+    const text = stored
+      .sort((left, right) => left.index - right.index)
+      .map((chunk) => chunk.data)
+      .join('');
+    return digest(text) === document.payloadSha256 ? text : undefined;
+  }
+
+  /** Returns false when another writer swapped the head first; nothing of this write remains. */
+  private async commit(
+    resolved: IResolvedAddress,
+    stored: FlexRecordDocument | undefined,
+    write: IFlexRecordWrite,
+  ): Promise<boolean> {
+    const text = JSON.stringify(write.value);
+    const chunked = text.length > FLEX_RECORD_CHUNK_CODE_UNITS;
+    let current = stored;
+    if (!current) {
+      if (!chunked) return this.insertHead(resolved, write.revision, text);
+      current = await this.insertPlaceholder(resolved);
+      if (!current) return false;
+    } else if (current.chunked) {
+      await this.sweep(current);
+    } else if (chunked && !await this.markChunked(current)) {
+      return false;
+    }
+    const blobId = chunked ? await this.writeBlob(resolved, current.writeToken, text) : null;
+    let swapped: boolean;
+    try {
+      const outcome = await this.records.atomicUpdate(
+        { recordId: resolved.recordId, writeToken: current.writeToken },
+        {
+          $set: {
+            revision: write.revision,
+            writeToken: plugins.crypto.randomUUID(),
+            payload: chunked ? null : text,
+            blobId,
+            chunkCount: chunked ? splitPayload(text).length : 0,
+            payloadSha256: chunked ? digest(text) : null,
+          },
+        },
+        { timeoutMS: this.timeoutMs },
+      );
+      swapped = outcome.matchedCount === 1;
+    } catch (error) {
+      if (isDefiniteRejection(error)) throw error;
+      throw new FlexHarnessStoreCommitUncertainError(resolved.path, 'write', { cause: error });
+    }
+    if (!swapped && blobId !== null) {
+      await this.chunks.atomicDeleteMany({ blobId }, { timeoutMS: this.timeoutMs });
+    }
+    return swapped;
+  }
+
+  private newHead(resolved: IResolvedAddress): FlexRecordDocument {
+    const head = new this.records();
+    head.recordId = resolved.recordId;
+    head.domain = resolved.domain;
+    head.ownerKey = resolved.ownerKey;
+    head.namespaceKey = resolved.namespaceKey;
+    head.writeToken = plugins.crypto.randomUUID();
+    head.blobId = null;
+    head.chunkCount = 0;
+    head.payloadSha256 = null;
+    head.sweepCount = 0;
+    return head;
+  }
+
+  private async insertHead(
+    resolved: IResolvedAddress,
+    revision: number,
+    text: string,
+  ): Promise<boolean> {
+    const head = this.newHead(resolved);
+    head.revision = revision;
+    head.payload = text;
+    head.chunked = false;
+    try {
+      await this.records.insert(head, { timeoutMS: this.timeoutMs });
+      return true;
+    } catch (error) {
+      if (isUniqueConflict(error)) return false;
+      if (isDefiniteRejection(error)) throw error;
+      throw new FlexHarnessStoreCommitUncertainError(resolved.path, 'write', { cause: error });
+    }
+  }
+
+  /** Reserves the record for a chunked first write, so its chunks have a head token to replace. */
+  private async insertPlaceholder(
+    resolved: IResolvedAddress,
+  ): Promise<FlexRecordDocument | undefined> {
+    const head = this.newHead(resolved);
+    head.revision = 0;
+    head.payload = null;
+    head.chunked = true;
+    try {
+      await this.records.insert(head, { timeoutMS: this.timeoutMs });
+      return head;
+    } catch (error) {
+      if (isUniqueConflict(error)) return undefined;
+      throw error;
+    }
+  }
+
+  private async markChunked(current: FlexRecordDocument): Promise<boolean> {
+    const outcome = await this.records.atomicUpdate(
+      { recordId: current.recordId, writeToken: current.writeToken },
+      { $set: { chunked: true } },
+      { timeoutMS: this.timeoutMs },
+    );
+    return outcome.matchedCount === 1;
+  }
+
+  private async writeBlob(
+    resolved: IResolvedAddress,
+    baseToken: string,
+    text: string,
+  ): Promise<string> {
+    const blobId = plugins.crypto.randomUUID();
+    const pieces = splitPayload(text);
+    for (let index = 0; index < pieces.length; index++) {
+      const chunk = new this.chunks();
+      chunk.chunkId = `${blobId}:${index}`;
+      chunk.recordId = resolved.recordId;
+      chunk.domain = resolved.domain;
+      chunk.ownerKey = resolved.ownerKey;
+      chunk.namespaceKey = resolved.namespaceKey;
+      chunk.blobId = blobId;
+      chunk.baseToken = baseToken;
+      chunk.index = index;
+      chunk.data = pieces[index];
+      await this.chunks.insert(chunk, { timeoutMS: this.timeoutMs });
+    }
+    return blobId;
+  }
+
+  /**
+   * Deletes the record's chunks that no head can reference any more: every blob but the current
+   * one that was written against another head token. A writer that read the current token keeps
+   * its chunks. Touching the head in the same transaction makes a concurrent deletion conflict,
+   * so chunks written after a deletion are never swept by a transaction that predates it.
+   */
+  private async sweep(current: FlexRecordDocument): Promise<void> {
+    const session = this.db.createSession();
+    try {
+      await session.withTransaction(async (transaction) => {
+        const touched = await this.records.atomicUpdate(
+          { recordId: current.recordId, writeToken: current.writeToken },
+          { $inc: { sweepCount: 1 } },
+          { session: transaction },
+        );
+        if (touched.matchedCount !== 1) return;
+        await this.chunks.atomicDeleteMany(
+          {
+            recordId: current.recordId,
+            baseToken: { $ne: current.writeToken },
+            ...(current.blobId === null ? {} : { blobId: { $ne: current.blobId } }),
+          },
+          { session: transaction },
+        );
+      }, { timeoutMS: this.timeoutMs });
+    } finally {
+      await session.close();
+    }
+  }
+}

package/ts_stores_nosqldb/index.ts

@@ -0,0 +1,9 @@
+export {
+  NoSqlFlexHarnessStores,
+  type INoSqlFlexHarnessStoresOptions,
+} from './classes.nosqldbstores.js';
+export {
+  FLEX_CHUNK_COLLECTION,
+  FLEX_RECORD_CHUNK_CODE_UNITS,
+  FLEX_RECORD_COLLECTION,
+} from './classes.recordstore.js';

package/ts_stores_nosqldb/plugins.ts

@@ -0,0 +1,38 @@
+// node native scope
+import * as crypto from 'node:crypto';
+
+export { crypto };
+
+// @modelprofile.com scope
+import {
+  AgentEventStoreConflictError,
+  ToolJobStoreConflictError,
+} from '@modelprofile.com/flexharness-agent';
+
+export { AgentEventStoreConflictError, ToolJobStoreConflictError };
+export type {
+  IAgentEventArchiveV2,
+  IAgentEventSnapshotV2,
+  IAgentEventStoreV2,
+  IToolJobSnapshot,
+  IToolJobState,
+  IToolJobStore,
+  TAgentEvent,
+} from '@modelprofile.com/flexharness-agent';
+
+// @lossless.org scope
+import {
+  SmartDataDbDoc,
+  SmartdataDb,
+  SmartdataPersistenceError,
+  SmartdataSession,
+  defineCollectionModel,
+} from '@lossless.org/client/nosqldb';
+
+export {
+  SmartDataDbDoc,
+  SmartdataDb,
+  SmartdataPersistenceError,
+  SmartdataSession,
+  defineCollectionModel,
+};

package/ts_stores_nosqldb/readme.md

@@ -0,0 +1,53 @@
+FlexHarness session stores on `@lossless.org/client/nosqldb`, with compare-and-swap that holds across processes.
+
+```sh
+pnpm add @modelprofile.com/flexharness @lossless.org/client
+```
+
+```typescript
+import { SmartdataDb } from '@lossless.org/client/nosqldb';
+import { FlexHarness } from '@modelprofile.com/flexharness';
+import { NoSqlFlexHarnessStores } from '@modelprofile.com/flexharness/stores/nosqldb';
+
+const db = new SmartdataDb({ mongoDbUrl, mongoDbName: 'app' });
+await db.init();
+const stores = new NoSqlFlexHarnessStores({ db });
+await stores.prepare();
+
+const harness = new FlexHarness({ scopeResolver, modelResolver, stores });
+```
+
+`NoSqlFlexHarnessStores` implements every `IFlexHarnessStores` domain: scopes, projections with undo and redo history, remembered permissions, project management, Agent events with their archives, and background jobs. Several processes may open the same database; every save is a compare-and-swap on the stored record, so a stale writer gets the domain's conflict error instead of overwriting a newer snapshot.
+
+The database is the application's. The stores never close it, and they need NoSQLDB or a MongoDB deployment with transactions. `prepare()` creates or verifies the `flexharness_records` and `flexharness_chunks` collections and their indexes; every store operation awaits the same preparation, so calling it at startup only moves that work and its failure forward. `operationTimeoutMs` (1 to 120000, default 30000) bounds every database call and transaction.
+
+A snapshot of up to `FLEX_RECORD_CHUNK_CODE_UNITS` UTF-16 code units of JSON is stored inside its record. A longer one is split into chunks of that size, each below 3 MiB of UTF-8, so a snapshot may exceed the 16 MiB document limit of NoSQLDB and MongoDB. Chunks are written before the record swaps to them. The chunks a record no longer references are removed by a later write of that record, in a transaction that also touches the record, and deleting a session or purging a namespace removes its records and chunks in one transaction. A writer that crashes between writing its chunks and swapping the record leaves only unreferenced chunks, never a record that points at missing ones. They are written against the record's current write token, which a concurrent writer may still win with, so the write after the next one removes them, or the deletion of the session or namespace does.
+
+A record swap that loses to a concurrent writer is decided again against the newer record, up to eight times, with a bounded exponential backoff between attempts; a writer that still loses gets the domain's conflict error.
+
+A save that may have reached the database without a confirmation, such as a timed-out or interrupted record write or a deletion transaction with an unknown commit outcome, rejects with `FlexHarnessStoreCommitUncertainError` (operation `write` or `delete`). FlexHarness then fences the namespace, as it does for the JSON file stores.
+
+## Issue Reporting and Security
+
+Report issues and security concerns through [community.foss.global](https://community.foss.global).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.