@brass-build/client 0.2.0 → 0.3.0

package/src/documents.ts

@@ -57,6 +57,7 @@ import {
   GoneSignal,
   WorkStatusSignal,
   DriveStatusSignal,
+  DrivePublishTargetSignal,
   type DocumentGoneListener,
   type DocumentGoneReason,
   type DocumentGoneUnsubscribe,
@@ -68,6 +69,8 @@ import {
   type DocumentDriveStatusUnsubscribe,
   type DocumentDriveTrackingState,
   type DriveMirrorDirection,
+  type DrivePublishTarget,
+  type DrivePublishState,
 } from './document-signals.js';
 import {
   ThumbnailCapture,
@@ -78,6 +81,7 @@ import {
   CheckpointScheduler,
   type CheckpointCreator,
 } from './document-checkpoints.js';
+import { whenSaved } from './when-saved.js';
 import {
   BranchController,
   type BranchProvider,
@@ -120,6 +124,7 @@ export type {
   DocumentDriveStatusUnsubscribe,
   DocumentDriveTrackingState,
   DriveMirrorDirection,
+  DrivePublishTarget,
 };
 
 // The proxy callback receives an object with the root map (`entities`)
@@ -612,10 +617,25 @@ export class Document {
       this._fireSubscribers({ kind: 'branches' });
     },
   });
+  // The version of the newest picture the server holds of this document, or
+  // `null` for none. Seeded from the join and moved by this instance's own
+  // uploads; a picture older than the document's head is what arms the seed
+  // trigger, so a placeholder taken before the content arrived is replaced
+  // once it does.
+  private _thumbnailVersion: number | null = null;
   private readonly _thumbnails = new ThumbnailCapture({
+    // `_forcedReadOnly` and not the whole `readOnly`: the server refuses a
+    // thumbnail from a reader it will not take writes from, so a capture
+    // there costs a request and a warn to be told so. The load lock is the
+    // other half of `readOnly` and must NOT gate this, because a document
+    // still hydrating is exactly the one the seed watch is armed for, and
+    // the arm happens while that lock is still on.
     isCaptureAllowed: (): boolean =>
-      this._isLive && this._checkout === null,
+      this._isLive && this._checkout === null && !this._forcedReadOnly,
     isAttached: (): boolean => this._isLive,
+    onCaptured: (): void => {
+      this._thumbnailVersion = this.currentSeq ?? 0;
+    },
   });
   private readonly _checkpoints = new CheckpointScheduler({
     docId: (): string | null => this._docId,
@@ -626,6 +646,7 @@ export class Document {
     sealUndoStep: (): void => {
       if (this._undo) this._undo.sealStep();
     },
+    whenLocalOpsSaved: (): Promise<boolean> => whenSaved(this),
   });
   // Drive push hook. `null` on the offline / test path; `pushToDrive`
   // then throws with a clear message rather than silently dropping.
@@ -738,6 +759,9 @@ export class Document {
   // Drive sync state, latest-retained. `null` until the open factory
   // seeds it (drive-linked docs only) and on docs with no drive link.
   private readonly _driveStatus = new DriveStatusSignal();
+  // Where this document could be published when it mirrors nothing yet.
+  // Seeded from the open, emptied once it becomes a mirror.
+  private readonly _drivePublishTarget = new DrivePublishTargetSignal();
 
   // Document-scoped presence. `null` until the WS transport is wired
   // on, and on the offline / test path where there is no transport.
@@ -1145,6 +1169,11 @@ export class Document {
     // reload/resync closure can't touch freed WASM. `_closed` only; a parked
     // doc still imports.
     if (this._closed) return;
+    // Arm the seed BEFORE the import, because this is the moment the content
+    // arrives and the Loro subscriber cannot be relied on to report it: it is
+    // attached lazily, so a document whose content lands before the session has
+    // bound its canvas has nobody subscribed and the import fires nothing.
+    this._armSeedIfPictureIsStale();
     this._doc.import(snapshot);
     // The undo stack pre-snapshot referenced ops the new snapshot
     // supersedes. Drop both stacks so undo doesn't try to revert
@@ -1651,6 +1680,23 @@ export class Document {
     this._thumbnails.setUploader(uploader);
   }
 
+  // Tell the document which version the server's picture of it depicts, from
+  // the join, and start a seed watch when that picture is behind the content.
+  /** @internal */
+  _setThumbnailVersion(version: number | null): void {
+    this._thumbnailVersion = version;
+    this._armSeedIfPictureIsStale();
+  }
+
+  // A picture at or above the head depicts what the document currently holds.
+  private _armSeedIfPictureIsStale(): void {
+    const head = this.currentSeq ?? 0;
+    if (this._thumbnailVersion !== null && this._thumbnailVersion >= head) {
+      return;
+    }
+    this._thumbnails.armSeed();
+  }
+
   // Install the checkpoint-create hook; `null` detaches.
   /** @internal */
   setCheckpointCreator(creator: CheckpointCreator | null): void {
@@ -1736,11 +1782,11 @@ export class Document {
     return await this._driveResolver();
   }
 
-  // Fetch the original file behind an opaque-blob document: a short-lived
-  // presigned GET plus the file's name / content type / size. An app that
-  // knows the format fetches the bytes from `url`, parses them, and writes
-  // the structured content into this document through the normal handle
-  // surface (`doc.map('instances').mutate(...)`):
+  // Fetch the file a document was uploaded as: a short-lived presigned GET
+  // plus the file's name / content type / size. An app that knows the format
+  // fetches the bytes from `url`, parses them, and writes the structured
+  // content into this document through the normal handle surface
+  // (`doc.map('instances').mutate(...)`):
   //
   //   const src = await doc.sourceBlob();
   //   const bytes = new Uint8Array(await (await fetch(src.url)).arrayBuffer());
@@ -1752,9 +1798,8 @@ export class Document {
   // each with its own URL, so a multi-stream format (a glTF with its
   // `.bin` buffer) fetches only the streams it needs.
   //
-  // Rejects with a `BrassError` when the document is not a stored opaque
-  // blob (it has no original file to hand back) or the caller cannot
-  // reach it (both 404).
+  // Rejects with a `BrassError` when the document holds no such file, or
+  // the caller cannot reach it (both 404).
   async sourceBlob(): Promise<DocumentSourceBlob> {
     this._assertOpen();
     if (this._docId === null) {
@@ -2450,9 +2495,9 @@ export class Document {
       this._maybeFireUndoState();
       // A local commit (mutate / undo / redo) schedules a debounced
       // thumbnail capture, when the app has registered a canvas via
-      // `useCanvas`. Remote ops never trigger a capture: a viewer or
-      // a passive collaborator must not re-upload a screenshot of
-      // someone else's edit.
+      // `useCanvas`. The debounce is for the peer that drew the change, so
+      // it is local-only: a passive collaborator re-uploading a screenshot
+      // of someone else's edit is what a per-op capture would be.
       if (isLocalCommit) {
         this._thumbnails.schedule();
         // Same reasoning for the implicit auto-checkpoint: only the
@@ -2460,6 +2505,17 @@ export class Document {
         // N-way session would write N redundant CHECKPOINT# rows per
         // idle period.
         this._checkpoints.scheduleAuto();
+      } else {
+        // Content arriving with no local commit behind it is what an import
+        // looks like from here, and it moves the head past whatever picture
+        // the document has. This DOES reach a reader who drew none of it,
+        // which the debounce above deliberately does not: an import runs on
+        // whichever client claimed it, so gating the seed on local authorship
+        // would leave the documents that most need a picture without one.
+        // Every such reader captures the same document at the same version,
+        // and the targeted snapshot each upload enqueues is idempotent on
+        // that version, so the concurrent seeds resolve themselves.
+        this._armSeedIfPictureIsStale();
       }
     });
   }
@@ -2671,6 +2727,55 @@ export class Document {
   _emitDriveStatus(status: DocumentDriveStatus): void {
     if (this._closed) return;
     this._driveStatus.emit(status);
+    // A document that has become a mirror publishes through its link from
+    // now on, so the create-an-artifact offer goes with the arrival of the
+    // status that replaces it.
+    this._drivePublishTarget.set(null);
+  }
+
+  // Whether this document's export runs in THIS app, which is what decides
+  // whether a push carries bytes. Not on `driveStatus`: it is a fact about
+  // the caller rather than about the document, and it is all an app is told
+  // about the exporter, never which app it is when it is not this one.
+  private _exportsHere = false;
+
+  /** @internal */
+  get _exportRunsHere(): boolean {
+    return this._exportsHere;
+  }
+
+  /** @internal */
+  _setExportRunsHere(runsHere: boolean): void {
+    this._exportsHere = runsHere;
+  }
+
+  // Internal: where this document can be published while it mirrors nothing.
+  /** @internal */
+  get _publishTarget(): DrivePublishTarget | null {
+    return this._drivePublishTarget.target;
+  }
+
+  /** @internal */
+  _setPublishTarget(target: DrivePublishTarget | null): void {
+    if (this._closed) return;
+    this._drivePublishTarget.set(target);
+  }
+
+  // Internal: how the publish of a document that mirrors nothing is going.
+  /** @internal */
+  get _publishState(): DrivePublishState {
+    return this._drivePublishTarget.state;
+  }
+
+  /** @internal */
+  _emitPublishState(state: DrivePublishState): void {
+    if (this._closed) return;
+    this._drivePublishTarget.setState(state);
+  }
+
+  /** @internal */
+  _onPublishState(cb: () => void): () => void {
+    return this._drivePublishTarget.onState(cb);
   }
 
   // Internal: mark the doc evicted. Idempotent (multiple frames arrive
@@ -3019,6 +3124,7 @@ export class Document {
     this._gone.clearListeners();
     this._workStatus.clearListeners();
     this._driveStatus.clearListeners();
+    this._drivePublishTarget.clearListeners();
     // Presence subscribes its OWN WS topic and keeps it alive across a park
     // (resume does not re-create the controller), so drop its app-side
     // change listeners here the same way as the sets above: a parked doc
@@ -3086,7 +3192,7 @@ export class Document {
       this._undo.free();
       this._undo = null;
     }
-    this._thumbnails.cancel();
+    this._thumbnails.destroy();
     this._checkpoints.cancelAuto();
     this._localOpHook = null;
     this._currentSeqProvider = null;
@@ -3102,6 +3208,7 @@ export class Document {
     this._gone.clearListeners();
     this._workStatus.clearListeners();
     this._driveStatus.clearListeners();
+    this._drivePublishTarget.clearListeners();
     // Detach handle subscriptions before freeing the doc (below): a handle's
     // per-container Loro subscription outlives the cache reference, and
     // `_doc.free()` must not run with subscriptions still attached.

package/src/handles.ts

@@ -816,9 +816,10 @@ function wrapLoroListProxy(
 // reading / editing `doc.map('instances')` works unchanged. Only a root
 // the `meta` markers name reaches here.
 
-// A flattened entry: whatever the map stores under one key. A codec's record
-// store holds `{ type, params }`; an app's map holds whatever the app assigns,
-// which is any JSON value and which the paged path carries through unchanged.
+// A flattened entry: whatever the map stores under one key. A store of typed
+// records holds `{ type, params }`; an app's map holds whatever the app
+// assigns, which is any JSON value and which the paged path carries through
+// unchanged.
 // Deliberately not narrowed to an object: a write path that assumes fields is
 // what turns `5` into an empty container and `'hello'` into one entry per
 // character.
@@ -2034,8 +2035,8 @@ function rewritePage(
   const page = plainEntry(m, pageKey);
   if (page === undefined) return false;
   // The RAW triples, not the memo's unpacked records: a triple carries either
-  // a codec's tag beside its body or one whole value, and `repackRecord` needs
-  // the original to keep each one in the shape its readers expect.
+  // a tag beside a body or one whole value, and `repackRecord` needs the
+  // original to keep each one in the shape its readers expect.
   const held = decodePageRecords(page);
   if (held.length === 0) return false;
   const next = new Map(group);

package/src/importer.ts

@@ -1,6 +1,7 @@
 import type { Document } from './documents.js';
 import type { DocumentSourceBlob } from './documents-namespace.js';
 import { BrassError } from './errors.js';
+import { whenSaved } from './when-saved.js';
 
 // The app's import half for a file Brass does not parse: given the stored
 // source file and the open document, parse the bytes and write the records
@@ -174,6 +175,7 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
         const stopWatchingWrites = doc.subscribe(() => {
           if (doc.savingCount > 0) wroteRecords = true;
         });
+        let saved = false;
         try {
           await run(source, doc);
           // The importer's ops are still in flight when it returns, and
@@ -181,19 +183,19 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
           // the head it lands on. Completing before they are acked stamps
           // a version below the records' own, which reads as a document
           // edited since it was uploaded from then on.
-          await whenSaved(doc);
+          saved = await whenSaved(doc);
         } finally {
           stopRefresh();
           stopWatchingWrites();
         }
-        // The wait above ends on the document going as well as on its writes
-        // draining, and only one of those means the records are stored. The
-        // completion stamps the document with the app's schema at the version
-        // it lands on, so running it over writes that never reached the server
-        // records an import of records the document does not hold. Abandoning
-        // instead leaves the claim to expire, and a client that is still open
-        // imports the file properly.
-        if (!doc._isLive) return;
+        // The wait ends on the document going, and on the acks stopping, as
+        // well as on the writes draining, and only the last of those means
+        // the records are stored. The completion stamps the document with the
+        // app's schema at the version it lands on, so running it over writes
+        // that never reached the server records an import of records the
+        // document does not hold. Abandoning instead leaves the claim to
+        // expire, and a client that is still open imports the file properly.
+        if (!saved) return;
         // An importer that returns without writing anything must not stamp the
         // document imported: the stamp is permanent, a later open reads
         // `already_imported`, and the file's records then have no path into a
@@ -270,53 +272,6 @@ export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
   return runner;
 }
 
-// How often the wait below re-checks that the document is still live. A
-// closing document drops its subscribers without firing them, so this is the
-// only thing that ends the wait for one that goes mid-import; it runs solely
-// while an import's writes are draining.
-const SAVED_LIVENESS_POLL_MS = 1_000;
-
-// Resolves once the document has no locally-issued op waiting for its
-// server ack, or once the document is no longer live.
-//
-// The liveness half is not belt-and-braces. Closing a Document CLEARS its
-// subscribers rather than firing them, so a wait that watched the ack count
-// alone would never settle for a document closed with writes outstanding, and
-// the caller's `finally` (which stops renewing the platform's import claim)
-// would never run. Resolving here does not claim the writes landed: the
-// completion that follows is what asserts that, and it fails against a
-// document this client can no longer write.
-function whenSaved(doc: Document): Promise<void> {
-  if (doc.savingCount === 0) return Promise.resolve();
-  return new Promise<void>((resolve) => {
-    let off: (() => void) | undefined;
-    let poll: ReturnType<typeof setInterval> | undefined;
-    const settle = (): void => {
-      off?.();
-      if (poll !== undefined) clearInterval(poll);
-      resolve();
-    };
-    try {
-      off = doc.subscribe(() => {
-        if (doc.savingCount > 0) return;
-        settle();
-      });
-    } catch {
-      // The document closed, so nothing more is going to be acked.
-      resolve();
-      return;
-    }
-    poll = setInterval(() => {
-      if (doc._isLive && doc.savingCount > 0) return;
-      settle();
-    }, SAVED_LIVENESS_POLL_MS);
-    // Node keeps the process alive for a pending interval; this one is
-    // bookkeeping for a wait that ends on its own, so it must not.
-    (poll as { unref?: () => void }).unref?.();
-    if (doc.savingCount === 0) settle();
-  });
-}
-
 function asError(err: unknown): Error {
   return err instanceof Error ? err : new Error(String(err));
 }

package/src/internal.ts

@@ -21,4 +21,10 @@ export {
   type TokenSet,
 } from './auth-flow.js';
 export { decodeIdToken } from './jwt.js';
+export {
+  fetchWithRetry,
+  RETRY_READ,
+  type RetryOptions,
+  type RetryPolicy,
+} from './fetch-retry.js';
 export { BRASS_INIT_ARG_KEYS, type BrassInitArgKey } from './init-keys.js';

package/src/open-document.ts

@@ -11,6 +11,7 @@ import {
   type DocumentOptions,
   type DocumentWorkStatus,
   type DocumentDriveStatus,
+  type DrivePublishTarget,
   type DocumentDriveTrackingState,
   type DriveMirrorDirection,
   type HostedUiProvider,
@@ -214,6 +215,33 @@ export interface DocumentSnapshotResponse {
   // Drive provenance + tracking state, present only on drive-linked docs.
   // Seeds `doc.driveStatus`; live changes stream in via `doc_drive_status`.
   drive?: DocumentDriveSummaryWire;
+  // Whether this document's export runs in the app this client acts as.
+  // Server-answered per caller, so it says only that this app is the one to
+  // serialize, never which app is if it is not. Absent for a caller carrying
+  // no app assertion.
+  calling_app_exports?: boolean;
+  // The version of the document's current picture, absent when it has none.
+  // Only the version is read (a picture behind the head is what makes this
+  // open seed one), so the shape is deliberately narrow: the full wire record
+  // is the thumbnail routes' surface, not the join's.
+  thumbnail?: { version?: number } | null;
+  // Where a document that mirrors nothing can be published, present only
+  // while it mirrors nothing and its project is linked to a drive that
+  // takes a new file. The hosted drive badge offers the publish off this.
+  drive_publish_target?: DrivePublishTargetWire;
+}
+
+// Wire shape of a publish target on the join response. Snake_case,
+// mirroring the server's `DocumentDrivePublishTarget` (CONTRACT.md "Where
+// a document with no drive item can publish").
+export interface DrivePublishTargetWire {
+  drive_type?: unknown;
+  drive_name?: unknown;
+  container_name?: unknown;
+  detail?: unknown;
+  source_unreadable?: unknown;
+  publishing?: unknown;
+  publish_failed?: unknown;
 }
 
 // Wire shape of the `drive` block carried on the join response and the
@@ -237,6 +265,7 @@ export interface DocumentDriveSummaryWire {
   // Optional: a frame from an older server omits it, treated as not
   // publishing (the `canPush` affordance then behaves as before).
   publishing?: boolean;
+  source_unreadable?: string;
 }
 
 // Wire-protocol-pinned response shape from
@@ -620,6 +649,21 @@ interface DocDriveStatusFrame {
   drive: DocumentDriveSummaryWire;
 }
 
+// Server-pushed publish state for a document that mirrors nothing on a drive
+// yet. Wire shape pinned in CONTRACT.md "Server-pushed `doc_drive_publish`".
+// The first publish creates the artifact, so until it lands the document has
+// no drive summary and `doc_drive_status` carries nothing about the push it
+// started.
+interface DocDrivePublishFrame {
+  type: 'doc_drive_publish';
+  topic: string;
+  publish: {
+    publishing?: unknown;
+    failed?: unknown;
+    detail?: unknown;
+  };
+}
+
 // Server-pushed frame fired when the platform discards ops it cannot apply.
 // The prompt half of the durability
 // handshake: the SDK re-checks durability against ground truth now rather
@@ -651,7 +695,9 @@ function toDriveStatus(wire: DocumentDriveSummaryWire): DocumentDriveStatus {
     // update) must not be treated as unbroken and offered a push the server
     // would reject. Require an explicit `false` to enable, and an explicit
     // `true` to flag broken. Behaviour is unchanged for today's frames, which
-    // always carry the boolean.
+    // always carry the boolean. Whether the file is written server-side or
+    // from the app's own serializer is a REQUEST SHAPE the push path resolves
+    // for itself, so it says nothing about whether this document can publish.
     canPush:
       wire.broken === false &&
       mirrorDirection === 'two_way' &&
@@ -666,6 +712,31 @@ function toDriveStatus(wire: DocumentDriveSummaryWire): DocumentDriveStatus {
     itemName: wire.item_name,
     itemUrl: wire.item_url,
     publishing: wire.publishing === true,
+    // Spread rather than assigned, because `exactOptionalPropertyTypes`
+    // separates an absent optional field from one holding `undefined`.
+    ...(wire.source_unreadable !== undefined
+      ? { sourceUnreadable: wire.source_unreadable }
+      : {}),
+  };
+}
+
+// Map the wire target to the public shape, dropping one that does not carry
+// what a publish needs. A malformed target is skipped rather than failing
+// the open: the document is readable whatever its publish offer says.
+function toPublishTarget(
+  wire: DrivePublishTargetWire | undefined,
+): DrivePublishTarget | null {
+  if (typeof wire !== 'object' || wire === null) return null;
+  const driveName = wire.drive_name;
+  if (typeof driveName !== 'string' || driveName === '') return null;
+  return {
+    driveName,
+    driveType: typeof wire.drive_type === 'string' ? wire.drive_type : '',
+    containerName:
+      typeof wire.container_name === 'string' ? wire.container_name : '',
+    detail: typeof wire.detail === 'string' ? wire.detail : '',
+    publishing: wire.publishing === true,
+    publishFailed: wire.publish_failed === true,
   };
 }
 
@@ -969,6 +1040,15 @@ function isDocMetaFrame(frame: unknown): frame is DocMetaFrame {
   );
 }
 
+function isDocDrivePublishFrame(frame: unknown): frame is DocDrivePublishFrame {
+  if (typeof frame !== 'object' || frame === null) return false;
+  const f = frame as Record<string, unknown>;
+  if (f.type !== 'doc_drive_publish' || typeof f.topic !== 'string') {
+    return false;
+  }
+  return typeof f.publish === 'object' && f.publish !== null;
+}
+
 function isDocDriveStatusFrame(frame: unknown): frame is DocDriveStatusFrame {
   if (typeof frame !== 'object' || frame === null) return false;
   const f = frame as Record<string, unknown>;
@@ -1738,10 +1818,19 @@ export function createOpenDocument(
     // (a stub opened mid-hydration returns `snapshot: null` + a `pending`
     // status).
     if (parsed.status !== undefined) doc._emitStatus(parsed.status);
+    // Whether this app is the one to serialize the document, which is what
+    // decides whether a push carries bytes. Answered by the server for the
+    // caller's own app and only on the join, since the fanout frame is one
+    // payload for every subscriber and has no caller to answer for.
+    doc._setExportRunsHere(parsed.calling_app_exports === true);
     // Seed `doc.driveStatus` from the join before the first
     // `doc_drive_status` frame.
     if (parsed.drive !== undefined) {
       doc._emitDriveStatus(toDriveStatus(parsed.drive));
+    } else {
+      // Only for a document that mirrors nothing: a mirror publishes through
+      // its link, and `_emitDriveStatus` clears any targets anyway.
+      doc._setPublishTarget(toPublishTarget(parsed.drive_publish_target));
     }
     // Highest seq seen; later `doc_op` / `op_ack` frames advance it. Kept in
     // a closure, not on the Document: it is a transport concern, not CRDT
@@ -2161,6 +2250,7 @@ export function createOpenDocument(
         await uploader(doc, image, width, height);
       });
     }
+    doc._setThumbnailVersion(parsed.thumbnail?.version ?? null);
     if (opts.checkpointCreator) {
       const creator = opts.checkpointCreator;
       doc.setCheckpointCreator(() => creator(doc));
@@ -4300,6 +4390,15 @@ function wireDocTransport(args: WireDocTransportArgs): void {
         args.doc._emitDriveStatus(toDriveStatus(frame.drive));
         return;
       }
+      if (isDocDrivePublishFrame(frame)) {
+        args.doc._emitPublishState({
+          publishing: frame.publish.publishing === true,
+          failed: frame.publish.failed === true,
+          detail:
+            typeof frame.publish.detail === 'string' ? frame.publish.detail : null,
+        });
+        return;
+      }
       if (isDocOpsDroppedFrame(frame)) {
         // Prompt durability re-check: the discard sealed a new snapshot, so
         // re-fetch the moved frontier and run the handshake now instead of at

package/src/record-paging.ts

@@ -232,16 +232,15 @@ const TOMBSTONE_PREFIX = `${RESERVED_KEY_PREFIX}x:`;
 
 /** Pack one stored value into a page triple. A `null` tag is what says the
  *  body IS the record: an app's map holds whatever the app assigned, which has
- *  no tag to split off. A codec's records arrive already split, and a codec
- *  tag is a string, so the two forms cannot be confused however a codec names
- *  its records. */
+ *  no tag to split off. A typed record arrives already split, and its tag is a
+ *  string, so the two forms cannot be confused whatever the tag says. */
 export function packWholeValue<B>(key: string, value: B): PackedRecord<B> {
   return [key, null, value];
 }
 
 /** Re-pack `value` in the same triple shape `packed` already uses, so a page
- *  rewritten in place keeps the form its readers expect: a codec's records
- *  stay a tag beside a body, and an app's stay one whole value. A streaming
+ *  rewritten in place keeps the form its readers expect: a typed record stays
+ *  a tag beside a body, and an app's stays one whole value. A streaming
  *  read visits a page's triples without unpacking them, so a rewrite that
  *  changed the shape would hand it the wrong half of the record. */
 export function repackRecord(
@@ -259,7 +258,7 @@ export function repackRecord(
 }
 
 /** The stored value a page triple carries: the value itself for a whole-value
- *  record, else the `{ type, params }` pair a codec split it into. */
+ *  record, else the `{ type, params }` pair a typed one was split into. */
 export function unpackRecord(packed: PackedRecord<unknown>): unknown {
   if (packed[1] === null) return packed[2];
   return { [TAG_FIELD]: packed[1], [BODY_FIELD]: packed[2] };
@@ -269,12 +268,12 @@ export function unpackRecord(packed: PackedRecord<unknown>): unknown {
  *  separately, or null when the triple packs a whole value that is not a
  *  record.
  *
- *  A page holds both forms: a codec packs a record it has already split into a
- *  tag and a body, and a map an app writes packs whatever the app assigned as
- *  one whole value. Both forms occur in ONE store, because an app's bulk add
- *  to a codec's record map seals its own pages, so a reader that took
- *  `packed[1]` for the tag would report every record those pages hold as
- *  having no type at all. */
+ *  A page holds both forms: a typed record is packed as the tag and body it
+ *  was already split into, and a map an app writes packs whatever the app
+ *  assigned as one whole value. Both forms occur in ONE store, because an
+ *  app's bulk add to a store of typed records seals its own pages, so a reader
+ *  that took `packed[1]` for the tag would report every record those pages
+ *  hold as having no type at all. */
 export function unpackRecordPair(
   packed: PackedRecord<unknown>,
 ): { tag: string; body: unknown } | null {
@@ -454,7 +453,7 @@ const WIDTH_SAMPLE = 256;
 /** Mean JSON bytes of a record body, over a stride sample of at most
  *  `WIDTH_SAMPLE` records, which is what `recordsPerPage` sizes a page
  *  against. `bodyOf` returns the value the caller will pack as the triple's
- *  body: a codec's records carry a tag beside a body, and an app's map packs
+ *  body: a typed record carries a tag beside a body, and an app's map packs
  *  its whole stored value (`packWholeValue`), so each caller weighs the bytes
  *  its own pages will hold.
  *
@@ -673,7 +672,7 @@ export function applyRecordPatches(
  * value and as the `(tag, body)` pair split out of it, and return all three
  * after the fold.
  *
- * A patch names the record's own fields, which for a codec record are
+ * A patch names the record's own fields, which for a typed record are
  * `type` and `params` together, so a reader that walks tag and body
  * separately has to re-split the result. Both readers of a paged store
  * (the flattening one and the streaming one) resolve patches through this

package/src/serializer.ts

@@ -22,9 +22,9 @@ export interface StoredList<T = unknown> extends ListHandle<T> {
 /**
  * The document as a serializer sees it: the same containers, readable whole.
  *
- * A `Document` satisfies this, which is what keeps a built-in codec and a
- * third-party one on one surface. The difference between them is where they
- * run, not what they are allowed to reach.
+ * A `Document` satisfies this, which is what keeps a serializer the platform
+ * ships and one an app registers on one surface. The difference between them
+ * is where they run, not what they are allowed to reach.
  */
 export interface StoredDocument {
   readonly id: string | null;