@modelprofile.com/flexharness 11.3.1 → 12.0.0

package/ts_stores_nosqldb/classes.recordstore.ts

@@ -47,6 +47,28 @@ export interface IFlexRecordReplacement {
   contention: (actualRevision: number) => Error;
 }
 
+/**
+ * How a record holds a snapshot as a base plus the changes saved since. Every function throws a
+ * `FlexHarnessStoreFormatError` for a value it rejects.
+ */
+export interface IFlexRecordLog<TSnapshot extends { revision: number }, TChange> {
+  /** Checks a snapshot in full. */
+  validate: (value: unknown) => TSnapshot;
+  /** Checks the form of a change. */
+  validateChange: (value: unknown) => TChange;
+  /** The snapshot `change` makes of `current`, before `validate` checks it. */
+  apply: (current: TSnapshot | undefined, change: TChange) => TSnapshot;
+}
+
+/** A change to save while the record's head holds `expectedRevision`; it makes the next one. */
+export interface IFlexRecordChange<TChange> {
+  expectedRevision: number;
+  /** The change, already checked by the log's `validateChange`. */
+  value: TChange;
+  /** The conflict to report when the head holds another revision. */
+  conflict: (actualRevision: number) => Error;
+}
+
 interface IFlexRecordDecision {
   document?: FlexRecordDocument;
   write?: IFlexRecordWrite;
@@ -55,6 +77,7 @@ interface IFlexRecordDecision {
 export const FLEX_RECORD_COLLECTION = 'flexharness_records';
 export const FLEX_CHUNK_COLLECTION = 'flexharness_chunks';
 export const FLEX_NAMESPACE_COLLECTION = 'flexharness_namespaces';
+export const FLEX_CHANGE_COLLECTION = 'flexharness_changes';
 
 /**
  * UTF-16 code units a record holds inline, and the size of each chunk of a longer payload. A
@@ -63,6 +86,18 @@ export const FLEX_NAMESPACE_COLLECTION = 'flexharness_namespaces';
  */
 export const FLEX_RECORD_CHUNK_CODE_UNITS = 1024 * 1024;
 
+/**
+ * UTF-16 code units the changes of a log may reach however short its base, so a young record
+ * keeps its changes instead of compacting on nearly every save.
+ */
+export const FLEX_RECORD_MIN_LOG_CODE_UNITS = 64 * 1024;
+
+/**
+ * UTF-16 code units of changes a log record's head holds inline. The save that would exceed it
+ * moves them, with its own change, into one change page.
+ */
+export const FLEX_RECORD_INLINE_CHANGE_CODE_UNITS = 16 * 1024;
+
 const mutationAttempts = 8;
 const mutationBackoffBaseMs = 5;
 const mutationBackoffMaxMs = 200;
@@ -73,7 +108,13 @@ 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.
+ * record for a first write longer than one chunk; it reads as absent.
+ *
+ * A log record's payload is a base, `{ base }`, always in chunks, and its head names a log,
+ * `logId`: the `changeCount` changes saved since the base. The head holds the latest of them in
+ * `recentChanges`; the earlier ones fill change pages, chained from `lastPageId` back to the log.
+ * A head without `logId`, also one an earlier version wrote, holds its value whole. A write that
+ * replaces a log names it `retiredLogId`, and the next write deletes its pages.
  */
 export class FlexRecordDocument extends plugins.SmartDataDbDoc<FlexRecordDocument, FlexRecordDocument> {
   public recordId!: string;
@@ -89,6 +130,21 @@ export class FlexRecordDocument extends plugins.SmartDataDbDoc<FlexRecordDocumen
   /** Set before the first chunk of this record is written; the record's writes then sweep. */
   public chunked!: boolean;
   public sweepCount!: number;
+  /** The write token of the base's commit, which names the log; null without a log. */
+  public logId!: string | null;
+  public changeCount!: number;
+  /** The log's changes saved since its last page, oldest first; empty without a log. */
+  public recentChanges!: string[];
+  /** The log's latest change page; null while the log has none. */
+  public lastPageId!: string | null;
+  /**
+   * UTF-16 code units of the log's changes and of its base; a log outgrows neither its base nor,
+   * for a shorter base, `FLEX_RECORD_MIN_LOG_CODE_UNITS`.
+   */
+  public changeLength!: number;
+  public baseLength!: number;
+  /** The log the last write replaced, whose pages the next write deletes; null without one. */
+  public retiredLogId!: string | null;
 }
 
 /** One immutable piece of a chunked payload, written against the head token it will replace. */
@@ -104,6 +160,21 @@ export class FlexChunkDocument extends plugins.SmartDataDbDoc<FlexChunkDocument,
   public data!: string;
 }
 
+/**
+ * One immutable page of a log record's changes, oldest first, written before the head swap that
+ * commits it. `previousId` names the log's previous page, or the log itself for its first page.
+ */
+export class FlexChangePageDocument extends plugins.SmartDataDbDoc<FlexChangePageDocument, FlexChangePageDocument> {
+  public pageId!: string;
+  public recordId!: string;
+  public domain!: TFlexRecordDomain;
+  public ownerKey!: string;
+  public namespaceKey!: string;
+  public logId!: string;
+  public previousId!: string;
+  public changes!: string[];
+}
+
 /**
  * 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
@@ -117,18 +188,21 @@ export class FlexNamespaceDocument extends plugins.SmartDataDbDoc<FlexNamespaceD
 
 type TRecordModel = typeof FlexRecordDocument;
 type TChunkModel = typeof FlexChunkDocument;
+type TChangePageModel = typeof FlexChangePageDocument;
 type TNamespaceModel = typeof FlexNamespaceDocument;
 
 export interface IFlexRecordModels {
   records: TRecordModel;
   chunks: TChunkModel;
+  changes: TChangePageModel;
   namespaces: TNamespaceModel;
 }
 
-/** Binds the record, chunk and namespace models to a database. */
+/** Binds the record, chunk, change page and namespace models to a database. */
 export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels {
   class BoundRecord extends FlexRecordDocument {}
   class BoundChunk extends FlexChunkDocument {}
+  class BoundChangePage extends FlexChangePageDocument {}
   class BoundNamespace extends FlexNamespaceDocument {}
   plugins.defineCollectionModel(BoundRecord, db, {
     collectionName: FLEX_RECORD_COLLECTION,
@@ -145,8 +219,15 @@ export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels
       'payloadSha256',
       'chunked',
       'sweepCount',
+      'logId',
+      'changeCount',
+      'recentChanges',
+      'lastPageId',
+      'changeLength',
+      'baseLength',
+      'retiredLogId',
     ],
-    numericFields: ['revision', 'chunkCount', 'sweepCount'],
+    numericFields: ['revision', 'chunkCount', 'sweepCount', 'changeCount', 'changeLength', 'baseLength'],
     identityFields: ['recordId'],
     indexes: [
       { name: 'flexharness_record_id', key: { recordId: 1 }, options: { unique: true } },
@@ -177,6 +258,26 @@ export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels
       { name: 'flexharness_chunk_namespace', key: { namespaceKey: 1, domain: 1 } },
     ],
   });
+  plugins.defineCollectionModel(BoundChangePage, db, {
+    collectionName: FLEX_CHANGE_COLLECTION,
+    persistedFields: [
+      'pageId',
+      'recordId',
+      'domain',
+      'ownerKey',
+      'namespaceKey',
+      'logId',
+      'previousId',
+      'changes',
+    ],
+    identityFields: ['pageId'],
+    indexes: [
+      { name: 'flexharness_change_page', key: { pageId: 1 }, options: { unique: true } },
+      { name: 'flexharness_change_log', key: { recordId: 1, logId: 1 } },
+      { name: 'flexharness_change_owner', key: { ownerKey: 1, domain: 1 } },
+      { name: 'flexharness_change_namespace', key: { namespaceKey: 1, domain: 1 } },
+    ],
+  });
   plugins.defineCollectionModel(BoundNamespace, db, {
     collectionName: FLEX_NAMESPACE_COLLECTION,
     persistedFields: ['namespaceKey', 'fenced', 'creationCount'],
@@ -186,7 +287,7 @@ export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels
       { name: 'flexharness_namespace_key', key: { namespaceKey: 1 }, options: { unique: true } },
     ],
   });
-  return { records: BoundRecord, chunks: BoundChunk, namespaces: BoundNamespace };
+  return { records: BoundRecord, chunks: BoundChunk, changes: BoundChangePage, namespaces: BoundNamespace };
 }
 
 interface IResolvedAddress {
@@ -202,6 +303,11 @@ interface IStoredHead {
   text?: string;
 }
 
+interface IStoredLog<TSnapshot> {
+  document?: FlexRecordDocument;
+  value?: TSnapshot;
+}
+
 const digest = (value: string): string =>
   plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
 
@@ -254,12 +360,22 @@ export interface IFlexRecordStoreOptions {
  * 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. A head is created in
  * a transaction that checks its namespace document, so a fenced namespace gains no record.
+ *
+ * A log record takes a change in the head swap itself, which appends it to the head's recent
+ * changes, so a save costs the change rather than the record and reads and writes only the head.
+ * The save that would grow the recent changes past `FLEX_RECORD_INLINE_CHANGE_CODE_UNITS` writes
+ * them, with its own change, as one change page first and empties them in its swap. The base lives
+ * in chunks whatever its length, so the head the swap rewrites holds no payload. Once the changes
+ * would outgrow the base, or a shorter base's minimum room, a save compacts the record instead: it
+ * writes the base with every change applied, checked in full.
+ * The change pages of earlier logs are swept like chunks.
  */
 export class FlexRecordStore {
   private readonly db: plugins.SmartdataDb;
   private readonly timeoutMs: number;
   private readonly records: TRecordModel;
   private readonly chunks: TChunkModel;
+  private readonly changes: TChangePageModel;
   private readonly namespaces: TNamespaceModel;
   private preparation?: Promise<void>;
 
@@ -270,8 +386,12 @@ export class FlexRecordStore {
     }
     this.db = options.db;
     this.timeoutMs = timeoutMs;
-    ({ records: this.records, chunks: this.chunks, namespaces: this.namespaces } =
-      bindFlexRecordModels(options.db));
+    ({
+      records: this.records,
+      chunks: this.chunks,
+      changes: this.changes,
+      namespaces: this.namespaces,
+    } = bindFlexRecordModels(options.db));
   }
 
   /** Creates or verifies the collections and their indexes once; a failed attempt is retried. */
@@ -298,6 +418,7 @@ export class FlexRecordStore {
     const options = { mode: 'ensureCompatible' as const, timeoutMs: this.timeoutMs };
     await this.records.prepareCollection(options);
     await this.chunks.prepareCollection(options);
+    await this.changes.prepareCollection(options);
     await this.namespaces.prepareCollection(options);
   }
 
@@ -323,7 +444,51 @@ export class FlexRecordStore {
   ): Promise<TValue | undefined> {
     await this.prepare();
     const resolved = this.resolve(address);
-    return this.parse(resolved, await this.readHead(resolved), validate);
+    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. */
+  public async readLog<TSnapshot extends { revision: number }, TChange>(
+    address: IFlexRecordAddress,
+    log: IFlexRecordLog<TSnapshot, TChange>,
+  ): Promise<TSnapshot | undefined> {
+    await this.prepare();
+    return (await this.loadLog(this.resolve(address), log)).value;
+  }
+
+  /**
+   * Saves a change to a log record while its head holds the expected revision. Only the head is
+   * read when the record takes the change; a compaction loads the record and checks the result in
+   * full. A change the record takes is checked in form only, by the caller; its content is checked
+   * once a compaction or a read applies it.
+   */
+  public async append<TSnapshot extends { revision: number }, TChange>(
+    address: IFlexRecordAddress,
+    log: IFlexRecordLog<TSnapshot, TChange>,
+    change: IFlexRecordChange<TChange>,
+  ): Promise<void> {
+    await this.prepare();
+    const resolved = this.resolve(address);
+    const text = JSON.stringify(change.value);
+    const revision = change.expectedRevision + 1;
+    let actualRevision = 0;
+    for (let attempt = 0; attempt < mutationAttempts; attempt++) {
+      if (attempt > 0) await mutationBackoff(attempt);
+      const head = await this.findHead(resolved);
+      actualRevision = head?.revision ?? 0;
+      if (actualRevision !== change.expectedRevision) throw change.conflict(actualRevision);
+      if (head && this.takesChange(head, text)) {
+        if (await this.commitChange(resolved, head, revision, text)) return;
+        continue;
+      }
+      const stored = await this.loadLog(resolved, log);
+      actualRevision = stored.document?.revision ?? 0;
+      if (actualRevision !== change.expectedRevision) throw change.conflict(actualRevision);
+      const value = log.validate(log.apply(stored.value, change.value));
+      if (await this.commit(resolved, stored.document, { revision, value }, true)) return;
+    }
+    throw change.conflict(actualRevision);
   }
 
   public async mutate<TValue>(
@@ -334,10 +499,10 @@ export class FlexRecordStore {
     const resolved = this.resolve(address);
     await this.swap(resolved, mutation.contention, async () => {
       const head = await this.readHead(resolved);
-      return {
-        document: head.document,
-        write: mutation.decide(this.parse(resolved, head, mutation.validate)),
-      };
+      const current = head.text === undefined
+        ? undefined
+        : this.parse(resolved, head.text, mutation.validate);
+      return { document: head.document, write: mutation.decide(current) };
     });
   }
 
@@ -374,14 +539,14 @@ export class FlexRecordStore {
     throw contention(actualRevision);
   }
 
-  /** Deletes one record and its chunks. */
+  /** Deletes one record with its chunks and change pages. */
   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 });
   }
 
-  /** Deletes every record and chunk one session owns in the given domains. */
+  /** Deletes every record, chunk and change page one session owns in the given domains. */
   public async deleteOwner(
     storageKey: string,
     sessionId: string,
@@ -396,8 +561,8 @@ export class FlexRecordStore {
   }
 
   /**
-   * Deletes every record and chunk of a storage namespace in one domain, or in every domain
-   * together with its namespace document unless a fence holds it.
+   * 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.
    */
   public async purgeNamespace(storageKey: string, domain?: TFlexRecordDomain): Promise<void> {
     await this.prepare();
@@ -415,9 +580,10 @@ export class FlexRecordStore {
   }
 
   /**
-   * Fences a storage namespace and deletes every record and chunk 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.
+   * 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.
    */
   public async fenceNamespace(storageKey: string): Promise<void> {
     await this.prepare();
@@ -433,7 +599,7 @@ export class FlexRecordStore {
     );
   }
 
-  /** Deletes the selected records and chunks, after `namespace` changes the namespace document. */
+  /** Deletes the selected records, chunks and change pages, after `namespace` changes the namespace document. */
   private async deleteInTransaction(
     path: string,
     selector:
@@ -448,6 +614,7 @@ export class FlexRecordStore {
         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 });
     } catch (error) {
       if (plugins.SmartdataSession.getCommitOutcome(error) === 'not_committed') throw error;
@@ -459,18 +626,22 @@ export class FlexRecordStore {
 
   private parse<TValue>(
     resolved: IResolvedAddress,
-    head: IStoredHead,
+    text: string,
     validate: (value: unknown) => TValue,
-  ): TValue | undefined {
-    if (head.text === undefined) return undefined;
+  ): TValue {
     let parsed: unknown;
     try {
-      parsed = JSON.parse(head.text);
+      parsed = JSON.parse(text);
     } catch (error) {
       throw new FlexHarnessStoreFormatError(`Malformed JSON at ${resolved.path}.`, { cause: error });
     }
+    return this.check(resolved, () => validate(parsed));
+  }
+
+  /** Runs a check of stored data and names the record in a format error it throws. */
+  private check<TValue>(resolved: IResolvedAddress, check: () => TValue): TValue {
     try {
-      return validate(parsed);
+      return check();
     } catch (error) {
       if (error instanceof FlexHarnessStoreFormatError) {
         throw new FlexHarnessStoreFormatError(`Invalid record at ${resolved.path}: ${error.message}`, {
@@ -505,6 +676,94 @@ export class FlexRecordStore {
     );
   }
 
+  /**
+   * Loads a log record with the head it was read at. A head without a log holds its value whole;
+   * a base must be wrapped, so a version that reads values whole fails on it.
+   */
+  private async loadLog<TSnapshot extends { revision: number }, TChange>(
+    resolved: IResolvedAddress,
+    log: IFlexRecordLog<TSnapshot, TChange>,
+  ): Promise<IStoredLog<TSnapshot>> {
+    for (let attempt = 0; attempt < chunkReadAttempts; attempt++) {
+      const head = await this.readHead(resolved);
+      const document = head.document;
+      if (!document || head.text === undefined) return { document };
+      if (!document.logId) return { document, value: this.parse(resolved, head.text, log.validate) };
+      const changes = await this.readChanges(document);
+      if (changes) {
+        return { document, value: this.fold(resolved, document, head.text, changes, log) };
+      }
+      const latest = await this.findHead(resolved);
+      if (latest?.writeToken === document.writeToken) {
+        throw new FlexHarnessStoreFormatError(
+          `${resolved.path} references ${document.changeCount} changes of log "${document.logId}", but they are incomplete.`,
+        );
+      }
+    }
+    throw new FlexHarnessStoreFormatError(
+      `${resolved.path} changed during ${chunkReadAttempts} consecutive reads.`,
+    );
+  }
+
+  /**
+   * The data of the head's changes, oldest first: its pages, found by walking back from its last
+   * page to its log, then its recent changes. Undefined when the pages are incomplete.
+   */
+  private async readChanges(document: FlexRecordDocument): Promise<string[] | undefined> {
+    const pages: string[][] = [];
+    if (document.lastPageId !== null) {
+      const stored = await this.changes.getInstances(
+        { recordId: document.recordId, logId: document.logId! },
+        { timeoutMS: this.timeoutMs },
+      );
+      const byId = new Map(stored.map((page) => [page.pageId, page]));
+      let pageId = document.lastPageId;
+      while (pageId !== document.logId) {
+        const page = byId.get(pageId);
+        if (!page || !Array.isArray(page.changes) || pages.length === stored.length) return undefined;
+        pages.push(page.changes);
+        pageId = page.previousId;
+      }
+    }
+    if (!Array.isArray(document.recentChanges)) return undefined;
+    const changes = [...pages.reverse().flat(), ...document.recentChanges];
+    return changes.length === document.changeCount ? changes : undefined;
+  }
+
+  /** The base with every change applied, checked in full and at the head's revision. */
+  private fold<TSnapshot extends { revision: number }, TChange>(
+    resolved: IResolvedAddress,
+    document: FlexRecordDocument,
+    text: string,
+    changes: readonly string[],
+    log: IFlexRecordLog<TSnapshot, TChange>,
+  ): TSnapshot {
+    let value = this.parse(resolved, text, (wrapper) => {
+      if (
+        typeof wrapper !== 'object' || wrapper === null || Array.isArray(wrapper) ||
+        Object.keys(wrapper).length !== 1 || !('base' in wrapper)
+      ) {
+        throw new FlexHarnessStoreFormatError('A log record must hold exactly { base }.');
+      }
+      return log.validate(wrapper.base);
+    });
+    if (changes.length > 0) {
+      for (const data of changes) {
+        const change = this.parse(resolved, data, log.validateChange);
+        const current = value;
+        value = this.check(resolved, () => log.apply(current, change));
+      }
+      const folded = value;
+      value = this.check(resolved, () => log.validate(folded));
+    }
+    if (value.revision !== document.revision) {
+      throw new FlexHarnessStoreFormatError(
+        `${resolved.path} holds revision ${value.revision}, but its head names ${document.revision}.`,
+      );
+    }
+    return value;
+  }
+
   private async readBlob(document: FlexRecordDocument): Promise<string | undefined> {
     const stored = await this.chunks.getInstances(
       { blobId: document.blobId! },
@@ -518,25 +777,30 @@ export class FlexRecordStore {
     return digest(text) === document.payloadSha256 ? text : undefined;
   }
 
-  /** Returns false when another writer swapped the head first; nothing of this write remains. */
+  /**
+   * Writes the value whole, or as the base of a new log, empty, when `log` is set; a base always
+   * goes into chunks. Returns false when another writer swapped the head first; nothing of this
+   * write remains.
+   */
   private async commit(
     resolved: IResolvedAddress,
     stored: FlexRecordDocument | undefined,
     write: IFlexRecordWrite,
+    log = false,
   ): Promise<boolean> {
-    const text = JSON.stringify(write.value);
-    const chunked = text.length > FLEX_RECORD_CHUNK_CODE_UNITS;
+    const text = JSON.stringify(log ? { base: write.value } : write.value);
+    const chunked = log || text.length > FLEX_RECORD_CHUNK_CODE_UNITS;
     let current = stored;
     if (!current) {
-      if (!chunked) return this.insertHead(resolved, write.revision, text);
+      if (text.length <= FLEX_RECORD_CHUNK_CODE_UNITS) return this.insertHead(resolved, write.revision, text, log);
       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;
+    } else {
+      if (current.chunked || current.retiredLogId) await this.sweep(current);
+      if (chunked && !current.chunked && !await this.markChunked(current)) return false;
     }
     const blobId = chunked ? await this.writeBlob(resolved, current.writeToken, text) : null;
+    const writeToken = plugins.crypto.randomUUID();
     let swapped: boolean;
     try {
       const outcome = await this.records.atomicUpdate(
@@ -544,11 +808,18 @@ export class FlexRecordStore {
         {
           $set: {
             revision: write.revision,
-            writeToken: plugins.crypto.randomUUID(),
+            writeToken,
             payload: chunked ? null : text,
             blobId,
             chunkCount: chunked ? splitPayload(text).length : 0,
             payloadSha256: chunked ? digest(text) : null,
+            logId: log ? writeToken : null,
+            changeCount: 0,
+            recentChanges: [],
+            lastPageId: null,
+            changeLength: 0,
+            baseLength: log ? text.length : 0,
+            retiredLogId: current.logId ?? null,
           },
         },
         { timeoutMS: this.timeoutMs },
@@ -564,6 +835,65 @@ export class FlexRecordStore {
     return swapped;
   }
 
+  /**
+   * Whether the record takes a change: a log that stays no longer than its base, or than the
+   * minimum room of a shorter base. A head whose recent changes are no list takes none, so the
+   * compaction's read refuses it.
+   */
+  private takesChange(head: FlexRecordDocument, text: string): boolean {
+    return Boolean(head.logId) && Array.isArray(head.recentChanges) &&
+      text.length <= FLEX_RECORD_CHUNK_CODE_UNITS &&
+      head.changeLength + text.length <= Math.max(head.baseLength, FLEX_RECORD_MIN_LOG_CODE_UNITS);
+  }
+
+  /**
+   * Appends a change to the head's recent changes in the head swap, or, when they would grow past
+   * their inline room, writes them with the change as a new page and empties them in the swap.
+   * Returns false when another writer swapped the head first; nothing of this write remains.
+   */
+  private async commitChange(
+    resolved: IResolvedAddress,
+    head: FlexRecordDocument,
+    revision: number,
+    text: string,
+  ): Promise<boolean> {
+    const recentLength = head.recentChanges.reduce((length, data) => length + data.length, 0);
+    const page = recentLength + text.length > FLEX_RECORD_INLINE_CHANGE_CODE_UNITS
+      ? new this.changes()
+      : undefined;
+    if (page) {
+      page.pageId = plugins.crypto.randomUUID();
+      page.recordId = resolved.recordId;
+      page.domain = resolved.domain;
+      page.ownerKey = resolved.ownerKey;
+      page.namespaceKey = resolved.namespaceKey;
+      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(
+        { 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 },
+      );
+      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;
+  }
+
   private newHead(resolved: IResolvedAddress): FlexRecordDocument {
     const head = new this.records();
     head.recordId = resolved.recordId;
@@ -575,27 +905,52 @@ export class FlexRecordStore {
     head.chunkCount = 0;
     head.payloadSha256 = null;
     head.sweepCount = 0;
+    head.logId = null;
+    head.changeCount = 0;
+    head.recentChanges = [];
+    head.lastPageId = null;
+    head.changeLength = 0;
+    head.baseLength = 0;
+    head.retiredLogId = null;
     return head;
   }
 
+  /**
+   * Creates the record with a first payload of up to one chunk in one transaction: inline, or as
+   * the single chunk of a log's base. The creation never touches the head again, so a concurrent
+   * fenced purge conflicts with it at most once.
+   */
   private async insertHead(
     resolved: IResolvedAddress,
     revision: number,
     text: string,
+    log: boolean,
   ): Promise<boolean> {
     const head = this.newHead(resolved);
     head.revision = revision;
-    head.payload = text;
-    head.chunked = false;
+    let chunk: FlexChunkDocument | undefined;
+    if (log) {
+      chunk = this.newChunk(resolved, plugins.crypto.randomUUID(), head.writeToken, 0, text);
+      head.payload = null;
+      head.chunked = true;
+      head.blobId = chunk.blobId;
+      head.chunkCount = 1;
+      head.payloadSha256 = digest(text);
+      head.logId = head.writeToken;
+      head.baseLength = text.length;
+    } else {
+      head.payload = text;
+      head.chunked = false;
+    }
     try {
-      return await this.create(resolved, head);
+      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 });
     }
   }
 
-  /** Reserves the record for a chunked first write, so its chunks have a head token to replace. */
+  /** Reserves the record for a first write longer than one chunk, so its chunks have a head token to replace. */
   private async insertPlaceholder(
     resolved: IResolvedAddress,
   ): Promise<FlexRecordDocument | undefined> {
@@ -607,12 +962,16 @@ export class FlexRecordStore {
   }
 
   /**
-   * Inserts a new head unless a fence holds its namespace. The transaction also increments the
-   * namespace document, so it conflicts with a concurrent fenced purge: whichever commits second
-   * retries on a snapshot that holds the other. Returns false when another writer created the
-   * record first.
+   * Inserts a new head, and the chunk it references if any, unless a fence holds its namespace.
+   * The transaction also increments the namespace document, so it conflicts with a concurrent
+   * fenced purge: whichever commits second retries on a snapshot that holds the other. Returns
+   * false when another writer created the record first.
    */
-  private async create(resolved: IResolvedAddress, head: FlexRecordDocument): Promise<boolean> {
+  private async create(
+    resolved: IResolvedAddress,
+    head: FlexRecordDocument,
+    chunk?: FlexChunkDocument,
+  ): Promise<boolean> {
     const session = this.db.createSession();
     try {
       await session.withTransaction(async (transaction) => {
@@ -627,6 +986,7 @@ export class FlexRecordStore {
           { upsert: true, session: transaction },
         );
         await this.records.insert(head, { session: transaction });
+        if (chunk) await this.chunks.insert(chunk, { session: transaction });
       }, { timeoutMS: this.timeoutMs });
       return true;
     } catch (error) {
@@ -659,26 +1019,39 @@ export class FlexRecordStore {
     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];
+      const chunk = this.newChunk(resolved, blobId, baseToken, index, pieces[index]);
       await this.chunks.insert(chunk, { timeoutMS: this.timeoutMs });
     }
     return blobId;
   }
 
+  private newChunk(
+    resolved: IResolvedAddress,
+    blobId: string,
+    baseToken: string,
+    index: number,
+    data: string,
+  ): FlexChunkDocument {
+    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 = data;
+    return chunk;
+  }
+
   /**
-   * 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.
+   * Deletes the record's chunks and change pages that no head can reference any more: every blob
+   * but the current one that was written against another head token, and every page of the log the
+   * last write retired, found by its index rather than by scanning the current log's pages. A
+   * writer that read the current token keeps its chunks.
+   * Touching the head in the same transaction makes a concurrent deletion conflict, so chunks and
+   * 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();
@@ -690,14 +1063,22 @@ export class FlexRecordStore {
           { 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 },
-        );
+        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();