@delali/sirannon-db 0.2.1 → 0.2.2

package/README.md

@@ -8,7 +8,7 @@
 
 Build a networked SQLite service with connection pooling, change data capture, live queries, migrations, backups, device sync, and a client SDK. Applications reach Sirannon over HTTP or WebSocket, and Sirannon nodes replicate primary-owned changes over gRPC.
 
-**Read the full documentation at [sirannon.sondelali.com/docs](https://sirannon.sondelali.com/docs).** This page gets you running, and the [guides](#documentation) hold the reference depth. Benchmarks against Postgres 17 are in [BENCHMARKS.md](../../BENCHMARKS.md).
+**Read the full documentation at [sirannon.sondelali.com/docs](https://sirannon.sondelali.com/docs).** This page gets you running, and the [guides](#documentation) hold the reference depth. The suite that measures Sirannon against Postgres 17 is a Python project under [`benchmarks/server`](../../benchmarks/server), and the write-up generator rewrites [BENCHMARKS.md](../../BENCHMARKS.md) from the latest committed run.
 
 The core engine, server, client, and primary-replica replication are stable. Coordinator-backed failover, device sync, and the Bun and Expo drivers are experimental.
 
@@ -108,6 +108,8 @@ const subscription = db
   .subscribe(event => console.log(event.type, event.table, event.row, event.oldRow, event.seq))
 ```
 
+A filter reports membership of the set it describes. An order whose `status` changes from `pending` to `shipped` arrives as an insert, because the row enters the filter, and one that changes away from `shipped` arrives as a delete carrying the old row. Read `event.type` as the row's arrival or departure, since a real insert and a row entering the filter look the same.
+
 A live query reports the current answer, updating the rows it holds from those same events:
 
 ```ts

package/dist/backup-scheduler/index.d.ts

@@ -1,5 +1,5 @@
-import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 
 declare class BackupManager {
     backup(conn: SQLiteConnection, destPath: string): Promise<void>;

package/dist/{change-tracker-DDmXB754.d.ts → change-tracker-C2Z8UbI0.d.ts}

@@ -1,5 +1,5 @@
-import { e as SQLiteConnection } from './types-rVZKnKN-.js';
-import { C as ChangeEvent } from './query-types-DL3LtPvY.js';
+import { e as SQLiteConnection } from './types-CXoPBeDM.js';
+import { C as ChangeEvent } from './query-types-BvkzxKQv.js';
 
 /**
  * How long a change tracker keeps changes, and how much it reads at a time.

package/dist/client/index.d.ts

@@ -1,15 +1,15 @@
 export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-B0np8JS3.js';
 import { C as ConflictResolver, R as ReplicationBatch } from '../types-CjhxcjhA.js';
 export { a as ConflictContext, b as ConflictResolution } from '../types-CjhxcjhA.js';
-import { C as ClientOptions, B as BulkLoadDurability } from '../server-options-Dab_Jvd_.js';
-import { D as DatabaseClient, T as Transport, L as LiveHandlers, R as RemoteSubscription, a as RemoteSubscriptionBuilder, S as SubscribeOptions, b as RegistryDigestSource } from '../client-base-CmZO0v3m.js';
-export { c as LoadAllOptions, d as RemoteDatabase, e as RemoteError, f as SQL_REFUSED_MESSAGE, g as ServerCapabilities, h as ServerCapabilityCheck } from '../client-base-CmZO0v3m.js';
+import { C as ClientOptions, B as BulkLoadDurability } from '../server-options-BVAFmguz.js';
+import { D as DatabaseClient, T as Transport, L as LiveHandlers, R as RemoteSubscription, a as RemoteSubscriptionBuilder, S as SubscribeOptions, b as RegistryDigestSource } from '../client-base-CqTMYzQP.js';
+export { c as LoadAllOptions, d as RemoteDatabase, e as RemoteError, f as SQL_REFUSED_MESSAGE, g as ServerCapabilities, h as ServerCapabilityCheck } from '../client-base-CqTMYzQP.js';
 import { a as LiveQuery, b as LiveQueryState, c as LiveUpdate } from '../types-BCejqzNA.js';
-import { e as DeviceSyncPort, D as Database } from '../database-B5Qv1-cU.js';
-import { C as ChangeEvent, P as Params, R as ReadConcern, W as WriteConcern } from '../query-types-DL3LtPvY.js';
-import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-rqANt-9Q.js';
-import '../operation-registry-hlbhqu7q.js';
-import '../types-rVZKnKN-.js';
+import { e as DeviceSyncPort, D as Database } from '../database-DvSvONb-.js';
+import { C as ChangeEvent, P as Params, R as ReadConcern, W as WriteConcern } from '../query-types-BvkzxKQv.js';
+import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-CEBVo1tO.js';
+import '../operation-registry-6qErmUT2.js';
+import '../types-CXoPBeDM.js';
 
 /**
  * @public

package/dist/client/topology.d.ts

@@ -1,11 +1,11 @@
-import { a as ReadConcernLevel } from '../query-types-DL3LtPvY.js';
-import { C as ClientOptions } from '../server-options-Dab_Jvd_.js';
-import { T as Transport, D as DatabaseClient } from '../client-base-CmZO0v3m.js';
-import '../operation-registry-hlbhqu7q.js';
+import { a as ReadConcernLevel } from '../query-types-BvkzxKQv.js';
+import { C as ClientOptions } from '../server-options-BVAFmguz.js';
+import { T as Transport, D as DatabaseClient } from '../client-base-CqTMYzQP.js';
+import '../operation-registry-6qErmUT2.js';
 import '../types-CjhxcjhA.js';
-import '../types-rVZKnKN-.js';
+import '../types-CXoPBeDM.js';
 import '../types-BCejqzNA.js';
-import '../protocol-rqANt-9Q.js';
+import '../protocol-CEBVo1tO.js';
 
 interface TopologyRouting {
     _getReadEndpoint(databaseId?: string, readConcern?: ReadConcernLevel): Promise<string>;

package/dist/{client-base-CmZO0v3m.d.ts → client-base-CqTMYzQP.d.ts}

@@ -1,8 +1,8 @@
-import { B as BulkLoadDurability, a as BulkLoadResult, C as ClientOptions } from './server-options-Dab_Jvd_.js';
+import { B as BulkLoadDurability, a as BulkLoadResult, C as ClientOptions } from './server-options-BVAFmguz.js';
 import { R as ResultOp, a as LiveQuery } from './types-BCejqzNA.js';
-import { O as OperationRef, b as OperationArguments } from './operation-registry-hlbhqu7q.js';
-import { P as Params, R as ReadConcern, W as WriteConcern, C as ChangeEvent, Q as QueryOptions } from './query-types-DL3LtPvY.js';
-import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse } from './protocol-rqANt-9Q.js';
+import { O as OperationRef, b as OperationArguments } from './operation-registry-6qErmUT2.js';
+import { P as Params, R as ReadConcern, W as WriteConcern, C as ChangeEvent, Q as QueryOptions } from './query-types-BvkzxKQv.js';
+import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse } from './protocol-CEBVo1tO.js';
 
 /**
  * Message a client raises when the server accepts no SQL over the network.
@@ -138,7 +138,16 @@ interface RemoteSubscription {
  * @public
  */
 interface RemoteSubscriptionBuilder {
-    /** Narrows the subscription to rows whose columns equal the given values. */
+    /**
+     * Narrows the subscription to rows whose columns equal the given values.
+     *
+     * The filter reports membership of the matching set, so an update that moves a row
+     * into the set arrives as an insert carrying no `oldRow`, and one that moves a row
+     * out arrives as a delete carrying the old row and an empty `row`. An update that
+     * leaves the row in the set arrives unchanged, and one that never touches the set
+     * is not delivered. A synthesised event is indistinguishable from a real insert or
+     * delete, so read `type` as the row's arrival or departure from the filter.
+     */
     filter(conditions: Record<string, unknown>): RemoteSubscriptionBuilder;
     /** Starts the subscription and calls back on each change. */
     subscribe(callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;

package/dist/codegen/index.d.ts

@@ -1,5 +1,5 @@
-import { a as OperationRegistry } from '../operation-registry-hlbhqu7q.js';
-import '../query-types-DL3LtPvY.js';
+import { a as OperationRegistry } from '../operation-registry-6qErmUT2.js';
+import '../query-types-BvkzxKQv.js';
 
 /**
  * @public

package/dist/core/index.d.ts

@@ -1,17 +1,17 @@
-import { e as SQLiteConnection, n as SynchronousLevel, a as SQLiteDriver, W as WorkerHostOptions, D as DatabaseOptions, L as LifecycleConfig, M as Migration, m as MigrationResult, R as RollbackResult } from '../types-rVZKnKN-.js';
-export { A as AfterQueryHook, o as AppliedMigration, p as AppliedMigrationEntry, f as BackupScheduleOptions, q as BatchSummary, b as BeforeConnectHook, B as BeforeQueryHook, h as BeforeSubscribeHook, l as CDCMetrics, r as ClusterReadEndpointInfo, C as ClusterStatusInfo, g as ConnectionHookContext, k as ConnectionMetrics, d as DatabaseCloseHook, c as DatabaseOpenHook, s as DriverCapabilities, t as DriverWorkerEntry, H as HookConfig, u as MIGRATION_NAME_RE, i as MetricsConfig, v as MigrationBaseline, w as MigrationSource, N as NodeHealth, x as NodeHealthReason, y as NodeHealthState, O as OpenOptions, Q as QueryHookContext, j as QueryMetrics, z as RunResult, E as SQLiteStatement, S as SirannonOptions, T as Transaction, F as WriterWorkerOptions } from '../types-rVZKnKN-.js';
-import { B as BulkLoadDurability, a as BulkLoadResult } from '../server-options-Dab_Jvd_.js';
-export { c as AuthenticateHook, b as BulkLoadOptions, C as ClientOptions, d as ClusterStatusAuthorizer, e as CorsOptions, R as ReplicationStatusInfo, f as RequestContext, g as ServerExecutionTarget, h as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-Dab_Jvd_.js';
-export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-DDmXB754.js';
-import { D as Database } from '../database-B5Qv1-cU.js';
-export { H as HookDispose, a as HookEvent, b as HookEventContextMap, c as HookHandler, d as HookRegistry, M as MetricsCollector, S as SubscribeHookContext } from '../database-B5Qv1-cU.js';
+import { e as SQLiteConnection, n as SynchronousLevel, a as SQLiteDriver, W as WorkerHostOptions, D as DatabaseOptions, L as LifecycleConfig, M as Migration, m as MigrationResult, R as RollbackResult } from '../types-CXoPBeDM.js';
+export { A as AfterQueryHook, o as AppliedMigration, p as AppliedMigrationEntry, f as BackupScheduleOptions, q as BatchSummary, b as BeforeConnectHook, B as BeforeQueryHook, h as BeforeSubscribeHook, l as CDCMetrics, r as ClusterReadEndpointInfo, C as ClusterStatusInfo, g as ConnectionHookContext, k as ConnectionMetrics, d as DatabaseCloseHook, c as DatabaseOpenHook, s as DriverCapabilities, t as DriverWorkerEntry, H as HookConfig, u as MIGRATION_NAME_RE, i as MetricsConfig, v as MigrationBaseline, w as MigrationSource, N as NodeHealth, x as NodeHealthReason, y as NodeHealthState, O as OpenOptions, Q as QueryHookContext, j as QueryMetrics, z as RunResult, E as SQLiteStatement, S as SirannonOptions, T as Transaction, F as WriterWorkerOptions } from '../types-CXoPBeDM.js';
+import { B as BulkLoadDurability, a as BulkLoadResult } from '../server-options-BVAFmguz.js';
+export { c as AuthenticateHook, b as BulkLoadOptions, C as ClientOptions, d as ClusterStatusAuthorizer, e as CorsOptions, R as ReplicationStatusInfo, f as RequestContext, g as ServerExecutionTarget, h as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-BVAFmguz.js';
+export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-C2Z8UbI0.js';
+import { D as Database } from '../database-DvSvONb-.js';
+export { H as HookDispose, a as HookEvent, b as HookEventContextMap, c as HookHandler, d as HookRegistry, M as MetricsCollector, S as SubscribeHookContext } from '../database-DvSvONb-.js';
 export { B as BackupError, C as CDCError, a as ConnectionPoolError, D as DatabaseAlreadyExistsError, b as DatabaseNotFoundError, E as ExtensionError, F as ForbiddenSqlError, H as HookDeniedError, M as MaxDatabasesError, c as MigrationError, Q as QueryError, R as ReadOnlyError, d as RequestDeniedError, S as SirannonError, T as TransactionError, W as WriteOverloadError } from '../errors-Dei4GdBb.js';
 export { a as LiveQuery, L as LiveQueryOptions, b as LiveQueryState, c as LiveUpdate, R as ResultOp } from '../types-BCejqzNA.js';
 import { B as BaselineFileOption } from '../baseline-D93hcIEE.js';
-import { P as Params, E as ExecuteResult } from '../query-types-DL3LtPvY.js';
-export { C as ChangeEvent, b as ChangeOperation, Q as QueryOptions, R as ReadConcern, a as ReadConcernLevel, c as Subscription, S as SubscriptionBuilder, W as WriteConcern, d as WriteConcernLevel } from '../query-types-DL3LtPvY.js';
-export { S as Sirannon } from '../sirannon-CMhiJa5Y.js';
-export { D as DatabaseOperations, b as OperationArguments, O as OperationRef, a as OperationRegistry, c as OperationStatement, R as ReadOperation, W as WriteOperation, o as operationName, d as operationRef } from '../operation-registry-hlbhqu7q.js';
+import { P as Params, E as ExecuteResult } from '../query-types-BvkzxKQv.js';
+export { C as ChangeEvent, b as ChangeOperation, Q as QueryOptions, R as ReadConcern, a as ReadConcernLevel, c as Subscription, S as SubscriptionBuilder, W as WriteConcern, d as WriteConcernLevel } from '../query-types-BvkzxKQv.js';
+export { S as Sirannon } from '../sirannon-DVYfrNiq.js';
+export { D as DatabaseOperations, b as OperationArguments, O as OperationRef, a as OperationRegistry, c as OperationStatement, R as ReadOperation, W as WriteOperation, o as operationName, d as operationRef } from '../operation-registry-6qErmUT2.js';
 import '../types-CjhxcjhA.js';
 
 /**

package/dist/{database-B5Qv1-cU.d.ts → database-DvSvONb-.d.ts}

@@ -1,7 +1,7 @@
-import { Q as QueryHookContext, g as ConnectionHookContext, h as BeforeSubscribeHook, H as HookConfig, i as MetricsConfig, j as QueryMetrics, k as ConnectionMetrics, l as CDCMetrics, a as SQLiteDriver, D as DatabaseOptions, T as Transaction, e as SQLiteConnection, M as Migration, m as MigrationResult, R as RollbackResult, f as BackupScheduleOptions, B as BeforeQueryHook, A as AfterQueryHook } from './types-rVZKnKN-.js';
+import { Q as QueryHookContext, g as ConnectionHookContext, h as BeforeSubscribeHook, H as HookConfig, i as MetricsConfig, j as QueryMetrics, k as ConnectionMetrics, l as CDCMetrics, a as SQLiteDriver, D as DatabaseOptions, T as Transaction, e as SQLiteConnection, M as Migration, m as MigrationResult, R as RollbackResult, f as BackupScheduleOptions, B as BeforeQueryHook, A as AfterQueryHook } from './types-CXoPBeDM.js';
 import { c as ReplicationChange, C as ConflictResolver, A as ApplyResult, R as ReplicationBatch } from './types-CjhxcjhA.js';
-import { C as ChangeEvent, P as Params, Q as QueryOptions, E as ExecuteResult, S as SubscriptionBuilder } from './query-types-DL3LtPvY.js';
-import { A as AppliedMigrationRow, b as BulkLoadOptions, a as BulkLoadResult } from './server-options-Dab_Jvd_.js';
+import { C as ChangeEvent, P as Params, Q as QueryOptions, E as ExecuteResult, S as SubscriptionBuilder } from './query-types-BvkzxKQv.js';
+import { A as AppliedMigrationRow, b as BulkLoadOptions, a as BulkLoadResult } from './server-options-BVAFmguz.js';
 import { L as LiveQueryOptions, a as LiveQuery } from './types-BCejqzNA.js';
 
 /**

package/dist/driver/better-sqlite3.d.ts

@@ -1,5 +1,5 @@
-import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import { a as SQLiteDriver } from '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 
 /**
  * @public

package/dist/driver/bun.d.ts

@@ -1,5 +1,5 @@
-import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import { a as SQLiteDriver } from '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 
 /**
  * @public

package/dist/driver/expo.d.ts

@@ -1,5 +1,5 @@
-import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import { a as SQLiteDriver } from '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 
 /**
  * @public

package/dist/driver/node.d.ts

@@ -1,5 +1,5 @@
-import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import { a as SQLiteDriver } from '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 
 /**
  * @public

package/dist/driver/wa-sqlite.d.ts

@@ -1,5 +1,5 @@
-import { a as SQLiteDriver } from '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import { a as SQLiteDriver } from '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 
 /**
  * @public

package/dist/file-migrations/index.d.ts

@@ -1,6 +1,6 @@
 import { B as BaselineFileOption } from '../baseline-D93hcIEE.js';
-import { M as Migration } from '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import { M as Migration } from '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 
 /**
  * @public

package/dist/{operation-registry-hlbhqu7q.d.ts → operation-registry-6qErmUT2.d.ts}

@@ -1,4 +1,4 @@
-import { P as Params } from './query-types-DL3LtPvY.js';
+import { P as Params } from './query-types-BvkzxKQv.js';
 
 /** One statement a registered operation runs, with its parameters bound.
  * @public

package/dist/{protocol-rqANt-9Q.d.ts → protocol-CEBVo1tO.d.ts}

@@ -1,5 +1,5 @@
-import { W as WriteConcern, R as ReadConcern, E as ExecuteResult } from './query-types-DL3LtPvY.js';
-import { B as BulkLoadDurability, a as BulkLoadResult } from './server-options-Dab_Jvd_.js';
+import { W as WriteConcern, R as ReadConcern, E as ExecuteResult } from './query-types-BvkzxKQv.js';
+import { B as BulkLoadDurability, a as BulkLoadResult } from './server-options-BVAFmguz.js';
 
 /**
  * Body of `POST /db/{id}/query`.

package/dist/{query-types-DL3LtPvY.d.ts → query-types-BvkzxKQv.d.ts}

@@ -79,7 +79,16 @@ interface ChangeEvent<T = Record<string, unknown>> {
  * @public
  */
 interface SubscriptionBuilder {
-    /** Narrows the subscription to rows whose columns equal the given values. */
+    /**
+     * Narrows the subscription to rows whose columns equal the given values.
+     *
+     * The filter reports membership of the matching set, so an update that moves a row
+     * into the set arrives as an insert carrying no `oldRow`, and one that moves a row
+     * out arrives as a delete carrying the old row and an empty `row`. An update that
+     * leaves the row in the set arrives unchanged, and one that never touches the set
+     * is not delivered. A synthesised event is indistinguishable from a real insert or
+     * delete, so read `type` as the row's arrival or departure from the filter.
+     */
     filter(conditions: Record<string, unknown>): SubscriptionBuilder;
     /** Starts the subscription and calls back on each change. */
     subscribe(callback: (event: ChangeEvent) => void): Subscription;

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 import { L as LiveQueryOptions, a as LiveQuery, b as LiveQueryState } from '../types-BCejqzNA.js';
-import { O as OperationRef } from '../operation-registry-hlbhqu7q.js';
-import { P as Params } from '../query-types-DL3LtPvY.js';
+import { O as OperationRef } from '../operation-registry-6qErmUT2.js';
+import { P as Params } from '../query-types-BvkzxKQv.js';
 
 /**
  * The one method these hooks need from a database, so both a local

package/dist/replication/index.d.ts

@@ -4,15 +4,15 @@ export { a as ConflictContext, b as ConflictResolution, c as ReplicationChange }
 import { c as ReplicationGroupState, e as CoordinatorWatchDisposer } from '../types-CMBcFPhb.js';
 export { A as AcquireControllerLeaseInput, a as AcquireControllerLeaseResult, h as AdmitNodeToInSyncSetInput, C as ClusterCoordinator, f as CompareAndAdvancePrimaryTermInput, g as CompareAndAdvancePrimaryTermResult, j as CoordinatorCompatibilityMetadata, k as CoordinatorLease, b as CoordinatorNodeSession, l as CoordinatorPrimary, P as PromoteEligibleReplicaInput, R as RegisterNodeSessionInput, d as ReplicationGroupWatcher, S as SetReplicationGroupStateInput, U as UpdateInSyncSetInput, i as UpdateNodeMaintenanceInput } from '../types-CMBcFPhb.js';
 import { EventEmitter } from 'node:events';
-import { C as ChangeTracker } from '../change-tracker-DDmXB754.js';
-import { D as Database } from '../database-B5Qv1-cU.js';
-import { e as SQLiteConnection, T as Transaction } from '../types-rVZKnKN-.js';
-import { P as Params, Q as QueryOptions, E as ExecuteResult } from '../query-types-DL3LtPvY.js';
-import { g as SyncPhase, I as InFlightBatch, P as PeerState, a as ForwardedTransactionResult, b as SyncBatch, c as SyncComplete, d as SyncAck, S as SyncRequest, h as ReplicationConfig, i as SyncState, j as ReplicationStatus, k as ReplicationErrorEvent, R as ReplicationAck, l as Topology, f as TopologyRole } from '../types-DyrCiWuc.js';
-export { F as ForwardedTransaction, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DyrCiWuc.js';
+import { C as ChangeTracker } from '../change-tracker-C2Z8UbI0.js';
+import { D as Database } from '../database-DvSvONb-.js';
+import { e as SQLiteConnection, T as Transaction } from '../types-CXoPBeDM.js';
+import { P as Params, Q as QueryOptions, E as ExecuteResult } from '../query-types-BvkzxKQv.js';
+import { g as SyncPhase, I as InFlightBatch, P as PeerState, a as ForwardedTransactionResult, b as SyncBatch, c as SyncComplete, d as SyncAck, S as SyncRequest, h as ReplicationConfig, i as SyncState, j as ReplicationStatus, k as ReplicationErrorEvent, R as ReplicationAck, l as Topology, f as TopologyRole } from '../types-DtUwSmAQ.js';
+export { F as ForwardedTransaction, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DtUwSmAQ.js';
 import { S as SirannonError } from '../errors-Dei4GdBb.js';
-import '../server-options-Dab_Jvd_.js';
-import '../operation-registry-hlbhqu7q.js';
+import '../server-options-BVAFmguz.js';
+import '../operation-registry-6qErmUT2.js';
 import '../types-BCejqzNA.js';
 
 /**

package/dist/server/index.d.ts

@@ -1,13 +1,13 @@
-import { T as TransactionStatement, Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-rqANt-9Q.js';
-export { b as BatchRequest, c as ErrorResponse, d as ExecuteRequest, e as LoadRequest, f as QueryRequest, g as TransactionRequest, t as toExecuteResponse } from '../protocol-rqANt-9Q.js';
-import { S as Sirannon } from '../sirannon-CMhiJa5Y.js';
-import { B as BulkLoadDurability, S as ServerOptions, W as WSHandlerOptions } from '../server-options-Dab_Jvd_.js';
-import { W as WriteConcern, R as ReadConcern } from '../query-types-DL3LtPvY.js';
-import '../database-B5Qv1-cU.js';
-import '../types-rVZKnKN-.js';
+import { T as TransactionStatement, Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-CEBVo1tO.js';
+export { b as BatchRequest, c as ErrorResponse, d as ExecuteRequest, e as LoadRequest, f as QueryRequest, g as TransactionRequest, t as toExecuteResponse } from '../protocol-CEBVo1tO.js';
+import { S as Sirannon } from '../sirannon-DVYfrNiq.js';
+import { B as BulkLoadDurability, S as ServerOptions, W as WSHandlerOptions } from '../server-options-BVAFmguz.js';
+import { W as WriteConcern, R as ReadConcern } from '../query-types-BvkzxKQv.js';
+import '../database-DvSvONb-.js';
+import '../types-CXoPBeDM.js';
 import '../types-CjhxcjhA.js';
 import '../types-BCejqzNA.js';
-import '../operation-registry-hlbhqu7q.js';
+import '../operation-registry-6qErmUT2.js';
 
 /**
  * Every message a client sends over the WebSocket. Each carries a `type` and a
@@ -439,6 +439,22 @@ interface WSConnection {
      * Sends one frame and reports whether it went out, was buffered, or was dropped.
      */
     send(data: string): WSSendOutcome;
+    /**
+     * Reports how many bytes the socket still holds unsent.
+     *
+     * A `buffered` outcome promises no later drain notification, because a send that
+     * queues only the tail of a frame can flush that tail without the socket ever
+     * becoming writable again. A sender that paused itself reads this to find out
+     * whether it is still waiting on anything.
+     */
+    bufferedAmount(): number;
+    /**
+     * Writes a control frame so the socket flushes what it is holding.
+     *
+     * uWebSockets keeps a partial write queued until the next write on that socket,
+     * so a sender with nothing left to send calls this to move the remainder.
+     */
+    flush(): void;
     /**
      * Closes the connection with a code and reason.
      */
@@ -457,6 +473,7 @@ declare class WSHandler<Identity = unknown> {
     private readonly connections;
     private readonly cdc;
     private readonly maxUnacknowledgedChanges;
+    private readonly socketResumeBytes;
     private readonly acceptSql;
     private readonly operations;
     private closed;

package/dist/server/index.mjs

@@ -326,7 +326,7 @@ var SQL_QUERY_CAPABILITY = "query.sql";
 function buildCapabilitiesResponse(options) {
   const capabilities = [...SERVER_CAPABILITIES];
   if (options?.registryDigest !== void 0) capabilities.push(NAMED_QUERY_CAPABILITY);
-  if (options?.acceptSql !== false) capabilities.push(SQL_QUERY_CAPABILITY);
+  if (options?.acceptSql === true) capabilities.push(SQL_QUERY_CAPABILITY);
   const response = { capabilities };
   if (options?.registryDigest !== void 0) response.registry = { digest: options.registryDigest };
   return response;
@@ -1594,7 +1594,8 @@ function worstOutcome(a, b) {
 
 // src/server/ws-device-stream.ts
 var DEFAULT_MAX_UNACKNOWLEDGED_CHANGES = 1e3;
-var CATCHUP_READ_BATCH = 1e3;
+var MAX_CATCHUP_READ_BATCH = 1e3;
+var MIN_CATCHUP_READ_BATCH = 32;
 var DeviceChangeStream = class {
   constructor(deps, baselineSeq, startMode) {
     this.deps = deps;
@@ -1614,8 +1615,11 @@ var DeviceChangeStream = class {
   lastQueuedTxId;
   midTransaction = false;
   draining = false;
+  wakeRequested = false;
   socketWait = false;
   halted = false;
+  lastBuffered = 0;
+  catchupBatch = MAX_CATCHUP_READ_BATCH;
   get deviceId() {
     return this.deps.deviceId;
   }
@@ -1627,7 +1631,7 @@ var DeviceChangeStream = class {
   }
   start() {
     if (this.mode === "catchup") {
-      void this.drain();
+      this.requestDrain();
     }
   }
   receiveLive(event) {
@@ -1635,7 +1639,12 @@ var DeviceChangeStream = class {
     this.ensureGrouper().receive(event);
   }
   onBatchEnd(atTxBoundary) {
-    if (this.halted || this.mode !== "live") return;
+    if (this.halted) return;
+    this.nudgeStalledSocket();
+    if (this.socketWait && !this.deps.socketCongested()) {
+      this.onSocketDrain();
+    }
+    if (this.mode !== "live") return;
     if (this.grouper !== null && !this.grouper.flush(atTxBoundary)) return;
     this.settleFrame(this.deps.packer?.flush() ?? "queued");
   }
@@ -1645,14 +1654,14 @@ var DeviceChangeStream = class {
       this.ackedSeq = seq;
     }
     if (this.mode === "catchup") {
-      void this.drain();
+      this.requestDrain();
     }
   }
   onSocketDrain() {
     if (this.halted) return;
     this.socketWait = false;
     if (this.mode === "catchup") {
-      void this.drain();
+      this.requestDrain();
     }
   }
   stop() {
@@ -1660,6 +1669,23 @@ var DeviceChangeStream = class {
     this.grouper = null;
     this.deps.packer?.clear();
   }
+  /**
+   * Moves a socket that stopped writing on its own. uWebSockets holds the
+   * remainder of a partial write until the next write on that socket and
+   * reports no drain in the meantime, so a stream that has queued everything
+   * it has would leave the last changes sitting there. A small buffered count
+   * that has not moved since the previous poll is that state, and a control
+   * frame carries the remainder out. A socket holding enough to count as
+   * congested is draining under its own flow control and takes nothing extra,
+   * because another frame there would cross the backpressure limit.
+   */
+  nudgeStalledSocket() {
+    const buffered = this.deps.socketBuffered();
+    if (buffered > 0 && buffered === this.lastBuffered && !this.deps.socketCongested()) {
+      this.deps.flushSocket();
+    }
+    this.lastBuffered = buffered;
+  }
   ensureGrouper() {
     this.grouper ??= new TransactionGrouper((event) => this.deliver(event));
     return this.grouper;
@@ -1689,12 +1715,24 @@ var DeviceChangeStream = class {
     }
     this.midTransaction = event.txEnd !== true && event.txId !== void 0;
     if (outcome === "buffered") {
-      this.socketWait = true;
+      this.parkOnSocket();
       this.enterCatchup();
       return false;
     }
     return true;
   }
+  /**
+   * Waits for the socket only while it holds enough to be worth waiting for.
+   * uWebSockets reports `buffered` for a send it could not finish in one go,
+   * including one that queued a few hundred bytes of a frame it otherwise
+   * sent, and it notifies a drain only when the socket becomes writable
+   * again. A stream that parked on the outcome alone would wait on a small
+   * remainder that the next send would have flushed, and the wake-up would
+   * never come.
+   */
+  parkOnSocket() {
+    this.socketWait = this.deps.socketCongested();
+  }
   /**
    * Abandons the in-flight stream state and falls back to the change log.
    * The grouper's held event was never queued and its seq is above both
@@ -1712,12 +1750,28 @@ var DeviceChangeStream = class {
       return;
     }
     if (flushed === "buffered") {
-      this.socketWait = true;
+      this.parkOnSocket();
     }
     this.mode = "catchup";
     this.grouper = null;
     this.heldSeq = null;
     this.catchupFrom = this.processedSeq > this.highestQueuedSeq ? this.processedSeq : this.highestQueuedSeq;
+    if (!this.socketWait) {
+      this.requestDrain();
+    }
+  }
+  /**
+   * Starts the catch-up read, or records that one is owed when a read is
+   * already running. A read that hands back the stream mid-pass, because the
+   * socket reported backpressure it no longer holds, would otherwise leave
+   * the stream in catch-up with nothing scheduled to resume it.
+   */
+  requestDrain() {
+    if (this.draining) {
+      this.wakeRequested = true;
+      return;
+    }
+    void this.drain();
   }
   /**
    * A closed window stops the catch-up read only where the window may pace
@@ -1731,11 +1785,28 @@ var DeviceChangeStream = class {
     if (!this.windowClosed()) return false;
     return this.deps.pacing === "perEvent" || !this.midTransaction;
   }
+  /**
+   * Sizes the next catch-up read from what the socket accepted this time.
+   * A read that ends at a full socket discards everything past the event
+   * that stopped it, so a device on a congested link would otherwise decode
+   * the same rows on every pause. Doubling the accepted count keeps a
+   * caught-up device reading whole batches while a paced one reads close to
+   * what it can send.
+   */
+  resizeCatchupBatch(accepted) {
+    const doubled = accepted * 2;
+    if (doubled < MIN_CATCHUP_READ_BATCH) {
+      this.catchupBatch = MIN_CATCHUP_READ_BATCH;
+      return;
+    }
+    this.catchupBatch = doubled > MAX_CATCHUP_READ_BATCH ? MAX_CATCHUP_READ_BATCH : doubled;
+  }
   async drain() {
     if (this.draining || this.halted) return;
     this.draining = true;
     try {
       while (!this.halted && this.mode === "catchup") {
+        this.wakeRequested = false;
         if (this.socketWait || this.readGateClosed()) return;
         const upTo = this.deps.logCursor();
         if (this.catchupFrom >= upTo) {
@@ -1744,7 +1815,7 @@ var DeviceChangeStream = class {
         }
         let events;
         try {
-          events = await this.deps.readLog(this.catchupFrom, upTo, CATCHUP_READ_BATCH);
+          events = await this.deps.readLog(this.catchupFrom, upTo, this.catchupBatch);
         } catch (err) {
           this.halted = true;
           this.deps.onFault(err);
@@ -1757,8 +1828,11 @@ var DeviceChangeStream = class {
           return;
         }
         const grouper = this.ensureGrouper();
+        let offered = 0;
+        let stopped = false;
         for (const event of events) {
           this.catchupFrom = event.seq;
+          offered += 1;
           const delivered = this.deps.transform(event);
           if (delivered === null) {
             if (this.heldSeq === null && event.seq > this.processedSeq) {
@@ -1766,16 +1840,27 @@ var DeviceChangeStream = class {
             }
             continue;
           }
-          if (!grouper.receive(delivered)) return;
+          if (!grouper.receive(delivered)) {
+            this.resizeCatchupBatch(offered);
+            stopped = true;
+            break;
+          }
           const settledBefore = event.seq - 1n;
           if (settledBefore > this.processedSeq) {
             this.processedSeq = settledBefore;
           }
           this.heldSeq = delivered.txId === void 0 ? null : event.seq;
         }
+        if (!stopped) {
+          this.resizeCatchupBatch(this.catchupBatch);
+        }
       }
     } finally {
       this.draining = false;
+      if (this.wakeRequested) {
+        this.wakeRequested = false;
+        void this.drain();
+      }
     }
   }
   /**
@@ -1803,7 +1888,7 @@ var DeviceChangeStream = class {
       return;
     }
     if (outcome === "buffered") {
-      this.socketWait = true;
+      this.parkOnSocket();
       if (this.mode === "live") {
         this.enterCatchup();
       }
@@ -2214,6 +2299,9 @@ async function subscribeDevice(deps, conn, state, request) {
         pacing: stagedStream ? "perEvent" : "perTransaction",
         packer: stagedStream ? new DeviceFramePacker(id, (data) => deps.sendText(conn, data)) : null,
         sendEvent: (event) => deps.sendChange(conn, id, event),
+        socketBuffered: () => conn.bufferedAmount(),
+        socketCongested: () => conn.bufferedAmount() >= deps.socketResumeBytes,
+        flushSocket: () => conn.flush(),
         onOverload: () => deps.handleOverload(conn),
         onFault: () => deps.closeFaulted(conn),
         readLog: (afterSeq, upToSeq, limit) => ctx.tracker.readSinceTables(ctx.cdcConn, tables, afterSeq, upToSeq, limit),
@@ -2457,6 +2545,7 @@ async function subscribeResuming(deps, conn, state, id, table, filter, sinceSeq,
 
 // src/server/ws-handler.ts
 var DEFAULT_MAX_PAYLOAD_LENGTH = 1048576;
+var DEFAULT_MAX_BACKPRESSURE_BYTES = 16 * 1048576;
 var SQL_MESSAGE_TYPES = /* @__PURE__ */ new Set(["query", "execute", "transaction", "batch", "load"]);
 var NAMED_MESSAGE_TYPES = /* @__PURE__ */ new Set(["query", "execute", "subscribe"]);
 var WSHandler = class {
@@ -2466,6 +2555,7 @@ var WSHandler = class {
   connections = /* @__PURE__ */ new Map();
   cdc;
   maxUnacknowledgedChanges;
+  socketResumeBytes;
   acceptSql;
   operations;
   closed = false;
@@ -2475,6 +2565,7 @@ var WSHandler = class {
     this.operations = createOperationSource(options?.operations);
     this.maxPayloadLength = options?.maxPayloadLength ?? DEFAULT_MAX_PAYLOAD_LENGTH;
     this.maxUnacknowledgedChanges = options?.maxUnacknowledgedChanges ?? DEFAULT_MAX_UNACKNOWLEDGED_CHANGES;
+    this.socketResumeBytes = Math.ceil((options?.maxBackpressureBytes ?? DEFAULT_MAX_BACKPRESSURE_BYTES) / 2);
     this.resolveExecutionTarget = options?.resolveExecutionTarget;
     this.cdc = new CdcContextRegistry(sirannon, options?.cdcRetentionMs, options?.deviceCursorRetentionMs);
   }
@@ -2660,6 +2751,7 @@ var WSHandler = class {
     return {
       cdc: this.cdc,
       maxUnacknowledgedChanges: this.maxUnacknowledgedChanges,
+      socketResumeBytes: this.socketResumeBytes,
       sendSubscribed: (conn, id, seq, epoch, resync, maxUnacknowledgedChanges) => this.send(conn, {
         type: "subscribed",
         id,
@@ -2811,6 +2903,19 @@ function registerWebSocketRoute(options) {
             return "dropped";
           }
         },
+        bufferedAmount() {
+          try {
+            return ws.getBufferedAmount();
+          } catch {
+            return 0;
+          }
+        },
+        flush() {
+          try {
+            ws.ping();
+          } catch {
+          }
+        },
         close(code, reason) {
           try {
             ws.end(code, reason);
@@ -2890,6 +2995,7 @@ var SirannonServer = class {
     this.wsHandler = new WSHandler(sirannon, {
       resolveExecutionTarget: this.resolveExecutionTarget,
       maxPayloadLength: this.maxBodyBytes,
+      maxBackpressureBytes: this.maxWsBackpressureBytes,
       cdcRetentionMs: options?.cdcRetentionMs,
       deviceCursorRetentionMs: options?.deviceCursorRetentionMs,
       maxUnacknowledgedChanges: options?.maxUnacknowledgedChanges,

package/dist/{server-options-Dab_Jvd_.d.ts → server-options-BVAFmguz.d.ts}

@@ -1,7 +1,7 @@
-import { a as OperationRegistry } from './operation-registry-hlbhqu7q.js';
+import { a as OperationRegistry } from './operation-registry-6qErmUT2.js';
 import { R as ReplicationBatch, C as ConflictResolver, A as ApplyResult } from './types-CjhxcjhA.js';
-import { N as NodeHealth, T as Transaction, C as ClusterStatusInfo } from './types-rVZKnKN-.js';
-import { P as Params, Q as QueryOptions, E as ExecuteResult } from './query-types-DL3LtPvY.js';
+import { N as NodeHealth, T as Transaction, C as ClusterStatusInfo } from './types-CXoPBeDM.js';
+import { P as Params, Q as QueryOptions, E as ExecuteResult } from './query-types-BvkzxKQv.js';
 
 interface AppliedMigrationRow {
     version: number;
@@ -229,6 +229,8 @@ interface CorsOptions {
 interface WSHandlerOptions<Identity = unknown> {
     /** Maximum message size in bytes. Default: 1_048_576 (1 MB). */
     maxPayloadLength?: number;
+    /** Outbound bytes a socket may hold before a device stream pauses itself. Default: 16 MB. */
+    maxBackpressureBytes?: number;
     /** Change-log retention for CDC subscriptions in milliseconds. Default: 3_600_000. */
     cdcRetentionMs?: number;
     deviceCursorRetentionMs?: number;

package/dist/{sirannon-CMhiJa5Y.d.ts → sirannon-DVYfrNiq.d.ts}

@@ -1,5 +1,5 @@
-import { D as Database } from './database-B5Qv1-cU.js';
-import { S as SirannonOptions, a as SQLiteDriver, D as DatabaseOptions, M as Migration, B as BeforeQueryHook, A as AfterQueryHook, b as BeforeConnectHook, c as DatabaseOpenHook, d as DatabaseCloseHook } from './types-rVZKnKN-.js';
+import { D as Database } from './database-DvSvONb-.js';
+import { S as SirannonOptions, a as SQLiteDriver, D as DatabaseOptions, M as Migration, B as BeforeQueryHook, A as AfterQueryHook, b as BeforeConnectHook, c as DatabaseOpenHook, d as DatabaseCloseHook } from './types-CXoPBeDM.js';
 
 /**
  * A registry of open SQLite databases, keyed by identifier.

package/dist/transport/grpc.d.ts

@@ -1,11 +1,11 @@
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import { Client, ClientDuplexStream, CallOptions, Metadata, ServiceError, ClientUnaryCall, ChannelCredentials, ClientOptions, ServerDuplexStream, Server } from '@grpc/grpc-js';
 import { HealthImplementation } from 'grpc-health-check';
-import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, T as TransportConfig } from '../types-DyrCiWuc.js';
+import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, T as TransportConfig } from '../types-DtUwSmAQ.js';
 import { R as ReplicationBatch } from '../types-CjhxcjhA.js';
-import '../change-tracker-DDmXB754.js';
-import '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import '../change-tracker-C2Z8UbI0.js';
+import '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 import '../types-CMBcFPhb.js';
 
 interface ColumnValue {

package/dist/transport/memory.d.ts

@@ -1,8 +1,8 @@
-import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DyrCiWuc.js';
+import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DtUwSmAQ.js';
 import { R as ReplicationBatch } from '../types-CjhxcjhA.js';
-import '../change-tracker-DDmXB754.js';
-import '../types-rVZKnKN-.js';
-import '../query-types-DL3LtPvY.js';
+import '../change-tracker-C2Z8UbI0.js';
+import '../types-CXoPBeDM.js';
+import '../query-types-BvkzxKQv.js';
 import '../types-CMBcFPhb.js';
 
 type BatchHandler = (batch: ReplicationBatch, fromPeerId: string) => Promise<void>;

package/dist/{types-rVZKnKN-.d.ts → types-CXoPBeDM.d.ts}

@@ -1,4 +1,4 @@
-import { P as Params, W as WriteConcern, R as ReadConcern, b as ChangeOperation, E as ExecuteResult, a as ReadConcernLevel } from './query-types-DL3LtPvY.js';
+import { P as Params, W as WriteConcern, R as ReadConcern, b as ChangeOperation, E as ExecuteResult, a as ReadConcernLevel } from './query-types-BvkzxKQv.js';
 
 /** Context passed to query hooks.
  * @public

package/dist/{types-DyrCiWuc.d.ts → types-DtUwSmAQ.d.ts}

@@ -1,5 +1,5 @@
-import { C as ChangeTracker } from './change-tracker-DDmXB754.js';
-import { e as SQLiteConnection, N as NodeHealth } from './types-rVZKnKN-.js';
+import { C as ChangeTracker } from './change-tracker-C2Z8UbI0.js';
+import { e as SQLiteConnection, N as NodeHealth } from './types-CXoPBeDM.js';
 import { S as SyncTableManifest, R as ReplicationBatch, C as ConflictResolver } from './types-CjhxcjhA.js';
 import { C as ClusterCoordinator, j as CoordinatorCompatibilityMetadata, c as ReplicationGroupState } from './types-CMBcFPhb.js';
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@delali/sirannon-db",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "A production-grade library that turns SQLite databases into a networked data layer with real-time subscriptions.",
   "author": "Delali (https://sondelali.com)",
   "license": "Apache-2.0",