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

package/README.md

@@ -1280,15 +1280,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 +1314,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

package/dist/JsBaoClient.d.ts

@@ -15,6 +15,7 @@ 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";
@@ -407,6 +408,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 +683,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 +1844,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 +2370,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;
@@ -3398,6 +3471,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 +3927,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).