@abloatai/ablo 0.25.0 → 0.27.0

package/dist/cli.cjs

@@ -211978,9 +211978,9 @@ Additional information: BADCLIENT: Bad error code, ${badCode} not found in range
   }
 });
 
-// node_modules/@ts-morph/common/node_modules/balanced-match/dist/commonjs/index.js
+// node_modules/balanced-match/dist/commonjs/index.js
 var require_commonjs = __commonJS({
-  "node_modules/@ts-morph/common/node_modules/balanced-match/dist/commonjs/index.js"(exports2) {
+  "node_modules/balanced-match/dist/commonjs/index.js"(exports2) {
     "use strict";
     init_cjs_shims();
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -212041,9 +212041,9 @@ var require_commonjs = __commonJS({
   }
 });
 
-// node_modules/@ts-morph/common/node_modules/brace-expansion/dist/commonjs/index.js
+// node_modules/brace-expansion/dist/commonjs/index.js
 var require_commonjs2 = __commonJS({
-  "node_modules/@ts-morph/common/node_modules/brace-expansion/dist/commonjs/index.js"(exports2) {
+  "node_modules/brace-expansion/dist/commonjs/index.js"(exports2) {
     "use strict";
     init_cjs_shims();
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -212215,9 +212215,9 @@ var require_commonjs2 = __commonJS({
   }
 });
 
-// node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/assert-valid-pattern.js
+// node_modules/minimatch/dist/commonjs/assert-valid-pattern.js
 var require_assert_valid_pattern = __commonJS({
-  "node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/assert-valid-pattern.js"(exports2) {
+  "node_modules/minimatch/dist/commonjs/assert-valid-pattern.js"(exports2) {
     "use strict";
     init_cjs_shims();
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -212235,9 +212235,9 @@ var require_assert_valid_pattern = __commonJS({
   }
 });
 
-// node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/brace-expressions.js
+// node_modules/minimatch/dist/commonjs/brace-expressions.js
 var require_brace_expressions = __commonJS({
-  "node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/brace-expressions.js"(exports2) {
+  "node_modules/minimatch/dist/commonjs/brace-expressions.js"(exports2) {
     "use strict";
     init_cjs_shims();
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -212353,9 +212353,9 @@ var require_brace_expressions = __commonJS({
   }
 });
 
-// node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/unescape.js
+// node_modules/minimatch/dist/commonjs/unescape.js
 var require_unescape = __commonJS({
-  "node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/unescape.js"(exports2) {
+  "node_modules/minimatch/dist/commonjs/unescape.js"(exports2) {
     "use strict";
     init_cjs_shims();
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -212370,9 +212370,9 @@ var require_unescape = __commonJS({
   }
 });
 
-// node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/ast.js
+// node_modules/minimatch/dist/commonjs/ast.js
 var require_ast = __commonJS({
-  "node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/ast.js"(exports2) {
+  "node_modules/minimatch/dist/commonjs/ast.js"(exports2) {
     "use strict";
     init_cjs_shims();
     var _a;
@@ -213025,9 +213025,9 @@ var require_ast = __commonJS({
   }
 });
 
-// node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/escape.js
+// node_modules/minimatch/dist/commonjs/escape.js
 var require_escape = __commonJS({
-  "node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/escape.js"(exports2) {
+  "node_modules/minimatch/dist/commonjs/escape.js"(exports2) {
     "use strict";
     init_cjs_shims();
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -213042,9 +213042,9 @@ var require_escape = __commonJS({
   }
 });
 
-// node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/index.js
+// node_modules/minimatch/dist/commonjs/index.js
 var require_commonjs3 = __commonJS({
-  "node_modules/@ts-morph/common/node_modules/minimatch/dist/commonjs/index.js"(exports2) {
+  "node_modules/minimatch/dist/commonjs/index.js"(exports2) {
     "use strict";
     init_cjs_shims();
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -214565,9 +214565,9 @@ var require_is_glob = __commonJS({
   }
 });
 
-// node_modules/glob-parent/index.js
+// node_modules/fast-glob/node_modules/glob-parent/index.js
 var require_glob_parent = __commonJS({
-  "node_modules/glob-parent/index.js"(exports2, module2) {
+  "node_modules/fast-glob/node_modules/glob-parent/index.js"(exports2, module2) {
     "use strict";
     init_cjs_shims();
     var isGlob = require_is_glob();
@@ -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();
@@ -276770,203 +276770,208 @@ var wire = (category, httpStatus, retryable, message, recovery) => ({ category,
 var client = (category, message) => ({ category, surface: "client", retryable: false, message });
 var ERROR_CODES = {
   // ── auth (401) ─────────────────────────────────────────────────────
-  apikey_invalid: wire("auth", 401, false, "API key is unknown or malformed."),
-  apikey_revoked: wire("auth", 401, false, "API key has been revoked."),
-  // 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`.
-  apikey_expired: wire("auth", 401, false, "API key has expired.", "access_credential_expiry"),
-  apikey_missing: wire("auth", 401, false, "No API key was supplied on the request."),
-  api_key_required: wire("auth", 401, false, "This operation requires an API key."),
-  capability_id_missing: wire("auth", 401, false, "A capability id was expected but not provided."),
-  exchange_failed: wire("auth", 401, false, "The API-key credential exchange was rejected."),
-  identity_resolve_failed: wire("auth", 401, false, "Identity resolution was rejected."),
+  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 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>`."),
+  capability_id_missing: wire("auth", 401, false, "This request must name a capability id, but none was provided."),
+  exchange_failed: wire("auth", 401, false, "The API key could not be exchanged for a working credential \u2014 the exchange was rejected. Check that the key is still valid."),
+  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 resolved to no organization context."),
-  // The long-lived login is gone — terminal, drives sign-out + re-auth.
-  session_expired: wire("auth", 401, false, "The session is invalid or expired; re-authenticate.", "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: wire("auth", 401, false, "The bearer JWT could not be validated (unclassified)."),
-  jwt_malformed: wire("auth", 401, false, "The bearer JWT is not a well-formed JWT and could not be decoded."),
+  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; 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 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_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).
-  jwt_expired: wire("auth", 401, false, "The bearer JWT has expired; obtain a fresh token.", "session_expiry"),
+  // 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 upload requires an authenticated session."),
-  browser_apikey_blocked: client("auth", "Raw API keys must not be used from a browser context."),
-  browser_database_url_blocked: client("auth", "A database connection string must not be used from a browser context \u2014 it carries DB credentials."),
-  datasource_registration_failed: client("auth", "Failed to register the provided databaseUrl as a datasource."),
-  datasource_connection_unsupported: wire("validation", 400, false, "This deployment cannot register a direct (connection string) datasource \u2014 use the signed endpoint kind."),
+  file_upload_auth_required: wire("auth", 401, false, "File uploads require an authenticated session. Sign in and retry."),
+  browser_apikey_blocked: client("auth", "A raw API key was used from a browser, where anyone can read it. Keep secret keys server-side and hand the browser a short-lived ephemeral key instead."),
+  browser_database_url_blocked: client("auth", "A database connection string was used from a browser context. It carries database credentials, so it must stay server-side."),
+  datasource_registration_failed: client("auth", "The provided `databaseUrl` could not be registered as a data source. Check that the connection string is valid and the database is reachable."),
+  datasource_connection_unsupported: wire("validation", 400, false, "This deployment does not accept direct connection-string data sources. Register a signed Data Source endpoint instead."),
   datasource_direct_deprecated: wire("validation", 410, false, "The direct (connection string) datasource is deprecated. Register a signed Data Source endpoint instead \u2014 your app owns the write and your credentials never leave it."),
   // ── permission / capability (403) ──────────────────────────────────
-  capability_scope_denied: wire("capability", 403, false, "The connection's resolved scope does not cover the attempted action."),
-  issuer_register_forbidden: wire("permission", 403, false, "Registering a trusted issuer requires a secret (sk_) API key."),
-  capability_invalid: wire("capability", 403, false, "The capability is unknown, revoked, or expired."),
+  capability_scope_denied: wire("capability", 403, false, "This action falls outside the scope granted to the connection, so it was denied."),
+  issuer_register_forbidden: wire("permission", 403, false, "Registering a trusted issuer requires a secret (`sk_`) API key. The key presented is not a secret key."),
+  capability_invalid: wire("capability", 403, false, "This capability cannot be used \u2014 it is unknown, revoked, or expired. Request a fresh grant."),
   test_database_not_registered: wire("permission", 403, false, "Test mode requires a registered dev database for this org \u2014 run `npx ablo init`, or construct the client with `databaseUrl` using your test key."),
   tenant_routing_failed: wire("server", 500, true, "The org's registered database could not be resolved or dialed. Ablo never falls back to shared storage for a dedicated tenant \u2014 retry, and check the datasource status if it persists."),
-  database_role_cannot_enforce_rls: wire("permission", 403, false, "The connected database role cannot enforce row-level security (superuser or BYPASSRLS)."),
-  database_role_unreadable: wire("permission", 403, false, "The connected database role could not be introspected."),
-  database_tables_unforced_rls: wire("permission", 403, false, "Synced tables in the connected database do not have FORCE ROW LEVEL SECURITY applied."),
-  database_host_not_allowed: wire("permission", 403, false, "The connected database host resolves to a private, loopback, or link-local address and cannot be used."),
-  // Deprecated spellings of the `database_*` codes above — still emitted by
-  // older servers; kept so they classify identically. Do not use in new code.
+  database_role_cannot_enforce_rls: wire("permission", 403, false, "The database role Ablo connects with is a superuser or has `BYPASSRLS`, so Postgres will not enforce row-level security for it. Connect with a role that is subject to RLS."),
+  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."),
+  // 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).
-  claim_conflict: wire("claim", 409, false, "The target entity is claimed by another participant."),
-  claim_lost: wire("claim", 409, false, "A previously held claim was lost before the write applied."),
-  entity_claimed: wire("claim", 409, false, "The target entity is currently claimed; write was blocked."),
-  malformed_claim: wire("claim", 400, false, "The claim payload was malformed."),
-  malformed_subscription: wire("validation", 400, false, "The update_subscription payload was malformed; expected { syncGroups: string[] }."),
-  model_claimed: wire("claim", 409, false, "The model instance is claimed by another participant."),
-  model_claimed_timeout: wire("claim", 409, false, "Timed out waiting for a model claim to clear."),
+  // 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."),
+  malformed_claim: wire("claim", 400, false, "The claim payload could not be parsed. A claim must name the model and the entity it targets; check the payload shape and resend."),
+  malformed_subscription: wire("validation", 400, false, "The `update_subscription` payload was malformed; expected `{ syncGroups: string[] }`."),
+  model_claimed: wire("claim", 409, false, "Another participant holds a claim on this row. Read `claim.state` to see who holds it, or queue behind them with a claim of your own."),
+  model_claimed_timeout: wire("claim", 409, false, "Another participant held a claim on this row and did not release it in time. Retry, or read `claim.state` to see who holds it."),
   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 write carried a readAt watermark that is now stale; re-read and retry."),
+  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."),
   // 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.
-  contention_exhausted: client("conflict", "A functional update could not land after exhausting its reconcile budget; the row stayed continuously contended."),
-  update_aborted: client("conflict", "The functional update reconcile loop was aborted via its AbortSignal before the write landed."),
-  idempotency_conflict: wire("conflict", 409, false, "The same Idempotency-Key was reused with a different request body."),
-  idempotency_key_too_long: wire("validation", 400, false, "The supplied Idempotency-Key exceeds the maximum length."),
+  // 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."),
+  idempotency_key_too_long: wire("validation", 400, false, "The supplied `Idempotency-Key` exceeds the maximum length. Use a shorter key \u2014 a UUID works well."),
   // ── validation (400 / 422) ─────────────────────────────────────────
   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 (missing delegate or model)."),
-  source_event_invalid: client("validation", "A data-source outbox event could not be built \u2014 the operation carries no entity id and none was supplied."),
+  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."),
+  // 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 failed server-side validation."),
+  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`."),
+  // 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`."),
+  commit_operations_ambiguous: wire("validation", 400, false, "A commit supplied both `operation` and `operations`. Send one or the other, not both."),
   commit_too_many_operations: wire("validation", 400, false, "A commit exceeded the per-commit operation limit; split it into smaller batches."),
-  model_required_field_missing: wire("validation", 400, false, "A required field was absent from the model payload."),
-  model_identifier_missing: wire("validation", 400, false, "The model payload is missing its identifier."),
-  snapshot_reserved_key: wire("validation", 400, false, "A snapshot used a reserved key name."),
-  mesh_message_invalid_input: wire("validation", 400, false, "The mesh message failed input validation."),
-  mesh_message_from_id_spoof: wire("validation", 403, false, "The mesh message `from` id does not match the authenticated sender."),
-  mesh_message_from_kind_mismatch: wire("validation", 403, false, "The mesh message `from` kind does not match the sender."),
-  agent_perception_missing_context: wire("validation", 422, false, "The agent perception request lacked required context."),
+  model_required_field_missing: wire("validation", 400, false, "The write is missing a field the model marks as required. Include the field and retry."),
+  model_identifier_missing: wire("validation", 400, false, "The payload is missing the model's identifier, so the target row cannot be determined. Include the `id` field."),
+  snapshot_reserved_key: wire("validation", 400, false, "The snapshot uses a key name that is reserved by the runtime. Rename the key and retry."),
+  mesh_message_invalid_input: wire("validation", 400, false, "The mesh message payload failed input validation and was not delivered."),
+  mesh_message_from_id_spoof: wire("validation", 403, false, "The mesh message's `from` id does not match the authenticated sender, so it was rejected \u2014 participants may only send as themselves."),
+  mesh_message_from_kind_mismatch: wire("validation", 403, false, "The mesh message's `from` kind does not match the kind of the authenticated sender, so it was rejected."),
+  agent_perception_missing_context: wire("validation", 422, false, "The agent perception request is missing context it needs to run. Include the required context fields and retry."),
   // ── not found (404) ────────────────────────────────────────────────
-  entity_not_found: wire("not_found", 404, false, "The referenced entity does not exist."),
-  model_not_found: wire("not_found", 404, false, "The referenced model row does not exist."),
-  mutate_update_entity_not_found: wire("not_found", 404, false, "The entity targeted by an update does not exist."),
-  task_id_missing: wire("server", 502, true, "The task-create response did not include an id."),
-  // ── 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.
-  not_null_violation: wire("validation", 400, false, "A required field was missing (database not-null constraint)."),
-  foreign_key_violation: wire("conflict", 409, false, "A referenced entity does not exist, or is still referenced (database foreign-key constraint)."),
-  unique_violation: wire("conflict", 409, false, "A value violates a uniqueness constraint."),
-  check_violation: wire("validation", 400, false, "A value violates a database check constraint."),
-  constraint_violation: wire("validation", 400, false, "A database integrity constraint was violated."),
+  entity_not_found: wire("not_found", 404, false, "No row exists with the requested id. It may have been deleted, or the id may belong to a different environment."),
+  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 / 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."),
+  check_violation: wire("validation", 400, false, "The database rejected a value that fails one of its check constraints. The error details name the constraint; adjust the value and retry."),
+  constraint_violation: wire("validation", 400, false, "The database rejected the write on an integrity constraint. The error details identify the specific constraint."),
   column_type_mismatch: wire("validation", 400, false, "A structured (JSON) value was written to a column whose database type cannot hold it. Ablo adapts a json field to either a jsonb column (native) or a text column (serialized) \u2014 but a scalar column (integer, boolean, uuid, timestamp, \u2026) cannot store a JSON object or array. Use a jsonb or text column for this field. Ablo adapts to your column; it does not alter your schema."),
   // ── tenant / unknown model (400) ───────────────────────────────────
   server_execute_unknown_model: wire("tenant", 400, false, "Wrote to a model the server does not know. The server keeps its own copy of the schema \u2014 run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models."),
   mutate_create_unknown_model: wire("tenant", 400, false, "Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first \u2014 the server keeps its own copy of the schema."),
-  tenant_model_columns_unknown: wire("tenant", 400, false, "The tenant model's columns could not be resolved."),
-  tenant_model_missing_organization_id: wire("tenant", 400, false, "The tenant model is missing the organization_id column required for isolation."),
+  tenant_model_columns_unknown: wire("tenant", 400, false, "The columns for this model could not be resolved in the tenant database, so the operation cannot be mapped onto its table."),
+  tenant_model_missing_organization_id: wire("tenant", 400, false, "This model's table has no `organization_id` column, which Ablo requires to isolate rows by organization. Add the column before syncing this model."),
   // ── schema migration / declaration (validation) ────────────────────
-  schema_mutable_missing_meta: wire("schema", 400, false, "A mutable schema is missing its required meta block."),
-  schema_scope_kind_invalid: wire("schema", 400, false, "A scope kind in the schema is invalid."),
-  schema_field_not_camelcase: wire("schema", 400, false, "A schema field name is not camelCase."),
-  schema_field_consecutive_caps: wire("schema", 400, false, "A schema field name has consecutive capital letters."),
+  schema_mutable_missing_meta: wire("schema", 400, false, "The schema is declared mutable but is missing its required `meta` block."),
+  schema_scope_kind_invalid: wire("schema", 400, false, "A scope declaration in the schema uses a kind the engine does not recognize."),
+  schema_field_not_camelcase: wire("schema", 400, false, "A schema field name is not camelCase. Rename the field (for example `dueDate`) \u2014 Ablo derives column names from camelCase field names."),
+  schema_field_consecutive_caps: wire("schema", 400, false, "A schema field name contains consecutive capital letters, which cannot be mapped to a column name unambiguously. Write acronyms in lower case (`apiKey`, not `APIKey`)."),
   schema_reserved_field: client("schema", "A model redeclared a reserved base field (id, createdAt, updatedAt, organizationId, createdBy) that the SDK provides automatically."),
-  schema_grants_shape_invalid: wire("schema", 400, false, "A grants declaration has an invalid shape."),
-  schema_grants_identifier_unsafe: wire("schema", 400, false, "A grants declaration referenced an unsafe identifier."),
-  schema_grants_relation_kind: wire("schema", 400, false, "A grants relation referenced an invalid kind."),
-  schema_grants_relation_missing: wire("schema", 400, false, "A grants declaration referenced a missing relation."),
-  schema_grants_target_not_scope_root: wire("schema", 400, false, "A grants target is not a scope root."),
-  drop_field: client("schema", "Migration would drop a field (destructive classification)."),
-  drop_model: client("schema", "Migration would drop a model (destructive classification)."),
-  lossy_recreate: client("schema", "Migration would require a lossy table recreate."),
-  made_required: client("schema", "Migration would make an existing field required."),
-  required_field_added: client("schema", "Migration adds a new required field."),
-  enum_value_removed: client("schema", "Migration removes an enum value (destructive classification)."),
-  risky_cast: client("schema", "Migration would perform a risky column type cast."),
+  schema_grants_shape_invalid: wire("schema", 400, false, "A `grants` declaration in the schema has an invalid shape and could not be parsed."),
+  schema_grants_identifier_unsafe: wire("schema", 400, false, "A `grants` declaration references an identifier that is not safe to use in SQL. Use plain column and relation names."),
+  schema_grants_relation_kind: wire("schema", 400, false, "A `grants` declaration references a relation of a kind it cannot traverse."),
+  schema_grants_relation_missing: wire("schema", 400, false, "A `grants` declaration references a relation the model does not define. Check the relation name against the model."),
+  schema_grants_target_not_scope_root: wire("schema", 400, false, "A `grants` declaration targets a model that is not a scope root, so access cannot be derived from it."),
+  drop_field: client("schema", "This migration would drop an existing field, destroying the data stored in it."),
+  drop_model: client("schema", "This migration would drop an entire model and its table, destroying the rows stored in it."),
+  lossy_recreate: client("schema", "This migration can only apply by recreating the table, which would not preserve its existing rows."),
+  made_required: client("schema", "This migration makes an existing optional field required, which rows without a value for it would violate."),
+  required_field_added: client("schema", "This migration adds a new required field that existing rows have no value for."),
+  enum_value_removed: client("schema", "This migration removes an enum value that existing rows may still hold."),
+  risky_cast: client("schema", "This migration changes a column to a type its current values may not convert to cleanly."),
   // ── claim / lease (409 / transport) ───────────────────────────────
-  claim_lease_unavailable: wire("claim", 503, true, "The claim-lease coordination subsystem is unavailable; retry."),
-  claim_not_wired: client("claim", "Claim support was used but is not wired in this runtime."),
-  claim_queued: wire("claim", 409, true, "The claim was queued behind an active lease holder."),
-  claim_wait_aborted: wire("claim", 409, true, "Waiting for the claim lease was aborted."),
-  claim_wait_poll_interval_required: client("claim", "A poll interval is required when waiting on an claim."),
-  grant_timeout: wire("claim", 504, true, "Timed out waiting for a capability grant."),
-  slide_intent_missing_deck_id: wire("claim", 400, false, "A slide claim was missing its deck id."),
-  slide_intent_unknown_sibling: wire("claim", 400, false, "A slide claim referenced an unknown sibling slide."),
+  claim_lease_unavailable: wire("claim", 503, true, "The claim-lease coordination subsystem is temporarily unavailable, so the claim could not be processed. Retry shortly."),
+  claim_not_wired: client("claim", "Claims were used, but this runtime has no claim support wired in. The standard `Ablo({ schema, apiKey })` client wires it up automatically."),
+  claim_queued: wire("claim", 409, true, "The claim was queued behind the current lease holder and will be granted in turn. Wait, or read `claim.queue` to see your position."),
+  claim_wait_aborted: wire("claim", 409, true, "The wait for this claim lease was aborted before the lease was granted."),
+  claim_wait_poll_interval_required: client("claim", "Waiting on a claim requires a poll interval, and none was provided."),
+  grant_timeout: wire("claim", 504, true, "The wait for a capability grant timed out before one arrived. Retry the request."),
+  slide_intent_missing_deck_id: wire("claim", 400, false, "This slide claim is missing the id of the deck it belongs to."),
+  slide_intent_unknown_sibling: wire("claim", 400, false, "This slide claim references a sibling slide that does not exist in the deck."),
   // ── bootstrap (transport) ──────────────────────────────────────────
-  bootstrap_fetch_timeout: wire("bootstrap", 504, true, "The bootstrap fetch timed out."),
-  bootstrap_offline: wire("bootstrap", 503, true, "Bootstrap could not run because the client is offline."),
-  bootstrap_offline_no_cache: wire("bootstrap", 503, false, "Bootstrap is offline and no cached snapshot is available."),
-  bootstrap_response_invalid: wire("bootstrap", 502, true, "The bootstrap response was malformed."),
-  bootstrap_response_schema_invalid: wire("bootstrap", 502, true, "The bootstrap response failed schema validation."),
+  bootstrap_fetch_timeout: wire("bootstrap", 504, true, "The initial bootstrap fetch timed out before the server responded. Retry shortly."),
+  bootstrap_offline: wire("bootstrap", 503, true, "Bootstrap could not run because the client is offline. It can proceed once the network returns."),
+  bootstrap_offline_no_cache: wire("bootstrap", 503, false, "The client is offline and no cached snapshot is available to start from, so there is no data to load until the network returns."),
+  bootstrap_response_invalid: wire("bootstrap", 502, true, "The bootstrap response could not be parsed. Retrying may succeed."),
+  bootstrap_response_schema_invalid: wire("bootstrap", 502, true, "The bootstrap response parsed but failed schema validation, so it was not applied. Retrying may succeed."),
   // ── transport / connection ─────────────────────────────────────────
-  exchange_malformed_response: wire("transport", 502, true, "The credential exchange returned a malformed response."),
-  exchange_network_error: wire("transport", 503, true, "A network error occurred during credential exchange."),
-  source_network_error: wire("transport", 503, true, "A network error occurred talking to the source."),
-  identity_network_error: wire("transport", 503, true, "A network error occurred resolving identity."),
-  commit_no_result: wire("transport", 504, true, "The commit was sent but no result frame arrived."),
-  commit_failed: wire("transport", 500, true, "The commit failed to apply."),
-  commit_offline_grace_expired: wire("transport", 503, false, "The offline grace window expired before the commit could be sent."),
-  queue_too_deep: wire("transport", 503, true, "The transaction queue exceeded its depth limit."),
-  flush_timeout: wire("transport", 504, true, "Timed out flushing the transaction queue."),
-  wait_for_timeout: wire("transport", 504, true, "A wait-for condition timed out."),
+  exchange_malformed_response: wire("transport", 502, true, "The credential exchange returned a response that could not be parsed. Retrying may succeed."),
+  exchange_network_error: wire("transport", 503, true, "A network error interrupted the credential exchange. Check connectivity and retry."),
+  source_network_error: wire("transport", 503, true, "A network error occurred while talking to the data source. Check connectivity and retry."),
+  identity_network_error: wire("transport", 503, true, "A network error occurred while resolving your identity. Check connectivity and retry."),
+  commit_no_result: wire("transport", 504, true, "The commit was sent, but no result frame arrived, so its outcome is unknown. It is safe to retry."),
+  commit_failed: wire("transport", 500, true, "The commit reached the server but failed to apply. Retrying may succeed."),
+  commit_offline_grace_expired: wire("transport", 503, false, "The offline grace window expired before this commit could be sent, so it was not applied. Re-apply the change once the connection returns."),
+  queue_too_deep: wire("transport", 503, true, "The transaction queue is over its depth limit, so new writes are being rejected until it drains. Retry shortly."),
+  flush_timeout: wire("transport", 504, true, "Flushing the transaction queue timed out before every pending write was sent. Retry once connectivity stabilizes."),
+  wait_for_timeout: wire("transport", 504, true, "A wait-for condition timed out before it was satisfied. Retry, or extend the timeout."),
   instance_at_capacity: wire("transport", 503, true, "The server is at connection capacity. Retry shortly \u2014 transient and not specific to your credentials."),
-  fetch_unavailable: client("transport", "No fetch implementation is available in this environment."),
-  base_url_missing: client("transport", "No base URL was configured for the client."),
-  sync_not_ready: client("transport", "A sync operation was attempted before the client was ready."),
-  ws_not_ready: client("transport", "A frame was sent before the WebSocket was connected."),
+  fetch_unavailable: client("transport", "This environment provides no `fetch` implementation, so HTTP requests cannot be made. Run on a platform with `fetch` (Node 18+, modern browsers) or supply a polyfill."),
+  base_url_missing: client("transport", "The client has no base URL configured, so it cannot address the server. Set the base URL when constructing the client."),
+  sync_not_ready: client("transport", "A sync operation ran before the client finished initializing. Wait for the client to be ready before syncing."),
+  ws_not_ready: client("transport", "A frame was sent before the WebSocket connection was established. Wait for the connection to open before sending."),
   // ── quota / rate limit (429) ──────────────────────────────────────
-  quota_exceeded: wire("rate_limit", 429, true, "The organization exceeded its configured usage quota."),
+  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.
-  rate_limit_exceeded: wire("rate_limit", 429, true, "This API key is sending requests too quickly; slow down and retry after the indicated 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, "An unexpected server error occurred."),
-  quota_lookup_failed: wire("server", 503, true, "The quota decision could not be loaded."),
-  // 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.
+  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 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 failed to open."),
-  turn_close_failed: wire("server", 500, true, "The agent turn failed to close cleanly."),
+  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."),
   // ── client-only invariants (never serialized) ──────────────────────
   invalid_options: client("client", "The Ablo client was constructed with invalid or incomplete options."),
   no_ablo_provider: client("client", "An Ablo hook was used outside of an Ablo provider."),
@@ -277006,58 +277011,72 @@ 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."),
   organization_mismatch: wire("permission", 403, false, "The request targeted an organization the caller is not scoped to."),
   project_scope_denied: wire("permission", 403, false, "The request targeted a project the caller's key is not scoped to."),
-  project_slug_taken: wire("validation", 409, false, "A project with this slug already exists in the organization."),
+  project_slug_taken: wire("validation", 409, false, "A project with this slug already exists in the organization. Choose a different slug."),
   forbidden: wire("permission", 403, false, "The caller lacks permission for this operation."),
-  source_api_key_unresolved: wire("auth", 401, false, "The source API key could not be resolved."),
+  source_api_key_unresolved: wire("auth", 401, false, "The API key presented for this data source could not be resolved to a known key. Check the key and its environment."),
   capability_auth_disabled: wire("server", 503, false, "Capability authentication is disabled on this server."),
-  provisioner_unavailable: wire("server", 503, false, "No database provisioner is configured."),
-  invalid_model: wire("validation", 400, false, "The request named an invalid model."),
-  invalid_id: wire("validation", 400, false, "The request carried an invalid id."),
+  provisioner_unavailable: wire("server", 503, false, "This deployment has no database provisioner configured, so tables cannot be created here."),
+  invalid_model: wire("validation", 400, false, "The model name in the request is not a valid model identifier."),
+  invalid_id: wire("validation", 400, false, "The id in the request is not a valid identifier."),
   unknown_model: wire("tenant", 400, false, "Named a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` \u2014 the server keeps its own copy of the schema."),
-  model_not_tenant_scoped: wire("tenant", 400, false, "The model is not tenant-scoped and cannot be queried this way."),
+  model_not_tenant_scoped: wire("tenant", 400, false, "This model is not tenant-scoped, so it cannot be queried through the tenant-scoped read path."),
   schema_table_invalid: wire("schema", 500, false, "The model's table identifier is invalid."),
   schema_scope_invalid: wire("schema", 500, false, "The model's scope predicate could not be built."),
-  entity_fetch_failed: wire("server", 500, true, "The entity fetch failed."),
-  events_required: wire("validation", 400, false, "The request must include a non-empty events array."),
-  ingest_failed: wire("validation", 400, false, "The source-event ingest failed."),
-  migration_failed: wire("server", 500, false, "The schema migration failed to apply."),
-  model_query_failed: wire("validation", 400, false, "The model query failed."),
-  queries_required: wire("validation", 400, false, "The request must include a non-empty queries array."),
+  entity_fetch_failed: wire("server", 500, true, "The server failed to fetch the requested entity. It is safe to retry."),
+  events_required: wire("validation", 400, false, "The request must include a non-empty `events` array."),
+  ingest_failed: wire("validation", 400, false, "The source-event batch was rejected during ingest and nothing was appended. Check the events against the expected shape and re-send."),
+  migration_failed: wire("server", 500, false, "The schema migration failed while applying and did not complete."),
+  schema_provisioning_forbidden: wire(
+    "permission",
+    403,
+    false,
+    "Schema registration could not create tables in the target database: the engine is not permitted to run DDL there."
+  ),
+  model_query_failed: wire("validation", 400, false, "The model query failed to execute. Check the query filters and operators."),
+  queries_required: wire("validation", 400, false, "The request must include a non-empty `queries` array."),
   query_unsupported_operator: wire("validation", 400, false, "The query used an unsupported operator."),
-  query_unknown_relation: wire("validation", 400, false, "The query referenced an unknown relation."),
-  query_relation_target_unknown: wire("schema", 500, false, "A relation targets a model the schema does not define."),
+  query_invalid_like_pattern: wire("validation", 400, false, "The `LIKE` pattern must not end with an escape character."),
+  query_invalid_boolean: wire("validation", 400, false, "The query compared a boolean column against an invalid boolean literal."),
+  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."),
   org_id_required: wire("validation", 400, false, "An organization id is required for this request."),
-  presence_identity_required: wire("validation", 400, false, "Both userId and organizationId are required."),
-  upload_fields_required: wire("validation", 400, false, "A required upload field was missing."),
-  upload_items_required: wire("validation", 400, false, "The request must include a non-empty items array."),
-  presigned_url_failed: wire("server", 500, true, "Failed to generate a presigned upload URL."),
+  presence_identity_required: wire("validation", 400, false, "Presence requests must carry both `userId` and `organizationId`."),
+  upload_fields_required: wire("validation", 400, false, "The upload request is missing a required field."),
+  upload_items_required: wire("validation", 400, false, "The request must include a non-empty `items` array."),
+  presigned_url_failed: wire("server", 500, true, "The server could not generate a presigned upload URL. It is safe to retry."),
+  upload_not_configured: wire("server", 503, false, "Uploads are not configured on this deployment: the upload storage bucket and CDN domain are unset."),
   task_id_required: wire("validation", 400, false, "A task id is required for this request."),
-  claim_id_required: wire("validation", 400, false, "An claim id is required for this request."),
+  claim_id_required: wire("validation", 400, false, "A claim id is required for this request."),
   commit_operation_action_required: wire("validation", 400, false, "A commit operation is missing its `action`."),
   commit_operation_unsupported: wire("validation", 400, false, "A commit operation used an unsupported `action`."),
   usage_invalid: wire("validation", 400, false, "The usage request was invalid."),
   invalid_request: wire("validation", 400, false, "The request parameters were invalid."),
   capability_not_found: wire("not_found", 404, false, "No capability exists with the given id."),
-  invalid_participant_kind: wire("validation", 400, false, "The participant kind is invalid."),
-  invalid_sync_group: wire("validation", 400, false, 'Sync groups must be "default" or "<namespace>:<id>".'),
-  narrow_scope_required: wire("validation", 400, false, "A narrowed scope is required for this request."),
-  wide_scope_forbidden: wire("permission", 403, false, "A wide scope is not permitted for this caller."),
-  capability_required: wire("auth", 401, false, "This operation requires a capability."),
+  invalid_participant_kind: wire("validation", 400, false, "The participant kind is not one the server recognizes."),
+  invalid_sync_group: wire("validation", 400, false, "Sync groups must be `default` or `<namespace>:<id>`."),
+  narrow_scope_required: wire("validation", 400, false, "This request requires a scope narrowed to specific resources; the presented scope is too broad."),
+  wide_scope_forbidden: wire("permission", 403, false, "This caller may not use a wide scope. Request a scope narrowed to the resources you need."),
+  capability_required: wire("auth", 401, false, "This operation requires a capability, and none was presented."),
   parent_turn_not_found: wire("not_found", 404, false, "The referenced parent turn does not exist."),
-  parent_turn_foreign_agent: wire("permission", 403, false, "The parent turn belongs to a different agent."),
+  parent_turn_foreign_agent: wire("permission", 403, false, "The referenced parent turn belongs to a different agent, so it cannot be used here."),
   turn_not_found: wire("not_found", 404, false, "The referenced turn does not exist."),
-  turn_foreign_agent: wire("permission", 403, false, "The turn belongs to a different agent."),
-  invalid_intent: wire("validation", 400, false, "The claim request was invalid."),
+  turn_foreign_agent: wire("permission", 403, false, "This turn belongs to a different agent, so the caller cannot act on it."),
+  invalid_intent: wire("validation", 400, false, "The claim request was malformed and could not be processed."),
   schema_too_large: wire("validation", 413, false, "The submitted schema exceeds the maximum size."),
+  request_too_large: wire("validation", 413, false, "The request body exceeds the maximum size."),
   invalid_schema: wire("validation", 400, false, "The submitted schema could not be parsed."),
-  incompatible_change: wire("conflict", 409, false, "The schema change is incompatible with the current schema.")
+  incompatible_change: wire("conflict", 409, false, "The schema change is incompatible with the schema currently deployed and cannot be applied as-is.")
 };
 function errorCodeSpec(code) {
   return ERROR_CODES[code];
@@ -277136,7 +277155,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(),
@@ -277156,8 +277175,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. */
@@ -277266,10 +277285,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()
 });
@@ -277283,6 +277302,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)
 });
@@ -277332,35 +277393,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);
@@ -277377,9 +277437,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 {
@@ -277393,12 +277454,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}]` : "";
@@ -277439,8 +277501,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,
@@ -279600,7 +279662,7 @@ function readProjectDatabaseUrl(cwd = process.cwd()) {
   for (const name of [".env.local", ".env"]) {
     const path = (0, import_path.resolve)(cwd, name);
     if (!(0, import_fs2.existsSync)(path)) continue;
-    const match = (0, import_fs2.readFileSync)(path, "utf8").match(/^DATABASE_URL=(.+)$/m);
+    const match = /^DATABASE_URL=(.+)$/m.exec((0, import_fs2.readFileSync)(path, "utf8"));
     if (match?.[1]) return match[1].trim().replace(/^["']|["']$/g, "");
   }
   return null;
@@ -279610,7 +279672,7 @@ function readProjectApiKey(cwd = process.cwd()) {
   for (const name of [".env.local", ".env"]) {
     const path = (0, import_path.resolve)(cwd, name);
     if (!(0, import_fs2.existsSync)(path)) continue;
-    const match = (0, import_fs2.readFileSync)(path, "utf8").match(/^ABLO_API_KEY=(.+)$/m);
+    const match = /^ABLO_API_KEY=(.+)$/m.exec((0, import_fs2.readFileSync)(path, "utf8"));
     if (match?.[1]) return { key: match[1].trim().replace(/^["']|["']$/g, ""), source: name };
   }
   return null;
@@ -279645,6 +279707,12 @@ var import_path3 = require("path");
 var import_child_process = require("child_process");
 var import_schema2 = require("@abloatai/ablo/schema");
 
+// src/client/hostedEndpoints.ts
+init_cjs_shims();
+var ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
+var ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
+var ABLO_DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;
+
 // src/cli/config.ts
 init_cjs_shims();
 var import_os2 = require("os");
@@ -279876,12 +279944,18 @@ function guardActiveProjectKey() {
   const available = Object.entries(profiles).filter(([, keys]) => hasKey(keys)).map(([name]) => name);
   return { ok: hasKey(profiles[activeProfile]), activeProfile, available };
 }
+function resolveEffectiveApiKey(modeOverride, cwd) {
+  const fromProject = readProjectApiKey(cwd);
+  if (fromProject) return { key: fromProject.key, source: fromProject.source };
+  const key = resolveApiKey(modeOverride);
+  return key ? { key, source: "stored" } : { key: void 0, source: null };
+}
 function resolvePushPlan() {
-  const envKey = process.env.ABLO_API_KEY;
-  if (envKey) return { flow: modeFromKey(envKey) ?? getMode(), apiKey: envKey, source: "env" };
-  const mode2 = getMode();
-  const apiKey = resolveApiKey(mode2);
-  return { flow: mode2, apiKey, source: apiKey ? "stored" : null };
+  const { key, source } = resolveEffectiveApiKey();
+  if (key != null && source != null && source !== "stored") {
+    return { flow: modeFromKey(key) ?? getMode(), apiKey: key, source };
+  }
+  return { flow: getMode(), apiKey: key, source };
 }
 
 // src/cli/theme.ts
@@ -279906,7 +279980,7 @@ function coerceBackfill(raw) {
 }
 var DEFAULT_SCHEMA_PATH = "ablo/schema.ts";
 var DEFAULT_EXPORT = "schema";
-var DEFAULT_URL = "https://api.abloatai.com";
+var DEFAULT_URL = ABLO_DEFAULT_BASE_URL;
 function fmtSignal(s) {
   const sig = s;
   const where = sig.field ? `${sig.model}.${sig.field}` : sig.model;
@@ -280049,7 +280123,9 @@ function schemaGitState(schemaPath) {
 }
 async function fetchActiveSchema(url, apiKey) {
   const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), 3e3);
+  const t = setTimeout(() => {
+    ctrl.abort();
+  }, 3e3);
   try {
     const res = await fetch(`${url}/api/schema`, {
       headers: { authorization: `Bearer ${apiKey}` },
@@ -280116,7 +280192,7 @@ async function confirmPush(args, env) {
     const project = getActiveProject();
     const expected = project?.slug ?? "production";
     const typed = await he({
-      message: `This deploys to ${import_picocolors3.default.red(import_picocolors3.default.bold("PRODUCTION"))}. Type ${import_picocolors3.default.bold(expected)} to confirm:`,
+      message: `This deploys to ${import_picocolors3.default.bold("production")}. Type ${import_picocolors3.default.bold(expected)} to confirm:`,
       placeholder: expected
     });
     if (pD(typed) || String(typed).trim() !== expected) {
@@ -280126,7 +280202,7 @@ async function confirmPush(args, env) {
     return;
   }
   if (!isProd && !args.yes && tty) {
-    const ok = await ye({ message: `Apply to ${import_picocolors3.default.green("sandbox")}?` });
+    const ok = await ye({ message: `Apply to ${import_picocolors3.default.bold("sandbox")}?` });
     if (pD(ok) || !ok) {
       xe("Aborted.");
       process.exit(1);
@@ -280135,11 +280211,11 @@ async function confirmPush(args, env) {
 }
 function printPushTarget(opts) {
   const env = modeFromKey(opts.apiKey);
-  const envLabel = env === "production" ? import_picocolors3.default.red(import_picocolors3.default.bold("production")) : env === "sandbox" ? import_picocolors3.default.green("sandbox") : import_picocolors3.default.yellow("unknown env");
+  const envLabel = env === "production" ? import_picocolors3.default.bold("production") : env === "sandbox" ? import_picocolors3.default.bold("sandbox") : import_picocolors3.default.yellow("unknown env");
   const project = getActiveProject();
-  const projectLabel = project ? `${import_picocolors3.default.bold(project.slug)} ${import_picocolors3.default.dim(`(${project.id})`)}` : `${import_picocolors3.default.bold("default")} ${import_picocolors3.default.dim("(org-default \u2014 `ablo projects use <slug>` to scope)")}`;
+  const projectLabel = project ? `${import_picocolors3.default.bold(project.slug)} ${import_picocolors3.default.dim(`(${project.id})`)}` : `${import_picocolors3.default.bold("default")} ${import_picocolors3.default.dim("(org-default)")}`;
   const cliMode = getMode();
-  const modeNote = env && env !== cliMode ? ` ${import_picocolors3.default.yellow(`(CLI mode is ${cliMode} \u2014 this key targets ${env})`)}` : "";
+  const modeNote = env && env !== cliMode ? ` ${import_picocolors3.default.yellow(`(cli mode: ${cliMode})`)}` : "";
   console.log(`
   ${brand("ablo")} ${import_picocolors3.default.dim("push")} ${import_picocolors3.default.dim("\u2192")} ${envLabel}${modeNote}`);
   console.log(`  ${import_picocolors3.default.dim("project")}  ${projectLabel}`);
@@ -280148,20 +280224,20 @@ function printPushTarget(opts) {
     `  ${import_picocolors3.default.dim("key")}      ${maskKey(opts.apiKey)} ${import_picocolors3.default.dim(`(${describeKeySource(opts.keySource)})`)}`
   );
   console.log(
-    `  ${import_picocolors3.default.dim("schema")}   ${import_picocolors3.default.bold(opts.schemaPath)} ${import_picocolors3.default.dim(`\xB7 ${opts.modelCount} models \xB7 hash ${opts.hash}`)}
+    `  ${import_picocolors3.default.dim("schema")}   ${import_picocolors3.default.bold(opts.schemaPath)} ${import_picocolors3.default.dim(`${opts.modelCount} models, hash ${opts.hash}`)}
 `
   );
 }
 function describeKeySource(source) {
   switch (source) {
     case "env":
-      return "ABLO_API_KEY (environment)";
+      return "ABLO_API_KEY";
     case ".env.local":
       return ".env.local";
     case ".env":
       return ".env";
-    case "login":
-      return "`ablo login` (stored sandbox config)";
+    case "stored":
+      return "ablo login";
   }
 }
 async function push(argv) {
@@ -280174,14 +280250,9 @@ async function push(argv) {
   }
   let keySource = "env";
   if (!args.apiKey) {
-    const fromProject = readProjectApiKey();
-    if (fromProject) {
-      args.apiKey = fromProject.key;
-      keySource = fromProject.source;
-    } else {
-      args.apiKey = resolveApiKey();
-      keySource = "login";
-    }
+    const resolved = resolveEffectiveApiKey();
+    args.apiKey = resolved.key;
+    keySource = resolved.source ?? "stored";
   }
   if (!args.apiKey) {
     console.error(
@@ -280278,6 +280349,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(
@@ -280287,7 +280364,7 @@ async function push(argv) {
     } else {
       console.error(
         import_picocolors3.default.dim(
-          `  This key isn't authorized to push schema (needs ${import_picocolors3.default.bold("schema:push")}). ` + (keySource === "login" ? `It's your stored ${import_picocolors3.default.bold("ablo login")} sandbox key \u2014 a key in ${import_picocolors3.default.bold(".env.local")} or ${import_picocolors3.default.bold("ABLO_API_KEY")} takes precedence, so put a schema:push key there (sandbox ${import_picocolors3.default.bold("sk_test_")} or production ${import_picocolors3.default.bold("sk_live_")}) and re-push. ` : `Use a schema:push key \u2014 a sandbox ${import_picocolors3.default.bold("sk_test_")} or production ${import_picocolors3.default.bold("sk_live_")}. `) + `Manage keys at https://abloatai.com`
+          `  This key isn't authorized to push schema (needs ${import_picocolors3.default.bold("schema:push")}). ` + (keySource === "stored" ? `It's your stored ${import_picocolors3.default.bold("ablo login")} sandbox key \u2014 a key in ${import_picocolors3.default.bold(".env.local")} or ${import_picocolors3.default.bold("ABLO_API_KEY")} takes precedence, so put a schema:push key there (sandbox ${import_picocolors3.default.bold("sk_test_")} or production ${import_picocolors3.default.bold("sk_live_")}) and re-push. ` : `Use a schema:push key \u2014 a sandbox ${import_picocolors3.default.bold("sk_test_")} or production ${import_picocolors3.default.bold("sk_live_")}. `) + `Manage keys at https://abloatai.com`
         )
       );
     }
@@ -280351,32 +280428,36 @@ function planFor(schema, targetSchema = "public") {
   return { statements: [...plan.statements, ...adapterTables], concurrent: plan.concurrent ?? [] };
 }
 var log = {
-  info: (msg, fields) => console.log(`[migrate] ${msg}`, fields),
-  warn: (msg, fields) => console.warn(import_picocolors4.default.yellow(`[migrate] ${msg}`), fields),
-  error: (msg, fields) => console.error(import_picocolors4.default.red(`[migrate] ${msg}`), fields)
+  info: (msg, fields) => {
+    console.log(`[migrate] ${msg}`, fields);
+  },
+  warn: (msg, fields) => {
+    console.warn(import_picocolors4.default.yellow(`[migrate] ${msg}`), fields);
+  },
+  error: (msg, fields) => {
+    console.error(import_picocolors4.default.red(`[migrate] ${msg}`), fields);
+  }
 };
-var PG_LOCK_NOT_AVAILABLE = "55P03";
-var LOCK_TIMEOUT = process.env.ABLO_SCHEMA_LOCK_TIMEOUT ?? process.env.ABLO_DDL_LOCK_TIMEOUT ?? "5s";
-var MAX_LOCK_ATTEMPTS = 5;
 async function applyStatements(dbUrl, targetSchema, statements, concurrent = []) {
   const sql = src_default(dbUrl, { max: 1, prepare: false, onnotice: () => {
   } });
   const total = statements.length;
   const startedAt = Date.now();
+  const lockTimeout = (0, import_schema3.resolveDdlLockTimeout)();
+  const maxLockAttempts = (0, import_schema3.resolveDdlMaxLockAttempts)();
   log.info("applying migration plan", { targetSchema, statements: total });
   try {
     for (let attempt = 1; ; attempt++) {
       try {
         await sql.begin(async (tx) => {
-          await tx.unsafe(`SET LOCAL lock_timeout = '${LOCK_TIMEOUT}'`);
+          await tx.unsafe(`SET LOCAL lock_timeout = '${lockTimeout}'`);
           await tx`SELECT pg_advisory_xact_lock(hashtext(${`provision:${targetSchema}`}))`;
-          for (let index = 0; index < total; index++) {
-            const statement = statements[index];
+          for (const [index, statement] of statements.entries()) {
             try {
               await tx.unsafe(statement);
             } catch (err) {
               const pg = err ?? {};
-              if (pg.code === PG_LOCK_NOT_AVAILABLE) throw err;
+              if (pg.code === import_schema3.PG_LOCK_NOT_AVAILABLE) throw err;
               log.error("migration plan failed", {
                 code: "migration_failed",
                 durationMs: Date.now() - startedAt,
@@ -280394,8 +280475,8 @@ async function applyStatements(dbUrl, targetSchema, statements, concurrent = [])
         break;
       } catch (err) {
         const pg = err ?? {};
-        if (pg.code === PG_LOCK_NOT_AVAILABLE && attempt < MAX_LOCK_ATTEMPTS) {
-          const backoffMs = Math.min(6e4, 10 * 2 ** attempt) + Math.floor(Math.random() * 50);
+        if (pg.code === import_schema3.PG_LOCK_NOT_AVAILABLE && attempt < maxLockAttempts) {
+          const backoffMs = (0, import_schema3.ddlLockRetryBackoffMs)(attempt);
           log.warn("schema change blocked by a lock; backing off and retrying", { targetSchema, attempt, backoffMs });
           await new Promise((resolve6) => setTimeout(resolve6, backoffMs));
           continue;
@@ -280615,10 +280696,11 @@ On Neon enable Logical Replication in the project (Console \u2192 Settings \u219
     `SELECT puballtables FROM pg_publication WHERE pubname = $1`,
     [publication]
   );
+  const pubRow = pubRows[0];
   items.push(
-    pubRows.length > 0 ? {
+    pubRow ? {
       ok: true,
-      label: `publication ${import_picocolors5.default.bold(publication)} exists ${import_picocolors5.default.dim(pubRows[0].puballtables ? "(all tables)" : "(table subset)")}`
+      label: `publication ${import_picocolors5.default.bold(publication)} exists ${import_picocolors5.default.dim(pubRow.puballtables ? "(all tables)" : "(table subset)")}`
     } : {
       ok: false,
       label: `publication ${import_picocolors5.default.bold(publication)} not found`,
@@ -280731,6 +280813,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();
@@ -280755,7 +280840,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 })
@@ -280776,22 +280861,32 @@ async function runRegister() {
     process.exit(0);
   }
   const body = await res.json().catch(() => ({}));
-  const code = body.error?.code;
-  const message = body.error?.message ?? `HTTP ${res.status}`;
+  const code = body.code ?? body.error?.code;
+  const message = body.message ?? body.error?.message ?? `HTTP ${res.status}`;
   console.error(import_picocolors5.default.red(`
   Registration failed: ${message}`));
   if (code === "forbidden") {
     console.error(import_picocolors5.default.dim(`  Registering a database needs a ${import_picocolors5.default.bold("secret")} key (sk_\u2026). Run ${import_picocolors5.default.bold("ablo login")} for one.`));
-  } else if (code === "datasource_direct_deprecated") {
-    console.error(
-      import_picocolors5.default.dim(
-        `  This deployment doesn\u2019t accept new connection-string registrations yet. The operator must enable it (${import_picocolors5.default.bold("ABLO_ALLOW_DIRECT_DATASOURCE=true")}) \u2014 see ${import_picocolors5.default.bold("docs/runbooks/connect-customer-database-byo-replication.md")}.`
-      )
-    );
   } else if (code === "datasource_connection_unsupported") {
     console.error(
       import_picocolors5.default.dim(`  This deployment can\u2019t accept connection strings \u2014 use a self-hosted/hosted engine, or the signed endpoint fallback.`)
     );
+  } else if (code === "database_not_replication_ready") {
+    for (const f of body.details?.failures ?? []) {
+      console.error(`  ${import_picocolors5.default.red("\u2717")} ${import_picocolors5.default.bold(f.item ?? "item")}${f.actual ? import_picocolors5.default.dim(` (${f.actual})`) : ""}`);
+      if (f.fix) for (const line of f.fix.split("\n")) console.error(`      ${import_picocolors5.default.red("\u2022")} ${line}`);
+    }
+    console.error(import_picocolors5.default.dim(`
+  Apply the fixes, verify with ${import_picocolors5.default.bold("ablo connect --check")}, then re-run.`));
+  } else if (code === "database_unreachable") {
+    if (body.details?.reason) console.error(import_picocolors5.default.dim(`  ${body.details.reason}`));
+    console.error(
+      import_picocolors5.default.dim(
+        `  Ablo's servers must be able to reach this database \u2014 a localhost or private-network
+  Postgres can't be replicated by the hosted service. Use a reachable host (or a tunnel),
+  or the signed ${import_picocolors5.default.bold("dataSource()")} endpoint fallback.`
+      )
+    );
   }
   console.error();
   process.exit(1);
@@ -280989,16 +281084,17 @@ function wireEnvLocal(apiKey, cwd = process.cwd()) {
     action = `Created ${import_picocolors7.default.bold(".env.local")} with ${import_picocolors7.default.bold("ABLO_API_KEY")}`;
   } else {
     const content = (0, import_fs7.readFileSync)(envPath, "utf8");
-    const match = content.match(/^ABLO_API_KEY=(.*)$/m);
+    const match = /^ABLO_API_KEY=(.*)$/m.exec(content);
+    const existing = match?.[1] ?? "";
     if (!match) {
       (0, import_fs7.appendFileSync)(envPath, `${content.endsWith("\n") || content.length === 0 ? "" : "\n"}${line}
 `);
       action = `Added ${import_picocolors7.default.bold("ABLO_API_KEY")} to ${import_picocolors7.default.bold(".env.local")}`;
-    } else if (match[1] === apiKey) {
+    } else if (existing === apiKey) {
       action = `${import_picocolors7.default.bold(".env.local")} already has this key`;
     } else {
       (0, import_fs7.writeFileSync)(envPath, content.replace(/^ABLO_API_KEY=.*$/m, line));
-      action = `Updated ${import_picocolors7.default.bold("ABLO_API_KEY")} in ${import_picocolors7.default.bold(".env.local")} ${import_picocolors7.default.dim(`(was ${match[1].slice(0, 12)}\u2026)`)}`;
+      action = `Updated ${import_picocolors7.default.bold("ABLO_API_KEY")} in ${import_picocolors7.default.bold(".env.local")} ${import_picocolors7.default.dim(`(was ${existing.slice(0, 12)}\u2026)`)}`;
     }
   }
   const gitignorePath = (0, import_path5.resolve)(cwd, ".gitignore");
@@ -281076,7 +281172,7 @@ async function dev(argv) {
     console.error(import_picocolors7.default.red(`  ${err instanceof Error ? err.message : String(err)}`));
     process.exit(1);
   }
-  if (!args.apiKey) args.apiKey = resolveApiKey("sandbox");
+  if (!args.apiKey) args.apiKey = resolveEffectiveApiKey("sandbox").key;
   const key = classifyKey(args.apiKey, getMode());
   if (!key.ok) {
     console.error(import_picocolors7.default.red(`  ${key.reason}`));
@@ -281200,7 +281296,7 @@ async function deviceLogin(argv, deps = {}) {
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ client_id: CLIENT_ID, scope: "openid profile email" })
   }).catch(() => null);
-  if (!codeRes || !codeRes.ok) {
+  if (!codeRes?.ok) {
     M2.error(`Couldn't start login against ${AUTH_URL}. Is the dashboard reachable?`);
     process.exit(1);
   }
@@ -281270,7 +281366,7 @@ ${import_picocolors8.default.dim(url)}`, "Approve in your browser");
       ...targetProject ? { project_slug: targetProject } : {}
     })
   }).catch(() => null);
-  if (!provRes || !provRes.ok) {
+  if (!provRes?.ok) {
     s.stop("Could not provision a key.");
     const reason = provRes ? (await provRes.json().catch(() => ({}))).error : void 0;
     if (reason) M2.error(reason);
@@ -281584,7 +281680,9 @@ function expiryLabel(iso) {
 }
 async function ping(apiUrl2) {
   const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), 3e3);
+  const t = setTimeout(() => {
+    ctrl.abort();
+  }, 3e3);
   try {
     const res = await fetch(`${apiUrl2}/api/health`, { signal: ctrl.signal });
     return res.ok;
@@ -281597,7 +281695,9 @@ async function ping(apiUrl2) {
 async function fetchPushedSchema(apiUrl2, apiKey) {
   if (!apiKey) return null;
   const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), 3e3);
+  const t = setTimeout(() => {
+    ctrl.abort();
+  }, 3e3);
   try {
     const res = await fetch(`${apiUrl2}/api/schema`, {
       headers: { authorization: `Bearer ${apiKey}` },
@@ -281613,7 +281713,9 @@ async function fetchPushedSchema(apiUrl2, apiKey) {
 }
 async function sampleRead(apiUrl2, apiKey, modelTypename, n) {
   const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), 4e3);
+  const t = setTimeout(() => {
+    ctrl.abort();
+  }, 4e3);
   try {
     const res = await fetch(
       `${apiUrl2}/v1/models/${encodeURIComponent(modelTypename)}/__ablo_health_probe_${n}__`,
@@ -281664,12 +281766,19 @@ async function status(args = []) {
     const key2 = describeEffectiveKey(mode2, process.env.ABLO_API_KEY, entry);
     const plan2 = resolvePushPlan();
     const activeProject2 = getActiveProject();
-    const introspectKey = process.env.ABLO_API_KEY ?? entry?.apiKey;
-    const pushed = await fetchPushedSchema(apiUrl2, introspectKey);
+    const effective2 = resolveEffectiveApiKey();
+    const pushed = await fetchPushedSchema(apiUrl2, effective2.key);
     const out = {
       mode: mode2,
       // The locally-active project (`ablo projects use`); null = org-default.
       project: activeProject2 ?? null,
+      // 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
+      },
       keyPrefix: key2.keyPrefix,
       keySource: key2.keySource,
       keyMode: key2.keyMode,
@@ -281678,16 +281787,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,
@@ -281703,9 +281812,11 @@ async function status(args = []) {
   console.log(`
   ${brand("ablo")} ${import_picocolors11.default.dim("status")}
 `);
-  if (process.env.ABLO_API_KEY) {
+  const effective = resolveEffectiveApiKey();
+  if (effective.key && effective.source && effective.source !== "stored") {
+    const label = effective.source === "env" ? "ABLO_API_KEY env" : effective.source;
     console.log(
-      `  ${import_picocolors11.default.dim("key")}     ${process.env.ABLO_API_KEY.slice(0, 12)}\u2026 ${import_picocolors11.default.dim("(ABLO_API_KEY env \u2014 overrides stored)")}`
+      `  ${import_picocolors11.default.dim("key")}     ${effective.key.slice(0, 12)}\u2026 ${import_picocolors11.default.dim(`(${label} \u2014 overrides stored)`)}`
     );
   } else if (!cfg) {
     console.log(`  ${import_picocolors11.default.yellow("!")} Not logged in \u2014 run ${import_picocolors11.default.bold("ablo login")}.`);
@@ -281740,9 +281851,9 @@ async function status(args = []) {
   const reachable = await ping(apiUrl2);
   console.log(reachable ? import_picocolors11.default.green("reachable") : import_picocolors11.default.red("unreachable"));
   if (reachable) {
-    const introspectKey = process.env.ABLO_API_KEY ?? activeEntry?.apiKey;
+    const introspectKey = effective.key;
     const pushed = await fetchPushedSchema(apiUrl2, introspectKey);
-    if (pushed && pushed.active) {
+    if (pushed?.active) {
       const when = pushed.pushedAt ? ` ${import_picocolors11.default.dim(`@ ${pushed.pushedAt.slice(0, 10)}`)}` : "";
       const ver = pushed.version != null ? ` ${import_picocolors11.default.dim(`(rev ${pushed.version})`)}` : "";
       console.log(`  ${import_picocolors11.default.dim("schema")}  ${import_picocolors11.default.bold(`${pushed.models.length} models pushed`)}${ver}${when}`);
@@ -281755,8 +281866,9 @@ async function status(args = []) {
     } else if (pushed && !pushed.active) {
       console.log(`  ${import_picocolors11.default.dim("schema")}  ${import_picocolors11.default.yellow("none pushed")} ${import_picocolors11.default.dim(`(run ${import_picocolors11.default.bold("ablo push")} or ${import_picocolors11.default.bold("ablo dev")})`)}`);
     }
-    if (pushed && pushed.active && pushed.models.length > 0) {
-      const probe = await probeDataPlane(apiUrl2, introspectKey, pushed.models[0].typename);
+    const firstPushedModel = pushed?.active ? pushed.models[0] : void 0;
+    if (firstPushedModel !== void 0) {
+      const probe = await probeDataPlane(apiUrl2, introspectKey, firstPushedModel.typename);
       if (probe.status === "no_database") {
         console.log(`  ${import_picocolors11.default.dim("data")}    ${import_picocolors11.default.red("\u2717 no database registered")}${org ? import_picocolors11.default.dim(` for org ${org}`) : ""}`);
         console.log(
@@ -281947,8 +282059,10 @@ function parseMode(args) {
 function positional(args) {
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
+    if (a === void 0) continue;
     if (a.startsWith("-")) {
-      if (!a.includes("=") && args[i + 1] && !args[i + 1].startsWith("-")) i++;
+      const next = args[i + 1];
+      if (!a.includes("=") && next && !next.startsWith("-")) i++;
       continue;
     }
     return a;
@@ -282269,8 +282383,8 @@ function verbRewrite(call, verb) {
   const params = VERB_ARGS[verb];
   if (!params) return null;
   const args = call.getArguments();
-  if (args.length === 0) return null;
   const first = args[0];
+  if (first === void 0) return null;
   const calleeText = call.getExpression().getText();
   if (verb === "create") {
     if (import_ts_morph.Node.isObjectLiteralExpression(first) && hasKey2(first, "data")) return null;
@@ -282319,7 +282433,7 @@ async function upgrade(argv) {
       edits.push({ file, line: node.getStartLineNumber(), rule, before, after });
     };
     const flag2 = (node, rule, hint) => {
-      manual.push({ file, line: node.getStartLineNumber(), rule, snippet: node.getText().split("\n")[0].slice(0, 120), hint });
+      manual.push({ file, line: node.getStartLineNumber(), rule, snippet: (node.getText().split("\n")[0] ?? "").slice(0, 120), hint });
     };
     for (const imp of sf.getImportDeclarations()) {
       if (!ABLO_REACT.has(imp.getModuleSpecifierValue())) continue;
@@ -282349,13 +282463,13 @@ async function upgrade(argv) {
       if (method in VERB_ARGS) {
         const next = verbRewrite(call, method);
         if (next) {
-          record(call, `${method}\u2192object-param`, call.getText().split("\n")[0].slice(0, 80), next.slice(0, 80));
+          record(call, `${method}\u2192object-param`, (call.getText().split("\n")[0] ?? "").slice(0, 80), next.slice(0, 80));
           call.replaceWithText(next);
         }
       } else if (method === "load") {
         const next = loadRewrite(call);
         if (next) {
-          record(call, "load\u2192retrieve/list", call.getText().split("\n")[0].slice(0, 80), next.slice(0, 80));
+          record(call, "load\u2192retrieve/list", (call.getText().split("\n")[0] ?? "").slice(0, 80), next.slice(0, 80));
           call.replaceWithText(next);
         }
       }
@@ -282567,12 +282681,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()}`);
@@ -282642,7 +282756,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";
@@ -282665,7 +282779,7 @@ function stripComments(src) {
     let inStr = false;
     let res = "";
     for (let i = 0; i < line.length; i++) {
-      const c = line[i];
+      const c = line.charAt(i);
       if (c === '"') {
         inStr = !inStr;
         res += c;
@@ -282693,8 +282807,10 @@ function parseBlocks(srcRaw) {
     }
     const body = src.slice(openIdx + 1, j2 - 1);
     const kw = m2[1];
+    const name = m2[2];
+    if (name === void 0) throw new Error("unparseable block header in the Prisma schema");
     const type = kw === "model" ? "model" : kw === "enum" ? "enum" : "other";
-    blocks.push({ type, name: m2[2], body });
+    blocks.push({ type, name, body });
     headerRe.lastIndex = j2;
   }
   return blocks;
@@ -282705,7 +282821,7 @@ function parseEnumMembers(body) {
     const t = line.trim();
     if (!t || t.startsWith("@") || t.startsWith("@@")) continue;
     const first = t.split(/\s+/)[0];
-    if (/^\w+$/.test(first)) members.push(first);
+    if (first !== void 0 && /^\w+$/.test(first)) members.push(first);
   }
   return members;
 }
@@ -282714,9 +282830,11 @@ function parseFieldLine(line) {
   if (!t || t.startsWith("@@") || t.startsWith("//")) return null;
   const m2 = /^(\w+)\s+([A-Za-z_]\w*)(\[\])?(\?)?\s*(.*)$/.exec(t);
   if (!m2) return null;
+  const [, name, type] = m2;
+  if (name === void 0 || type === void 0) return null;
   return {
-    name: m2[1],
-    type: m2[2],
+    name,
+    type,
     list: Boolean(m2[3]),
     optional: Boolean(m2[4]),
     attrs: m2[5] ?? ""
@@ -282729,11 +282847,11 @@ function blockMap(body) {
   return /@@map\("([^"]+)"\)/.exec(body)?.[1];
 }
 function relationFkFields(attrs) {
-  const rel = /@relation\(([^)]*)\)/.exec(attrs);
-  if (!rel) return null;
-  const fields = /fields:\s*\[([^\]]*)\]/.exec(rel[1]);
-  if (!fields) return null;
-  return fields[1].split(",").map((s) => s.trim()).filter(Boolean);
+  const rel = /@relation\(([^)]*)\)/.exec(attrs)?.[1];
+  if (rel === void 0) return null;
+  const fields = /fields:\s*\[([^\]]*)\]/.exec(rel)?.[1];
+  if (fields === void 0) return null;
+  return fields.split(",").map((s) => s.trim()).filter(Boolean);
 }
 function parsePrismaSchema(src) {
   const blocks = parseBlocks(src);
@@ -282758,8 +282876,9 @@ function parsePrismaSchema(src) {
       const column = mapAttr(raw.attrs);
       if (modelNames.has(raw.type)) {
         const fks = relationFkFields(raw.attrs);
-        if (fks && fks.length === 1) {
-          relations.push({ name: raw.name, target: tableOf.get(raw.type) ?? raw.type, fkField: fks[0] });
+        const fkField = fks && fks.length === 1 ? fks[0] : void 0;
+        if (fkField !== void 0) {
+          relations.push({ name: raw.name, target: tableOf.get(raw.type) ?? raw.type, fkField });
         }
         continue;
       }
@@ -282822,6 +282941,7 @@ function parsePrismaPullArgs(argv) {
   let force = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
+    if (arg === void 0) continue;
     switch (arg) {
       case "--schema":
         schema = argv[++i] ?? schema;
@@ -282893,7 +283013,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");
@@ -282971,8 +283091,8 @@ async function lowerDrizzleModule(mod) {
     const { foreignKeys } = getTableConfig(table);
     for (const fk of foreignKeys) {
       const ref = fk.reference();
-      if (ref.columns.length !== 1) continue;
-      const localCol = ref.columns[0];
+      const [localCol, ...extraCols] = ref.columns;
+      if (localCol === void 0 || extraCols.length > 0) continue;
       const fkField = fieldKeyByColumn.get(localCol) ?? fieldKeyByColName.get(localCol.name) ?? localCol.name;
       const target = getTableName(ref.foreignTable);
       relations.push({ name: stripIdSuffix(fkField), target, fkField });
@@ -283000,6 +283120,7 @@ function parseDrizzlePullArgs(argv) {
   let force = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
+    if (arg === void 0) continue;
     switch (arg) {
       case "--schema":
         schema = argv[++i] ?? schema;
@@ -283059,7 +283180,7 @@ async function drizzlePull(argv) {
     result = await buildSchemaSourceFromDrizzle({ mod, importPath: args.importPath });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    const hint = /Cannot find package 'drizzle-orm'/.test(msg) ? import_picocolors18.default.dim(` (install ${import_picocolors18.default.bold("drizzle-orm")} in this project)`) : "";
+    const hint = msg.includes("Cannot find package 'drizzle-orm'") ? import_picocolors18.default.dim(` (install ${import_picocolors18.default.bold("drizzle-orm")} in this project)`) : "";
     console.error(import_picocolors18.default.red(`  Couldn't load the schema: ${msg}`) + hint);
     process.exit(1);
   }
@@ -283091,7 +283212,7 @@ var RECOVERY_HINT = {
   permission: "Your key isn't allowed to do this \u2014 check its scopes or role.",
   session_expiry: "Your session expired \u2014 sign in again.",
   access_credential_expiry: "Your access credential expired \u2014 refresh it and retry.",
-  auth_blocked: "Authentication was blocked."
+  auth_blocked: "Authentication was blocked \u2014 the credential itself was rejected. Check that the key matches this environment."
 };
 function titleForType(type) {
   const core = type.replace(/^Ablo/, "").replace(/Error$/, "");
@@ -283127,7 +283248,9 @@ function renderKnownDetails(details, line) {
   }
 }
 function renderCliError(err, opts = {}) {
-  const line = opts.write ?? ((l2) => console.error(l2));
+  const line = opts.write ?? ((l2) => {
+    console.error(l2);
+  });
   const verbose = opts.verbose ?? (process.argv.includes("--verbose") || process.env.ABLO_VERBOSE === "1");
   if (err instanceof AbloError) {
     const codeTag = err.code ? `  ${import_picocolors19.default.dim(`[${err.code}]`)}` : "";
@@ -283356,7 +283479,7 @@ function detectOrm(override) {
   try {
     const pkg = JSON.parse((0, import_fs12.readFileSync)("package.json", "utf-8"));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-    if (deps["@prisma/client"] || deps["prisma"]) return "prisma";
+    if (deps["@prisma/client"] || deps.prisma) return "prisma";
     if (deps["drizzle-orm"]) return "drizzle";
   } catch {
   }
@@ -283564,7 +283687,9 @@ async function init(args = []) {
     `Set ${import_picocolors20.default.bold("DATABASE_URL")} in ${import_picocolors20.default.bold(envFile)} \u2014 your Postgres is the system of record; rows live there, never with Ablo`,
     `Run ${import_picocolors20.default.bold("npx ablo dev")} \u2014 pushes your schema definition and watches for changes`,
     ...storage === "replication" ? [
-      `Connect your database: ${import_picocolors20.default.bold("npx ablo connect")} prints the logical-replication setup SQL (run it once on your Postgres), then ${import_picocolors20.default.bold("npx ablo connect --register")} tells Ablo to replicate it \u2014 your app keeps writing through your own backend, Ablo tails the WAL`
+      `Connect your database \u2014 ${import_picocolors20.default.bold("npx ablo connect")} prints the one-time logical-replication setup SQL to run on your Postgres`,
+      `Verify it \u2014 ${import_picocolors20.default.bold("npx ablo connect --check")} walks wal_level, the publication, the role, and replica identity, with the exact fix for anything missing`,
+      `Register it \u2014 ${import_picocolors20.default.bold("npx ablo connect --register")} tells Ablo to start replicating; your app keeps writing through your own backend while Ablo tails the WAL`
     ] : storage === "direct" ? [
       `Provision your DB: ${import_picocolors20.default.bold("npx ablo migrate")} (creates your synced-model tables with row-level security; keep your own migrations for everything else)`
     ] : [
@@ -283937,23 +284062,12 @@ import Ablo from '@abloatai/ablo';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
-// The browser client holds NO secret. The \`apiKey\` resolver fetches the route
+// The browser client holds NO secret. The endpoint string points at the route
 // below, which mints a short-lived session token (already scoped to the org +
-// user); the client keeps it fresh (refresh timer + wake/online/focus re-mint).
-// Contract: return the token, return \`null\` when the user is signed out
-// (\u2192 the client signs out), or throw on a transient failure (\u2192 it retries).
-const ablo = Ablo({
-  schema,
-  apiKey: async () => {
-    const res = await fetch('/api/ablo-session', {
-      method: 'POST',
-      credentials: 'include',
-    });
-    if (!res.ok) return null;
-    const { token } = (await res.json()) as { token: string | null };
-    return token;
-  },
-});
+// user); the SDK owns the exchange \u2014 it fetches the route (POST, same-origin
+// cookies) and keeps the token fresh (refresh timer + wake re-mint). A 401
+// from the route signs the user out; any other failure is retried.
+const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider client={ablo}>{children}</AbloProvider>;
@@ -283974,8 +284088,8 @@ export async function POST(): Promise<Response> {
   const user = await getCurrentUser();
   if (!user) return new Response('Unauthorized', { status: 401 });
 
-  const { token } = await sync.sessions.create({ user: { id: user.id } });
-  return Response.json({ token });
+  const { token, expiresAt } = await sync.sessions.create({ user: { id: user.id } });
+  return Response.json({ token, expiresAt });
 }
 
 // Validate the signed-in user SERVER-SIDE. This ships wired for Better Auth;