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

package/README.md

@@ -18,7 +18,6 @@ A TypeScript/JavaScript client library for js-bao-wss that provides HTTP APIs an
 - **Analytics**: Buffered event logging API with optional automatic lifecycle events
 - **Blob Storage**: Upload/list/get/downloadUrl/delete per document with offline cache
 - **Server Functions**: Invoke your app's server functions, start and wait on long-running runs, and join the channels they authorize
-- **LLM**: Chat API and model listing _(deprecated — run a managed prompt from a server function (`ctx.prompts.run`) instead)_
 - **Offline-first Open**: Non-blocking open with IndexedDB-backed cache
 - **Offline Blob Cache**: Cache API + IndexedDB backed uploads/reads with eviction and retry
 - **Network Controls**: Online/offline modes, reachability, connection control
@@ -595,7 +594,6 @@ The client exposes a buffered analytics queue that batches events, retries on re
 - `client.analytics.logEvent({ action, feature, context_json?, ... })`: enqueue a single event. `context_json` accepts an object (auto-serialized) or a JSON string.
 - `client.analytics.flush()`: attempt to send the queue immediately; also runs automatically on reconnect and right before unload/destroy.
 - `client.analytics.setPlanOverride(plan)` and `.setAppVersionOverride(version)`: stamp metadata onto every subsequent event until you clear or replace it.
-- `client.getLlmAnalyticsContext()`: returns `{ logEvent, isEnabled }` when any LLM auto phases are enabled so higher-level features can coordinate their own analytics.
 
 Queued events are persisted in IndexedDB when offline storage is active, so short offline windows or reloads do not drop data. Everything funnels through the same `analytics.batch` WebSocket channel used by the live event test.
 
@@ -608,9 +606,6 @@ All automatic emitters are on by default; pass `analyticsAutoEvents` when constr
 - `sync_error` (`"sync"`, toggle: `analyticsAutoEvents.syncErrors.enabled`): records the `documentId` and `reason` when flush/send attempts fail (with interval throttling).
 - `blob_upload_started` / `blob_upload_succeeded` / `blob_upload_failed` (`"blobs"`, toggles: `analyticsAutoEvents.blobUploads.{start|success|failure}`): include blob/document identifiers, attempt counts, byte size, and retry details (with truncated error text on failure).
 - `session_end` (`"session"`, toggle: `analyticsAutoEvents.sessionEnd`): emitted on `beforeunload` and `client.destroy()`, including `duration_ms` and exit reason.
-- `prompt_started` / `prompt_succeeded` / `prompt_failed` (`"llm"` or `"gemini"`, toggles: `analyticsAutoEvents.llm.{start|success|failure}` and `analyticsAutoEvents.gemini.{start|success|failure}`): unified prompt lifecycle events emitted by `client.llm.chat()` and `client.gemini.generate()`/`client.gemini.countTokens()`. The `feature` field distinguishes the provider.
-
-When `analyticsAutoEvents.llm` enables any of `start`, `success`, or `failure`, `client.getLlmAnalyticsContext()` becomes non-null so LLM helpers can emit structured events without guessing configuration. `analyticsAutoEvents.gemini` controls `client.getGeminiAnalyticsContext()`, which powers automatic logging inside the Gemini namespace.
 
 **Removed events** (no longer emitted, and their option flags have been removed from `analyticsAutoEvents`): `client_boot` (`boot`), `first_doc_open` (`firstDocOpen`), `first_doc_edit` (`firstDocEdit`), `offline_recovery` (`offlineRecovery`), `service_worker_control` / `service_worker_token_update` (`serviceWorker`), `llm_request_*`, `gemini_request_*`.
 
@@ -621,7 +616,7 @@ const client = await initializeClient({
   ...options,
   analyticsAutoEvents: {
     blobUploads: { start: false, success: true, failure: true },
-    llm: { start: true, success: true, failure: false },
+    sessionEnd: false,
   },
 });
 ```
@@ -1280,15 +1275,19 @@ console.log(result.documentId); // The created document ID
 console.log(result.alias.aliasKey); // "current-draft"
 console.log(result.alias.documentId); // Same as documentId
 
-// The alias create takes `documentFormat` too, so a large document can be
-// created with its alias atomically. The response carries `documentFormat: 2`
-// for a large document and omits the key for an ordinary one.
+// The alias create takes the whole create vocabulary — `tags`, `metadata` and
+// `documentFormat` — with the same meaning they have on `create()`: applied when
+// the call creates the document. The response echoes what it applied, and omits
+// `documentFormat` for an ordinary document.
 const ledger = await client.documents.createWithAlias({
   title: "Ledger",
   alias: { scope: "user", aliasKey: "ledger" },
+  tags: ["ledger", "q3"],
+  metadata: { owner: "finance" },
   documentFormat: 2,
 });
 console.log(ledger.documentFormat); // 2
+console.log(ledger.tags); // ["ledger", "q3"]
 
 // Attempting to create with an existing alias throws HTTP 409
 try {
@@ -1310,6 +1309,27 @@ try {
 
 Use `createWithAlias()` when you need guaranteed uniqueness based on an alias (e.g., "only one home page per app"). Use regular `create()` + `aliases.set()` when offline support is needed or when the document should be created regardless of alias conflicts.
 
+#### Get-or-Create with Alias
+
+When you want the document to exist rather than to be new — "this user's ledger" — `getOrCreateWithAlias()` is the idempotent form: the first call creates it, every later one returns the same document. It takes the same options, applied only when the call creates the document:
+
+```typescript
+const ledger = await client.documents.getOrCreateWithAlias({
+  title: "Ledger",
+  alias: { scope: "user", aliasKey: "ledger" },
+  tags: ["ledger"],
+  documentFormat: 2,
+});
+
+console.log(ledger.created); // true on the call that made it, false after
+console.log(ledger.documentFormat); // 2 either way
+console.log(ledger.tags); // ["ledger"] on the create; absent afterwards
+```
+
+A stated `documentFormat` is also a statement about a document the alias already names. If the stored format **differs**, the call is refused with `DOCUMENT_FORMAT_MISMATCH` (409) naming the document and both formats, and nothing is created — being handed an ordinary document when you asked for a large one is the mistake this route exists to prevent. If it agrees, the format is echoed. Omit it and an existing binding is answered exactly as it always was.
+
+> All three create routes refuse a top-level body key they do not read, with 400 `VALIDATION_FAILED` and a `details` entry naming it. The typed methods above send only keys the routes read; this reaches you only if you build a request body by hand.
+
 ### Manage Permissions
 
 ```typescript
@@ -1777,142 +1797,6 @@ const user = await client.users.getBasic("u01H...");
 console.log(user.name, user.email, user.appRole);
 ```
 
-## Large Language Models (LLM)
-
-> **Deprecated.** The direct LLM client API (`client.llm.*`) is deprecated and will be removed in a future major release. Run a managed prompt from a server function (`ctx.prompts.run`) instead.
-
-```typescript
-// List available models
-const { models, defaultModel } = await client.llm.models();
-console.log("Default model:", defaultModel);
-
-// Basic chat
-const reply = await client.llm.chat({
-  // model is optional; uses server default when omitted
-  messages: [
-    { role: "system", content: "You are a helpful assistant." },
-    { role: "user", content: "Summarize: Collaborative editing with Yjs." },
-  ],
-  temperature: 0.2,
-  max_tokens: 512,
-  reasoning: {
-    effort: "medium",
-    exclude: false,
-  },
-});
-console.log(reply.content);
-
-// Chat with image attachment (base64-encoded PNG)
-const imageBase64 = await loadImageAsBase64("/path/to/screenshot.png");
-const imageReply = await client.llm.chat({
-  messages: [
-    {
-      role: "system",
-      content: "You analyze screenshots and respond helpfully.",
-    },
-    { role: "user", content: "Describe what you see in this image." },
-  ],
-  attachments: [
-    {
-      type: "image",
-      mime: "image/png",
-      base64: imageBase64,
-    },
-  ],
-});
-console.log(imageReply.content);
-```
-
-## Gemini
-
-> **Deprecated.** The direct Gemini client API (`client.gemini.*`) is deprecated and will be removed in a future major release. Run a managed prompt from a server function (`ctx.prompts.run`) instead.
-
-```typescript
-// Text generation with optional structured output
-const result = await client.gemini.generate({
-  messages: [
-    {
-      role: "system",
-      parts: [{ type: "text", text: "Reply in JSON with keys title and summary." }],
-    },
-    {
-      role: "user",
-      parts: [{ type: "text", text: "Summarize collaborative editing with Yjs." }],
-    },
-  ],
-  structuredOutput: {
-    responseMimeType: "application/json",
-    responseJsonSchema: {
-      type: "object",
-      properties: {
-        title: { type: "string" },
-        summary: { type: "string" },
-      },
-      required: ["title", "summary"],
-    },
-  },
-});
-console.log(result.message.parts[0].text);
-
-// Multimodal prompt with inline image data
-const screenshot = await loadImageAsBase64("/path/to/screenshot.png");
-await client.gemini.generate({
-  messages: [
-    {
-      role: "user",
-      parts: [
-        { type: "text", text: "Describe this screenshot." },
-        { type: "image", mimeType: "image/png", base64Data: screenshot },
-      ],
-    },
-  ],
-});
-
-// Raw passthrough using Google's payload schema
-const rawPayload = {
-  contents: [
-    {
-      role: "user",
-      parts: [
-        {
-          text: "Summarize this JSON.",
-        },
-        {
-          inline_data: {
-            mimeType: "application/json",
-            data: someBase64Json,
-          },
-        },
-      ],
-    },
-  ],
-};
-const rawResponse = await client.gemini.generateRaw({
-  model: "models/gemini-2.5-flash",
-  body: rawPayload,
-});
-console.log(rawResponse.candidates?.[0]?.content);
-
-// Token usage estimation
-const tokens = await client.gemini.countTokens({
-  model: "models/gemini-2.5-flash",
-  messages: [{ role: "user", parts: [{ type: "text", text: "How many tokens?" }] }],
-});
-console.log(tokens.totalTokens);
-```
-
-### Gemini Configuration & Notes
-
-- `client.gemini` proxies to server-side routes:
-  - `GET /gemini/models` → `client.gemini.models()`
-  - `POST /gemini/generate` → `client.gemini.generate(...)`
-  - `POST /gemini/count-tokens` → `client.gemini.countTokens(...)`
-  - `POST /gemini/generate-raw` → `client.gemini.generateRaw({ model, body })`
-  These endpoints run server-side, so browser clients never see Google credentials.
-- Inline multimodal content uses base64 `parts` (text, image, file), up to about 25 MB per request.
-- Structured output leverages `generationConfig.responseMimeType` plus optional `responseSchema` / `responseJsonSchema` so Gemini can return deterministic JSON. The full server response is always available via the `raw` field when you need annotations or safety metadata.
-- Error handling surfaces `JsBaoError` with `code: "GEMINI_ERROR"`; the `details` property contains the raw upstream payload so you can log or render troubleshooting info.
-
 ## Server Functions
 
 A server function is TypeScript your app's team writes in its config tree and

package/dist/JsBaoClient.d.ts

@@ -15,12 +15,11 @@ 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 { JsBaoError } from "./errors";
 import { DocumentsAPI, DocumentContext, type DocumentInfo, type ResolveAliasParams, type CreateDocumentOptions } from "./api/documentsApi";
 import { type CacheFacade } from "./api/cacheFacade";
 import { MeAPI } from "./api/meApi";
 import { SessionAPI } from "./api/sessionApi";
-import { LlmAPI } from "./api/llmApi";
-import { GeminiAPI } from "./api/geminiApi";
 import { UsersAPI } from "./api/usersApi";
 import { DatabasesAPI } from "./api/databasesApi";
 import { GroupsAPI } from "./api/groupsApi";
@@ -55,15 +54,12 @@ export type { AppInvitationInfo, InvitationQuota, CreateInvitationParams, Invita
 export type { DoDb, DOClientEngine, ModelIdentifier, ModelFieldInfo, SaveOptions } from "js-bao/client";
 export type { DiscoveredSchema, DiscoveredModel, DiscoveredField, DiscoveredConstraint, DiscoveredRelationship } from "js-bao";
 export type { CacheFacade } from "./api/cacheFacade";
-export type { ReasoningOptions, LlmChatOptions } from "./api/llmApi";
 export type { AnalyticsEventInput } from "./internal/analyticsQueue";
 export { ANALYTICS_UNAUTHENTICATED_USER } from "./internal/analyticsQueue";
 export type { DocumentBlobContext, BlobUploadSourceOptions, BlobUploadResult, BlobListResult, BlobUploadStatus, BlobReadOptions, BlobPrefetchOptions, BlobProxyUrlOptions, BlobDisposition, } from "./internal/blobManager";
 export type { DocumentsAPI, DocumentContext, DocumentAliasesAPI, DocumentIngestsAPI, DocumentSnapshotsAPI, } from "./api/documentsApi";
 export type { DatabasesAPI } from "./api/databasesApi";
 export type { CollectionsAPI } from "./api/collectionsApi";
-export type { GeminiAPI } from "./api/geminiApi";
-export type { LlmAPI } from "./api/llmApi";
 export type { MeAPI } from "./api/meApi";
 export type { SessionAPI } from "./api/sessionApi";
 export type { UsersAPI } from "./api/usersApi";
@@ -85,7 +81,6 @@ export type { CreateGroupTypeConfigParams, UpdateGroupTypeConfigParams, } from "
 export type { CreateRuleSetParams, DebugRuleSetParams, ListRuleSetsOptions, TestRuleSetParams, UpdateRuleSetParams, } from "./api/ruleSetsApi";
 export type { GetMeOptions, UpdateMeParams } from "./api/meApi";
 export type { GetUserOptions } from "./api/usersApi";
-export type { GeminiCandidate, GeminiFilePart, GeminiGenerationConfig, GeminiImagePart, GeminiSafetySetting, GeminiTextPart, } from "./api/geminiApi";
 export type { AggregateGroupByEntry, CreateOperationParamsOf, DatabaseOperationInfoOf, ObjectOrParamsRef, PipelineAggregateStep, PipelineCountStep, PipelineQueryStep, } from "./api/operationDefinition";
 export type { NotificationTokenAttempt } from "./api/notificationsApi";
 export type { InvitationsAPI, InvitationListOptions, DeferredGrantListOptions, } from "./api/invitationsApi";
@@ -105,7 +100,7 @@ export type { ResourceMetadataReadResult, ResourceMetadataWriteResult, ResourceM
  * `analyticsAutoEvents` in {@link JsBaoClientOptions}. Every category is
  * enabled by default; set a flag (or a category's sub-flags) to `false` to
  * opt out. Categories cover daily auth, return-to-active resumes, sync
- * errors, blob upload lifecycle, session end, and LLM / Gemini calls.
+ * errors, blob upload lifecycle, and session end.
  */
 export interface AnalyticsAutoEventsOptions {
     dailyAuth?: boolean;
@@ -121,18 +116,7 @@ export interface AnalyticsAutoEventsOptions {
         failure?: boolean;
     };
     sessionEnd?: boolean;
-    llm?: boolean | {
-        start?: boolean;
-        success?: boolean;
-        failure?: boolean;
-    };
-    gemini?: boolean | {
-        start?: boolean;
-        success?: boolean;
-        failure?: boolean;
-    };
 }
-export type { GeminiRole, GeminiContentPart, GeminiMessage, GeminiPromptOptions, GeminiGenerateOptions, GeminiGenerateResult, GeminiModelSummary, GeminiStructuredOutput, GeminiGenerateRawOptions, } from "./api/geminiApi";
 /**
  * Request passed to `client.integrations.call()`. Identifies the integration
  * by key and describes the HTTP request to send through the integration
@@ -407,6 +391,25 @@ export interface ExecutePromptResult<R = unknown> {
     success: boolean;
     output: string;
     error?: string;
+    /**
+     * The upstream provider's own HTTP status, on a failure where the call
+     * reached the provider and it answered. It does not depend on which provider
+     * the prompt's configuration names, and it is what a retry decision is made
+     * on without parsing `error`: retry on 408, 429, 502, 503 and 504; any other
+     * 4xx will fail the same way next time.
+     *
+     * Absent on success, and absent on a failure where no provider answer was
+     * observed — an unset provider key, an oversized payload, a completion that
+     * came back empty — so a number here is always the provider's own.
+     */
+    upstreamStatus?: number;
+    /**
+     * `"PROMPT_UPSTREAM_TIMEOUT"` when the provider itself ran out of time,
+     * which is the one failure of the model call that carries a code. Absent on
+     * success and on every other provider failure, so `error` with no
+     * `errorCode` still means "the call failed for some other reason".
+     */
+    errorCode?: "PROMPT_UPSTREAM_TIMEOUT";
     metrics: {
         durationMs: number;
         inputTokens?: number;
@@ -663,6 +666,36 @@ export interface DocumentWriteRefusedEvent {
      */
     error: DocumentOfflineWindowError;
 }
+/**
+ * Payload of the `document:format-mismatch` event
+ * (`client.on("document:format-mismatch", ...)`).
+ *
+ * Fired when the platform refuses a document because the format this client
+ * believed it had is not the format the platform resolved. The document is
+ * CLOSED when this arrives — its local rows and its unacknowledged writes are
+ * kept, nothing is evicted — because two of the three open shapes have no
+ * waiter to reject: a cached open sends its handshake from a microtask, and an
+ * already-open document re-syncs on reconnect. An open that WAS waiting on the
+ * network rejects with the same error as well.
+ *
+ * Diagnose from {@link declared} and {@link actual} before doing anything: the
+ * server also logs `Document format disagreement` naming its own pinned format.
+ * Evicting the document clears this client's belief, which repairs a stale row
+ * and HIDES a mis-pinned document.
+ */
+export interface DocumentFormatMismatchEvent {
+    documentId: string;
+    /** What this client believed, from its own local metadata row. */
+    declared: 1 | 2;
+    /** What the platform resolved for the document. */
+    actual: 1 | 2;
+    /**
+     * The very error a waiting `documents.open` rejects with: `code` is
+     * `DOCUMENT_FORMAT_MISMATCH` and `details` carries `documentId`, `declared`
+     * and `actual`.
+     */
+    error: JsBaoError;
+}
 /**
  * Options for `client.syncMetadata()`. Controls whether the sync covers all
  * of the user's document metadata or a single document (`scope` /
@@ -1794,6 +1827,7 @@ export interface JsBaoEvents {
     awareness: AwarenessEvent;
     "document:snapshot-load": DocumentSnapshotLoadEvent;
     "document:write-refused": DocumentWriteRefusedEvent;
+    "document:format-mismatch": DocumentFormatMismatchEvent;
     "blobs:upload-progress": BlobUploadProgressEvent;
     "blobs:upload-completed": BlobUploadCompletedEvent;
     "blobs:upload-failed": BlobUploadFailedEvent;
@@ -2319,6 +2353,28 @@ export declare class JsBaoClient extends Observable<any> {
      * and released once the handshake has been answered.
      */
     private readonly format2AwaitingHandshake;
+    /**
+     * The format each open attempt in flight pinned — #3764, decision D8.
+     *
+     * One format per open, declared on `syncStep1` and BOUND by the ORM. The
+     * background document read `DocumentManager.openDocument` starts rewrites the
+     * metadata row in between, so reading the row at the bind could bind the
+     * other format after the handshake had agreed on this one — the exact failure
+     * this feature exists to prevent. Cleared when the open settles, after which
+     * the row is the source again.
+     */
+    private readonly openAttemptFormats;
+    /**
+     * Documents the platform has REFUSED on this connection — #3764.
+     *
+     * A refused document sends no further handshake, is not retried by the sync
+     * watchdog, and does not rebuild the socket on its account; a fresh open of it
+     * is rejected with the refusal rather than waiting out an availability budget
+     * for a handshake this client will not send. The mark is cleared when the
+     * document is closed, evicted, or its metadata row's format changes — after
+     * any of which this client's belief is no longer the one that was refused.
+     */
+    private readonly format2FormatRefusals;
     /** Outbound sequences per large document: queued, sent, acknowledged. */
     private readonly format2Ack;
     private jsBaoAddDocumentModelMapping;
@@ -2447,18 +2503,6 @@ export declare class JsBaoClient extends Observable<any> {
     /** Sub-API for session management (sign in, sign out, token refresh).
      * @group Sub-APIs */
     session: SessionAPI;
-    /** Sub-API for LLM (large language model) operations.
-     * @group Sub-APIs
-     * @deprecated The direct LLM client API is deprecated and will be removed in a
-     * future major release. Run a managed prompt from a
-     * server function instead: `ctx.prompts.run` (see the Server Functions guide). */
-    llm: LlmAPI;
-    /** Sub-API for Gemini model operations.
-     * @group Sub-APIs
-     * @deprecated The direct Gemini client API is deprecated and will be removed in
-     * a future major release. Run a managed prompt from a
-     * server function instead: `ctx.prompts.run` (see the Server Functions guide). */
-    gemini: GeminiAPI;
     /** Sub-API for managing app users.
      * @group Sub-APIs */
     users: UsersAPI;
@@ -2976,18 +3020,6 @@ export declare class JsBaoClient extends Observable<any> {
     private handleBlobUploadComplete;
     private handleBlobUploadFailed;
     private logSessionEndEvent;
-    /** Get the analytics context for LLM operations.
-     * @group Configuration */
-    getLlmAnalyticsContext(): {
-        logEvent: (event: Omit<AnalyticsEventInput, "user_ulid">) => void;
-        isEnabled: (phase?: "start" | "success" | "failure") => boolean;
-    } | null;
-    /** Get the analytics context for Gemini operations.
-     * @group Configuration */
-    getGeminiAnalyticsContext(): {
-        logEvent: (event: Omit<AnalyticsEventInput, "user_ulid">) => void;
-        isEnabled: (phase?: "start" | "success" | "failure") => boolean;
-    } | null;
     private sanitizeOverride;
     private readEnvNumber;
     /** Check if a document is synced with the server.
@@ -3398,6 +3430,12 @@ export declare class JsBaoClient extends Observable<any> {
      * 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.
+     *
+     * A `legacy` note (#3760) is the same debt reached a different way — writes
+     * taken over from a pre-amendment pool and kept off the overlay until they
+     * are judged — so it withholds exactly as an ordinary one does (finding
+     * 3760-REVIEW-07). Only the bulk-load kind is left out: `_discontinuities`
+     * owns that debt and its own hold.
      */
     private format2ApplyDurableWithhold;
     /** The withheld writes have been replayed: their sequences may travel. */
@@ -3848,6 +3886,95 @@ export declare class JsBaoClient extends Observable<any> {
      * nothing of its local state may go out (see `format2RequireReload`).
      */
     private format2NeedsReload;
+    /**
+     * Pin what this open attempt BELIEVES the document's format is, before any
+     * handshake can leave (#3764, D8).
+     *
+     * Deliberately the local row's own answer rather than `_resolveDocumentFormat`,
+     * and the difference is the whole point twice over:
+     *
+     *   - that resolver DEFAULTS. It answers 1 for a document nobody knows about,
+     *     which is the right thing to BIND (the compatible layout) and a false
+     *     thing to DECLARE — a first open of somebody else's document would claim
+     *     format 1 and be refused. Only a row that NAMES a format is a belief, and
+     *     `documentFormatOf` answers `null` for anything else (criterion 3).
+     *   - it can reach the SERVER, and this runs before the connection is up, so
+     *     resolving here would both add a request to the open's critical path and
+     *     answer differently depending on how far the connect had got.
+     *
+     * Nothing is pinned when nothing is believed, and the bind then resolves as it
+     * always has. When something IS pinned, the declaration and the bind are that
+     * one value — which is what makes a row rewritten in between unable to move
+     * the bind under a handshake that has already agreed.
+     */
+    private pinOpenAttemptFormat;
+    /**
+     * The format the ORM binds this document on (#3764, D8).
+     *
+     * The attempt's pinned answer when an open is in flight — never a second
+     * resolution, which is what let a row rewritten mid-open move the bind under a
+     * handshake that had already agreed. With no attempt (a rebind outside an
+     * open) the ordinary resolution stands.
+     */
+    private boundDocumentFormat;
+    /**
+     * The format this client DECLARES for a document on `syncStep1` (#3764).
+     *
+     * The attempt's pinned answer while an open is in flight, else what the local
+     * metadata row says. `undefined` — a first open of somebody else's document,
+     * or one whose row an eviction removed — declares nothing, and such a client
+     * is served exactly as it was before this field existed (criterion 3).
+     */
+    private declaredDocumentFormat;
+    /**
+     * Whether the platform has refused this document on this connection (#3764).
+     *
+     * The recorded belief is re-read before the mark is: behavior 17's rule is
+     * that the mark clears when the row's format changes, and a row is written
+     * from more places than the format resolver's own `remember` — a listing
+     * upgrades it, and so does the canonical read an open performs. Asking here
+     * means no write site has to remember, and the answer cannot drift from what
+     * the next handshake would declare.
+     */
+    private formatRefusalFor;
+    /**
+     * Reject an open whose document the platform refused while it ran (#3764).
+     *
+     * A cached open resolves without a waiter, so a refusal landing while it is
+     * still binding the ORM has nothing to fail. Checked after the bind and
+     * before the handle is returned, the open rejects with the typed error
+     * instead of handing back a document whose sync and persistence the
+     * refusal's teardown has detached. A mark that stood before the open began
+     * never gets here: the open refuses it on entry.
+     */
+    private rejectIfRefusedDuringOpen;
+    /** Drop a format refusal, naming why it no longer applies (#3764). */
+    private clearFormatRefusal;
+    /**
+     * A document's locally recorded format changed, so the belief that was
+     * refused is no longer the one this client holds (#3764, behavior 17).
+     *
+     * Only a change AWAY from the refused declaration clears the mark: a row that
+     * still says the refused thing would only be refused again.
+     */
+    private noteDocumentFormatChanged;
+    /**
+     * Refuse ONE document because the platform and this client disagree about its
+     * format — #3764, decision D7.
+     *
+     * A document-scoped teardown rather than a waiter failer, and that is the
+     * whole finding: of the three shapes an open takes, only a network wait has a
+     * waiter. A cached open sends its `syncStep1` from a microtask with nothing
+     * waiting, and an already-open document re-syncs on reconnect — so an
+     * event-only answer would leave both bound and syncing against a document the
+     * platform is refusing to serve them.
+     *
+     * What it does NOT do: close the connection (D1 — one document is refused,
+     * and the socket's other documents are none of its business) and clear any
+     * local data (the rows and `_pending_ops` are kept, so a corrected open
+     * publishes what this client wrote).
+     */
+    private refuseDocumentFormat;
     /**
      * Hold every open large document's queued writes until its own handshake on
      * this connection has been answered (#3435).