@abloatai/ablo 0.12.0 → 0.14.0

package/dist/cli.cjs

@@ -276903,9 +276903,18 @@ var ERROR_CODES = {
   // ── quota / rate limit (429) ──────────────────────────────────────
   quota_exceeded: wire("rate_limit", 429, true, "The organization exceeded its configured usage quota."),
   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."),
   // ── 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.
+  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."),
   // ── client-only invariants (never serialized) ──────────────────────
@@ -277023,6 +277032,7 @@ var roleSchema = import_zod2.z.object({
   kind: import_zod2.z.string().regex(/^[a-z][a-z0-9_]*$/, 'kind must be a lowercase identifier, e.g. "deck"'),
   source: roleSourceSchema
 });
+var entityRoleSchema = roleSchema;
 var scopeSchema = import_zod2.z.union([
   import_zod2.z.boolean(),
   import_zod2.z.string().regex(/^[a-z][a-z0-9_]*$/, 'scope kind must be a lowercase identifier, e.g. "dataroom"')
@@ -277031,6 +277041,11 @@ var grantsRefSchema = import_zod2.z.object({
   subject: import_zod2.z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "grants.subject must name a relation"),
   scope: import_zod2.z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "grants.scope must name a relation")
 });
+var groupsInputSchema = import_zod2.z.object({
+  root: scopeSchema.optional(),
+  grants: grantsRefSchema.optional(),
+  roles: import_zod2.z.union([entityRoleSchema, import_zod2.z.array(entityRoleSchema)]).optional()
+});
 
 // src/coordination/schema.ts
 var targetRangeSchema = import_zod3.z.object({
@@ -279646,6 +279661,7 @@ init_cjs_shims();
 var import_os2 = require("os");
 var import_path2 = require("path");
 var import_fs3 = require("fs");
+var DEFAULT_PROFILE = "default";
 function configDir() {
   if (process.env.ABLO_CONFIG_DIR) return process.env.ABLO_CONFIG_DIR;
   const xdg = process.env.XDG_CONFIG_HOME;
@@ -279657,12 +279673,32 @@ function configPath() {
 function credentialsPath() {
   return (0, import_path2.join)(configDir(), "credentials.json");
 }
+function activeProfileName(cfg) {
+  return cfg.activeProject?.slug ?? DEFAULT_PROFILE;
+}
 function asKeyEntry(value) {
   if (value && typeof value === "object" && typeof value.apiKey === "string") {
     return value;
   }
   return void 0;
 }
+function asProfileKeys(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const v = value;
+  const sandbox = asKeyEntry(v.sandbox);
+  const production = asKeyEntry(v.production);
+  if (!sandbox && !production) return void 0;
+  return { ...sandbox ? { sandbox } : {}, ...production ? { production } : {} };
+}
+function asProfileMap(value) {
+  if (!value || typeof value !== "object") return {};
+  const out = {};
+  for (const [name, v] of Object.entries(value)) {
+    const keys = asProfileKeys(v);
+    if (keys) out[name] = keys;
+  }
+  return out;
+}
 function readJson(path) {
   if (!(0, import_fs3.existsSync)(path)) return null;
   try {
@@ -279683,7 +279719,7 @@ function normalizeStoredMode(value) {
   if (value === "sandbox" || value === "production") return value;
   return void 0;
 }
-function extractEntries(obj) {
+function extractLegacyEntries(obj) {
   const sandbox = asKeyEntry(obj.sandbox);
   const production = asKeyEntry(obj.production);
   if (sandbox || production) {
@@ -279692,24 +279728,33 @@ function extractEntries(obj) {
   const flat = asKeyEntry(obj);
   return flat ? { sandbox: flat } : {};
 }
+function hasKey(keys) {
+  return !!(keys?.sandbox || keys?.production);
+}
 function readConfig() {
   const cfgObj = readJson(configPath());
   const credObj = readJson(credentialsPath());
   const mode2 = normalizeStoredMode(cfgObj?.mode) ?? normalizeStoredMode(credObj?.mode);
   const activeProject = asActiveProject(cfgObj?.activeProject);
-  const cfgEntries = cfgObj ? extractEntries(cfgObj) : {};
-  const entries = {
-    ...cfgEntries,
-    ...credObj ? extractEntries(credObj) : {}
-    // credentials file wins
+  const activeName = activeProject?.slug ?? DEFAULT_PROFILE;
+  const profiles = {
+    ...asProfileMap(credObj?.profiles),
+    ...asProfileMap(cfgObj?.profiles)
   };
-  if (!mode2 && !entries.sandbox && !entries.production) return null;
+  const legacyCfg = cfgObj ? extractLegacyEntries(cfgObj) : {};
+  const legacyCred = credObj ? extractLegacyEntries(credObj) : {};
+  const legacy = { ...legacyCfg, ...legacyCred };
+  const migratedLegacy = hasKey(legacy) && !hasKey(profiles[activeName]);
+  if (migratedLegacy) profiles[activeName] = legacy;
+  const anyKey = Object.values(profiles).some(hasKey);
+  if (!mode2 && !anyKey) return null;
   const config = {
     mode: mode2 ?? "sandbox",
     ...activeProject ? { activeProject } : {},
-    ...entries
+    profiles
   };
-  if (cfgEntries.sandbox || cfgEntries.production) writeConfig(config);
+  const secretsInConfig = hasKey(legacyCfg);
+  if (secretsInConfig || migratedLegacy) writeConfig(config);
   return config;
 }
 function writeConfig(cfg) {
@@ -279725,16 +279770,34 @@ function writeConfig(cfg) {
 `,
     { mode: 384 }
   );
-  const credentials = {
-    ...cfg.sandbox ? { sandbox: cfg.sandbox } : {},
-    ...cfg.production ? { production: cfg.production } : {}
-  };
-  (0, import_fs3.writeFileSync)(credentialsPath(), `${JSON.stringify(credentials, null, 2)}
+  const profiles = {};
+  for (const [name, keys] of Object.entries(cfg.profiles)) {
+    if (!hasKey(keys)) continue;
+    profiles[name] = {
+      ...keys.sandbox ? { sandbox: keys.sandbox } : {},
+      ...keys.production ? { production: keys.production } : {}
+    };
+  }
+  (0, import_fs3.writeFileSync)(credentialsPath(), `${JSON.stringify({ profiles }, null, 2)}
 `, { mode: 384 });
   return credentialsPath();
 }
+function emptyConfig(mode2 = "sandbox") {
+  return { mode: mode2, profiles: {} };
+}
+function setProfileKeys(profileName, keys, opts) {
+  const cfg = readConfig() ?? emptyConfig(opts.mode);
+  cfg.mode = opts.mode;
+  cfg.profiles[profileName] = {
+    ...keys.sandbox ? { sandbox: keys.sandbox } : {},
+    ...keys.production ? { production: keys.production } : {}
+  };
+  if (opts.activeProject) cfg.activeProject = opts.activeProject;
+  else delete cfg.activeProject;
+  return writeConfig(cfg);
+}
 function setMode(mode2) {
-  const cfg = readConfig() ?? { mode: mode2 };
+  const cfg = readConfig() ?? emptyConfig(mode2);
   cfg.mode = mode2;
   return writeConfig(cfg);
 }
@@ -279745,13 +279808,15 @@ function getActiveProject() {
   return readConfig()?.activeProject;
 }
 function setActiveProject(project) {
-  const cfg = readConfig() ?? { mode: "sandbox" };
+  const cfg = readConfig() ?? emptyConfig("sandbox");
   if (project) cfg.activeProject = project;
   else delete cfg.activeProject;
   return writeConfig(cfg);
 }
 function getKeyEntry(mode2) {
-  return readConfig()?.[mode2];
+  const cfg = readConfig();
+  if (!cfg) return void 0;
+  return cfg.profiles[activeProfileName(cfg)]?.[mode2];
 }
 function modeFromKey(key) {
   if (/^(sk|rk)_test_/.test(key)) return "sandbox";
@@ -279775,11 +279840,21 @@ function resolveApiKey(modeOverride) {
   if (process.env.ABLO_API_KEY) return process.env.ABLO_API_KEY;
   const cfg = readConfig();
   if (!cfg) return void 0;
-  const entry = cfg[modeOverride ?? cfg.mode];
+  const entry = cfg.profiles[activeProfileName(cfg)]?.[modeOverride ?? cfg.mode];
   if (!entry) return void 0;
   if (entry.expiresAt && Date.parse(entry.expiresAt) <= Date.now()) return void 0;
   return entry.apiKey;
 }
+function guardActiveProjectKey() {
+  if (process.env.ABLO_API_KEY) {
+    return { ok: true, activeProfile: DEFAULT_PROFILE, available: [] };
+  }
+  const cfg = readConfig();
+  const activeProfile = cfg ? activeProfileName(cfg) : DEFAULT_PROFILE;
+  const profiles = cfg?.profiles ?? {};
+  const available = Object.entries(profiles).filter(([, keys]) => hasKey(keys)).map(([name]) => name);
+  return { ok: hasKey(profiles[activeProfile]), activeProfile, available };
+}
 function resolvePushPlan() {
   const envKey = process.env.ABLO_API_KEY;
   if (envKey) return { flow: modeFromKey(envKey) ?? getMode(), apiKey: envKey, source: "env" };
@@ -280425,8 +280500,19 @@ function openBrowser(url) {
   } catch {
   }
 }
-async function deviceLogin() {
+function parseProjectFlag(argv) {
+  const i = argv.indexOf("--project");
+  if (i >= 0) {
+    const slug = argv[i + 1];
+    if (slug && !slug.startsWith("-")) return slug;
+  }
+  const eq = argv.find((a) => a.startsWith("--project="));
+  return eq ? eq.slice("--project=".length) || void 0 : void 0;
+}
+async function deviceLogin(argv) {
   Ie(`${brand("ablo")} login`);
+  const requested = parseProjectFlag(argv) ?? getActiveProject()?.slug;
+  const targetProject = requested === DEFAULT_PROFILE ? void 0 : requested;
   const interactive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
   let account = "login";
   if (interactive) {
@@ -280504,13 +280590,19 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
     s.stop("Timed out waiting for approval.");
     process.exit(1);
   }
-  s.message("Provisioning a sandbox key\u2026");
+  s.message(
+    targetProject ? `Provisioning keys for ${targetProject}\u2026` : "Provisioning a sandbox key\u2026"
+  );
   const provRes = await fetch(`${AUTH_URL}/api/cli/provision-key`, {
     method: "POST",
     headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
-    // Pass the device_code so the server can scope the minted keys to the
-    // project the user picked at /cli (login project picker). Harmless if none.
-    body: JSON.stringify({ device_code: code.device_code })
+    // Scope the minted keys to the chosen project (`--project`/active), with
+    // the device_code as a legacy fallback for the /cli picker. Both harmless
+    // if absent → org-default keys.
+    body: JSON.stringify({
+      device_code: code.device_code,
+      ...targetProject ? { project_slug: targetProject } : {}
+    })
   }).catch(() => null);
   if (!provRes || !provRes.ok) {
     s.stop("Could not provision a key.");
@@ -280528,16 +280620,23 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
     ...prov.organizationId ? { organizationId: prov.organizationId } : {},
     ...k3.expiresAt ? { expiresAt: k3.expiresAt } : {}
   });
-  const path = writeConfig({
-    mode: "sandbox",
-    sandbox: entry(prov.test),
-    ...prov.live ? { production: entry(prov.live) } : {}
-  });
+  const profileName = prov.project?.slug ?? DEFAULT_PROFILE;
+  const path = setProfileKeys(
+    profileName,
+    {
+      sandbox: entry(prov.test),
+      ...prov.live ? { production: entry(prov.live) } : {}
+    },
+    { mode: "sandbox", activeProject: prov.project ?? void 0 }
+  );
   s.stop(`Saved keys to ${path}`);
-  Se(`${import_picocolors7.default.green("\u2713")} Logged in ${import_picocolors7.default.dim("(sandbox)")}. Run ${import_picocolors7.default.bold("npx ablo push")} to push your schema.`);
+  const where = prov.project ? ` ${import_picocolors7.default.dim(`(project ${prov.project.slug})`)}` : "";
+  Se(
+    `${import_picocolors7.default.green("\u2713")} Logged in ${import_picocolors7.default.dim("(sandbox)")}${where}. Run ${import_picocolors7.default.bold("npx ablo push")} to push your schema.`
+  );
 }
-async function login() {
-  await deviceLogin();
+async function login(argv = []) {
+  await deviceLogin(argv);
 }
 function logout() {
   const removed = clearCredential();
@@ -280790,11 +280889,13 @@ async function projects(argv) {
       setActiveProject({ id: target.id, slug: target.slug });
       console.log(`  ${import_picocolors9.default.green("\u2713")} now targeting project ${import_picocolors9.default.bold(target.slug)} ${import_picocolors9.default.dim(`(${target.id})`)}`);
     }
-    console.log(
-      import_picocolors9.default.dim(
-        "  Note: a key\u2019s project scope is fixed at mint \u2014 switch keys (or mint one for this project) to act in it."
-      )
-    );
+    const guard = guardActiveProjectKey();
+    if (!guard.ok) {
+      const loginCmd = guard.activeProfile === DEFAULT_PROFILE ? "ablo login" : `ablo login --project ${guard.activeProfile}`;
+      console.log(
+        import_picocolors9.default.dim(`  No key stored for this project yet \u2014 run ${import_picocolors9.default.bold(loginCmd)} to mint one.`)
+      );
+    }
     return;
   }
   console.error(
@@ -281370,7 +281471,7 @@ function spreadOpts(optsArg) {
   }
   return `, ...${optsArg.getText()}`;
 }
-function hasKey(obj, key) {
+function hasKey2(obj, key) {
   return obj.getProperties().some(
     (p2) => (import_ts_morph.Node.isPropertyAssignment(p2) || import_ts_morph.Node.isShorthandPropertyAssignment(p2)) && p2.getName() === key
   );
@@ -281383,7 +281484,7 @@ function verbRewrite(call, verb) {
   const first = args[0];
   const calleeText = call.getExpression().getText();
   if (verb === "create") {
-    if (import_ts_morph.Node.isObjectLiteralExpression(first) && hasKey(first, "data")) return null;
+    if (import_ts_morph.Node.isObjectLiteralExpression(first) && hasKey2(first, "data")) return null;
     return `${calleeText}({ data: ${first.getText()}${spreadOpts(args[1])} })`;
   }
   if (import_ts_morph.Node.isObjectLiteralExpression(first)) return null;
@@ -282212,7 +282313,7 @@ async function main() {
   if (command === "init") {
     await init(process.argv.slice(3));
   } else if (command === "login") {
-    await login();
+    await login(process.argv.slice(3));
   } else if (command === "logout") {
     logout();
   } else if (command === "mode") {
@@ -282251,6 +282352,22 @@ async function main() {
     const rest = process.argv.slice(3);
     const advanced = rest.some((a) => ["--force", "--rename", "--backfill", "--url"].includes(a));
     const watching = rest.includes("--watch");
+    const guard = guardActiveProjectKey();
+    if (!guard.ok && guard.available.length > 0 && !rest.includes("--url")) {
+      console.error(
+        `  ${import_picocolors18.default.yellow("\u26A0")} active project ${import_picocolors18.default.bold(guard.activeProfile)} has no stored key ${import_picocolors18.default.dim(
+          `(you have keys for: ${guard.available.join(", ")})`
+        )}`
+      );
+      const loginCmd = guard.activeProfile === "default" ? "ablo login" : `ablo login --project ${guard.activeProfile}`;
+      console.error(
+        import_picocolors18.default.dim(
+          `    Mint one with ${import_picocolors18.default.bold(loginCmd)}, or switch with ${import_picocolors18.default.bold("ablo projects use <slug>")}.`
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
     const plan = resolvePushPlan();
     if (advanced || plan.flow === "production" && !watching) {
       await push(rest);
@@ -282275,11 +282392,12 @@ async function main() {
     console.log(`                  [--auth apikey] [--storage direct|endpoint] [--project <slug>] [--no-project]`);
     console.log(`                  [--no-agent] [--no-pull] [--no-install] [--no-login]`);
     console.log(`    npx ablo login                         Authorize in your browser (provisions sandbox + production keys)`);
+    console.log(`    npx ablo login --project <slug>        Same, scoped to a project (mints its keys, makes it active)`);
     console.log(`    npx ablo logout                        Remove the stored API key`);
     console.log(`    npx ablo mode [sandbox|production]     Switch active environment, like Stripe`);
     console.log(`    npx ablo projects list                 List the org's projects (default + your own)`);
     console.log(`    npx ablo projects create <slug>        Create a project (its keys/schema/data are isolated)`);
-    console.log(`    npx ablo projects use <slug|default>   Set the active project for new key mints`);
+    console.log(`    npx ablo projects use <slug|default>   Switch the active project (run login --project to mint its keys)`);
     console.log(`    npx ablo status                        Show org, mode, keys, and server health`);
     console.log(`    npx ablo status --json                 Same, machine-readable (mode, key prefix, org id, api host)`);
     console.log(`    npx ablo logs [-n N] [--since 15m]     Tail commit activity (follows; --no-follow to exit)`);

package/dist/client/Ablo.d.ts

@@ -28,7 +28,7 @@ import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import type { SyncGroupInput } from '../schema/roles.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
 import type { ClaimStream, ClaimWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
-import type { ClaimHandle, Duration, Claim } from '../types/streams.js';
+import type { ClaimHandle, Duration } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiClaims } from './ApiClient.js';
 import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
 /**
@@ -371,7 +371,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  *   `claim({ id })` — durable claim handle for coordinated writes
  */
 export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './createModelProxy.js';
-import type { ModelOperations, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ServerReadOptions } from './createModelProxy.js';
+import type { ModelOperations, ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod, ServerReadOptions } from './createModelProxy.js';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
 export interface ModelRead<T = Record<string, unknown>> {
@@ -473,30 +473,21 @@ export interface ModelMutationOptions extends ClaimedOptions {
  * The HTTP/stateless claim surface. Normal tools usually put `claim` directly
  * on the write (`update({ id, data, claim })`) and let the SDK release it. Use
  * this namespace for multi-step handles and coordination screens.
+ *
+ * Same surface as the reactive {@link ClaimApi}, but every read is a server
+ * round-trip, so `state`/`queue`/`reorder` are **awaited** here (the WebSocket
+ * client resolves them synchronously from its local pool — which is what lets
+ * `useAblo((ablo) => ablo.x.claim.state({ id }))` work inside a React render; a
+ * stateless client has no pool to read, so the `Promise` is unavoidable).
+ *
+ * Mechanically DERIVED from `ClaimReadApi` via {@link AwaitedClaimMethod} so the
+ * two transports can never drift: the ONLY difference is the uniform `Promise`
+ * wrapper that statelessness forces. `claim({ id })` is identical (already async
+ * on both); `state`/`queue`/`reorder`/`release` are the awaited form.
  */
-export interface HttpClaimApi<T> {
-    /** Take a manual claim handle for multi-step work. Release it when done. */
-    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
-    /** Release a manual claim you hold. */
-    release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
-    /**
-     * Current holder of the lease on a row, or `null` when free. For UI badges,
-     * preflight checks, and operators.
-     */
-    state(params: ClaimLookupParams<T>): Promise<Claim | null>;
-    /**
-     * FIFO wait line behind the holder. Advanced: useful for operator UIs and
-     * schedulers.
-     */
-    queue(params: ClaimLookupParams<T>): Promise<{
-        readonly object: 'list';
-        readonly data: readonly Claim[];
-    }>;
-    /**
-     * Re-rank the wait line. Advanced and permission-gated.
-     */
-    reorder(params: ClaimReorderParams<T>): Promise<void>;
-}
+export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<ClaimHandle<T>>) & {
+    [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
+};
 export interface ModelClient<T = Record<string, unknown>> {
     /**
      * Single-row read over HTTP. **Returns an envelope, not the bare row** — the

package/dist/client/Ablo.js

@@ -1325,7 +1325,7 @@ export function Ablo(options) {
             }),
             queue: (target) => publicClaims.queueFor({ type: target.model, id: target.id }),
             reorder: (target, order) => publicClaims.reorder({ type: target.model, id: target.id }, order),
-            observe: (target) => {
+            state: (target) => {
                 // The live claim stream only tracks *open* (active) claims;
                 // terminal states (committed / expired / canceled) drop out of
                 // the list entirely — exactly the ephemeral coordination model.

package/dist/client/auth.js

@@ -54,6 +54,14 @@ export function resolveDatabaseUrl(input) {
  * explicit option instead of flipping their mode for them. Warns once per process
  * so it never spams, and falls back to `console.warn` when no logger is supplied
  * (the `transport: 'api'` client has none).
+ *
+ * Suppressed entirely on the hosted/token path: if an `apiKey` resolves (option
+ * or `ABLO_API_KEY` env), the caller has chosen the hosted capability-token /
+ * Data Source transport, which is mutually exclusive with direct `databaseUrl`
+ * mode. A `DATABASE_URL` sitting in that environment is unrelated infra (Prisma,
+ * Drizzle, the sync-server) — never an omitted option — so nudging would be a
+ * false positive. This is the first-party hosted app's exact shape, where the
+ * stray nudge otherwise reaches end-user desktop logs.
  */
 let warnedDatabaseUrlEnvIgnored = false;
 export function warnIfDatabaseUrlEnvIgnored(input, warn) {
@@ -61,6 +69,9 @@ export function warnIfDatabaseUrlEnvIgnored(input, warn) {
         return;
     if (input.options.databaseUrl != null)
         return;
+    // Hosted/token path → DATABASE_URL is unrelated infra, not an omitted option.
+    if (resolveApiKey(input) != null)
+        return;
     const envUrl = input.env.DATABASE_URL;
     if (typeof envUrl !== 'string' || envUrl.length === 0)
         return;

package/dist/client/createModelProxy.d.ts

@@ -109,8 +109,13 @@ export interface ModelCollaboration<T> {
      * `null` when the target is free. The wiring site computes it because
      * only it knows the local participant id (needed to distinguish "I
      * hold it" from "someone else holds it").
+     *
+     * Named `state` to match the public `ablo.<model>.claim.state({ id })` read —
+     * one verb for "who holds this" across every claim surface; the only
+     * difference is this internal contract takes an explicit `{ model, id }`
+     * target because it isn't bound to a single model.
      */
-    observe(target: {
+    state(target: {
         model: string;
         id: string;
     }): Claim | null;
@@ -202,10 +207,11 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
      * work-distribution dedup ("if someone else has this job, skip it") where
      * waiting would mean double-processing.
      *
-     * Named `queue` to match every other claim surface (low-level
-     * `claims.claim`, HTTP `claim.create`, and the wire). The high-level typed
-     * claim defaults it ON because it serializes writers; the low-level lease
-     * and HTTP default it OFF — they return/resolve immediately and can't
+     * Named `queue` to match every other claim surface — `ablo.<model>.claim`
+     * on both the WS and HTTP clients (take-a-claim is the callable `claim({ id
+     * })` on both; the HTTP reads are just awaited) and the wire. The high-level
+     * typed claim defaults it ON because it serializes writers; the low-level
+     * lease and HTTP default it OFF — they return/resolve immediately and can't
      * transparently wait for a grant.
      */
     queue?: boolean;
@@ -276,9 +282,18 @@ export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
  * handle. `state`, `queue`, and `reorder` are coordination reads/scheduler
  * controls for UI and operators.
  */
-export interface ClaimApi<T> {
-    /** Take a claim and get an explicit held-work handle back. */
-    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+/**
+ * Coordination reads + scheduler controls on a claim namespace, in their
+ * REACTIVE (synchronous) form — `state`/`queue`/`reorder` resolve against the
+ * local pool with no round-trip, which is what lets `useAblo((ablo) =>
+ * ablo.x.claim.state({ id }))` read coordination state inside a React render.
+ *
+ * This is the single source of truth for the claim read surface: the stateless
+ * HTTP client exposes the *awaited* projection of EXACTLY these methods
+ * (`HttpClaimApi` in `Ablo.ts`, derived via {@link AwaitedClaimMethod}), so the
+ * two transports can never drift — edit a signature here and HTTP follows.
+ */
+export interface ClaimReadApi<T = Record<string, unknown>> {
     /**
      * Current holder for a row, or `null` when free. Use this for UI badges and
      * preflight checks, not for the normal write path.
@@ -299,6 +314,16 @@ export interface ClaimApi<T> {
     /** Release a manual claim handle early. Single-write claims auto-release. */
     release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
 }
+/**
+ * The awaited form of a claim method: a synchronous return becomes a `Promise`,
+ * an already-async one (`release`) is left untouched. Used to derive the
+ * stateless HTTP claim surface from the reactive {@link ClaimReadApi}.
+ */
+export type AwaitedClaimMethod<F> = F extends (...args: infer A) => infer R ? R extends Promise<unknown> ? (...args: A) => R : (...args: A) => Promise<R> : F;
+export interface ClaimApi<T> extends ClaimReadApi<T> {
+    /** Take a claim and get an explicit held-work handle back. */
+    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+}
 export interface ModelRetrieveParams extends ServerRetrieveOptions {
     readonly id: string;
 }

package/dist/client/createModelProxy.js

@@ -141,7 +141,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // Is someone ELSE already on this target? Read the local coordination
         // snapshot up front — it decides whether we'll need to re-read after the
         // claim (a free / already-mine target can't have changed under us).
-        const held = collaboration.observe({ model: wireModel, id });
+        const held = collaboration.state({ model: wireModel, id });
         const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
         const failFast = options?.queue === false;
         // Fail-fast (`queue: false`): if another participant already holds it,
@@ -215,7 +215,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         const snapshot = collaboration.createSnapshot(schemaKey, id);
         const reason = options?.reason ?? 'editing';
         // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
-        // report (`observe` maps `held.target.model` → `type`), so a holder and a
+        // report (`state` maps `held.target.model` → `type`), so a holder and a
         // peer see the SAME target.type for one row — the wire model token.
         const selfTarget = {
             type: wireModel,
@@ -271,7 +271,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             // presence. Soft + fire-and-forget — never blocks or rejects the read.
             void collaboration?.enterScope?.({ [schemaKey]: params.id });
             // Self-awareness: the server excludes a holder's OWN presence frames and
-            // the client skips them, so `observe` returns null for a row WE hold.
+            // the client skips them, so `state` returns null for a row WE hold.
             // Synthesize the active claim for self from the stored lease so the
             // holder sees its own claim (the JSDoc contract on `claim.state`).
             const own = activeClaims.get(params.id);
@@ -287,7 +287,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     expiresAt: own.expiresAt,
                 };
             }
-            return collaboration?.observe({ model: wireModel, id: params.id }) ?? null;
+            return collaboration?.state({ model: wireModel, id: params.id }) ?? null;
         },
         queue(params) {
             return {

package/dist/errorCodes.d.ts

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export declare const ERROR_CONTRACT_VERSION = "2026-06-13";
+export declare const ERROR_CONTRACT_VERSION = "2026-06-20";
 /** Coarse grouping for metrics dashboards and docs sectioning. */
 export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'claim' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
 /**
@@ -239,8 +239,10 @@ export declare const ERROR_CODES: {
     readonly ws_not_ready: ErrorCodeSpec;
     readonly quota_exceeded: ErrorCodeSpec;
     readonly connection_limit_exceeded: ErrorCodeSpec;
+    readonly rate_limit_exceeded: ErrorCodeSpec;
     readonly internal_error: ErrorCodeSpec;
     readonly quota_lookup_failed: ErrorCodeSpec;
+    readonly rate_limiter_unavailable: ErrorCodeSpec;
     readonly turn_open_failed: ErrorCodeSpec;
     readonly turn_close_failed: ErrorCodeSpec;
     readonly invalid_options: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export const ERROR_CONTRACT_VERSION = '2026-06-13';
+export const ERROR_CONTRACT_VERSION = '2026-06-20';
 /**
  * The closed taxonomy of *how a failure recovers* — one rung above the raw
  * `code`. Where `code` says **what** went wrong, `RecoveryClass` says **what
@@ -258,9 +258,18 @@ export const ERROR_CODES = {
     // ── quota / rate limit (429) ──────────────────────────────────────
     quota_exceeded: wire('rate_limit', 429, true, 'The organization exceeded its configured usage quota.'),
     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.'),
     // ── 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.
+    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.'),
     // ── client-only invariants (never serialized) ──────────────────────

package/dist/schema/index.d.ts

@@ -23,13 +23,13 @@
 export { z } from 'zod';
 export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from './field.js';
 export { relation, type RelationDef, type RelationType } from './relation.js';
-export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type TenancyInput, } from './tenancy.js';
+export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type PolicyInput, } from './tenancy.js';
 export { planeSchema, DEFAULT_PLANE, type SchemaPlane } from './plane.js';
 export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_PLANES, type SyncDeltaCore, type DeltaAttribution, type DeltaProvenance, type SyncDeltaRow, type ParticipantKind, type ConfirmationState, type BackfillProvenance, } from './sync-delta-row.js';
 export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, type SyncDeltaAction, type WireDeltaData, type ParticipantRef, type SyncDeltaWireCore, type ClientSyncDelta, type ServerSyncDelta, } from './sync-delta-wire.js';
 export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, } from './model.js';
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
-export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';