@abloatai/transaction 0.46.0 → 0.48.0

package/src/resources/httpResources.ts

@@ -276,7 +276,6 @@ export interface ModelMutationOptions extends ClaimedOptions {
   readonly idempotencyKey?: string | null;
   readonly readAt?: number | null;
   readonly onStale?: OnStaleMode | null;
-  readonly wait?: CommitWait;
   readonly claim?: Claim | ClaimOptions | null;
   /** Fencing token (Option B) from the claim; server-validated at commit. */
   readonly fenceToken?: number | null;

package/src/resources/modelOperations.ts

@@ -558,15 +558,26 @@ export interface ModelRetrieveParams extends ServerRetrieveOptions {
   readonly id: string;
 }
 
+/**
+ * Options shared by schema model writes.
+ *
+ * Reactive clients apply the row change optimistically before returning from
+ * the call. The returned promise has one stable settlement contract across
+ * reactive and stateless clients: it resolves only after authoritative
+ * confirmation. Callers that need an earlier queued receipt use the lower-level
+ * `commits.create` resource instead.
+ */
+export type ModelWriteOptions = Omit<MutationOptions, 'wait'>;
+
 export interface ModelCreateParams<T, CreateInput>
-  extends MutationOptions {
+  extends ModelWriteOptions {
   readonly data: CreateInput;
   readonly id?: string | null;
   readonly claim?: Claim<T> | ClaimTargetOptions<CreateInput> | null;
 }
 
 export interface ModelUpdateParams<T, Fields = T>
-  extends MutationOptions {
+  extends ModelWriteOptions {
   readonly id: string;
   /**
    * Patch only fields declared by the model's Zod input shape. Hydrated rows
@@ -578,7 +589,7 @@ export interface ModelUpdateParams<T, Fields = T>
 }
 
 export interface ModelDeleteParams<T, Fields = T>
-  extends MutationOptions {
+  extends ModelWriteOptions {
   readonly id: string;
   readonly claim?: Claim<T> | ClaimTargetOptions<Fields> | null;
 }

package/src/schema/openapi.ts

@@ -644,7 +644,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
     '/v1/branches/{id}/status': {
       get: {
         tags: ['branches'],
-        summary: 'Diagnose one branch plane',
+        summary: 'Diagnose one branch',
         description:
           'Returns branch lifecycle, active schema, compatibility with the parent schema, safe datasource coordinates, and readiness blockers.',
         parameters: [idParam()],
@@ -699,7 +699,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         description:
           'One round trip per cadence for a worker holding many rows, instead of ' +
           'one per row. Takes only `ttl`; the leases are whichever ones your ' +
-          'credential holds on this plane.',
+          'credential holds on this branch.',
         requestBody: optionalJsonBody(derive(claimHeartbeatRequestSchema, 'input')),
         responses: {
           '200': namedResp(
@@ -812,7 +812,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         tags: ['schema'],
         summary: 'What the models look like',
         description:
-          "The schema deployed on your credential's plane: every model with its " +
+          "The schema deployed on your credential's branch: every model with its " +
           'fields, their types, and its relations. Read this when you have no ' +
           'local schema declaration to read types from — it is what makes a ' +
           'field typo a local check rather than a rejected write. Each model ' +
@@ -835,7 +835,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
           'How a caller without a socket learns what its peers did. Omit ' +
           '`after` for the most recent entries, then copy each page\'s ' +
           '`next_cursor` back as `after` to walk forward. Scope is taken from ' +
-          'your key — organization, plane and sync groups — so a caller cannot ' +
+          'your key — organization, branch and sync groups — so a caller cannot ' +
           'widen what it sees by asking.',
         parameters: queryParams(logQuerySchema),
         responses: {

package/src/source/index.ts

@@ -192,5 +192,5 @@ export {
   type FootprintArtifact,
   type FootprintKind,
   type FootprintNames,
-  type FootprintPlane,
+  type DataSourceIdentity,
 } from '../footprint.js';

package/src/source/migrations.ts

@@ -22,15 +22,28 @@ import type { Migration } from './contract.js';
  * block resolves the ledger through the search path and runs the `ALTER` only
  * when the column is absent — a true no-op on a table that already has it.
  */
-function addColumnIfAbsent(column: string, definition: string): string {
+function quoteIdent(value: string): string {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+function quoteLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function qualified(schema: string, relation: string): string {
+  return `${quoteIdent(schema)}.${quoteIdent(relation)}`;
+}
+
+function addColumnIfAbsent(schema: string, column: string, definition: string): string {
+  const ledger = qualified(schema, 'ablo_idempotency');
   return `DO $$
-DECLARE ledger regclass := to_regclass('ablo_idempotency');
+DECLARE ledger regclass := to_regclass(${quoteLiteral(ledger)});
 BEGIN
   IF ledger IS NOT NULL AND NOT EXISTS (
     SELECT 1 FROM pg_attribute
     WHERE attrelid = ledger AND attname = '${column}' AND attnum > 0 AND NOT attisdropped
   ) THEN
-    ALTER TABLE ablo_idempotency ADD COLUMN ${column} ${definition};
+    ALTER TABLE ${ledger} ADD COLUMN ${quoteIdent(column)} ${definition};
   END IF;
 END $$;`;
 }
@@ -39,11 +52,12 @@ END $$;`;
  *  rows carry a bounded `expires_at` (set by the adapter at write time) so the
  *  customer can prune them; the `infinity` column default is only a fallback for
  *  a row inserted without one. */
-export function idempotencyLedgerMigrations(): readonly Migration[] {
+export function idempotencyLedgerMigrations(schema = 'public'): readonly Migration[] {
+  const ledger = qualified(schema, 'ablo_idempotency');
   return [
     {
       name: 'ablo_idempotency',
-      up: `CREATE TABLE IF NOT EXISTS ablo_idempotency (
+      up: `CREATE TABLE IF NOT EXISTS ${ledger} (
   client_tx_id TEXT PRIMARY KEY,
   response     JSONB NOT NULL,
   request_hash TEXT,
@@ -64,11 +78,11 @@ export function idempotencyLedgerMigrations(): readonly Migration[] {
       // setup — owned by another role — the no-op still errors "must be owner".
       // Guard on the catalog (readable regardless of ownership) so the ALTER
       // runs only when the column is genuinely absent, keeping re-runs safe.
-      up: addColumnIfAbsent('request_hash', 'TEXT'),
+      up: addColumnIfAbsent(schema, 'request_hash', 'TEXT'),
     },
     {
       name: 'ablo_idempotency_permanent_retention',
-      up: addColumnIfAbsent('expires_at', `TIMESTAMPTZ NOT NULL DEFAULT 'infinity'`),
+      up: addColumnIfAbsent(schema, 'expires_at', `TIMESTAMPTZ NOT NULL DEFAULT 'infinity'`),
     },
   ];
 }

package/src/transport/httpTransport.ts

@@ -1433,7 +1433,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
         idempotencyKey: options.idempotencyKey,
         readAt: options.readAt,
         onStale: options.onStale,
-        wait: options.wait,
         claim: options.claim,
       },
       `${modelName} ${action}`
@@ -1476,7 +1475,10 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
           method,
           idempotencyKey: clientTxId,
           body: requestBody,
-          wait: options?.wait ?? 'confirmed',
+          // Model methods have one promise contract: authoritative
+          // confirmation. Early queued receipts remain available through the
+          // lower-level `commits.create` lifecycle surface.
+          wait: 'confirmed',
         },
         beforeSettlement
       );
@@ -1837,7 +1839,6 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
             mutateModel('update', name, id, patch, {
               readAt,
               onStale: 'reject',
-              wait: 'confirmed',
             }),
         });
       }
@@ -1879,13 +1880,7 @@ export function createHttpTransport(options: HttpTransportOptions): HttpTranspor
             name,
             id,
             params.data,
-            {
-              ...options,
-              // This method returns the authoritative row, not a receipt. A
-              // queued source acceptance cannot satisfy that return contract,
-              // even when the caller supplied `wait: 'queued'`.
-              wait: 'confirmed',
-            },
+            options,
             async () => {
               const read = await retrieveModel<T>(name, { id });
               if (read.data === undefined) {

package/src/transport/wsTransport.ts

@@ -70,6 +70,7 @@ import {
   noopSocketObservability,
   type SocketObservability,
 } from '../observability.js';
+import type { DeliveryPartitionRoute } from '../auth/deliveryPartition.js';
 
 /**
  * Ceiling for the exponential reconnect backoff (`reconnectDelay * 2^n`,
@@ -95,6 +96,11 @@ export interface WsTransportOptions {
    */
   userId?: string;
   organizationId?: string;
+  /**
+   * Opaque server-resolved delivery route. The transport echoes it on every
+   * WebSocket upgrade; the receiving gateway authenticates and verifies it.
+   */
+  deliveryPartition?: DeliveryPartitionRoute | null;
   lastSyncId?: number;
   syncGroups?: string[];
   capabilities?: SyncCapabilities;
@@ -450,6 +456,7 @@ export class WsTransport<
       lastSyncId: 0,
       userId: '',
       organizationId: '',
+      deliveryPartition: null,
       capabilities: {
         partialBootstrap: true,
         compressedDeltas: true,
@@ -672,6 +679,12 @@ export class WsTransport<
     this.options.syncGroups.forEach((group) => {
       params.append('syncGroups', group);
     });
+    if (this.options.deliveryPartition) {
+      params.set(
+        'deliveryPartition',
+        `${this.options.deliveryPartition.index}-${this.options.deliveryPartition.count}`,
+      );
+    }
 
     const wsUrl = `${this.options.url}?${params.toString()}`;
 
@@ -1488,4 +1501,9 @@ export class WsTransport<
   setSyncGroups(syncGroups: readonly string[]): void {
     this.options.syncGroups = [...syncGroups];
   }
+
+  /** Seeds the server-resolved route before the held first connection opens. */
+  setDeliveryPartition(deliveryPartition: DeliveryPartitionRoute | null): void {
+    this.options.deliveryPartition = deliveryPartition;
+  }
 }

package/src/wire/dataSourceResponses.ts

@@ -42,8 +42,10 @@ export const READINESS_ITEMS = [
   'wal_level',
   'publication',
   'replication_role',
+  'replication_slot_capacity',
   'replica_identity',
   'table_select',
+  'snapshot_row_security',
   'write_role',
   'row_security',
   'database_privileges',
@@ -153,6 +155,22 @@ export const datasourceValidationResponseSchema = z.object({
 });
 export type DatasourceValidationResponse = z.infer<typeof datasourceValidationResponseSchema>;
 
+/** `POST /v1/datasources/resnapshot` — accepted reset of the direct source's
+ * initial load. The replacement snapshot completes asynchronously. */
+export const datasourceResnapshotResponseSchema = z.object({
+  object: z.literal('datasource_resnapshot'),
+  initial_snapshot: z.object({ status: z.literal('loading') }),
+  replication_slot: z
+    .object({
+      slot: z.string(),
+      released: z.boolean(),
+      detail: z.string().optional(),
+      remove_with: z.string().optional(),
+    })
+    .optional(),
+});
+export type DatasourceResnapshotResponse = z.infer<typeof datasourceResnapshotResponseSchema>;
+
 /**
  * `POST /v1/datasources/locate` — which plane already holds a database.
  * A targeted lookup, not an enumeration: the caller must hold the connection
@@ -161,6 +179,8 @@ export type DatasourceValidationResponse = z.infer<typeof datasourceValidationRe
  */
 export const datasourceLocationResponseSchema = z.object({
   object: z.literal('datasource_location').optional(),
+  /** False with held=null means another organization owns the binding. */
+  available: z.boolean().optional(),
   held: z
     .object({
       project: z.string().nullable(),

package/src/wire/index.ts

@@ -315,6 +315,7 @@ export {
   datasourceListResponseSchema,
   datasourceValidationResponseSchema,
   datasourceLocationResponseSchema,
+  datasourceResnapshotResponseSchema,
   datasourceDisconnectedResponseSchema,
 } from './dataSourceResponses.js';
 export type {
@@ -326,6 +327,7 @@ export type {
   DatasourceListResponse,
   DatasourceValidationResponse,
   DatasourceLocationResponse,
+  DatasourceResnapshotResponse,
   DatasourceDisconnectedResponse,
 } from './dataSourceResponses.js';