@abloatai/ablo 0.29.3 → 0.30.0

package/dist/wire/commit.js

@@ -0,0 +1,300 @@
+/**
+ * Canonical runtime contracts for commit settlement.
+ *
+ * A commit crosses several boundaries during its lifetime: the server's
+ * execution cache, the HTTP/WS receipt, and the client's acknowledgement
+ * tracker. Those boundaries intentionally have different envelopes, but they
+ * all compose the same settlement vocabulary from this module:
+ *
+ *   - `confirmed` — the authoritative change is visible at a sync watermark.
+ *   - `queued` — a connected source durably accepted the write and only its
+ *     correlated authoritative source delta (WAL for direct, endpoint event
+ *     for endpoint-only), identified by `correlationId`, may promote it.
+ *
+ * Keeping the variants discriminated here makes an impossible receipt (most
+ * importantly, `queued` without a correlation) unrepresentable at every
+ * untrusted boundary without collapsing the distinct lifecycle envelopes into
+ * one giant object.
+ */
+import { z } from 'zod';
+import { staleNotificationSchema } from '../coordination/schema.js';
+/** Matches the permanent source/idempotency-key ceiling. */
+export const COMMIT_CORRELATION_ID_MAX_LENGTH = 255;
+/** Opaque server-authored identity shared by a queued receipt and its authoritative source delta. */
+export const correlationIdSchema = z.string().min(1).max(COMMIT_CORRELATION_ID_MAX_LENGTH);
+export const commitStatusSchema = z.enum(['queued', 'confirmed']);
+const queuedSettlementShape = {
+    status: z.literal('queued'),
+    correlationId: correlationIdSchema,
+};
+const confirmedSettlementShape = {
+    status: z.literal('confirmed'),
+    correlationId: correlationIdSchema.optional(),
+};
+const queuedSettlementSchema = z.strictObject(queuedSettlementShape);
+const confirmedSettlementSchema = z.strictObject(confirmedSettlementShape);
+/** The one settlement discriminant shared by every commit boundary. */
+export const commitSettlementSchema = z.discriminatedUnion('status', [
+    queuedSettlementSchema,
+    confirmedSettlementSchema,
+]);
+const missingIdsSchema = z.array(z.string().min(1));
+const notificationsSchema = z.array(staleNotificationSchema);
+const successfulReceiptCommonShape = {
+    object: z.literal('commit_receipt'),
+    /** Optional convenience id used by some HTTP surfaces. */
+    id: z.string().min(1).optional(),
+    clientTxId: z.string().min(1),
+    serverTxId: z.string().min(1),
+    success: z.literal(true),
+    lastSyncId: z.number().int().nonnegative(),
+    ops: z.number().int().nonnegative(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+};
+const queuedCommitReceiptSchema = z
+    .object({
+    ...successfulReceiptCommonShape,
+    ...queuedSettlementShape,
+})
+    .superRefine((receipt, context) => {
+    if (receipt.lastSyncId !== 0) {
+        context.addIssue({
+            code: 'custom',
+            path: ['lastSyncId'],
+            message: 'A queued source receipt cannot claim a confirmed sync watermark',
+        });
+    }
+});
+const confirmedCommitReceiptSchema = z
+    .object({
+    ...successfulReceiptCommonShape,
+    ...confirmedSettlementShape,
+})
+    .superRefine((receipt, context) => {
+    if (receipt.correlationId && receipt.lastSyncId <= 0) {
+        context.addIssue({
+            code: 'custom',
+            path: ['lastSyncId'],
+            message: 'A source-confirmed receipt requires a positive sync watermark',
+        });
+    }
+});
+/**
+ * Successful HTTP/WS receipt. This schema is deliberately strict about the
+ * settlement discriminant. Zod's default object behavior strips additive
+ * fields, which is forward compatible without allowing server-internal
+ * recovery evidence to leak through a parsed wire receipt.
+ */
+export const commitReceiptSchema = z.discriminatedUnion('status', [
+    queuedCommitReceiptSchema,
+    confirmedCommitReceiptSchema,
+]);
+/**
+ * Compatibility decoder for pre-contract WebSocket acknowledgements. It
+ * supplies fields old servers omitted and normalizes their string sync ids,
+ * then hands the result to the exact same canonical receipt schema. It never
+ * invents a source correlation: an old/malformed queued receipt still fails
+ * closed.
+ */
+export const legacyCompatibleCommitReceiptSchema = z.preprocess((value) => {
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const receipt = value;
+    if (receipt.success !== true)
+        return value;
+    const rawLastSyncId = receipt.lastSyncId;
+    const numericLastSyncId = typeof rawLastSyncId === 'string' && rawLastSyncId.trim().length > 0
+        ? Number(rawLastSyncId)
+        : rawLastSyncId;
+    const normalizedLastSyncId = typeof numericLastSyncId === 'number' &&
+        Number.isSafeInteger(numericLastSyncId) &&
+        numericLastSyncId >= 0
+        ? numericLastSyncId
+        : undefined;
+    return {
+        ...receipt,
+        object: receipt.object ?? 'commit_receipt',
+        status: receipt.status ?? 'confirmed',
+        serverTxId: typeof receipt.serverTxId === 'string'
+            ? receipt.serverTxId
+            : String(normalizedLastSyncId ?? 0),
+        ops: typeof receipt.ops === 'number' && Number.isSafeInteger(receipt.ops) ? receipt.ops : 0,
+        lastSyncId: normalizedLastSyncId ?? 0,
+    };
+}, commitReceiptSchema);
+const requiredCapabilitySchema = z.custom((value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.scope === 'string', { message: 'requiredCapability must contain a scope' });
+const errorCodeSchema = z.custom((value) => typeof value === 'string' && value.length > 0, { message: 'commit rejection code must be a non-empty string' });
+/** The failure arm is separate: queued/confirmed always imply `success:true`. */
+export const rejectedCommitReceiptSchema = z.object({
+    object: z.literal('commit_receipt'),
+    clientTxId: z.string(),
+    serverTxId: z.string(),
+    success: z.literal(false),
+    status: z.literal('rejected'),
+    lastSyncId: z.number().int().nonnegative().optional(),
+    ops: z.number().int().nonnegative().optional(),
+    error: z.object({
+        code: errorCodeSchema,
+        message: z.string(),
+        field: z.string().optional(),
+        requiredCapability: requiredCapabilitySchema.optional(),
+    }),
+});
+export const mutationResultPayloadSchema = z.union([
+    commitReceiptSchema,
+    rejectedCommitReceiptSchema,
+]);
+export const mutationResultMessageSchema = z.object({
+    type: z.literal('mutation_result'),
+    payload: mutationResultPayloadSchema,
+});
+const confirmationTransactionIdsSchema = z
+    .array(z.string().min(1))
+    .min(1)
+    .refine((ids) => new Set(ids).size === ids.length, {
+    message: 'confirmation transaction ids must be unique',
+});
+/**
+ * Server-internal execution result persisted in `mutation_log`.
+ *
+ * `status` remains optional only for pre-settlement hosted rows. At runtime an
+ * omitted value has the established meaning `confirmed`; new source-forwarded
+ * rows must use the explicit queued arm with both public correlation and exact
+ * internal storage ids.
+ */
+const rawCommitExecutionResultSchema = z
+    .strictObject({
+    lastSyncId: z.number().int().nonnegative(),
+    firstSyncId: z.number().int().nonnegative(),
+    status: commitStatusSchema.optional(),
+    correlationId: correlationIdSchema.optional(),
+    confirmationTransactionIds: confirmationTransactionIdsSchema.optional(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+})
+    .superRefine((result, context) => {
+    const validRange = (result.firstSyncId === 0 && result.lastSyncId === 0) ||
+        (result.firstSyncId > 0 && result.firstSyncId <= result.lastSyncId);
+    if (!validRange) {
+        context.addIssue({
+            code: 'custom',
+            path: ['firstSyncId'],
+            message: 'CommitResult sync range is inconsistent',
+        });
+    }
+    if (result.status === 'queued') {
+        if (!result.correlationId) {
+            context.addIssue({
+                code: 'custom',
+                path: ['correlationId'],
+                message: 'A queued source result requires a correlationId',
+            });
+        }
+        if (!result.confirmationTransactionIds) {
+            context.addIssue({
+                code: 'custom',
+                path: ['confirmationTransactionIds'],
+                message: 'A queued source result requires durable confirmation ids',
+            });
+        }
+        if (result.firstSyncId !== 0 || result.lastSyncId !== 0) {
+            context.addIssue({
+                code: 'custom',
+                path: ['lastSyncId'],
+                message: 'A queued source result cannot claim a confirmed sync range',
+            });
+        }
+    }
+    if (result.confirmationTransactionIds && !result.correlationId) {
+        context.addIssue({
+            code: 'custom',
+            path: ['correlationId'],
+            message: 'Confirmation transaction ids require their source correlation',
+        });
+    }
+    if (result.correlationId && !result.confirmationTransactionIds) {
+        context.addIssue({
+            code: 'custom',
+            path: ['confirmationTransactionIds'],
+            message: 'A source correlation requires exact confirmation transaction ids',
+        });
+    }
+    if (result.correlationId && result.status === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['status'],
+            message: 'Source-correlated results require explicit settlement status',
+        });
+    }
+    if (result.status === 'confirmed' &&
+        result.correlationId &&
+        (result.firstSyncId <= 0 || result.lastSyncId <= 0)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['lastSyncId'],
+            message: 'A source-confirmed result requires a durable positive sync range',
+        });
+    }
+});
+export const commitExecutionResultSchema = rawCommitExecutionResultSchema.transform((result) => ({
+    ...result,
+    status: result.status ?? 'confirmed',
+}));
+const ackCommonShape = {
+    lastSyncId: z.number().int().nonnegative(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+};
+/** Normalized acknowledgement handed from a mutation transport to the queue. */
+export const commitAckSchema = z.discriminatedUnion('status', [
+    z
+        .strictObject({
+        ...ackCommonShape,
+        ...queuedSettlementShape,
+    })
+        .refine(({ lastSyncId }) => lastSyncId === 0, {
+        path: ['lastSyncId'],
+        message: 'A queued acknowledgement cannot claim a sync watermark',
+    }),
+    z
+        .strictObject({
+        ...ackCommonShape,
+        ...confirmedSettlementShape,
+    })
+        .refine(({ correlationId, lastSyncId }) => correlationId === undefined || lastSyncId > 0, {
+        path: ['lastSyncId'],
+        message: 'A source-confirmed acknowledgement requires a sync watermark',
+    }),
+]);
+const legacyMutationCommitResultSchema = z.strictObject({
+    ...ackCommonShape,
+    status: z.undefined().optional(),
+    correlationId: z.undefined().optional(),
+});
+/**
+ * Compatibility boundary for injected/older mutation executors. New
+ * transports return `commitAckSchema`; a legacy `{lastSyncId}` is normalized
+ * to explicit confirmed settlement before queue code branches on it.
+ */
+export const mutationCommitResultSchema = z
+    .union([commitAckSchema, legacyMutationCommitResultSchema])
+    .transform((result) => (result.status ? result : { ...result, status: 'confirmed' }));
+/**
+ * Public SDK projection returned by `ablo.commits` and model mutations.
+ *
+ * This intentionally does not compose `commitSettlementSchema`: on the WS
+ * facade, `wait:'queued'` currently means locally sealed/enqueued, before a
+ * server has necessarily accepted the write. Renaming that public state to
+ * `enqueued` is a separate protocol change; the authoritative settlement
+ * union above is reserved for server acknowledgements.
+ */
+export const clientCommitReceiptSchema = z.strictObject({
+    id: z.string().min(1),
+    status: commitStatusSchema,
+    lastSyncId: z.number().int().nonnegative().optional(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+});

package/dist/wire/delta.d.ts

@@ -105,6 +105,7 @@ export declare const syncDeltaWireCoreSchema: z.ZodObject<{
     previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
     syncGroups: z.ZodArray<z.ZodString>;
     transactionId: z.ZodOptional<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodString;
 }, z.core.$strip>;
 export type SyncDeltaWireCore = z.infer<typeof syncDeltaWireCoreSchema>;
@@ -130,6 +131,7 @@ export declare const clientSyncDeltaSchema: z.ZodObject<{
     previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
     syncGroups: z.ZodArray<z.ZodString>;
     transactionId: z.ZodOptional<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodString;
     createdBy: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
@@ -158,7 +160,9 @@ export declare const serverSyncDeltaSchema: z.ZodObject<{
     data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
     previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
     syncGroups: z.ZodArray<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodString;
+    projectId: z.ZodString;
     transactionId: z.ZodNullable<z.ZodString>;
     createdBy: z.ZodNullable<z.ZodObject<{
         kind: z.ZodEnum<{

package/dist/wire/delta.js

@@ -24,6 +24,7 @@
  * up into the schema DSL for them.
  */
 import { z } from 'zod';
+import { correlationIdSchema } from './commit.js';
 // ── Shared participant vocabulary (mirrors the corresponding Postgres enums) ──
 /** `participant_kind` — who a delta is attributed to. */
 export const participantKindSchema = z.enum(['user', 'agent', 'system']);
@@ -78,6 +79,8 @@ export const syncDeltaWireCoreSchema = z.object({
     previousData: wireDeltaDataSchema.optional(),
     syncGroups: z.array(z.string()),
     transactionId: z.string().optional(),
+    /** Opaque source-batch identity present only on decoded customer-WAL echoes. */
+    correlationId: correlationIdSchema.optional(),
     createdAt: z.string(),
 });
 /**
@@ -99,6 +102,12 @@ export const clientSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
  * projection also narrows `transactionId` to nullable, matching the stored column.
  */
 export const serverSyncDeltaSchema = syncDeltaWireCoreSchema.extend({
+    /** The plane project the delta was committed on (`''` = the org's default
+     *  project). Server-only: the broadcaster uses it to fan a mixed-project batch
+     *  out ONLY to same-project subscribers. It rides on the frame but the client's
+     *  `clientSyncDeltaSchema` (a non-strict object) strips it — a client only ever
+     *  receives its own project's deltas, so the value is redundant to it. */
+    projectId: z.string(),
     transactionId: z.string().nullable(),
     /** @deprecated Duplicates `actor`; read `actor` instead. */
     createdBy: participantRefSchema.nullable(),

package/dist/wire/frames.d.ts

@@ -13,8 +13,8 @@
  * server to update together.
  */
 import { z } from 'zod';
-import type { OnStaleMode, StaleNotification, ReadDependency } from '../coordination/index.js';
-import type { ErrorCode, RequiredCapability } from '../errors.js';
+import type { OnStaleMode, ReadDependency } from '../coordination/index.js';
+import type { MutationResultMessageWire } from './commit.js';
 /**
  * A single operation within a {@link CommitMessage} batch. Each operation is
  * the smallest unit the server applies atomically — one create, update,
@@ -55,6 +55,15 @@ export interface CommitOperation {
      * framework identities; a bypass requested by an agent is ignored.
      */
     bypass?: boolean | null;
+    /**
+     * The monotonic fencing token of the held claim this write was issued under
+     * ({@link https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html Kleppmann fencing}).
+     * The server rejects the write if a later holder already advanced this
+     * entity's persisted high-water past the token — closing the "lapsed holder
+     * resumes after its successor came and went" residual that the live-lease
+     * claim guard cannot see. Absent on every unclaimed write.
+     */
+    fenceToken?: number | null;
 }
 /**
  * Runtime validator for {@link CommitOperation}. Both commit transports — the
@@ -83,6 +92,7 @@ export declare const commitOperationSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     bypass: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
 }, z.core.$strip>;
 /**
@@ -138,6 +148,7 @@ export declare const commitPayloadSchema: z.ZodObject<{
         id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
         transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         bypass: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, z.core.$strip>>;
     clientTxId: z.ZodString;
@@ -163,47 +174,8 @@ export declare const commitPayloadSchema: z.ZodObject<{
     }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 /**
- * The server's acknowledgement of a {@link CommitMessage}. Its payload mirrors
- * the commit-receipt shape, so a commit acknowledged over a WebSocket, over the
- * HTTP `/v1/commits` endpoint, or read back from a persisted job result all
- * carry the same fields.
- *
- * `object`, `status`, and `ops` are optional in the type but the server always
- * populates them, so a current client can rely on them being present.
+ * The server's acknowledgement of a {@link CommitMessage}. Runtime shape and
+ * TypeScript type are both owned by `wire/commit.ts`; HTTP, WebSocket, and
+ * cached replay no longer maintain parallel receipt declarations.
  */
-export interface MutationResultMessage {
-    type: 'mutation_result';
-    payload: {
-        object?: 'commit_receipt';
-        clientTxId: string;
-        serverTxId: string;
-        success: boolean;
-        status?: 'confirmed' | 'rejected';
-        lastSyncId?: number;
-        ops?: number;
-        /**
-         * Notifications for operations that used `onStale: 'notify'` and whose
-         * premise changed while the batch was being applied. Present only on a
-         * successful acknowledgement that resolved such a conflict; the client
-         * surfaces each one through its `conflict:notified` event and the commit
-         * receipt rather than failing the write.
-         */
-        notifications?: StaleNotification[];
-        /**
-         * Ids of update or delete targets that matched no rows — because they do
-         * not exist or fall outside the caller's organization. Present and
-         * non-empty only when a write missed. The client raises a not-found error
-         * for the affected caller rather than treating the no-op as a success.
-         */
-        missingIds?: string[];
-        error?: {
-            code: ErrorCode;
-            message: string;
-            field?: string;
-            /** The capability the commit required but the caller lacked. Present when
-             *  the commit was denied for want of a capability, so the client can tell
-             *  the caller exactly what to obtain. */
-            requiredCapability?: RequiredCapability;
-        };
-    };
-}
+export type MutationResultMessage = MutationResultMessageWire;

package/dist/wire/index.d.ts

@@ -25,6 +25,8 @@ export { commitOperationSchema, commitPayloadSchema, } from './frames.js';
 export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, DEFAULT_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, resolveProtocolVersion, } from './protocolVersion.js';
 export type { SupportedProtocolVersion, ProtocolVersionProblem, } from './protocolVersion.js';
 export type { CommitOperation, CommitMessage, MutationResultMessage, } from './frames.js';
+export { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, commitStatusSchema, commitSettlementSchema, commitReceiptSchema, legacyCompatibleCommitReceiptSchema, rejectedCommitReceiptSchema, mutationResultPayloadSchema, mutationResultMessageSchema, commitAckSchema, mutationCommitResultSchema, } from './commit.js';
+export type { CorrelationId, CommitStatus, CommitSettlement, CommitReceiptWire, RejectedCommitReceiptWire, MutationResultPayload, MutationResultMessageWire, CommitAck, MutationCommitResultInput, MutationCommitResult, } from './commit.js';
 export { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './delta.js';
 export type { ParticipantKind, ConfirmationState, SyncDeltaAction, WireDeltaData, ParticipantRef, SyncDeltaWireCore, ClientSyncDelta, ServerSyncDelta, } from './delta.js';
 export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, errorCodeSpec, } from '../errors.js';

package/dist/wire/index.js

@@ -27,6 +27,10 @@ export { commitOperationSchema, commitPayloadSchema, } from './frames.js';
 // confirm they can speak to each other, plus the WebSocket close code used to
 // reject a mismatch. See protocolVersion.ts for the changelog and deploy rules.
 export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, DEFAULT_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, resolveProtocolVersion, } from './protocolVersion.js';
+// Commit settlement backbone. The transport receipt, server execution cache,
+// and normalized client acknowledgement are different envelopes composed from
+// this one discriminated settlement vocabulary.
+export { COMMIT_CORRELATION_ID_MAX_LENGTH, correlationIdSchema, commitStatusSchema, commitSettlementSchema, commitReceiptSchema, legacyCompatibleCommitReceiptSchema, rejectedCommitReceiptSchema, mutationResultPayloadSchema, mutationResultMessageSchema, commitAckSchema, mutationCommitResultSchema, } from './commit.js';
 // The read-path delta contract: the shape the server broadcasts to clients as the
 // payload of a `delta` or `sync_response` frame, together with the shared
 // participant vocabulary it carries. Both ends derive their delta type from these

package/docs/agent-messaging.md

@@ -61,22 +61,21 @@ npx ablo push
 
 ## Server-side agent
 
-Most server-side agents use the direct database path. Pass the schema, API key,
-database URL, and transport selector:
+Most server-side agents use the stateless HTTP transport. Pass the schema, API
+key, and transport selector:
 
 ```ts
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
-  databaseUrl: process.env.DATABASE_URL,
   transport: "http",
 });
 
 await ablo.ready();
 ```
 
-`databaseUrl` is server-only. Browser clients must not receive it; live UIs use
-the default WebSocket transport with a minted user/session token.
+The secret `apiKey` is server-only. Browser clients must not receive it; live UIs
+use the default WebSocket transport with a minted user/session token.
 
 If your backend mints restricted agent tokens, register the database once from a
 secret-key server process as above. Workers using the restricted token can then

package/docs/agents.md

@@ -75,8 +75,7 @@ reconnects or be readable by HTTP agents. The recipe is a `messages` model
 scoped by the same syncGroup field as the work row, with `aboutIntentId` linking
 a message back to the claim it discusses.
 
-See [Agent Messaging](/agent-messaging) for the schema and direct
-`databaseUrl` setup.
+See [Agent Messaging](/agent-messaging) for the schema and setup details.
 
 ## Humans + agents on one state
 

package/docs/api-keys.md

@@ -47,7 +47,7 @@ tab-focus / network-online / device-wake). This is the Stripe ephemeral-key / Su
 session model. For a read-only app you don't need any of this — just the `pk_` above.
 
 Server-side, because `apiKey` defaults to `process.env.ABLO_API_KEY`, most backend and agent
-code passes nothing. The secret `sk_` (and `databaseUrl`) are **server-only** — never in a
+code passes nothing. The secret `sk_` is **server-only** — never in a
 browser bundle. There is no `getToken` or `as` option — `apiKey` (the key a server holds)
 and `authEndpoint` (the mint route a browser points at) are the two credential
 knobs, and you set exactly one.
@@ -58,7 +58,6 @@ knobs, and you set exactly one.
 |---|---|---|
 | Human end-user session | `await server.sessions.create({ user: { id } })` | `ek_` (full user authority) |
 | Scoped delegated agent | `await server.sessions.create({ agent: { id }, can: { Task: ['update'] } })` | `rk_` (scoped to `can`) |
-| Connect Ablo to your own Postgres | `Ablo({ schema, apiKey, databaseUrl })` (server-only) | dedicated tenant |
 
 The principal kind comes from *which* shape you pass — `{ user }` → `user`, `{ agent, can }` → `agent`.
 

package/docs/client-behavior.md

@@ -29,7 +29,6 @@ Common options:
 |---|---|
 | `schema` | Required for typed model clients. |
 | `apiKey` | Bearer credential for trusted server runtimes. Defaults to `ABLO_API_KEY` when available. |
-| `databaseUrl` | Optional, server-only. Registers your Postgres directly (the connection-string path). Pass it explicitly — it is **not** auto-read from the environment. Omit it for a signed Data Source endpoint or the hosted sandbox. The SDK throws if it sees this in a browser. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `durableWrites` | Optional crash recovery for unacknowledged agent/worker writes. Independent of the default memory cache; accepts `{ store, namespace? }`. |
@@ -39,11 +38,10 @@ Common options:
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |
 | `dangerouslyAllowBrowser` | Required before sending an API key from browser code. Prefer a server route instead. |
 
-`databaseUrl` is an optional, server-only constructor option. It is **not**
-auto-read from the environment — pass it explicitly to register your Postgres
-directly (the connection-string path). Omit it when you expose a signed
-[Data Source](./data-sources.md) endpoint, or when trying Ablo against the hosted
-sandbox.
+Your database connects out of band — through logical replication (`npx ablo
+connect`) or a signed [Data Source](./data-sources.md) endpoint — so the client
+holds only `apiKey`, never a connection string. See
+[Connect Your Database](./data-sources.md) for the full setup.
 
 ## Model Methods