js-bao-wss-client 2.2.0-alpha.12 → 2.2.0-alpha.13

package/README.md

@@ -123,9 +123,10 @@ const client = await initializeClient({
   appId: "my-app",
   models: [Task, Project],
 
-  // Yjs document persistence for Node.js
-  yjsPersistence: (docId, ydoc, { appId, userId }) => {
-    return new SqlitePersistence(docId, ydoc, {
+  // Yjs document persistence for Node.js. The first argument is the store
+  // name — see "What the first argument is" below.
+  yjsPersistence: (storeName, ydoc, { appId, userId }) => {
+    return new SqlitePersistence(storeName, ydoc, {
       dbPath: `${process.env.HOME}/.my-app/${appId}/${userId}/yjs.sqlite`
     });
   },
@@ -137,6 +138,34 @@ const { ydoc } = await client.documents.open("doc-123", {
 });
 ```
 
+**What the first argument is**
+
+The factory's first argument is the **store name** to persist this Yjs state
+under, not necessarily the document id. For an ordinary document, and for a
+large document (`documentFormat: 2`) that has not rotated yet, the two are the
+same value.
+
+A large document's Yjs state is an epoch *overlay* rather than the document
+itself, so once it rotates each epoch gets its own store name,
+`{documentId}@{epoch}`. A rotation attaches a provider for the fresh epoch and
+then clears the sealed one, so a factory that put both epochs under one name
+would lose every write made since the rotation to that clear. Keying your
+storage on the first argument — as the example above does — is correct for both
+kinds of document, and needs no change when a document grows large.
+
+The third argument carries the rest of what the store is for:
+
+| Field | Meaning |
+|-------|---------|
+| `appId` | The application id |
+| `userId` | The authenticated user, or `"anon"` |
+| `documentId` | The plain document id, without the epoch suffix |
+| `documentFormat` | `2` for a large document, `1` for an ordinary one — absent on the very first open of a document created elsewhere, whose format nothing local knows yet |
+| `epoch` | The epoch the store name is scoped to, or `null` when the name is the plain document id |
+
+Use `context.documentId` when you want to group every store belonging to one
+document; use the first argument whenever you are naming storage.
+
 **Why two storage systems?**
 
 - `storageConfig` → General key-value data (auth, cache, metadata)

package/dist/JsBaoClient.d.ts

@@ -14,6 +14,7 @@ import { type GoogleClientsConfig } from "./internal/authController";
 import { type RequestOptions } from "./internal/httpClient";
 import { type DocumentPermission as DocumentAccessLevel, type LocalDocumentEntry, type LocalMetadataEntry, type DocumentDebugSnapshot } from "./internal/documentManager";
 import { type OfflineReplayNotice } from "js-bao";
+import type { DocumentOfflineWindowError } from "js-bao";
 import { DocumentsAPI, DocumentContext, type DocumentInfo, type ResolveAliasParams, type CreateDocumentOptions } from "./api/documentsApi";
 import { type CacheFacade } from "./api/cacheFacade";
 import { MeAPI } from "./api/meApi";
@@ -420,6 +421,15 @@ export interface ExecutePromptResult<R = unknown> {
          * Absent when the provider reports none.
          */
         reasoningTokens?: number;
+        /**
+         * What this call cost, in USD, as the provider reported it.
+         *
+         * A decisions model's case is largely economic — a fraction of a chat
+         * model's cost on the same workload — so a result that reported tokens
+         * and not price would leave the number the choice turns on off the wire.
+         * Absent when the provider reports none.
+         */
+        cost?: number;
     };
     rawResponse: R;
     configId: string;
@@ -519,6 +529,18 @@ export interface JsBaoClientOptions {
      * - Browser: uses y-indexeddb (built-in)
      * - Node.js: no Yjs persistence (documents only synced via server)
      *
+     * The factory's first argument is the STORE NAME to persist this Yjs state
+     * under, not necessarily the document id. For an ordinary document, and for a
+     * large document (`documentFormat: 2`) that has not rotated yet, the two are
+     * the same. A large document's Yjs state is an epoch OVERLAY, so once it
+     * rotates each epoch gets its own name (`{documentId}@{epoch}`): a rotation
+     * attaches a provider for the fresh epoch and then clears the sealed one, so
+     * a factory that put both epochs under one name would lose the writes made
+     * since the rotation to that clear. Keying storage on the first argument, as
+     * the example below does, is therefore correct for both kinds of document;
+     * `context.documentId` is the plain document id when you want to group a
+     * document's stores.
+     *
      * For Node.js persistence, use y-sqlite3:
      * @example
      * ```typescript
@@ -526,8 +548,8 @@ export interface JsBaoClientOptions {
      *
      * const client = new JsBaoClient({
      *   // ...
-     *   yjsPersistence: (docId, ydoc, { appId, userId }) => {
-     *     return new SqlitePersistence(docId, ydoc, {
+     *   yjsPersistence: (storeName, ydoc, { appId, userId }) => {
+     *     return new SqlitePersistence(storeName, ydoc, {
      *       dbPath: `~/.my-app/${appId}/${userId}/yjs.sqlite`
      *     });
      *   }
@@ -615,6 +637,32 @@ export interface DocumentOfflineWritesResolvedEvent {
     epoch: number;
     notices: OfflineReplayNotice[];
 }
+/**
+ * Payload of the `document:write-refused` event
+ * (`client.on("document:write-refused", ...)`).
+ *
+ * Fired for EVERY local write a large document refuses because it is past its
+ * offline write window — the same event, by the same name, the Swift client
+ * emits. A call that can throw throws {@link error} as well, so the throw
+ * stays the call site's signal; this is the channel for handling the refusal
+ * once, in one place, on either client.
+ *
+ * Nothing is emitted for an accepted write, for an ordinary (format-1)
+ * document, or for a refusal of another kind.
+ */
+export interface DocumentWriteRefusedEvent {
+    documentId: string;
+    /** The model the refused write was on. */
+    model: string;
+    /** The record it was on. */
+    recordId: string;
+    /**
+     * The very error the call threw: `code` is
+     * `DOCUMENT_OFFLINE_WINDOW_EXPIRED`, and `details` carries `documentId`,
+     * `lastSyncAt`, `windowDays` and `overdueMs`.
+     */
+    error: DocumentOfflineWindowError;
+}
 /**
  * Options for `client.syncMetadata()`. Controls whether the sync covers all
  * of the user's document metadata or a single document (`scope` /
@@ -1649,6 +1697,13 @@ export interface ListLocalDocumentsOptions {
 export interface EvictAllLocalOptions {
     /** If true, only evicts documents that are fully synced with the server. */
     onlySynced?: boolean;
+    /**
+     * Whose local stores to remove, when it is not whoever is signed in.
+     *
+     * @internal The sign-out path captures the departing user before the token is
+     * cleared and passes it here; nothing else needs to.
+     */
+    storageUser?: string | null;
 }
 /**
  * Map of every event the client emits to its payload type. This is the
@@ -1738,6 +1793,7 @@ export interface JsBaoEvents {
     sync: SyncEvent;
     awareness: AwarenessEvent;
     "document:snapshot-load": DocumentSnapshotLoadEvent;
+    "document:write-refused": DocumentWriteRefusedEvent;
     "blobs:upload-progress": BlobUploadProgressEvent;
     "blobs:upload-completed": BlobUploadCompletedEvent;
     "blobs:upload-failed": BlobUploadFailedEvent;
@@ -2005,6 +2061,17 @@ export declare class JsBaoClient extends Observable<any> {
     private jsBaoFormat2NoteDiscontinuity;
     /** #3435 — the convergence landed: forget what it reconciled. */
     private jsBaoFormat2ClearDiscontinuities;
+    /**
+     * #3755 — record durably that this client owes a deferred judgement.
+     *
+     * Written BEFORE the overlay swap and again inside the epoch mark's own
+     * transaction: the client keeps two marks (the document metadata row and the
+     * store's `_epoch`) and the bind raises the second to the first, so a crash
+     * between them reproduces the window the note exists to close.
+     */
+    private jsBaoFormat2NoteDeferredReplay;
+    /** #3755 — the deferred judgement has been made: forget the note. */
+    private jsBaoFormat2ClearDeferredReplay;
     /**
      * #3435 — the models this client holds rows of, which is the inventory a
      * convergence plan decides its whole-model prunes against.
@@ -2088,12 +2155,33 @@ export declare class JsBaoClient extends Observable<any> {
      * behavior 15).
      */
     private jsBaoFormat2LoadSnapshot;
+    /**
+     * Remove one large document's local record store (#3754).
+     *
+     * The three doors an app removes local data through — `documents.evict`,
+     * `closeDocument({ evictLocal: true })` and `logout({ wipeLocal: true })` —
+     * cleared the Yjs overlay and the metadata row and nothing else, so a large
+     * document's records, its unacknowledged writes and its projected query rows
+     * stayed on disk and opened read-only from the same profile. This is what
+     * removes them, and the Swift client has had its twin since #3436.
+     */
+    private jsBaoFormat2Purge;
+    /** The same for every large document of one scope except `keep` (#3754). */
+    private jsBaoFormat2PurgeAll;
     /**
      * Runs an epoch move with the document's local writes held back: a write
      * that lands on the sealed overlay after what is owed has been read off it
      * goes down with that document (#2816, behavior 10).
      */
     private jsBaoFormat2HoldWrites;
+    /**
+     * How to stop hearing this ORM instance's refused writes.
+     *
+     * Held so the subscription goes down with the instance it belongs to: an
+     * ORM torn down and replaced would otherwise leave a listener re-emitting
+     * on a client that has moved on.
+     */
+    private jsBaoFormat2WriteRefusedUnsubscribe;
     /**
      * Documents whose writes this client is already holding.
      *
@@ -2181,6 +2269,33 @@ export declare class JsBaoClient extends Observable<any> {
      * the bind. They stay silent until it has (#2816, behavior 12).
      */
     private readonly format2OwedCatchUps;
+    /**
+     * Documents whose last move was REFUSED because its deferred judgement
+     * could not be recorded durably (#3755, finding 3755-R1).
+     *
+     * The debt stays owed and the document stays held behind the room, so the
+     * existing owed-catch-up path retries the catch-up and the move on the next
+     * `epoch.info` or `snapshot.ready`. Deliberately not a stop: nothing is
+     * broken, one write did not land.
+     */
+    private readonly format2DeferredNoteRefusals;
+    /**
+     * Documents whose deferred judgement is being planned right now (#3755).
+     *
+     * Both triggers — the bind and the document's `epoch.info` — can land while
+     * the other's archive reads are in flight, and two resumes over one note
+     * would judge the same writes twice.
+     */
+    private readonly format2ResumingJudgements;
+    /**
+     * Test-only (#3755): hold a deferred judgement instead of settling it.
+     *
+     * `null` in every build an application runs, and read in exactly one place
+     * ({@link format2SettlePendingReplay}). Not on the package's public surface:
+     * an integrated test reaches it the way it reaches the other private fields
+     * it drives, and nothing an app can call installs it.
+     */
+    private format2ReplaySettleGate;
     /**
      * Large documents stopped on a superseded epoch: their overlay belongs to an
      * epoch the room has left behind, so nothing of their local state may be
@@ -2829,6 +2944,21 @@ export declare class JsBaoClient extends Observable<any> {
     private getServiceWorkerApiBase;
     private handleServiceWorkerAuthChange;
     private emitAuthSuccess;
+    /**
+     * What a large document's browser store is named by, for one NAMED user
+     * (#3754).
+     *
+     * The same three parts every open uses. Taking the user as an argument is the
+     * whole point: at logout the token has already gone, so anything that asked
+     * "who is signed in?" would answer `anon` and name stores this user never
+     * wrote (finding R1).
+     */
+    private largeDocumentScopeFor;
+    /**
+     * The purge hook as an eviction context wants it: the scope filled in from
+     * the user the caller captured (#3754).
+     */
+    private largeDocumentPurgeContext;
     private getCurrentUserIdForStorage;
     private resolveAnalyticsUserUlid;
     private resolveAnalyticsPlan;
@@ -3209,6 +3339,30 @@ export declare class JsBaoClient extends Observable<any> {
      * next frame on THIS connection reads, before any store has been bound.
      */
     private format2NoteDiscontinuity;
+    /**
+     * Record durably that this document owes a deferred judgement (#3755).
+     *
+     * Written BEFORE the overlay swap, and again inside the epoch mark's own
+     * transaction: the client keeps TWO epoch marks — the document metadata row
+     * (moved by `swapEpochDocument`) and the store's `_epoch` (moved after it) —
+     * and the bind raises the second to the first. A crash between them would
+     * otherwise leave a store whose mark reads current with nothing saying a
+     * judgement is owed, which is the very defect this note closes. One row, one
+     * idempotent upsert, whichever of the two lands.
+     *
+     * REJECTS on failure rather than logging and carrying on (finding 3755-R1):
+     * the caller refuses the move, so nothing advances without the note.
+     */
+    private format2NoteDeferredReplay;
+    /**
+     * The deferred judgement has been made: forget the note (#3755).
+     *
+     * Awaited before the withhold is released, so a flush that fires during the
+     * clear still finds the covered sequences held back. A failure leaves the
+     * note standing — the survivors are stated and safe; only their claim waits
+     * for the next bind to read the note again.
+     */
+    private format2ClearDeferredReplay;
     /**
      * Run `run` with this document's local writes held back, once.
      *
@@ -3229,6 +3383,23 @@ export declare class JsBaoClient extends Observable<any> {
      * prevent.
      */
     private format2WithholdSequences;
+    /**
+     * Hold back every sequence a DURABLE deferred judgement still covers
+     * (#3755, finding 3755-R3).
+     *
+     * Applied by every caller of `claimCatchUp` before it claims, because there
+     * is no barrier between the ORM's adoption and the post-bind hook:
+     * `handleSyncStep1` reads these very marks and claims straight off them, and
+     * a handshake landing in that window would otherwise claim sequences whose
+     * content is on no frame. One synchronous read of the mirror the adoption
+     * refreshed, on a path the client already takes.
+     *
+     * The floor is the lowest UNACKNOWLEDGED sequence, not the note's own span:
+     * the server's mark is contiguous, so nothing above a covered sequence can be
+     * acknowledged anyway, and claiming it would only invite the prune this
+     * exists to prevent.
+     */
+    private format2ApplyDurableWithhold;
     /** The withheld writes have been replayed: their sequences may travel. */
     private format2ReleaseWithheldSequences;
     /** The highest bulk-load epoch this document has not converged past (#3435). */
@@ -3396,6 +3567,107 @@ export declare class JsBaoClient extends Observable<any> {
      * about and classified by presence alone (finding 3435-R07).
      */
     private format2SettleConvergenceReplay;
+    /**
+     * Resume a judgement a restart interrupted (#3755, C4).
+     *
+     * The debt is durable and this is where it is paid. Runs when BOTH halves
+     * are in — the store is bound (so the note and the owed writes are readable)
+     * and the document's `epoch.info` has arrived (so the chain and the seal
+     * times are) — whichever comes second.
+     *
+     * The evidence is rebuilt into the DOCUMENT's own conflict ledger, never a
+     * replacement (finding 3755-R2): `format2NoteClock` has already seeded it
+     * with the handshake's seal times, and a fresh ledger without them would
+     * make a provably outdated write merely ambiguous and replay it. Each
+     * archive of `[from_epoch, to_epoch)` is NOTED, never folded — the merged
+     * view already holds those epochs; what is missing is the record of what
+     * they touched.
+     *
+     * The judgement itself is then held exactly as an in-session deferral is, so
+     * it runs on the joined epoch's `syncComplete` (with the open epoch's content
+     * noted first and the dropped-delete question asked) or on the same 15 s
+     * fallback.
+     */
+    private format2MaybeResumeDeferredJudgement;
+    /**
+     * Pay a durable judgement NOW, from the recorded mutations (#3755, findings
+     * 3755-C01 and 3755-C03).
+     *
+     * A note stands exactly where the writes it covers are on no overlay: a
+     * deferral installed a fresh one without them, or a bind kept them off it on
+     * purpose. So no carry read off an overlay can ever settle this debt —
+     * `carryUnackedOverlay` finds nothing to carry and the note would be cleared
+     * over writes that reached no frame. It is settled here instead, from the
+     * durable log, and closed in the order an uninterrupted judgement closes it.
+     *
+     * Unlike {@link format2MaybeResumeDeferredJudgement} this does not wait for
+     * the joined epoch to sync: every caller is already at the point where that
+     * epoch's content is in (a judgement that has just run, or a rebuild that
+     * has just landed its base).
+     *
+     * Answers whether there was a debt; a caller told `false` still owes its own
+     * close-out.
+     */
+    private format2SettleDurableDebt;
+    /**
+     * The durable debt this document is standing under, if any (#3755).
+     *
+     * The same reading the bind makes, off the same marks: a note is honoured
+     * only where it still names writes this store has not had acknowledged.
+     */
+    private format2DurableDebtNote;
+    /**
+     * The writes a resumed judgement is about (#3755).
+     *
+     * This client's ops inside the note's span, MINUS the ones a bulk load's
+     * convergence owns: the discontinuity path judges everything at or below its
+     * boundary (#3435, finding FROZEN-01), so the two sets are disjoint and no
+     * write is judged twice (edge E4).
+     */
+    private format2OwedForJudgement;
+    /**
+     * Note the archives of `[from_epoch, to_epoch)` as conflict evidence, without
+     * folding any of them (#3755, behavior 13).
+     *
+     * The merged view already holds those epochs — the interrupted session
+     * applied them — so folding would re-apply state the document has. What was
+     * lost is the RECORD of which records and fields each of them touched, which
+     * is what a recency judgement is made of. An archive a concurrent catch-up
+     * has already noted is not fetched again.
+     */
+    private format2NoteResumedChain;
+    /** The document's conflict ledger, created only if it has none. */
+    private format2EnsureConflictLedger;
+    /**
+     * Judge a resumed deferral and state what survives (#3755, C4 steps 1-3).
+     *
+     * The same three things an uninterrupted judgement does, in the same order,
+     * which is why the verdict an app receives is the same either way.
+     */
+    private format2RunResumedJudgement;
+    /**
+     * Steps 1 and 2 of a resumed judgement: resolve, and state what survives.
+     *
+     * Apart from the close-out, so a caller that has more to do before the note
+     * may be cleared can take the same two steps (#3755, finding 3755-C01).
+     */
+    private format2StateResumedJudgement;
+    /**
+     * Close out a judgement, in the order that keeps a flush honest (#3755,
+     * finding 3755-R5).
+     *
+     * Clear the note durably, THEN release the withhold, THEN send the
+     * state-complete claim. A flush that fires during the awaited clear still
+     * finds the covered sequences held back, so it carries the survivors and
+     * claims nothing — and the claim that follows covers them.
+     *
+     * The claim is not conditional on anything having been dropped: the
+     * survivors are STATED from their recorded mutations rather than committed,
+     * so no sequence is noted for them and an ordinary frame's claim starts at
+     * the session floor. Only a state-complete frame may claim what this session
+     * did not write, and this is that frame.
+     */
+    private format2FinishDeferredJudgement;
     /**
      * The owed writes a RESTART left for the convergence to judge (#3435,
      * finding FROZEN-01).
@@ -4478,26 +4750,39 @@ export declare class JsBaoClient extends Observable<any> {
     private metadataHydratedFromIdb;
     private _loadAllMetadataFromIdb;
     /**
-     * Seed the local-only marker for one document from its persisted metadata.
+     * Seed what the open path must know about a document BEFORE it acts on it,
+     * from that document's persisted metadata row.
      *
-     * `openDocument` can be handed the id of a document created with
-     * `localOnly: true` in an earlier session, and nothing on the open path
-     * reads local storage first — the in-memory metadata index is only ever
-     * filled by a listing call, which an app that stores document ids need never
-     * make. Without this, the document opens looking ordinary and its first edit
-     * goes out as an `update` frame (#2691).
+     * Two facts, one keyed read:
      *
-     * One keyed read, and only while the flag could still be unknown: once the
-     * whole index has been hydrated this session, or the document is already
-     * known local-only, there is nothing to learn.
+     * - Local-only-ness (#2691). `openDocument` can be handed the id of a
+     *   document created with `localOnly: true` in an earlier session, and
+     *   nothing else on the open path reads local storage first — the in-memory
+     *   metadata index is only ever filled by a listing call, which an app that
+     *   stores document ids need never make. Without this the document opens
+     *   looking ordinary and its first edit goes out as an `update` frame.
+     * - The naming fields (#3669). A large document's local overlay is stored
+     *   under `documentId@format2Epoch`, and `format2Epoch` lives in that row.
+     *   A by-id open in an un-hydrated session would otherwise attach the plain
+     *   name — an empty overlay — and the whole-row metadata write that follows
+     *   would erase the fields that said which store was the real one.
      *
      * "Hydrated" means a read that actually reached the store
      * (`metadataHydratedFromIdb`), not one that was merely attempted: the bulk
      * read gives up after 2s and swallows its own failures, and taking that
      * empty result as an answer would put a stored local-only document back on
      * the wire on exactly the sessions where storage was slow or unavailable.
+     * The naming half is read even on a hydrated session when the cache says
+     * this is a large document, because another tab may have rotated since the
+     * hydration — one keyed get per open of a large document, and nothing at all
+     * for an ordinary one.
+     *
+     * @returns whether the read produced the durable ROW. There is no definite
+     *   null to be had below this call — every layer answers a failure by
+     *   resolving `null` — so an absent row is read as a naming that is not
+     *   durable, and no store is reclaimed on one.
      */
-    private _primeLocalOnlyFromLocalMetadata;
+    private _primeFromLocalMetadata;
     /**
      * The format of a document being opened (#2816).
      *
@@ -4512,7 +4797,30 @@ export declare class JsBaoClient extends Observable<any> {
      * opens as legacy, exactly as it does today.
      */
     private _resolveDocumentFormat;
+    /**
+     * The durable naming read the manager uses before it chooses a store name
+     * (#3745), or `undefined` when there is nothing a read could add.
+     *
+     * Only worth a keyed read when the in-memory index is NOT already the whole
+     * picture: a hydration that reached the store answered for every document in
+     * it, so an ordinary open must not pay a second read. The same gate
+     * `_resolveDocumentFormat` applies to its own persisted source.
+     *
+     * A LARGE document is the one exception, and it is why this takes the
+     * document rather than answering for the session (#3669): another tab can
+     * rotate it after the hydration, so the epoch the index holds for it can be
+     * behind the row on disk, and the sweep on open re-reads that row under the
+     * epoch lock. An ordinary document on a hydrated session still pays nothing.
+     */
+    private _persistedNamingReader;
     private _putMetadataToIdb;
+    /**
+     * Persist a DELTA of one document's metadata row (#3746) — the fields named
+     * and nothing else, merged into whatever is stored. What the document-open
+     * path writes with, so opening one document in one tab cannot regress a field
+     * another tab's rotation or a listing wrote.
+     */
+    private _mergeMetadataToIdb;
     private _deleteMetadataFromIdb;
     private _enforceRetentionPolicy;
     /** Get the current network status including connectivity and transport state.
@@ -4635,7 +4943,28 @@ export declare class JsBaoClient extends Observable<any> {
     evictLocalDocument(documentId: string, opts?: {
         force?: boolean;
         suppressMetadataEvent?: boolean;
+        /**
+         * Whose local stores this is about. Defaults to the signed-in user; the
+         * sign-out path names the user who is signing OUT, because by then
+         * nobody is.
+         *
+         * @internal
+         */
+        storageUser?: string | null;
     }): Promise<void>;
+    /**
+     * Whose stores an eviction is about, decided NOW (#3754).
+     *
+     * The sign-out path names the user explicitly, because by the time it evicts
+     * the token is gone and nobody is signed in (finding R1). Every other caller
+     * names nobody — and "nobody" used to mean "whoever is signed in when the
+     * purge eventually runs", which is a different user for the one eviction that
+     * does not run at once: evicting a document that is OPEN defers its purge to
+     * the close, and a sign-out or a sign-in as somebody else can happen in
+     * between. Resolved at the door, the scope the close purges under is the one
+     * the eviction was asked for (criterion 5, finding 3754-C01).
+     */
+    private capturedStorageUser;
     /** Remove all locally stored document data.
      * @param opts - Optional eviction behavior
      * @group Offline & Sync */