@syncular/client 0.30.16 → 0.31.0

package/README.md

@@ -404,6 +404,26 @@ current version and links the replacement through `superseded`. Edit can choose
 a free unique key. Take-server uses `resolved_keep_server`. Revocation and local
 security purge erase the retained aggregate's protected journal payloads.
 
+## Push batching limits
+
+`limits` carries three per-request push budgets:
+
+- `maxPushCommitsPerRequest`: whole commits per request. Default: unbounded.
+- `maxPushOperationsPerRequest`: operations across those commits. Default:
+  500.
+- `maxPushRequestBytes`: bytes of the complete encoded SSP2 request, including
+  the request header, pull header, subscriptions, framing, and E2EE ciphertext.
+  Default: unbounded.
+
+The client sends whole commits in FIFO order and never splits one. A later
+commit that does not fit defers with the complete suffix. A first commit over
+the operation or byte budget fails with `client.push_request_too_large`
+(non-retryable) and details `{ kind, limit, size, clientCommitId? }`; the
+commit stays queued with its optimistic rows. A request whose fixed frames
+alone exceed the byte budget reports the same code without `clientCommitId`.
+Push limits are integers in `1..=4294967295`; a JSON `null` at the native
+command boundary is treated as omitted.
+
 ## Application-authorized local security purge
 
 `purgeLocalData({ purgeId, targets })` is the narrow local-storage primitive

package/dist/client.d.ts

@@ -87,6 +87,14 @@ export interface SyncSummary {
      * queued; sync-needed stays raised and `syncUntilIdle` keeps going. */
     readonly deferredCommits?: number;
 }
+/**
+ * The result of `syncUntilIdle`. The report aggregates every round that ran;
+ * `budgetExhausted` is true when the round budget ran out with the client not
+ * idle. An exhausted run is a partial success, never idle.
+ */
+export interface SyncIdleResult extends SyncSummary {
+    readonly budgetExhausted: boolean;
+}
 export interface SyncClientLimits {
     readonly limitCommits?: number;
     readonly limitSnapshotRows?: number;
@@ -103,6 +111,22 @@ export interface SyncClientLimits {
      * deleted to satisfy this cap. Defaults to 1,000.
      */
     readonly outcomeRetentionMaxEntries?: number;
+    /** §7.1: maximum whole commits in one push request. Default: unbounded. */
+    readonly maxPushCommitsPerRequest?: number;
+    /**
+     * §7.1: maximum operations across the push commits in one request. Default
+     * 500. A first commit that alone exceeds it is a typed
+     * `client.push_request_too_large` capacity error and stays queued.
+     */
+    readonly maxPushOperationsPerRequest?: number;
+    /**
+     * §7.1: maximum bytes of the complete encoded SSP2 request (8-byte
+     * envelope, request header, push commits, pull header, subscriptions,
+     * framing, and any §5.11 ciphertext). Default: unbounded. A request whose
+     * fixed frames alone exceed it, or whose first commit alone does not fit,
+     * raises `client.push_request_too_large` and stays queued.
+     */
+    readonly maxPushRequestBytes?: number;
 }
 export interface SyncClientConfig {
     readonly transportEnabled?: boolean;
@@ -276,6 +300,69 @@ export interface QuerySnapshot<Row = SqlRow> {
     readonly rows: readonly Row[];
     readonly coverage: CoverageSnapshot;
 }
+/** §7.5: one read-only statement in an atomic snapshot read. */
+export interface SnapshotStatement {
+    readonly sql: string;
+    readonly params?: readonly SqlValue[];
+}
+/**
+ * §7.5: the catch-up state of one subscription as persisted in the snapshot,
+ * never the mutable owner cache. `unknown` means the client does not currently
+ * hold the subscription (never registered, forgotten, or removed) and carries
+ * no fabricated table or cursor.
+ */
+export type SubscriptionCatchup = {
+    readonly state: 'unknown';
+    readonly id: string;
+} | {
+    readonly state: 'known';
+    readonly id: string;
+    readonly table: string;
+    readonly status: 'active' | 'revoked' | 'failed';
+    readonly cursor: number;
+    readonly hasResumeToken: boolean;
+    /** True only for `active` with `cursor >= 0` and no resume token. */
+    readonly bootstrapComplete: boolean;
+    /** True only for `active` while a resume token remains or `cursor < 0`. */
+    readonly knownPendingPages: boolean;
+    readonly effectiveScopes?: unknown;
+    readonly reasonCode?: string;
+};
+/**
+ * §7.5: delivery status for one client commit id. `pending` while the id still
+ * has an outbox entry (outbox precedence), otherwise the persisted-journal
+ * outcome, otherwise an explicit `unknown` (never held, or pruned by
+ * retention). The outcome omits the owner-derived `retainedRows` images.
+ */
+export type CommitDelivery = {
+    readonly status: 'pending';
+    readonly clientCommitId: string;
+} | {
+    readonly status: 'known';
+    readonly clientCommitId: string;
+    readonly outcome: CommitOutcome;
+} | {
+    readonly status: 'unknown';
+    readonly clientCommitId: string;
+};
+/** §7.5: one atomic read request over a single SQLite read transaction. */
+export interface SnapshotReadRequest {
+    readonly statements: readonly SnapshotStatement[];
+    readonly coverage?: readonly WindowCoverage[];
+    readonly subscriptions?: readonly string[];
+    readonly commitIds?: readonly string[];
+    /** §7.5 owner: a failed owned read is reported in `queryFailures`. */
+    readonly owner?: QueryOwner;
+}
+/** §7.5: one atomic read result: one revision, every statement's rows, the
+ * requested coverage, catch-up states, and deliveries. */
+export interface SnapshotRead<Row = SqlRow> {
+    readonly revision: LocalRevision;
+    readonly queries: readonly (readonly Row[])[];
+    readonly coverage: CoverageSnapshot;
+    readonly subscriptions: readonly SubscriptionCatchup[];
+    readonly deliveries: readonly CommitDelivery[];
+}
 /**
  * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
  * registered and not pending. A unit with zero server rows still becomes
@@ -283,7 +370,7 @@ export interface QuerySnapshot<Row = SqlRow> {
  */
 export declare function windowComplete(state: WindowState, unit: string): boolean;
 /** Canonical client reads, shared by synchronous cores and promise hosts. */
-export type ClientSnapshotMethods = Pick<SyncClient, 'querySnapshot' | 'statusSnapshot' | 'diagnosticsSnapshot' | 'conflicts' | 'rejections' | 'commitOutcome' | 'commitOutcomes' | 'resolveCommitOutcome'>;
+export type ClientSnapshotMethods = Pick<SyncClient, 'querySnapshot' | 'snapshotRead' | 'statusSnapshot' | 'diagnosticsSnapshot' | 'conflicts' | 'rejections' | 'commitOutcome' | 'commitOutcomes' | 'resolveCommitOutcome'>;
 /** Project a method contract across an asynchronous host boundary. */
 export type PromiseMethods<Methods> = {
     [Key in keyof Methods]: Methods[Key] extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<Awaited<Result>> : never;
@@ -336,6 +423,19 @@ export declare class SyncClient {
      * `windowState()` across separate worker/IPC calls.
      */
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row>;
+    /**
+     * §7.5: resolve several read-only statements, window coverage, subscription
+     * catch-up states, and commit deliveries from one SQLite read transaction
+     * and one revision. A host that needs those together reads them together;
+     * every statement passes the read-only guard and any failure rolls the whole
+     * read back.
+     */
+    snapshotRead<Row = SqlRow>(spec: SnapshotReadRequest): SnapshotRead<Row>;
+    /** §7.5: one subscription's persisted catch-up state (never the owner cache). */
+    subscriptionCatchup(id: string): SubscriptionCatchup;
+    /** §7.5: one client commit's delivery status: pending, its retained outcome,
+     * or an explicit unknown (never held, or pruned by retention). */
+    commitDelivery(id: string): CommitDelivery;
     /**
      * RFC 0005 D7: read captured rows from the previous local schema. `state` is
      * always `'previousVersion'`; the container never makes `querySnapshot()`
@@ -540,7 +640,7 @@ export declare class SyncClient {
      * Pull repeatedly until quiescent: no commits delivered, no bootstrap
      * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
      */
-    syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
+    syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult>;
     connectRealtime(): Promise<void>;
     disconnectRealtime(): void;
 }