@abloatai/ablo 0.26.0 → 0.28.0

package/dist/cli.cjs

@@ -215687,9 +215687,9 @@ var require_braces = __commonJS({
   }
 });
 
-// node_modules/picomatch/lib/constants.js
+// node_modules/micromatch/node_modules/picomatch/lib/constants.js
 var require_constants2 = __commonJS({
-  "node_modules/picomatch/lib/constants.js"(exports2, module2) {
+  "node_modules/micromatch/node_modules/picomatch/lib/constants.js"(exports2, module2) {
     "use strict";
     init_cjs_shims();
     var path = require("path");
@@ -215889,9 +215889,9 @@ var require_constants2 = __commonJS({
   }
 });
 
-// node_modules/picomatch/lib/utils.js
+// node_modules/micromatch/node_modules/picomatch/lib/utils.js
 var require_utils2 = __commonJS({
-  "node_modules/picomatch/lib/utils.js"(exports2) {
+  "node_modules/micromatch/node_modules/picomatch/lib/utils.js"(exports2) {
     "use strict";
     init_cjs_shims();
     var path = require("path");
@@ -215951,9 +215951,9 @@ var require_utils2 = __commonJS({
   }
 });
 
-// node_modules/picomatch/lib/scan.js
+// node_modules/micromatch/node_modules/picomatch/lib/scan.js
 var require_scan = __commonJS({
-  "node_modules/picomatch/lib/scan.js"(exports2, module2) {
+  "node_modules/micromatch/node_modules/picomatch/lib/scan.js"(exports2, module2) {
     "use strict";
     init_cjs_shims();
     var utils = require_utils2();
@@ -216282,9 +216282,9 @@ var require_scan = __commonJS({
   }
 });
 
-// node_modules/picomatch/lib/parse.js
+// node_modules/micromatch/node_modules/picomatch/lib/parse.js
 var require_parse2 = __commonJS({
-  "node_modules/picomatch/lib/parse.js"(exports2, module2) {
+  "node_modules/micromatch/node_modules/picomatch/lib/parse.js"(exports2, module2) {
     "use strict";
     init_cjs_shims();
     var constants = require_constants2();
@@ -217285,9 +217285,9 @@ var require_parse2 = __commonJS({
   }
 });
 
-// node_modules/picomatch/lib/picomatch.js
+// node_modules/micromatch/node_modules/picomatch/lib/picomatch.js
 var require_picomatch = __commonJS({
-  "node_modules/picomatch/lib/picomatch.js"(exports2, module2) {
+  "node_modules/micromatch/node_modules/picomatch/lib/picomatch.js"(exports2, module2) {
     "use strict";
     init_cjs_shims();
     var path = require("path");
@@ -217427,9 +217427,9 @@ var require_picomatch = __commonJS({
   }
 });
 
-// node_modules/picomatch/index.js
+// node_modules/micromatch/node_modules/picomatch/index.js
 var require_picomatch2 = __commonJS({
-  "node_modules/picomatch/index.js"(exports2, module2) {
+  "node_modules/micromatch/node_modules/picomatch/index.js"(exports2, module2) {
     "use strict";
     init_cjs_shims();
     module2.exports = require_picomatch();
@@ -276772,12 +276772,12 @@ var ERROR_CODES = {
   // ── auth (401) ─────────────────────────────────────────────────────
   apikey_invalid: wire("auth", 401, false, "This API key isn't one Ablo recognizes \u2014 it may be mistyped, truncated, or belong to a different environment. Check the key and try again."),
   apikey_revoked: wire("auth", 401, false, "This API key has been revoked and can no longer be used. Mint a new key from the dashboard."),
-  // THE sync-engine access credential — the Stripe-style ephemeral key
-  // (`ek_` for users, `rk_` for agents) minted server-side from the login and
-  // presented as a Bearer. Its expiry is routine and re-mintable: get a fresh
-  // key from the still-valid session and retry — NEVER a sign-out. (An agent's
-  // expired `rk_` must not log a human out either.) This is the ONLY code on
-  // the silent re-mint path; see RecoveryClass `access_credential_expiry`.
+  // The short-lived access credential — the ephemeral key (`ek_` for users,
+  // `rk_` for agents) minted from the login and presented as a bearer token.
+  // Its expiry is routine and re-mintable: get a fresh key from the still-valid
+  // session and retry, rather than signing out. An agent's expired `rk_` must
+  // not sign a human out either. This is the one code on the silent re-mint
+  // path; see the `access_credential_expiry` recovery class.
   apikey_expired: wire("auth", 401, false, "This ephemeral API key has expired. Mint a fresh key from your still-valid session and retry the request.", "access_credential_expiry"),
   apikey_missing: wire("auth", 401, false, "The request arrived without an API key. Send one as `Authorization: Bearer <key>`."),
   api_key_required: wire("auth", 401, false, "This operation requires an API key, and none was presented. Send one as `Authorization: Bearer <key>`."),
@@ -276786,25 +276786,25 @@ var ERROR_CODES = {
   identity_resolve_failed: wire("auth", 401, false, "The server could not resolve an identity for this credential \u2014 the identity lookup was rejected. Check that the credential is still valid."),
   auth_no_credentials: wire("auth", 401, false, "No recognized authentication credential was presented \u2014 no API key and no bearer JWT. Send `Authorization: Bearer <token>`."),
   identity_missing_organization: wire("auth", 401, false, "Authentication succeeded, but the credential resolves to no organization, so requests cannot be scoped. Check that the key or token carries an organization."),
-  // The long-lived login is gone — terminal, drives sign-out + re-auth.
+  // The long-lived login is gone; this is terminal and drives sign-out and
+  // re-authentication.
   session_expired: wire("auth", 401, false, "Your session has expired or is no longer valid. Sign in again to continue.", "session_expiry"),
-  // `jwt_invalid` is the residual fallback; the codes below split out the
-  // specific failure modes so an integrating customer can tell "I registered
-  // the wrong JWKS" from "my token has no org claim" from "wrong audience"
-  // rather than getting one opaque code for all of them.
+  // `jwt_invalid` is the general fallback; the codes below it split out specific
+  // failure modes, so an integrator can tell a wrong JWKS registration from a
+  // token with no organization claim from a wrong audience, instead of getting
+  // one opaque code for all of them.
   jwt_invalid: wire("auth", 401, false, "The bearer JWT failed validation for a reason the server could not classify further. Check the token's issuer, signature, audience, and expiry."),
   jwt_malformed: wire("auth", 401, false, "The bearer token is not a well-formed JWT and could not be decoded. Check that the full, unmodified token was sent."),
   jwt_missing_issuer: wire("auth", 401, false, "The bearer JWT has no `iss` (issuer) claim, so it cannot be routed to a trusted issuer."),
-  jwt_issuer_untrusted: wire("auth", 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Register it via POST /v1/trusted-issuers, or check the token's issuer claim."),
+  jwt_issuer_untrusted: wire("auth", 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Check the token's issuer claim, or register the issuer with your deployment before retrying."),
   jwt_signature_invalid: wire("auth", 401, false, "The bearer JWT's signature could not be verified against the issuer's JWKS (wrong key, rotated key, or forged token)."),
   jwt_audience_mismatch: wire("auth", 401, false, "The bearer JWT's `aud` (audience) claim does not match the audience this issuer is registered with."),
   jwt_missing_subject: wire("auth", 401, false, "The bearer JWT has no `sub` (subject) claim to identify the user."),
   jwt_missing_organization: wire("auth", 401, false, "The bearer JWT carries no organization context \u2014 neither a fixed org for the issuer nor the configured organization claim."),
-  // Trusted-issuer / BYO-IdP path only — Ablo's own sync-engine no longer
-  // authenticates with JWTs (it uses the Stripe-style ephemeral key, below).
-  // When a customer DOES present an external-IdP JWT, its expiry means
-  // re-authenticate against that IdP, so it classifies as a session expiry
-  // (which also keeps `isSessionErrorResponse` behaviour unchanged).
+  // Applies only to the trusted-issuer path, where a customer authenticates with
+  // a JWT from their own identity provider. When such a token expires, the
+  // remedy is to re-authenticate against that provider, so it classifies as a
+  // session expiry.
   jwt_expired: wire("auth", 401, false, "The bearer JWT has expired. Obtain a fresh token from your identity provider and retry.", "session_expiry"),
   jwt_org_membership_denied: wire("auth", 403, false, "The bearer JWT's subject is not an active member of the organization in its `org_id` claim (removed, suspended, or the claim does not match a membership)."),
   file_upload_auth_required: wire("auth", 401, false, "File uploads require an authenticated session. Sign in and retry."),
@@ -276823,22 +276823,18 @@ var ERROR_CODES = {
   database_role_unreadable: wire("permission", 403, false, "Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced."),
   database_tables_unforced_rls: wire("permission", 403, false, "Some synced tables do not have `FORCE ROW LEVEL SECURITY` applied, so the table owner can bypass row isolation. Run `ALTER TABLE ... FORCE ROW LEVEL SECURITY` on each synced table."),
   database_host_not_allowed: wire("permission", 403, false, "The database host resolves to a private, loopback, or link-local address, which Ablo's servers will not connect to. Use a publicly resolvable host."),
-  // Deprecated spellings of the `database_*` codes above — still emitted by
-  // older servers; kept so they classify identically. Do not use in new code.
+  // Older spellings of the `database_*` codes above, still sent by some servers
+  // and kept so they classify identically. Prefer the `database_*` codes.
   byo_role_cannot_enforce_rls: wire("permission", 403, false, "The direct Postgres connector role cannot enforce row-level security."),
   byo_role_unreadable: wire("permission", 403, false, "The direct Postgres connector role could not be introspected."),
   byo_tenant_tables_unforced_rls: wire("permission", 403, false, "Tenant tables do not have RLS forced under the direct Postgres connector role."),
   byo_host_not_allowed: wire("permission", 403, false, "The direct Postgres connector host resolves to a private, loopback, or link-local address and cannot be used."),
   // ── claim / claim conflict (409) ──────────────────────────────────
-  // Held-claim rejections are NOT queue-retryable (gRPC FAILED_PRECONDITION /
-  // ABORTED semantics; Replicache/Zero SETTLE a rejected mutation — reject the
-  // caller, roll back the optimistic effect — instead of resending it).
-  // Blindly re-sending the same payload cannot succeed while the lease is
-  // held, and a lease can outlive any sane retry budget. The correct recovery
-  // lives at the CALLER: take a claim (`ablo.<model>.claim` queues fairly
-  // behind the holder) or re-read and rebase. `retryable: true` here turned
-  // every cross-client claim conflict into an infinite client resend loop
-  // (~150ms storm — found by the claims journey, 2026-06-10).
+  // A rejection because another participant holds a claim is not retryable.
+  // Re-sending the same write cannot succeed while the claim is held, and a
+  // claim can outlive any reasonable retry budget, so an automatic retry would
+  // only loop. Recovery belongs to the caller: take a claim, which queues fairly
+  // behind the holder (`ablo.<model>.claim`), or re-read and rebase.
   claim_conflict: wire("claim", 409, false, "Another participant holds a claim on this row, so the write was rejected. Take a claim with `ablo.<model>.claim` to queue fairly behind the holder, or re-read and rebase."),
   claim_lost: wire("claim", 409, false, "The claim held on this row was lost before the write could apply. Re-acquire the claim and retry."),
   entity_claimed: wire("claim", 409, false, "This row is currently claimed by another participant, so the write was blocked. Queue behind the holder with `ablo.<model>.claim`, or wait for the claim to clear."),
@@ -276849,11 +276845,15 @@ var ERROR_CODES = {
   model_claim_not_configured: client("claim", "Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically \u2014 there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path)."),
   model_watch_not_configured: client("claim", "watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport)."),
   // ── stale context / idempotency (409) ──────────────────────────────
-  stale_context: wire("conflict", 409, true, "The row changed after you read it \u2014 the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
+  // Not retryable at the transport: the rejected request carries its frozen
+  // `readAt`, so resending the identical payload can never succeed. Recovery
+  // is a caller-level re-read that produces a NEW request with a fresh
+  // watermark — the same shape as `claim_conflict`.
+  stale_context: wire("conflict", 409, false, "The row changed after you read it \u2014 the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
   // Raised by the functional `update(id, current => next)` form once its
-  // internal reconcile budget is exhausted — the row stayed continuously
-  // contended. Client-side: the SDK already retried; the caller decides whether
-  // to back off, raise `retries`, or move the row to the WebSocket transport.
+  // internal reconcile budget is exhausted, because the row stayed continuously
+  // contended. The SDK has already retried; the caller decides whether to back
+  // off, raise `retries`, or move the row to the WebSocket transport.
   contention_exhausted: client("conflict", "A functional update kept losing to concurrent writes and exhausted its reconcile budget. Back off and retry, raise `retries`, or move the row to the WebSocket transport."),
   update_aborted: client("conflict", "The functional update was aborted via its `AbortSignal` before the write landed; nothing was written."),
   idempotency_conflict: wire("conflict", 409, false, "This `Idempotency-Key` was already used with a different request body. Reuse a key only to retry an identical request; otherwise generate a new one."),
@@ -276862,21 +276862,20 @@ var ERROR_CODES = {
   write_options_invalid: client("validation", "The write options (`idempotencyKey` / `label` / `wait` / `readAt` / `onStale` / `claim`) failed validation against the write-options schema."),
   source_operation_id_required: client("validation", "A data-source operation arrived without the entity `id` it targets."),
   source_adapter_misconfigured: client("validation", "The data-source ORM adapter could not map a schema model onto the backing client \u2014 the client exposes no matching delegate or model. Check that the adapter and schema agree on model names."),
-  // Wire since 2026-07-01: the sync-server validates every pushed/polled
-  // source event before appending to the log and rejects the whole batch
-  // with this code (`param` names the offending index + field path, e.g.
-  // `events[3].entityId`). Also raised client-side by
-  // `sourceEventForOperation` when an outbox event cannot be built.
+  // The server validates every incoming data-source event before appending it
+  // to the log and rejects the whole batch with this code; `param` names the
+  // offending index and field path, such as `events[3].entityId`. It is also
+  // raised on the client when an outbound source event cannot be built.
   source_event_invalid: wire("validation", 400, false, "A data-source event was malformed \u2014 missing or invalid id, model, entityId, type, or field value. The whole event batch was rejected and nothing was ingested; fix the offending outbox row and re-send."),
   duration_invalid: client("validation", 'A duration value was not a number of seconds or a "500ms" | "30s" | "3m" | "24h" string.'),
   schema_definition_invalid: client("validation", "A schema definition value was invalid (bad column identifier, non-finite backfill, or unsupported schema-JSON version)."),
   cli_invalid_arguments: client("validation", "The CLI was invoked with an unknown flag or a malformed flag value."),
   turn_validation_failed: wire("validation", 422, false, "The agent turn payload failed server-side validation and was not applied."),
   commit_operation_required: wire("validation", 400, false, "A commit must carry `operation` or `operations`."),
-  // Wire since 2026-07-01: both commit transports (WS `commit` frame and HTTP
-  // `/v1/commits`) validate every operation against `commitOperationSchema`
-  // (`wire/frames.ts`) and reject the whole batch with this code. `param`
-  // names the offending index + field path (e.g. `operations[3].readAt`).
+  // Both commit transports — the WebSocket `commit` frame and the HTTP
+  // `/v1/commits` endpoint — validate every operation and reject the whole batch
+  // with this code. `param` names the offending index and field path, such as
+  // `operations[3].readAt`.
   commit_operation_invalid: wire("validation", 400, false, "A commit operation failed validation against the wire commit-operation schema \u2014 wrong field type (e.g. a string `readAt`), unknown `type`, or missing `model`. The whole batch was rejected; the error names the offending operation index and field path."),
   commit_operation_model_required: wire("validation", 400, false, "A commit operation is missing its `model`."),
   commit_operations_ambiguous: wire("validation", 400, false, "A commit supplied both `operation` and `operations`. Send one or the other, not both."),
@@ -276893,13 +276892,12 @@ var ERROR_CODES = {
   model_not_found: wire("not_found", 404, false, "No row of this model exists with the requested id. It may have been deleted, or the id may belong to a different environment."),
   mutate_update_entity_not_found: wire("not_found", 404, false, "The row targeted by this update does not exist \u2014 it may have been deleted since you read it. Re-read before retrying."),
   task_id_missing: wire("server", 502, true, "The task-create response arrived without a task id, so the result cannot be used. Retry the request."),
-  // ── data integrity / DB constraints ────────────────────────────────
-  // Emitted when a write is rejected by a database integrity constraint
-  // (Postgres class-23). All NON-retryable: the same payload re-sent
-  // unchanged will fail identically, so the client must roll back, not
-  // retry. The server normalizer maps SQLSTATE → these codes and tucks the
-  // raw constraint/column/table detail into `details` rather than leaking
-  // the driver's message text onto the wire.
+  // ── data integrity / database constraints ──────────────────────────
+  // Emitted when a database integrity constraint rejects a write. None are
+  // retryable: the same payload re-sent unchanged fails identically, so the
+  // client must roll back rather than retry. The server maps the underlying SQL
+  // constraint to one of these codes and places the raw constraint, column, and
+  // table detail in `details` instead of exposing the driver's message text.
   not_null_violation: wire("validation", 400, false, "The database rejected the write because a required column was left empty \u2014 a not-null constraint. The error details name the column; supply a value and retry."),
   foreign_key_violation: wire("conflict", 409, false, "The database rejected the write on a foreign-key constraint: a referenced row does not exist, or the row being deleted is still referenced by others. The error details name the constraint."),
   unique_violation: wire("conflict", 409, false, "The write duplicates a value that must be unique \u2014 another row already holds it. Choose a different value, or update the existing row."),
@@ -276963,17 +276961,18 @@ var ERROR_CODES = {
   // ── quota / rate limit (429) ──────────────────────────────────────
   quota_exceeded: wire("rate_limit", 429, true, "Your organization has used up its configured usage quota. Requests will succeed again once the quota resets or the limit is raised."),
   connection_limit_exceeded: wire("rate_limit", 429, true, "Too many concurrent WebSocket connections for this principal or organization. Close idle connections, or retry once others drain."),
-  // Per-CREDENTIAL request-rate limit — the fast (RPS/burst) axis, distinct from
-  // the slow-axis `quota_exceeded` (org daily/monthly usage). Keyed per API key,
-  // so one noisy key backs off without affecting the rest of the org. The
-  // `Retry-After` header carries the bucket-refill delay.
+  // A per-key request-rate limit — the fast, requests-per-second axis, as
+  // opposed to `quota_exceeded`, which is the slower organization-wide usage
+  // limit. It is keyed per API key, so one noisy key backs off without affecting
+  // the rest of the organization. The `Retry-After` header carries the delay
+  // before the next request is allowed.
   rate_limit_exceeded: wire("rate_limit", 429, true, "This API key is sending requests faster than its rate limit allows. Slow down and retry after the delay in the `Retry-After` header."),
   // ── server (5xx) ───────────────────────────────────────────────────
   internal_error: wire("server", 500, true, "Something went wrong on Ablo's side \u2014 an unexpected server error. It is safe to retry."),
   quota_lookup_failed: wire("server", 503, true, "The server could not load this organization's quota state, so the request was rejected rather than admitted unchecked. Retry shortly."),
-  // The per-key rate-limiter backend (Redis) was unreachable and the API is
-  // configured to FAIL CLOSED on that path, so the request was rejected rather
-  // than admitted unchecked. Retryable: the next attempt re-probes the backend.
+  // The rate-limiter backend was unreachable and this endpoint is configured to
+  // fail closed, so the request was rejected rather than admitted unchecked. It
+  // is retryable: the next attempt re-probes the backend.
   rate_limiter_unavailable: wire("server", 503, true, "The rate-limiter backend is unavailable and this endpoint is configured to fail closed; retry shortly."),
   turn_open_failed: wire("server", 500, true, "The agent turn could not be opened on the server. It is safe to retry."),
   turn_close_failed: wire("server", 500, true, "The agent turn could not be closed cleanly on the server. It is safe to retry the close."),
@@ -277016,7 +277015,7 @@ var ERROR_CODES = {
   undo_entry_invalid: client("client", "An undo entry failed inverse-op schema validation."),
   mock_mutation_failed: client("client", "A mock mutation adapter was configured to fail."),
   mock_unsupported_operation: client("client", "A mock adapter received an unsupported operation."),
-  // ── HTTP route edge codes (egress through app.onError) ─────────────
+  // ── HTTP route edge codes ──────────────────────────────────────────
   invalid_body: wire("validation", 400, false, "The request body was missing, unparseable, or the wrong shape."),
   invalid_json: wire("validation", 400, false, "The request body was not valid JSON."),
   capability_id_required: wire("validation", 400, false, "A capability id is required for this request."),
@@ -277051,6 +277050,7 @@ var ERROR_CODES = {
   protocol_version_unsupported: wire("transport", 426, false, "The client sync-protocol version is outside the range this server supports \u2014 upgrade the SDK (or the server was rolled back mid-fleet)."),
   database_unreachable: wire("validation", 400, false, "Ablo could not reach this database to check that it can stream replication. The connection string may be wrong, the host may not be reachable from Ablo's servers, or the credentials may not be accepted."),
   database_not_replication_ready: wire("validation", 400, false, "This database is not set up for logical replication yet. Every failing item \u2014 wal_level, the publication, the replication grant, a replica identity \u2014 is listed in the error details with its exact fix. `ablo connect` prints the one-time setup; `ablo connect --check` verifies it."),
+  replication_publication_drift: wire("validation", 400, false, "Your schema maps to tables that are not members of the replication publication, so their changes silently never stream and the source looks frozen. The missing tables and the exact `ALTER PUBLICATION \u2026 ADD TABLE \u2026` to add them are in the error details \u2014 Ablo never alters your database for you."),
   query_unknown_relation: wire("validation", 400, false, "The query references a relation the model does not define. Check the relation name against the schema."),
   query_relation_target_unknown: wire("schema", 500, false, "A relation in the query targets a model the schema does not define."),
   query_invalid_identifier: wire("validation", 400, false, "The query contained an invalid identifier."),
@@ -277159,7 +277159,7 @@ var writeGuardSchema = import_zod3.z.object({
   bypass: import_zod3.z.boolean().optional()
 });
 var staleNotificationSchema = import_zod3.z.object({
-  /** Stripe-style object tag — every returned object names its type. */
+  /** Names this object's type; every returned object carries such a tag. */
   object: import_zod3.z.literal("stale_notification").optional(),
   /** Model name of the conflicting row. */
   model: import_zod3.z.string(),
@@ -277179,8 +277179,8 @@ var staleNotificationSchema = import_zod3.z.object({
    */
   conflictingFields: import_zod3.z.array(import_zod3.z.string()),
   /**
-   * Post-conflict live values of `conflictingFields` — the part a plain stale
-   * error never carried. Lets the LLM self-heal without a round-trip read.
+   * The live values of `conflictingFields` after the conflict — the piece a
+   * plain stale error omits. It lets the actor reconcile without a follow-up read.
    */
   currentValues: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()),
   /** Who wrote the conflicting delta. */
@@ -277289,10 +277289,10 @@ var claimBeginPayloadSchema = targetRefSchema.extend({
   /** Hint for `expiresAt`; the server caps it. */
   estimatedMs: import_zod3.z.number().optional(),
   /**
-   * Opt into the fair wait queue: when the target is already held, the server
-   * enqueues this claim (FIFO) and replies `claim_queued` → later
-   * `claim_granted`, instead of `claim_rejected`. Clients that set this MUST
-   * handle the grant.
+   * Opt into the fair wait queue. When the target is already held, the server
+   * enqueues this claim in FIFO order and replies `claim_queued`, then
+   * `claim_granted` later, instead of `claim_rejected`. A client that sets this
+   * must be ready to handle the grant.
    */
   queue: import_zod3.z.boolean().optional()
 });
@@ -277306,6 +277306,48 @@ var claimReorderPayloadSchema = import_zod3.z.object({
   entityId: import_zod3.z.string(),
   order: import_zod3.z.array(import_zod3.z.object({ heldBy: import_zod3.z.string(), claimId: import_zod3.z.string() }))
 });
+var claimHeartbeatFieldsSchema = import_zod3.z.object({
+  claimId: import_zod3.z.string().optional(),
+  entityType: import_zod3.z.string().optional(),
+  entityId: import_zod3.z.string().optional(),
+  /** Requested extension from now; the server clamps it, and an extension
+   *  never shortens a lease. */
+  ttlMs: import_zod3.z.number().positive().optional(),
+  /**
+   * Lightweight progress the beat carries along ("42/100 pages") — stored
+   * as the claim's `meta.progress` (last beat wins) and peer-visible via
+   * `claim.state` while the lease is held. This is presence, not a
+   * checkpoint: it dies with the lease. Crash-recoverable progress belongs
+   * in the data itself — write a row, and every subscriber already sees it.
+   */
+  details: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()).optional()
+});
+var claimHeartbeatPayloadSchema = claimHeartbeatFieldsSchema.refine(
+  (payload) => payload.claimId !== void 0 || payload.entityType !== void 0 && payload.entityId !== void 0,
+  {
+    message: "a heartbeat must identify its claim \u2014 pass claimId, or entityType and entityId together"
+  }
+);
+var claimHeartbeatAckPayloadSchema = import_zod3.z.object({
+  claimId: import_zod3.z.string(),
+  status: import_zod3.z.enum(["held", "queued", "lost"]),
+  expiresAt: import_zod3.z.number().optional(),
+  position: import_zod3.z.number().optional(),
+  /**
+   * How many participants are waiting in line behind a held lease — the
+   * cooperative-yield pressure signal (present on `held`). A worker that can
+   * checkpoint may choose to release early when others wait. Hard
+   * cancellation needs no extra field: a preempted, expired, or revoked
+   * lease answers the next beat with `lost`.
+   */
+  queueDepth: import_zod3.z.number().optional()
+});
+var claimHeartbeatBatchPayloadSchema = claimHeartbeatFieldsSchema.pick(
+  { ttlMs: true }
+);
+var claimHeartbeatBatchAckPayloadSchema = import_zod3.z.object({
+  results: import_zod3.z.array(claimHeartbeatAckPayloadSchema)
+});
 var updateSubscriptionPayloadSchema = import_zod3.z.object({
   syncGroups: import_zod3.z.array(syncGroupInputSchema)
 });
@@ -277355,35 +277397,34 @@ var presenceUpdateFrameSchema = import_zod3.z.object({
 
 // src/errors.ts
 var AbloError = class extends Error {
-  /** Discriminator string — matches the class name. Lets consumers
-   *  switch on `e.type` without `instanceof` checks across package
-   *  boundaries (matches Stripe's `err.type` pattern). */
+  /** A discriminator string equal to the class name. Switch on `error.type` to
+   *  distinguish error kinds when `instanceof` is unreliable, such as after an
+   *  error has crossed a serialization boundary. */
   type = "AbloError";
-  /** Stable short identifier for logs + metrics, drawn from the closed
-   *  {@link ErrorCode} registry — e.g. `'apikey_invalid'`,
-   *  `'capability_scope_denied'`. Stored as a plain `string` (not
-   *  `ErrorCode`) so an older SDK still surfaces a newer server's code it
-   *  doesn't recognise yet; producers are constrained at the constructor
-   *  param instead. */
+  /** A stable, machine-readable identifier for the error, drawn from the
+   *  {@link ErrorCode} registry — for example `'apikey_invalid'` or
+   *  `'capability_scope_denied'` — suitable for logs, metrics, and `switch`
+   *  handling. It is typed as a plain `string` rather than {@link ErrorCode} so
+   *  this client can still surface a code from a newer server that it does not
+   *  yet recognize; code producers are constrained at the constructor instead. */
   code;
-  /** HTTP status code when the error originated from an HTTP response. */
+  /** HTTP status code, when the error originated from an HTTP response. */
   httpStatus;
-  /** Correlation id for ops — present when the server sent one on
-   *  `x-request-id`. Include in support tickets. */
+  /** A correlation id for tracing a request through the server, present when the
+   *  server returned one on the `x-request-id` header. Include it in support
+   *  requests. */
   requestId;
-  /** Which input caused the error — a model/field path like
-   *  `'dataroomMember.grants.subject'`. Mirrors Stripe's `error.param`;
-   *  lets tooling point at the exact offending declaration. */
+  /** The specific input that caused the error, as a model or field path such as
+   *  `'dataroomMember.grants.subject'`, so tooling can point at the exact
+   *  offending value. */
   param;
-  /** Link to the docs for this `code`. Mirrors Stripe's `error.doc_url`.
-   *  Defaults from `code` via {@link docUrlForCode} when omitted. */
+  /** A link to the documentation for this error's {@link code}. When not set
+   *  explicitly, it is derived from the code by {@link docUrlForCode}. */
   docUrl;
-  /** Domain-specific structured payload merged into the wire envelope —
-   *  e.g. a schema push's `{ warnings, unexecutable }`, a stale write's
-   *  conflicting rows. Mirrors how Stripe attaches type-specific fields
-   *  (`decline_code`, `payment_intent`) alongside the standard ones, so a
-   *  structured error keeps its detail through `toJSON` instead of being
-   *  flattened to a bare message. */
+  /** Extra structured data specific to this error, merged into the serialized
+   *  envelope — for example a schema push's `{ warnings, unexecutable }`, or the
+   *  conflicting rows of a stale write. This detail is preserved through
+   *  {@link toJSON} rather than flattened into the message. */
   details;
   constructor(message, options) {
     super(message);
@@ -277400,9 +277441,10 @@ var AbloError = class extends Error {
     }
   }
   /**
-   * Serialize to Stripe's error-object shape: `{ type, code, param, message,
-   * doc_url, request_id }`. One JSON shape across HTTP bodies, WS frames, and
-   * logs — so consumers parse Ablo errors the way they already parse Stripe's.
+   * Serializes the error to its wire shape: `{ type, code, param, message,
+   * doc_url, request_id }`, with any {@link details} merged in. This is the same
+   * JSON shape the SDK uses across HTTP bodies, WebSocket frames, and logs, so a
+   * consumer parses every Ablo error the same way.
    */
   toJSON() {
     return {
@@ -277416,12 +277458,13 @@ var AbloError = class extends Error {
     };
   }
   /**
-   * A single, leak-proof line for logs and `String(err)` / template
-   * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+   * Formats the error as a single line for logs and string interpolation:
+   * `AbloValidationError [code]: message (see docs) [request_id: …]`.
    *
-   * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
-   * makes `console.error(richError)` an unreadable wall of text. The structured
-   * payload stays available via {@link toJSON}; this is the human one-liner.
+   * It intentionally omits {@link details}, the cause, and the stack, which are
+   * what turn a logged rich error into an unreadable wall of text. The full
+   * structured payload remains available through {@link toJSON}; this is the
+   * concise human-readable form.
    */
   toString() {
     const code = this.code ? ` [${this.code}]` : "";
@@ -277462,8 +277505,8 @@ var ErrorFieldSchema = import_zod4.z.preprocess(
   import_zod4.z.union([import_zod4.z.string(), NestedErrorShapeSchema]).optional()
 ).catch(void 0);
 var ErrorBodyShapeSchema = import_zod4.z.object({
-  /** Legacy: `error` was a flat code string on older endpoints. Newer
-   *  endpoints (CommitReceipt) carry `error` as a nested object. */
+  /** The `error` field may be a flat code string, as some endpoints return,
+   *  or a nested error object, as a {@link CommitReceipt} carries. */
   error: ErrorFieldSchema,
   code: OptionalWireStringSchema,
   reason: OptionalWireStringSchema,
@@ -280310,6 +280353,12 @@ async function push(argv) {
           `  This is a ${import_picocolors3.default.bold("database privilege")} error (Postgres 42501 / row-level security), not a key scope \u2014 a different API key won't help. The role behind this org's database can't write the target. Provision a writable, RLS-scoped role with ${import_picocolors3.default.bold("npx ablo migrate")}, or check the org's database registration. See docs/plans/read-path-logical-replication-vs-hosting.md.`
         )
       );
+    } else if (code === "schema_provisioning_forbidden") {
+      console.error(
+        import_picocolors3.default.dim(
+          `  This is not a key problem \u2014 the push was authorized, but the target database refused to let the engine create tables (Postgres 42501). On the replication read path Ablo never runs DDL: register your database as a data source with ${import_picocolors3.default.bold("npx ablo connect --register")}, and pushes to that environment record the schema as metadata only \u2014 no tables are created anywhere.`
+        )
+      );
     } else if (args.apiKey != null && classifyCredentialKind(args.apiKey) === "restricted") {
       console.error(
         import_picocolors3.default.dim(
@@ -280768,6 +280817,9 @@ async function runCheck() {
   );
   process.exit(1);
 }
+function registerEndpoint(baseUrl2) {
+  return `${baseUrl2.replace(/\/+$/, "")}/api/v1/datasources`;
+}
 async function runRegister() {
   const dbUrl = requireDatabaseUrl("--register");
   const apiKey = resolveApiKey();
@@ -280792,7 +280844,7 @@ async function runRegister() {
   const apiUrl2 = (process.env.ABLO_API_URL ?? DEFAULT_URL).replace(/\/+$/, "");
   let res;
   try {
-    res = await fetch(`${apiUrl2}/v1/datasources`, {
+    res = await fetch(registerEndpoint(apiUrl2), {
       method: "POST",
       headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
       body: JSON.stringify({ connectionString: dbUrl })
@@ -281724,9 +281776,9 @@ async function status(args = []) {
       mode: mode2,
       // The locally-active project (`ablo projects use`); null = org-default.
       project: activeProject2 ?? null,
-      // The credential the CLI resolves for requests, with its provenance —
-      // 'env' | '.env.local' | '.env' | 'stored' (users debug key confusion
-      // constantly; the SOURCE is usually the answer).
+      // The credential the CLI resolves for requests, with its source —
+      // 'env' | '.env.local' | '.env' | 'stored'. Key confusion is a common
+      // source of trouble, and the source is usually the answer.
       effectiveKey: {
         prefix: effective2.key ? effective2.key.slice(0, 12) : null,
         source: effective2.source
@@ -281739,16 +281791,16 @@ async function status(args = []) {
       keyMatchesStoredActiveKey: key2.keyMatchesStoredActiveKey,
       keyMismatch: key2.keyMismatch,
       organizationId: entry?.organizationId ?? null,
-      // What `ablo push` would do right now — the one-command answer to
-      // "why did push demand a different key" (2026-06-11 live-key incident).
+      // What `ablo push` would do right now — the answer to "why did push
+      // demand a different key".
       push: {
         flow: plan2.flow,
         keyPrefix: plan2.apiKey?.slice(0, 12) ?? null,
         keySource: plan2.source
       },
-      // The schema ACTIVE on this key's plane — the typename/conflict the
-      // engine enforces, which may differ from local `schema.ts`. null = the
-      // server didn't answer (unreachable / old server / no key).
+      // The schema active for this key's environment — the typename and conflict
+      // rules the engine enforces, which may differ from your local `schema.ts`.
+      // null means the server did not answer (unreachable, too old, or no key).
       schema: pushed ? {
         active: pushed.active,
         version: pushed.version ?? null,
@@ -282633,12 +282685,12 @@ async function pull(argv) {
   );
 }
 
-// src/cli/prisma-pull.ts
+// src/cli/prismaPull.ts
 init_cjs_shims();
 var import_picocolors17 = __toESM(require_picocolors(), 1);
 var import_fs10 = require("fs");
 
-// src/cli/schema-ir.ts
+// src/cli/schemaIr.ts
 init_cjs_shims();
 function camelToSnake3(s) {
   return s.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
@@ -282708,7 +282760,7 @@ function emitSchemaSource(schema, importPath) {
   return lines.join("\n");
 }
 
-// src/cli/prisma-pull.ts
+// src/cli/prismaPull.ts
 var DEFAULT_SCHEMA = "prisma/schema.prisma";
 var DEFAULT_OUT3 = "ablo/schema.ts";
 var DEFAULT_IMPORT2 = "@abloatai/ablo/schema";
@@ -282965,7 +283017,7 @@ async function prismaPull(argv) {
   );
 }
 
-// src/cli/drizzle-pull.ts
+// src/cli/drizzlePull.ts
 init_cjs_shims();
 var import_picocolors18 = __toESM(require_picocolors(), 1);
 var import_fs11 = require("fs");