@modelprofile.com/flexharness 12.0.0 → 12.1.1

package/ts_stores_nosqldb/classes.recordstore.ts

@@ -176,14 +176,16 @@ export class FlexChangePageDocument extends plugins.SmartDataDbDoc<FlexChangePag
 }
 
 /**
- * One storage namespace. Every record creation in the namespace increments `creationCount` in
- * its transaction, so a concurrent fenced purge, which sets `fenced`, conflicts with it. A fenced
- * namespace accepts no new record.
+ * A namespace fence or a target's deletion marker. Every write touches its namespace in its
+ * transaction, so it conflicts with a concurrent fence or deletion admission. A purge token
+ * hides the target until bounded cleanup completes; a fence permanently refuses writes.
  */
 export class FlexNamespaceDocument extends plugins.SmartDataDbDoc<FlexNamespaceDocument, FlexNamespaceDocument> {
   public namespaceKey!: string;
   public fenced!: boolean;
   public creationCount!: number;
+  public purgeToken?: string | null;
+  public storageNamespaceKey?: string;
 }
 
 type TRecordModel = typeof FlexRecordDocument;
@@ -280,11 +282,12 @@ export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels
   });
   plugins.defineCollectionModel(BoundNamespace, db, {
     collectionName: FLEX_NAMESPACE_COLLECTION,
-    persistedFields: ['namespaceKey', 'fenced', 'creationCount'],
+    persistedFields: ['namespaceKey', 'fenced', 'creationCount', 'purgeToken', 'storageNamespaceKey'],
     numericFields: ['creationCount'],
     identityFields: ['namespaceKey'],
     indexes: [
       { name: 'flexharness_namespace_key', key: { namespaceKey: 1 }, options: { unique: true } },
+      { name: 'flexharness_namespace_storage', key: { storageNamespaceKey: 1 } },
     ],
   });
   return { records: BoundRecord, chunks: BoundChunk, changes: BoundChangePage, namespaces: BoundNamespace };
@@ -308,6 +311,15 @@ interface IStoredLog<TSnapshot> {
   value?: TSnapshot;
 }
 
+type TDeletionSelector =
+  | { recordId: string; domain: TFlexRecordDomain }
+  | { ownerKey: string; domain: TFlexRecordDomain }
+  | { namespaceKey: string; domain?: TFlexRecordDomain };
+
+type TDeletionDocument = FlexRecordDocument | FlexChunkDocument | FlexChangePageDocument | FlexNamespaceDocument;
+
+const deletionBatchSize = 4;
+
 const digest = (value: string): string =>
   plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
 
@@ -324,17 +336,6 @@ function splitPayload(text: string): string[] {
   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.
@@ -444,8 +445,10 @@ export class FlexRecordStore {
   ): Promise<TValue | undefined> {
     await this.prepare();
     const resolved = this.resolve(address);
-    const head = await this.readHead(resolved);
-    return head.text === undefined ? undefined : this.parse(resolved, head.text, validate);
+    return this.readVisible(resolved, async () => {
+      const head = await this.readHead(resolved);
+      return head.text === undefined ? undefined : this.parse(resolved, head.text, validate);
+    });
   }
 
   /** Reads a log record: its base with every change applied, checked in full. */
@@ -454,7 +457,8 @@ export class FlexRecordStore {
     log: IFlexRecordLog<TSnapshot, TChange>,
   ): Promise<TSnapshot | undefined> {
     await this.prepare();
-    return (await this.loadLog(this.resolve(address), log)).value;
+    const resolved = this.resolve(address);
+    return this.readVisible(resolved, async () => (await this.loadLog(resolved, log)).value);
   }
 
   /**
@@ -539,11 +543,12 @@ export class FlexRecordStore {
     throw contention(actualRevision);
   }
 
-  /** Deletes one record with its chunks and change pages. */
+  /** Logically deletes one record before removing its chunks and change pages in bounded batches. */
   public async delete(address: IFlexRecordAddress): Promise<void> {
     await this.prepare();
     const resolved = this.resolve(address);
-    await this.deleteInTransaction(resolved.path, { recordId: resolved.recordId, domain: resolved.domain });
+    await this.deleteBatched(resolved.path, resolved.namespaceKey, `record/${resolved.recordId}`,
+      { recordId: resolved.recordId, domain: resolved.domain });
   }
 
   /** Deletes every record, chunk and change page one session owns in the given domains. */
@@ -554,76 +559,195 @@ export class FlexRecordStore {
   ): 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] } },
-    );
+    for (const domain of domains) {
+      await this.deleteBatched(`${FLEX_RECORD_COLLECTION}/${domain}/owner/${ownerKey}`,
+        digest(storageKey), `owner/${ownerKey}/${domain}`, { ownerKey, domain });
+    }
   }
 
   /**
-   * Deletes every record, chunk and change page of a storage namespace in one domain, or in every
-   * domain together with its namespace document unless a fence holds it.
+   * Marks the namespace or domain absent before draining its records, chunks and change pages.
+   * The marker survives interruption and is removed after cleanup unless a fence holds it.
    */
   public async purgeNamespace(storageKey: string, domain?: TFlexRecordDomain): Promise<void> {
     await this.prepare();
     const namespaceKey = digest(storageKey);
-    await this.deleteInTransaction(
+    await this.deleteBatched(
       `${FLEX_RECORD_COLLECTION}/${domain ?? 'all'}/namespace/${namespaceKey}`,
+      namespaceKey,
+      domain ? `domain/${namespaceKey}/${domain}` : namespaceKey,
       domain ? { namespaceKey, domain } : { namespaceKey },
-      domain
-        ? undefined
-        : (transaction) => this.namespaces.atomicDeleteMany(
-          { namespaceKey, fenced: false },
-          { session: transaction },
-        ),
     );
   }
 
   /**
-   * Fences a storage namespace and deletes every record, chunk and change page of it in one
-   * transaction. The fence is permanent: every later record creation in the namespace is refused,
-   * and a creation that runs concurrently either commits first and is deleted, or conflicts and is
-   * refused.
+   * Atomically fences a storage namespace before bounded physical deletion. The fence is
+   * permanent: every later write is refused, and a concurrent write either commits before
+   * the fence and is deleted, or conflicts and is refused.
    */
   public async fenceNamespace(storageKey: string): Promise<void> {
     await this.prepare();
     const namespaceKey = digest(storageKey);
-    await this.deleteInTransaction(
+    await this.deleteBatched(
       `${FLEX_RECORD_COLLECTION}/all/namespace/${namespaceKey}`,
+      namespaceKey,
+      namespaceKey,
       { namespaceKey },
-      (transaction) => this.namespaces.atomicUpdate(
-        { namespaceKey },
-        { $set: { fenced: true }, $setOnInsert: { creationCount: 0 } },
-        { upsert: true, session: transaction },
-      ),
+      true,
     );
   }
 
-  /** Deletes the selected records, chunks and change pages, after `namespace` changes the namespace document. */
-  private async deleteInTransaction(
+  private async deleteBatched(
     path: string,
-    selector:
-      | { recordId: string; domain: TFlexRecordDomain }
-      | { ownerKey: string; domain: { $in: TFlexRecordDomain[] } }
-      | { namespaceKey: string; domain?: TFlexRecordDomain },
-    namespace?: (transaction: plugins.SmartdataSession) => Promise<unknown>,
+    namespaceKey: string,
+    markerKey: string,
+    selector: TDeletionSelector,
+    fence = false,
   ): Promise<void> {
+    const token = await this.transaction(path, 'delete', async (transaction) => {
+      await this.touchNamespace(namespaceKey, transaction);
+      const marker = await this.namespaces.getInstance({ namespaceKey: markerKey }, { session: transaction });
+      const purgeToken = marker?.purgeToken ?? plugins.crypto.randomUUID();
+      await this.namespaces.atomicUpdate({ namespaceKey: markerKey }, {
+        $set: { purgeToken, storageNamespaceKey: namespaceKey, ...(fence ? { fenced: true } : {}) },
+        $setOnInsert: { creationCount: 0, ...(fence ? {} : { fenced: false }) },
+      }, { upsert: true, session: transaction });
+      return purgeToken;
+    });
+    if (!token) return;
+    const batches: {
+      model: TRecordModel | TChunkModel | TChangePageModel | TNamespaceModel;
+      identity: string;
+      filter: TDeletionSelector | { storageNamespaceKey: string; namespaceKey: { $ne: string } };
+    }[] = [
+      { model: this.records, identity: 'recordId', filter: selector },
+      { model: this.chunks, identity: 'chunkId', filter: selector },
+      { model: this.changes, identity: 'pageId', filter: selector },
+    ];
+    if (markerKey === namespaceKey && !('domain' in selector)) batches.push({ model: this.namespaces,
+      identity: 'namespaceKey', filter: { storageNamespaceKey: namespaceKey, namespaceKey: { $ne: markerKey } } });
+    for (const { model, identity, filter } of batches) {
+      for (;;) {
+        const page = await model.getPagedInstances<TDeletionDocument>({ filter, sortField: identity,
+          uniqueField: identity, limit: deletionBatchSize, timeoutMS: this.timeoutMs });
+        if (page.documents.length === 0) break;
+        const active = await this.transaction(path, 'delete', async (transaction) => {
+          const touched = await this.namespaces.atomicUpdate({ namespaceKey: markerKey, purgeToken: token },
+            { $inc: { creationCount: 1 } }, { session: transaction });
+          if (touched.matchedCount !== 1) return false;
+          const identifiers = page.documents.map((document) => this.documentIdentity(document, identity));
+          await model.atomicDeleteMany<TDeletionDocument>({ ...filter, [identity]: { $in: identifiers } },
+            { session: transaction });
+          return true;
+        });
+        if (!active) return;
+      }
+    }
+    await this.transaction(path, 'delete', async (transaction) => {
+      await this.touchNamespace(namespaceKey, transaction);
+      const completed = await this.namespaces.atomicUpdate({ namespaceKey: markerKey, purgeToken: token },
+        { $set: { purgeToken: null } }, { session: transaction });
+      if (completed.matchedCount !== 1) return;
+      await this.namespaces.atomicDeleteMany({ namespaceKey: markerKey, purgeToken: null, fenced: false },
+        { session: transaction });
+    });
+  }
+
+  private async transaction<TResult>(
+    path: string,
+    operation: 'write' | 'delete',
+    callback: (transaction: plugins.SmartdataSession) => Promise<TResult>,
+  ): Promise<TResult | undefined> {
     const session = this.db.createSession();
     try {
-      await session.withTransaction(async (transaction) => {
-        await namespace?.(transaction);
-        await this.records.atomicDeleteMany(selector, { session: transaction });
-        await this.chunks.atomicDeleteMany(selector, { session: transaction });
-        await this.changes.atomicDeleteMany(selector, { session: transaction });
-      }, { timeoutMS: this.timeoutMs });
+      return await session.withTransaction(callback, { timeoutMS: this.timeoutMs });
     } catch (error) {
       if (plugins.SmartdataSession.getCommitOutcome(error) === 'not_committed') throw error;
-      throw new FlexHarnessStoreCommitUncertainError(path, 'delete', { cause: error });
+      throw new FlexHarnessStoreCommitUncertainError(path, operation, { cause: error });
     } finally {
       await session.close();
     }
   }
 
+  private documentIdentity(document: TDeletionDocument, identity: string): string {
+    if (identity === 'recordId') return (document as FlexRecordDocument).recordId;
+    if (identity === 'chunkId') return (document as FlexChunkDocument).chunkId;
+    if (identity === 'pageId') return (document as FlexChangePageDocument).pageId;
+    return document.namespaceKey;
+  }
+
+  private markerKeys(resolved: IResolvedAddress): string[] {
+    return [resolved.namespaceKey, `domain/${resolved.namespaceKey}/${resolved.domain}`,
+      `owner/${resolved.ownerKey}/${resolved.domain}`, `record/${resolved.recordId}`];
+  }
+
+  private async blocked(resolved: IResolvedAddress, session?: plugins.SmartdataSession): Promise<boolean> {
+    const markers = await this.namespaces.getInstances({ namespaceKey: { $in: this.markerKeys(resolved) } },
+      session ? { session } : { timeoutMS: this.timeoutMs });
+    return markers.some((marker) => marker.fenced || Boolean(marker.purgeToken));
+  }
+
+  private touchNamespace(namespaceKey: string, session: plugins.SmartdataSession): Promise<unknown> {
+    return this.namespaces.atomicUpdate({ namespaceKey },
+      { $inc: { creationCount: 1 }, $setOnInsert: { fenced: false } }, { upsert: true, session });
+  }
+
+  private writeTransaction<TResult>(resolved: IResolvedAddress,
+    callback: (transaction: plugins.SmartdataSession) => Promise<TResult>): Promise<TResult | undefined> {
+    return this.transaction(resolved.path, 'write', async (transaction) => {
+      if (await this.blocked(resolved, transaction)) throw new FlexHarnessStorePurgedError(resolved.path);
+      await this.touchNamespace(resolved.namespaceKey, transaction);
+      return callback(transaction);
+    });
+  }
+
+  private async readVisible<TValue>(resolved: IResolvedAddress,
+    read: () => Promise<TValue | undefined>): Promise<TValue | undefined> {
+    if (await this.blocked(resolved)) return undefined;
+    try {
+      const value = await read();
+      return await this.blocked(resolved) ? undefined : value;
+    } catch (error) {
+      if (await this.blocked(resolved)) return undefined;
+      throw error;
+    }
+  }
+
+  private addressOf(document: FlexRecordDocument): IResolvedAddress {
+    return { recordId: document.recordId, domain: document.domain, ownerKey: document.ownerKey,
+      namespaceKey: document.namespaceKey, path: `${FLEX_RECORD_COLLECTION}/${document.domain}/${document.recordId}` };
+  }
+
+  private async removeBlob(resolved: IResolvedAddress, blobId: string): Promise<void> {
+    await this.sweepDocuments(resolved, this.chunks, 'chunkId', { blobId });
+  }
+
+  private async sweepDocuments(
+    resolved: IResolvedAddress,
+    model: TChunkModel | TChangePageModel,
+    identity: 'chunkId' | 'pageId',
+    selector: { recordId?: string; blobId?: string | { $ne: string }; baseToken?: { $ne: string }; logId?: string },
+    current?: FlexRecordDocument,
+  ): Promise<void> {
+    for (;;) {
+      const page = await model.getPagedInstances<TDeletionDocument>({ filter: selector, sortField: identity, uniqueField: identity,
+        limit: deletionBatchSize, timeoutMS: this.timeoutMs });
+      if (page.documents.length === 0) return;
+      const active = await this.writeTransaction(resolved, async (transaction) => {
+        if (current) {
+          const head = await this.records.atomicUpdate({ recordId: current.recordId, writeToken: current.writeToken },
+            { $inc: { sweepCount: 1 } }, { session: transaction });
+          if (head.matchedCount !== 1) return false;
+        }
+        const identifiers = page.documents.map((document) => this.documentIdentity(document, identity));
+        await model.atomicDeleteMany<TDeletionDocument>({ ...selector, [identity]: { $in: identifiers } },
+          { session: transaction });
+        return true;
+      });
+      if (!active) return;
+    }
+  }
+
   private parse<TValue>(
     resolved: IResolvedAddress,
     text: string,
@@ -800,10 +924,10 @@ export class FlexRecordStore {
       if (chunked && !current.chunked && !await this.markChunked(current)) return false;
     }
     const blobId = chunked ? await this.writeBlob(resolved, current.writeToken, text) : null;
+    if (blobId === undefined) return false;
     const writeToken = plugins.crypto.randomUUID();
-    let swapped: boolean;
-    try {
-      const outcome = await this.records.atomicUpdate(
+    const outcome = await this.writeTransaction(resolved, (transaction) =>
+      this.records.atomicUpdate(
         { recordId: resolved.recordId, writeToken: current.writeToken },
         {
           $set: {
@@ -822,15 +946,11 @@ export class FlexRecordStore {
             retiredLogId: current.logId ?? null,
           },
         },
-        { timeoutMS: this.timeoutMs },
-      );
-      swapped = outcome.matchedCount === 1;
-    } catch (error) {
-      if (isDefiniteRejection(error)) throw error;
-      throw new FlexHarnessStoreCommitUncertainError(resolved.path, 'write', { cause: error });
-    }
+        { session: transaction },
+      ));
+    const swapped = outcome?.matchedCount === 1;
     if (!swapped && blobId !== null) {
-      await this.chunks.atomicDeleteMany({ blobId }, { timeoutMS: this.timeoutMs });
+      await this.removeBlob(resolved, blobId);
     }
     return swapped;
   }
@@ -870,28 +990,21 @@ export class FlexRecordStore {
       page.logId = head.logId!;
       page.previousId = head.lastPageId ?? head.logId!;
       page.changes = [...head.recentChanges, text];
-      await this.changes.insert(page, { timeoutMS: this.timeoutMs });
     }
     const writeToken = plugins.crypto.randomUUID();
     const counts = { changeCount: 1, changeLength: text.length };
-    let swapped: boolean;
-    try {
-      const outcome = await this.records.atomicUpdate(
+    const outcome = await this.writeTransaction(resolved, async (transaction) => {
+      const updated = await this.records.atomicUpdate(
         { recordId: resolved.recordId, writeToken: head.writeToken },
         page
           ? { $set: { revision, writeToken, recentChanges: [], lastPageId: page.pageId }, $inc: counts }
           : { $set: { revision, writeToken }, $inc: counts, $push: { recentChanges: text } },
-        { timeoutMS: this.timeoutMs },
+        { session: transaction },
       );
-      swapped = outcome.matchedCount === 1;
-    } catch (error) {
-      if (isDefiniteRejection(error)) throw error;
-      throw new FlexHarnessStoreCommitUncertainError(resolved.path, 'write', { cause: error });
-    }
-    if (!swapped && page) {
-      await this.changes.atomicDeleteMany({ pageId: page.pageId }, { timeoutMS: this.timeoutMs });
-    }
-    return swapped;
+      if (updated.matchedCount === 1 && page) await this.changes.insert(page, { session: transaction });
+      return updated;
+    });
+    return outcome?.matchedCount === 1;
   }
 
   private newHead(resolved: IResolvedAddress): FlexRecordDocument {
@@ -942,12 +1055,7 @@ export class FlexRecordStore {
       head.payload = text;
       head.chunked = false;
     }
-    try {
-      return await this.create(resolved, head, chunk);
-    } catch (error) {
-      if (plugins.SmartdataSession.getCommitOutcome(error) === 'not_committed') throw error;
-      throw new FlexHarnessStoreCommitUncertainError(resolved.path, 'write', { cause: error });
-    }
+    return this.create(resolved, head, chunk);
   }
 
   /** Reserves the record for a first write longer than one chunk, so its chunks have a head token to replace. */
@@ -972,22 +1080,11 @@ export class FlexRecordStore {
     head: FlexRecordDocument,
     chunk?: FlexChunkDocument,
   ): Promise<boolean> {
-    const session = this.db.createSession();
     try {
-      await session.withTransaction(async (transaction) => {
-        const namespace = await this.namespaces.getInstance(
-          { namespaceKey: resolved.namespaceKey },
-          { session: transaction },
-        );
-        if (namespace?.fenced) throw new FlexHarnessStorePurgedError(resolved.path);
-        await this.namespaces.atomicUpdate(
-          { namespaceKey: resolved.namespaceKey },
-          { $inc: { creationCount: 1 }, $setOnInsert: { fenced: false } },
-          { upsert: true, session: transaction },
-        );
+      await this.writeTransaction(resolved, async (transaction) => {
         await this.records.insert(head, { session: transaction });
         if (chunk) await this.chunks.insert(chunk, { session: transaction });
-      }, { timeoutMS: this.timeoutMs });
+      });
       return true;
     } catch (error) {
       if (
@@ -997,30 +1094,38 @@ export class FlexRecordStore {
         return false;
       }
       throw error;
-    } finally {
-      await session.close();
     }
   }
 
   private async markChunked(current: FlexRecordDocument): Promise<boolean> {
-    const outcome = await this.records.atomicUpdate(
+    const outcome = await this.writeTransaction(this.addressOf(current), (transaction) => this.records.atomicUpdate(
       { recordId: current.recordId, writeToken: current.writeToken },
       { $set: { chunked: true } },
-      { timeoutMS: this.timeoutMs },
-    );
-    return outcome.matchedCount === 1;
+      { session: transaction },
+    ));
+    return outcome?.matchedCount === 1;
   }
 
   private async writeBlob(
     resolved: IResolvedAddress,
     baseToken: string,
     text: string,
-  ): Promise<string> {
+  ): Promise<string | undefined> {
     const blobId = plugins.crypto.randomUUID();
     const pieces = splitPayload(text);
     for (let index = 0; index < pieces.length; index++) {
       const chunk = this.newChunk(resolved, blobId, baseToken, index, pieces[index]);
-      await this.chunks.insert(chunk, { timeoutMS: this.timeoutMs });
+      const inserted = await this.writeTransaction(resolved, async (transaction) => {
+        const head = await this.records.atomicUpdate({ recordId: resolved.recordId, writeToken: baseToken },
+          { $inc: { sweepCount: 1 } }, { session: transaction });
+        if (head.matchedCount !== 1) return false;
+        await this.chunks.insert(chunk, { session: transaction });
+        return true;
+      });
+      if (!inserted) {
+        await this.removeBlob(resolved, blobId);
+        return undefined;
+      }
     }
     return blobId;
   }
@@ -1054,34 +1159,12 @@ export class FlexRecordStore {
    * pages 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;
-        if (current.chunked) {
-          await this.chunks.atomicDeleteMany(
-            {
-              recordId: current.recordId,
-              baseToken: { $ne: current.writeToken },
-              ...(current.blobId === null ? {} : { blobId: { $ne: current.blobId } }),
-            },
-            { session: transaction },
-          );
-        }
-        if (current.retiredLogId) {
-          await this.changes.atomicDeleteMany(
-            { recordId: current.recordId, logId: current.retiredLogId },
-            { session: transaction },
-          );
-        }
-      }, { timeoutMS: this.timeoutMs });
-    } finally {
-      await session.close();
-    }
+    const resolved = this.addressOf(current);
+    if (current.chunked) await this.sweepDocuments(resolved, this.chunks, 'chunkId', {
+      recordId: current.recordId, baseToken: { $ne: current.writeToken },
+      ...(current.blobId === null ? {} : { blobId: { $ne: current.blobId } }),
+    }, current);
+    if (current.retiredLogId) await this.sweepDocuments(resolved, this.changes, 'pageId',
+      { recordId: current.recordId, logId: current.retiredLogId }, current);
   }
 }

package/ts_stores_nosqldb/readme.md

@@ -21,22 +21,28 @@ const harness = new FlexHarness({ scopeResolver, modelResolver, stores });
 
 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`, `flexharness_chunks`, `flexharness_changes` and `flexharness_namespaces` 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 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, in small transactions that check the namespace and the record's current write token. The chunks a record no longer references are removed by a later write of that record, in bounded transactions that also touch the record. 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.
 
-`stores.purgeNamespace(storageKey)` is the durable deletion of a scope: it removes every record and chunk of that storage namespace in every domain, including the scope snapshot and the project-management tombstones that deleting its sessions keeps, in one transaction. Deleting every session alone leaves those records, keyed by the storage key. Stop new admission for every alias of the scope first. A plain purge must then wait until `harness.retireScope()` has returned on every harness that owns the scope: a harness that still holds it can write records back, because the purge removed the revisions its writes would conflict with.
+`stores.purgeNamespace(storageKey)` is the durable deletion of a scope: it removes every record, chunk and change page of that storage namespace in every domain, including the scope snapshot and the project-management tombstones that deleting its sessions keeps. Deleting every session alone leaves those records, keyed by the storage key. Stop new admission for every alias of the scope first. A plain purge must then wait until `harness.retireScope()` has returned on every harness that owns the scope: after a completed plain purge a harness that still holds it can write records back, because the purge removed the revisions its writes would conflict with.
 
 ```typescript
 await harness.retireScope(scopeId);
 await stores.purgeNamespace(storageKey);
 ```
 
-When a harness may still hold the scope, such as one on another server, purge with `{ fence: true }`. The same transaction fences the namespace in `flexharness_namespaces`: every later record creation in it, from any process, is refused with `FlexHarnessStorePurgedError`, and a write that extends a purged record conflicts, so nothing a stale harness writes lands. A creation that races the purge either commits first and is removed with the rest, or is refused. The fence is permanent, so the storage key is never usable again, and a later purge without the fence does not lift it. FlexHarness reports a refused write of a session operation through `externalErrorProjector`, like every other store failure there.
+When a harness may still hold the scope, such as one on another server, purge with `{ fence: true }`. The first small transaction atomically fences the namespace and marks its purge in progress in `flexharness_namespaces`, before deleting any payload. Every later write, including a chunk insertion, a change append or a replacement of an existing record, checks and touches the namespace in its transaction. A write that races the fence either commits first and is removed with the rest, or is refused with `FlexHarnessStorePurgedError` (a save whose expected revision is already gone may instead report its domain's conflict). The fence is permanent, so the storage key is never usable again, and a later purge without the fence does not lift it. FlexHarness reports a refused write of a session operation through `externalErrorProjector`, like every other store failure there.
 
 ```typescript
 await stores.purgeNamespace(storageKey, { fence: true });
 ```
 
-Every record creation is a transaction that checks the namespace's fence document and writes to it, so concurrent creations in one namespace contend on that document and the driver retries the ones that conflict.
+The purge's durable `purgeToken` makes the entire namespace logically absent: reads return `undefined` as soon as the marker commits, including while payload still exists or cleanup is interrupted. A plain purge uses the same temporary marker and refuses writes until cleanup completes, but does not install a permanent fence. Cleanup deletes heads first, then chunks and change pages, in transactions of at most four payload documents. Each payload document is below about 3 MiB, leaving room below NoSQLDB's 32 MiB transaction budget even for a namespace or one snapshot much larger than that budget. Each batch checks and touches the purge marker, so an old concurrent cleanup cannot delete a new generation after a completed plain purge. The final transaction clears the in-progress marker, retaining a permanent fence when present. Namespace cleanup also removes its subordinate deletion markers.
+
+If cleanup fails or the process stops, physical payload may remain, but readers never hydrate it as valid state and writers cannot resurrect it. Retry the same purge from any prepared store, including after a restart; it resumes the remaining work. A retry without `{ fence: true }` preserves an already-installed fence. Repeated completed purges are idempotent. A failure before the first marker commits leaves the namespace unchanged; an error in a later, definitely aborted batch does not undo the already-committed marker or batches.
+
+Deleting a record, a session's records in one domain, or the project-management namespace uses the same protocol with a marker restricted to that target. Reads of the target return `undefined` while it is being deleted; unrelated targets remain usable. A provider that deletes several domains processes them in order, so interruption may leave later domains intact; retry its `deleteSession()` to finish. These markers are temporary, and creation becomes possible again after successful cleanup. Unreferenced chunks and retired change pages are also swept in bounded batches guarded by the record's head token.
+
+All writes in one namespace now contend on its namespace document, not only creations; the driver retries transaction conflicts. Upgrade every writer sharing a database to this implementation before using batched deletion: earlier adapters do not recognize in-progress deletion markers or fence their existing-record writes.
 
 A projection and an Agent event history are each stored as a base plus the changes saved since. FlexHarness saves a projection as an `IFlexProjectionChange` and an Agent event history as an `IAgentEventChange`, which carry only the entries that changed, and the store appends the change to the record's head in the compare-and-swap that commits it, so a save reads and writes the head alone and costs the change rather than the whole session. The head holds the latest changes up to 16 Ki characters of JSON; the save that would exceed that first writes them, with its own change, as one page in `flexharness_changes`, and empties them in its swap. The base lives in chunks whatever its length, so the head each change swaps holds no payload; a session's first save creates the record together with a base of up to one chunk in one transaction. The changes are kept while together they stay no longer than the base, or than 64 Ki characters of JSON while the base is shorter, and no single change is longer than one chunk. The save that would exceed that compacts the record instead: it reads the record, applies the change, checks the resulting snapshot in full and writes it as the new base. The earlier base and its pages are removed like unreferenced chunks, by the record's next compaction, which finds those pages by their log instead of scanning the current one. A record therefore holds its base and changes no longer than it or that minimum, plus the earlier base and its pages until the next compaction. A session whose history shrank, after an undo branch for example, keeps its larger base until its changes outgrow it. A read applies every change to the base and checks the result in full, so it costs the base and every change since, and a record whose pages are incomplete fails with `FlexHarnessStoreFormatError`. A page a crashed writer left behind without swapping the head onto it is removed with the rest of its log, or by the record's deletion.
 
@@ -44,7 +50,7 @@ A save of a scope, permission or job snapshot checks its expected revision again
 
 A projection or Agent event record that an earlier version wrote whole is read whole, and its next save rewrites it as a base. Versions before 12.0.0 cannot read a base: they fail closed on such a record with `FlexHarnessStoreFormatError` instead of reading the session without its changes, so rolling back to them is unsupported for every session 12.x has saved, as is running them beside 12.x on one database, and they leave the `flexharness_changes` documents in place.
 
-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.
+A write or 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. Every mutation uses the transaction's reported commit outcome, rather than inferring uncertainty from an error-class allowlist: an engine capacity rejection or any other error before commit is a definite failure and keeps its original error. A deadline before commit is definite too; an interrupted commit whose reply was not confirmed remains uncertain. For batched cleanup, this classification describes the failed transaction, not the earlier batches that were already acknowledged; its durable deletion marker still requires a retry to finish physical cleanup.
 
 ## Issue Reporting and Security
 

package/ts_typedrequest/catalog.ts

@@ -27,10 +27,10 @@ export class FlexTypedRequestError extends Error {
 /**
  * The tool catalog of a typedrequest surface: every included method becomes a catalog method of
  * its path, declared as its contract writes it and validated against its schema, and runs through
- * `router.routeAndAddResponse()` in process, its request the model's parameters with the omitted
- * properties `request` fills and its result what `response` makes of the answer. A refusal rejects
- * with `FlexTypedRequestError`. A method `readOnly` marks is declared read-only and not gated by
- * `onCall`.
+ * `router.routeAndAddResponse()` in process, its request what `params` makes of the model's
+ * parameters with the omitted properties its request has as `request` fills them, and its result
+ * what `response` makes of the answer. A refusal rejects with `FlexTypedRequestError`. A method
+ * `readOnly` marks is declared read-only and not gated by `onCall`.
  */
 export function catalogFromTypedRequests<TScope = unknown>(
   surface: IFlexTypedRequestSurface,
@@ -39,6 +39,12 @@ export function catalogFromTypedRequests<TScope = unknown>(
   if (typeof options?.router?.routeAndAddResponse !== 'function') {
     throw new plugins.FlexHarnessValidationError('catalogFromTypedRequests needs a router with routeAndAddResponse().');
   }
+  const unlisted = surface.methods.find((method) => !Array.isArray(method.omitted));
+  if (unlisted) {
+    throw new plugins.FlexHarnessValidationError(
+      `The surface's method ${unlisted.method} has no omitted list, as one an earlier version described; describe it again with this version's describeTypedRequests().`,
+    );
+  }
   const aliases = options.aliases ?? {};
   const known = new Set(surface.methods.map((method) => method.method));
   const unknown = Object.keys(aliases).filter((method) => !known.has(method));
@@ -58,12 +64,24 @@ export function catalogFromTypedRequests<TScope = unknown>(
     params: Record<string, unknown>,
     context: IFlexCatalogRunContext<TScope>,
   ): Promise<unknown> => {
-    const filled = options.request ? await options.request(method, context) : {};
+    const mapped = options.params ? await options.params(method, params, context) : params;
+    if (typeof mapped !== 'object' || mapped === null || Array.isArray(mapped)) {
+      throw new plugins.FlexHarnessValidationError(`The options' params() made no request object for ${method.method}.`);
+    }
+    // An omitted property is the binding's alone: the model's value never reaches the router.
+    const request: Record<string, unknown> = { ...mapped };
+    for (const key of surface.omit) delete request[key];
+    if (method.omitted.length > 0) {
+      const filled = options.request ? await options.request(method, context) : {};
+      for (const key of method.omitted) {
+        if (Object.hasOwn(filled, key)) request[key] = filled[key];
+      }
+    }
     const localData = options.localData ? await options.localData(method, context) : undefined;
     const answer = await router.routeAndAddResponse(
       {
         method: method.method,
-        request: { ...params, ...filled },
+        request,
         response: {},
         correlation: { id: plugins.crypto.randomUUID(), phase: 'request' },
       },