@abloatai/ablo 0.11.0 → 0.11.2

package/dist/cli.cjs

@@ -276803,7 +276803,8 @@ var ERROR_CODES = {
   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."),
-  model_claim_not_configured: client("claim", "Claiming was requested on a model that has no claim configuration."),
+  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."),
   idempotency_conflict: wire("conflict", 409, false, "The same Idempotency-Key was reused with a different request body."),
@@ -276855,6 +276856,7 @@ var ERROR_CODES = {
   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_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."),
@@ -279616,6 +279618,23 @@ var import_source = require("@abloatai/ablo/source");
 // src/cli/push.ts
 init_cjs_shims();
 var import_picocolors3 = __toESM(require_picocolors(), 1);
+
+// src/auth/credentialPolicy.ts
+init_cjs_shims();
+var KIND_BY_PREFIX = [
+  ["sk_", "secret"],
+  ["ek_", "ephemeral"],
+  ["rk_", "restricted"],
+  ["pk_", "publishable"]
+];
+function classifyCredentialKind(value) {
+  for (const [prefix, kind] of KIND_BY_PREFIX) {
+    if (value.startsWith(prefix)) return kind;
+  }
+  return null;
+}
+
+// src/cli/push.ts
 var import_fs4 = require("fs");
 var import_path3 = require("path");
 var import_schema2 = require("@abloatai/ablo/schema");
@@ -279928,7 +279947,7 @@ async function push(argv) {
     console.error(import_picocolors3.default.dim(`  Re-push with ${import_picocolors3.default.bold("--force")} to override, or use ${import_picocolors3.default.bold("--rename old:new")} if you renamed a model.`));
   } else if (status2 === 403) {
     console.error(import_picocolors3.default.red(`  Forbidden: ${body.message ?? body.reason ?? "key lacks schema:push scope"}`));
-    if (args.apiKey?.startsWith("rk_")) {
+    if (args.apiKey != null && classifyCredentialKind(args.apiKey) === "restricted") {
       console.error(
         import_picocolors3.default.dim(
           `  Schema pushes need a SECRET key: ${import_picocolors3.default.bold("sk_test_")} (sandbox dev loop) or a dashboard ${import_picocolors3.default.bold("sk_live_")} (production deploy: ${import_picocolors3.default.bold("ABLO_API_KEY=sk_live_\u2026 npx ablo push")}).`
@@ -279942,6 +279961,14 @@ async function push(argv) {
 }
 
 // src/cli/migrate.ts
+var MIGRATE_USAGE = `  ablo migrate \u2014 provision your schema's tables in your own Postgres (DATABASE_URL)
+
+  Usage:
+    npx ablo migrate                      Create the synced-model tables (with row-level security)
+    npx ablo migrate --dry-run            Print the SQL without executing it
+    npx ablo migrate --output schema.sql  Write the SQL to a file instead of applying
+    npx ablo migrate --schema <path>      Use a schema file other than ablo/schema.ts
+    npx ablo migrate --export <name>      Use a named export other than \`schema\``;
 var DEFAULT_SCHEMA_PATH2 = "ablo/schema.ts";
 var DEFAULT_EXPORT2 = "schema";
 function parseMigrateArgs(argv) {
@@ -280215,7 +280242,7 @@ function classifyKey(apiKey, activeMode) {
       reason: `Production schema deploys run one-shot: ${import_picocolors6.default.bold("ABLO_API_KEY=sk_live_\u2026 npx ablo push")} (or ${import_picocolors6.default.bold("ablo mode production")}). ${import_picocolors6.default.bold("--watch")} is sandbox-only.`
     };
   }
-  if (apiKey.startsWith("rk_")) {
+  if (classifyCredentialKind(apiKey) === "restricted") {
     return {
       ok: false,
       reason: `Restricted (${import_picocolors6.default.bold("rk_")}) keys can't push schema. Use a secret key: ${import_picocolors6.default.bold("sk_test_")} for the sandbox dev loop, or ${import_picocolors6.default.bold("sk_live_")} with ${import_picocolors6.default.bold("npx ablo push")} for a production deploy.`
@@ -280478,7 +280505,10 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
   s.message("Provisioning a sandbox key\u2026");
   const provRes = await fetch(`${AUTH_URL}/api/cli/provision-key`, {
     method: "POST",
-    headers: { authorization: `Bearer ${accessToken}` }
+    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 })
   }).catch(() => null);
   if (!provRes || !provRes.ok) {
     s.stop("Could not provision a key.");
@@ -280706,6 +280736,39 @@ async function projects(argv) {
     );
     return;
   }
+  if (sub === "rename") {
+    const ref = argv[1];
+    const name = argv.slice(2).join(" ").trim();
+    if (!ref || ref.startsWith("-") || !name) {
+      console.error(import_picocolors9.default.red("  usage: ablo projects rename <slug|id> <new name>"));
+      process.exit(1);
+    }
+    const all = await fetchProjects();
+    const target = all.find((p2) => p2.slug === ref || p2.id === ref);
+    if (!target) {
+      console.error(import_picocolors9.default.red(`  No project "${ref}".`) + import_picocolors9.default.dim(" Run ablo projects list."));
+      process.exit(1);
+    }
+    if (target.default) {
+      console.error(import_picocolors9.default.red("  The default project cannot be renamed."));
+      process.exit(1);
+    }
+    const { status: status2, body } = await request(`/api/v1/projects/${target.id}`, requireKey(), {
+      method: "PATCH",
+      body: { name }
+    });
+    if (status2 !== 200) {
+      console.error(
+        import_picocolors9.default.red(`  Rename failed (${status2}): ${String(body.message ?? body.code ?? "")}`)
+      );
+      process.exit(1);
+    }
+    const updated = body;
+    console.log(
+      `  ${import_picocolors9.default.green("\u2713")} Renamed ${import_picocolors9.default.bold(updated.slug)} \u2192 ${import_picocolors9.default.bold(updated.name ?? updated.slug)} ${import_picocolors9.default.dim(`(${updated.id})`)}`
+    );
+    return;
+  }
   if (sub === "use") {
     const ref = argv[1];
     if (!ref) {
@@ -280733,7 +280796,9 @@ async function projects(argv) {
     return;
   }
   console.error(
-    import_picocolors9.default.red(`  unknown subcommand: ${sub}`) + import_picocolors9.default.dim(` (expected ${import_picocolors9.default.bold("list")}, ${import_picocolors9.default.bold("create")}, or ${import_picocolors9.default.bold("use")})`)
+    import_picocolors9.default.red(`  unknown subcommand: ${sub}`) + import_picocolors9.default.dim(
+      ` (expected ${import_picocolors9.default.bold("list")}, ${import_picocolors9.default.bold("create")}, ${import_picocolors9.default.bold("rename")}, or ${import_picocolors9.default.bold("use")})`
+    )
   );
   process.exit(1);
 }
@@ -281006,7 +281071,7 @@ function requireKey2(mode2) {
     );
     process.exit(1);
   }
-  if (!apiKey.startsWith("sk_")) {
+  if (classifyCredentialKind(apiKey) !== "secret") {
     console.error(import_picocolors12.default.red("  Managing webhooks requires a secret key ") + import_picocolors12.default.dim("(sk_test_ / sk_live_)."));
     process.exit(1);
   }
@@ -282130,8 +282195,18 @@ async function drizzlePull(argv) {
 var LOGO = `
   ${brand("ablo")} ${import_picocolors18.default.dim("sync engine")}
 `;
+var SUBCOMMAND_USAGE = {
+  migrate: MIGRATE_USAGE
+};
 async function main() {
-  const command = process.argv[2];
+  let command = process.argv[2];
+  if (command && process.argv.slice(3).some((a) => a === "--help" || a === "-h")) {
+    if (SUBCOMMAND_USAGE[command]) {
+      console.log(SUBCOMMAND_USAGE[command]);
+      return;
+    }
+    command = void 0;
+  }
   if (command === "init") {
     await init(process.argv.slice(3));
   } else if (command === "login") {
@@ -282149,8 +282224,14 @@ async function main() {
   } else if (command === "webhooks") {
     await webhooks(process.argv.slice(3));
   } else if (command === "dev") {
-    console.log(import_picocolors18.default.dim("  `ablo dev` is now `ablo push --watch` \u2014 running that."));
-    await dev([...process.argv.slice(3), "--watch"]);
+    const devArgs = process.argv.slice(3);
+    const oneShot = devArgs.includes("--no-watch");
+    console.log(
+      import_picocolors18.default.dim(
+        oneShot ? "  `ablo dev --no-watch` is `ablo push` (push once, no watcher) \u2014 running that." : "  `ablo dev` is now `ablo push --watch` \u2014 running that."
+      )
+    );
+    await dev(oneShot ? devArgs : [...devArgs, "--watch"]);
   } else if (command === "check") {
     await check(process.argv.slice(3));
   } else if (command === "pull") {
@@ -282208,6 +282289,8 @@ async function main() {
     console.log(`    npx ablo pull prisma [path]            Generate schema.ts from a Prisma schema (keeps enums + relations)`);
     console.log(`    npx ablo pull drizzle <module>         Generate schema.ts from a Drizzle schema (keeps enums + relations)`);
     console.log(`    npx ablo check                         Check your existing database fits the schema (read-only, creates no tables)`);
+    console.log(`    npx ablo migrate                       Provision your synced-model tables in your own Postgres (DATABASE_URL)`);
+    console.log(`    npx ablo migrate --dry-run             Print the SQL without executing (preview)`);
     console.log(`    npx ablo push                          Upload your schema definition to Ablo (metadata only \u2014 rows stay in your DB)`);
     console.log(`    npx ablo push --force                  Allow destructive/unexecutable changes`);
     console.log(`    npx ablo push --rename a:b             Treat model "a" as renamed to "b"`);
@@ -282285,6 +282368,10 @@ function detectOrm(override) {
   }
   return "none";
 }
+function detectNextLayout() {
+  const useSrc = (0, import_fs12.existsSync)((0, import_path7.join)("src", "app")) || !(0, import_fs12.existsSync)("app") && (0, import_fs12.existsSync)("src");
+  return useSrc ? { appBase: (0, import_path7.join)("src", "app"), aliasBase: "src" } : { appBase: "app", aliasBase: "." };
+}
 async function chooseOption(name, flagValue, fallback, allowed, interactive, prompt) {
   if (flagValue !== void 0) {
     if (!allowed.includes(flagValue)) {
@@ -282384,7 +282471,8 @@ async function init(args = []) {
       "Non-interactive (no TTY / --yes)"
     );
   }
-  const abloDir = "ablo";
+  const layout = framework === "nextjs" ? detectNextLayout() : { appBase: "app", aliasBase: "." };
+  const abloDir = (0, import_path7.join)(layout.aliasBase, "ablo");
   (0, import_fs12.mkdirSync)(abloDir, { recursive: true });
   const created = [];
   let schemaSource = generateSchema();
@@ -282415,41 +282503,51 @@ async function init(args = []) {
   created.push(`${abloDir}/schema.ts${schemaNote}`);
   (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "index.ts"), generateSyncConfig(auth, storage));
   created.push(`${abloDir}/index.ts`);
+  (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "register.ts"), generateRegister());
+  created.push(`${abloDir}/register.ts`);
   const orm = detectOrm(opts.orm);
   if (storage === "endpoint") {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "data-source.ts"), generateDataSource(orm));
     created.push(`${abloDir}/data-source.ts${orm === "drizzle" ? " (Drizzle)" : " (Prisma)"}`);
   }
   const envFile = framework === "nextjs" ? ".env.local" : ".env";
+  const resolvedKey = process.env.ABLO_API_KEY ? void 0 : resolveApiKey("sandbox");
+  const wireRealKey = envFile === ".env.local" && Boolean(resolvedKey);
+  const envBody = generateEnv(storage, { includeApiKey: !wireRealKey });
   if (!(0, import_fs12.existsSync)(envFile)) {
-    (0, import_fs12.writeFileSync)(envFile, generateEnv(storage));
+    (0, import_fs12.writeFileSync)(envFile, envBody);
     created.push(envFile);
   } else {
     const existing = (0, import_fs12.readFileSync)(envFile, "utf-8");
     if (!existing.includes("ABLO_")) {
-      (0, import_fs12.writeFileSync)(envFile, existing + "\n" + generateEnv(storage));
+      (0, import_fs12.writeFileSync)(envFile, existing + "\n" + envBody);
       created.push(`${envFile} ${import_picocolors18.default.dim("(appended)")}`);
     } else {
       created.push(`${envFile} ${import_picocolors18.default.dim("(already configured)")}`);
     }
   }
+  if (wireRealKey && resolvedKey) {
+    wireEnvLocal(resolvedKey);
+    created.push(`.env.local ${import_picocolors18.default.dim("(ABLO_API_KEY set from your login)")}`);
+  }
   if (agent) {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "agent.ts"), generateAgent());
     created.push(`${abloDir}/agent.ts`);
   }
   if (framework === "nextjs") {
     if (storage === "endpoint") {
-      const webhookDir = (0, import_path7.join)("app", "api", "ablo", "webhooks");
+      const webhookDir = (0, import_path7.join)(layout.appBase, "api", "ablo", "webhooks");
       (0, import_fs12.mkdirSync)(webhookDir, { recursive: true });
       (0, import_fs12.writeFileSync)((0, import_path7.join)(webhookDir, "route.ts"), generateWebhookRoute(orm));
       created.push(`${webhookDir}/route.ts${orm === "prisma" ? " (Prisma mirror)" : " (add your database write)"}`);
     }
-    (0, import_fs12.writeFileSync)((0, import_path7.join)("app", "providers.tsx"), generateProviders());
-    created.push(`app/providers.tsx ${import_picocolors18.default.dim("(wrap app/layout.tsx in <Providers>)")}`);
-    const sessionDir = (0, import_path7.join)("app", "api", "ablo-session");
+    const providersPath = (0, import_path7.join)(layout.appBase, "providers.tsx");
+    (0, import_fs12.writeFileSync)(providersPath, generateProviders());
+    created.push(`${providersPath} ${import_picocolors18.default.dim(`(wrap ${(0, import_path7.join)(layout.appBase, "layout.tsx")} in <Providers>)`)}`);
+    const sessionDir = (0, import_path7.join)(layout.appBase, "api", "ablo-session");
     (0, import_fs12.mkdirSync)(sessionDir, { recursive: true });
     (0, import_fs12.writeFileSync)((0, import_path7.join)(sessionDir, "route.ts"), generateSessionRoute());
-    created.push(`app/api/ablo-session/route.ts ${import_picocolors18.default.dim("(wire your auth)")}`);
+    created.push(`${(0, import_path7.join)(sessionDir, "route.ts")} ${import_picocolors18.default.dim("(wire your auth)")}`);
   }
   if (framework !== "vanilla") {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "TaskList.tsx"), generateComponent());
@@ -282478,7 +282576,7 @@ async function init(args = []) {
       `Provision your DB: ${import_picocolors18.default.bold("npx ablo migrate")} (creates your Ablo-model tables + the adapter tables; keep your own migrations for everything else), then mount ${import_picocolors18.default.bold(`${abloDir}/data-source.ts`)} at ${import_picocolors18.default.bold("/api/ablo/source")}`
     ],
     ...framework === "nextjs" ? [
-      `Wrap ${import_picocolors18.default.bold("app/layout.tsx")} in ${import_picocolors18.default.bold("<Providers>")} (app/providers.tsx) and add your auth to ${import_picocolors18.default.bold("app/api/ablo-session/route.ts")}`
+      `Wrap ${import_picocolors18.default.bold((0, import_path7.join)(layout.appBase, "layout.tsx"))} in ${import_picocolors18.default.bold("<Providers>")} (${(0, import_path7.join)(layout.appBase, "providers.tsx")}) and add your auth to ${import_picocolors18.default.bold((0, import_path7.join)(layout.appBase, "api", "ablo-session", "route.ts"))}`
     ] : [],
     `Run ${import_picocolors18.default.bold(`${pm} run dev`)} and open two browser tabs \u2014 changes sync in real-time`,
     ...agent ? [
@@ -282557,14 +282655,31 @@ export const sync = Ablo({
   apiKey: process.env.ABLO_API_KEY,${databaseLine}${authLine}
   schema,
 });
+
+// Name the client's type off the constructed value \u2014 the overload resolves at
+// this call site, so this carries the full typed surface. (Like tRPC's
+// \`typeof appRouter\`, Drizzle's \`typeof db\`.) Prefer this over \`ReturnType<typeof Ablo>\`.
+export type Sync = typeof sync;
+`;
+}
+function generateRegister() {
+  return `import type { schema } from './schema';
+
+declare module '@abloatai/ablo' {
+  interface Register {
+    Schema: typeof schema;
+  }
+}
+
+export {};
 `;
 }
-function generateEnv(storage) {
+function generateEnv(storage, opts = {}) {
+  const { includeApiKey = true } = opts;
   const databaseBlock = storage === "direct" ? "# Your Postgres \u2014 the system of record. The client registers this connection\n# (sent once over TLS, stored sealed) and every row lives HERE, never with Ablo.\n# Use a dedicated non-superuser role; the browser never sees this value.\nDATABASE_URL=postgres://user:password@host:5432/db\n" : "# Used by ablo/data-source.ts (your DB endpoint) + `ablo migrate` \u2014 NOT the client.\n# Ablo never sees it; the browser never sees it. Your DB stays in your app.\nDATABASE_URL=postgres://user:password@host:5432/db\n";
   const webhookBlock = storage === "endpoint" ? "# Signing secret for the webhook receiver (app/api/ablo/webhooks/route.ts).\n# Ablo mints this when you register the endpoint's URL (POST /v1/webhook_endpoints\n# or the dashboard) and returns it once \u2014 paste it here.\nABLO_WEBHOOK_SECRET=whsec_your_endpoint_secret_here\n" : "";
-  return `# Ablo Sync Engine \u2014 use a sk_test_ key for local dev (\`npx ablo dev\`)
-ABLO_API_KEY=sk_test_your_key_here
-${webhookBlock}${databaseBlock}`;
+  const apiKeyBlock = includeApiKey ? "# Ablo Sync Engine \u2014 use a sk_test_ key for local dev (`npx ablo push`)\nABLO_API_KEY=sk_test_your_key_here\n" : "";
+  return `${apiKeyBlock}${webhookBlock}${databaseBlock}`;
 }
 function generateDataSource(orm) {
   return orm === "drizzle" ? drizzleDataSourceScaffold() : prismaDataSourceScaffold();
@@ -282826,9 +282941,23 @@ import Ablo from '@abloatai/ablo';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
-// The browser client holds NO secret. \`authEndpoint\` points at the route below,
-// which mints a short-lived session token (already scoped to the org + user).
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+// The browser client holds NO secret. The \`apiKey\` resolver fetches 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;
+  },
+});
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider client={ablo}>{children}</AbloProvider>;

package/dist/client/Ablo.d.ts

@@ -28,7 +28,6 @@ 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 { ParticipantManager } from '../sync/participants.js';
 import type { ClaimHandle, Duration, Claim } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiClaims } from './ApiClient.js';
 import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
@@ -77,35 +76,24 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * usually pass nothing). A long-lived key needs no refresh; the client uses
      * it as-is.
      *
-     * Accepts a static string or an async `() => Promise<string>` resolver if you
-     * rotate keys out-of-band (resolved at bootstrap).
+     * Accepts a static string OR an async `() => Promise<string | null>` resolver
+     * — the single credential path. Use the resolver form for two cases:
      *
-     * Browser apps that mint a SHORT-LIVED per-user key (`ek_`) from a login can't
-     * ship a secret — those use {@link getToken} (or {@link authEndpoint}) instead,
-     * which the client refreshes for you. That's the only case that isn't "just
-     * `apiKey`".
-     */
-    apiKey?: string | ApiKeySetter | null | undefined;
-    /**
-     * Opt-in for the SHORT-LIVED per-user browser case: an async resolver for a
-     * fresh bearer (`ek_`/`rk_`) your backend minted for the signed-in user. The
-     * client calls it once before connect and then keeps the key fresh for you —
-     * a refresh timer ahead of expiry plus re-mint on OS-wake / network-online /
-     * tab-focus, and a reactive re-mint when a probe finds the key stale. You
-     * never call a refresh method (Supabase `autoRefreshToken` model).
+     *  - **Key rotation** (server): pull a fresh `sk_`/`pk_` from a vault on each
+     *    bootstrap (AWS STS, GCP IAM, Vault).
+     *  - **Short-lived per-user browser** auth: return the fresh `ek_`/`rk_` bearer
+     *    your backend minted for the signed-in user. The client mints once before
+     *    connect, then keeps it fresh for you — a refresh timer ahead of expiry
+     *    plus re-mint on OS-wake / network-online / tab-focus, and a reactive
+     *    re-mint when a probe finds the key stale. You never call a refresh method
+     *    (Supabase `autoRefreshToken` model).
      *
-     * Contract: resolve a token, resolve `null` when the login itself is gone
-     * (terminal → sign out), or THROW on a transient failure (→ back off, never
-     * sign out). Leave unset for the static-`apiKey` path.
-     */
-    getToken?: (() => Promise<string | null>) | undefined;
-    /**
-     * Convenience over {@link getToken}: a URL on YOUR backend that returns
-     * `{ token }`. The client POSTs to it (with cookies, so it's authed by the
-     * user's session) to mint + refresh the bearer. Ignored when `getToken` is
-     * set. Pure sugar — `getToken: () => fetch(url).then(r => r.json()).then(b => b.token)`.
+     * Resolver contract: resolve a token; resolve `null` when the login itself is
+     * gone (terminal → the client signs out / fails `ready()` with `session_expired`);
+     * or THROW on a transient failure (→ back off and retry, never sign out). A
+     * static string never refreshes — it is used as-is.
      */
-    authEndpoint?: string | undefined;
+    apiKey?: string | ApiKeySetter | null | undefined;
     /**
      * Direct-URL convenience connector: a connection string to your own Postgres
      * that Ablo can register for a dedicated tenant.
@@ -138,6 +126,9 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * `AbloHttpClient<S>`, so stateful-only capabilities (`get`/`getAll`,
      * `onChange`) are compile errors rather than latent runtime gaps.
      *
+     * Note: session/credential minting (`sessions.create`) currently runs on the
+     * stateful (default) client, not the http client.
+     *
      * @default 'websocket'
      */
     transport?: 'websocket' | 'http' | undefined;
@@ -225,18 +216,6 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * only for the advanced Model / Claim / Commit client.
      */
     schema: Schema<S>;
-    /**
-     * Short-lived-bearer resolver for the per-user browser path (mirrors the
-     * public {@link AbloOptions.getToken}). The client mints the first token
-     * before connect and refreshes it (timer + wake/online/focus) — see
-     * {@link resolveCredentialResolver}.
-     */
-    getToken?: (() => Promise<string | null>) | undefined;
-    /**
-     * Backend URL returning `{ token }`; sugar over {@link getToken}. Mirrors the
-     * public {@link AbloOptions.authEndpoint}.
-     */
-    authEndpoint?: string | undefined;
     /**
      * @deprecated Server derives participant kind from the apiKey's
      * scope. Pass apiKey only; this option will be removed once the
@@ -385,8 +364,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
  *   `claim({ id })` — durable claim handle for coordinated writes
  */
-export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './createModelProxy.js';
-import type { ModelOperations, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ModelLoadOptions } from './createModelProxy.js';
+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';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
 export interface ModelRead<T = Record<string, unknown>> {
@@ -394,23 +373,15 @@ export interface ModelRead<T = Record<string, unknown>> {
     readonly stamp: number;
     readonly claims: readonly ModelClaim[];
 }
-export type IfClaimedPolicy = 'return' | 'wait' | 'fail';
+export type IfClaimedPolicy = 'return' | 'fail';
 export interface ClaimedOptions {
     /**
-     * What to do when another participant has claimed the target. `return`
-     * includes active claim metadata in the response, `wait` resolves after the
-     * claim clears, and `fail` throws `AbloClaimedError`.
+     * What to do when another participant has claimed the target: `return`
+     * includes active claim metadata in the response; `fail` throws
+     * `AbloClaimedError`. Waiting for a claim to clear is a claim-side concern —
+     * take `ablo.<model>.claim({ id })` (it queues fairly); reads never block.
      */
     readonly ifClaimed?: IfClaimedPolicy;
-    /** Max time to wait for peer claims to clear, in milliseconds. */
-    readonly claimedTimeout?: number;
-    /** HTTP API polling interval while waiting. WebSocket clients ignore it. */
-    readonly claimedPollInterval?: number;
-    /**
-     * Backpressure for `ifClaimed: 'wait'`: reject instead of waiting if the
-     * row's FIFO line is already `>= maxQueueDepth` deep.
-     */
-    readonly maxQueueDepth?: number;
 }
 export type { ClaimWaitOptions } from '../types/streams.js';
 export interface ModelReadOptions extends ClaimedOptions {
@@ -527,7 +498,7 @@ export interface ModelClient<T = Record<string, unknown>> {
      * `limit`. Present on the stateless protocol client; the store-backed
      * `.model(name)` accessor omits it (use the typed `ablo.<model>.list` there).
      */
-    list?(options?: ModelLoadOptions<T>): Promise<T[]>;
+    list?(options?: ServerReadOptions<T>): Promise<T[]>;
     create(params: ModelMutationOptions & {
         readonly data: Record<string, unknown>;
         readonly id?: string | null;
@@ -560,7 +531,7 @@ export interface CreateUserSessionParams {
         id: string;
     };
     /** Sync groups this session may subscribe to — typed (`'default'` or
-     *  `<namespace>:<id>`; build with `syncGroup.org()/user()/of()` from
+     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
      *  `@abloatai/ablo/schema`). Omit for the server default:
      *  `[org:<your org>, user:<user.id>]`. */
     syncGroups?: readonly SyncGroupInput[];
@@ -585,7 +556,7 @@ export interface CreateAgentSessionParams<S extends SchemaRecord> {
         [M in keyof S & string]?: readonly SessionOperation[];
     };
     /** Sync groups this session may subscribe to — typed (`'default'` or
-     *  `<namespace>:<id>`; build with `syncGroup.org()/user()/of()` from
+     *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
      *  `@abloatai/ablo/schema`). Omit for the server default: the org
      *  anchor (`org:<your org>`) + the agent's own anchor. */
     syncGroups?: readonly SyncGroupInput[];
@@ -667,7 +638,7 @@ export type Ablo<S extends SchemaRecord> = {
      * Replace the bearer auth token used for the WebSocket upgrade and HTTP
      * requests, WITHOUT tearing down the engine. Use to push a refreshed
      * short-lived access key (the Stripe-style `ek_`/`rk_`) before it expires —
-     * `<AbloProvider>`'s `getToken` refresh loop calls this. Reuses the same
+     * the client's `apiKey`-resolver refresh loop calls this. Reuses the same
      * rotation path as the internal capability-token refresh; safe to call before
      * `ready()`. Also nudges a parked connection to re-probe with the new token.
      */
@@ -675,8 +646,8 @@ export type Ablo<S extends SchemaRecord> = {
     /**
      * Resolve the active bearer credential this engine authenticates with — the
      * live `ek_`/`rk_` the WebSocket and HTTP transports currently carry (kept
-     * fresh by the `getToken` refresh loop), falling back to a configured API
-     * key. Returns `null` when no credential is set yet. Use it to authenticate
+     * fresh by the `apiKey`-resolver refresh loop), falling back to a configured
+     * API key. Returns `null` when no credential is set yet. Use it to authenticate
      * a side-band request to the same server with the very token this client
      * already holds — no extra mint round-trip.
      */
@@ -685,10 +656,10 @@ export type Ablo<S extends SchemaRecord> = {
      * Register a re-mint hook for the short-lived access key. The connection
      * layer calls it WHEN it finds the key stale (a `credential_stale` probe) or
      * on an external nudge; the hook mints a fresh `ek_`/`rk_` from the still-valid
-     * login. Mirrors the `getToken` contract: resolve a token, resolve `null` when
-     * the login itself is gone (→ sign out), or THROW on a transient failure (→
-     * back off, never sign out). `<AbloProvider>` wires this from its
-     * `getToken`/`authEndpoint`. Safe to call before `ready()`.
+     * login. Mirrors the `apiKey`-resolver contract: resolve a token, resolve
+     * `null` when the login itself is gone (→ sign out), or THROW on a transient
+     * failure (→ back off, never sign out). The client wires this automatically
+     * from a function `apiKey`. Safe to call before `ready()`.
      */
     setCredentialRefresher(refresher: (() => Promise<string | null>) | null): void;
     /**
@@ -703,14 +674,15 @@ export type Ablo<S extends SchemaRecord> = {
      * Mint a short-lived, scoped **session token** for one end user — the
      * Stripe `ephemeralKeys.create` / Supabase session shape. Call this on YOUR
      * BACKEND (where the `sk_` secret key lives), then hand the returned
-     * `token` to that user's browser (typically via an authEndpoint the client
-     * fetches). The browser presents it as the bearer; the sync-server verifies
+     * `token` to that user's browser (typically via a token route the browser's
+     * `apiKey` resolver fetches). The browser presents it as the bearer; the sync-server verifies
      * it via `apiKeyProvider`.
      *
      * The browser must NEVER see the `sk_` key — only the per-user session token.
      *
      * Pass `{ user: { id } }` for a full-authority end-user session (mints `ek_`,
-     * `actor_kind: 'user'` attribution), or `{ agent: { id }, can: { tasks:
+     * `participantKind: 'user'` attribution, stored as `actor_kind` on the delta
+     * row), or `{ agent: { id }, can: { tasks:
      * ['update'] } }` for a scoped agent session (mints `rk_`); `can` is typed
      * against your schema's model names. Always authenticates with the original
      * `sk_` — never the client's exchanged sync credential.
@@ -822,24 +794,6 @@ export type Ablo<S extends SchemaRecord> = {
      * are schema-powered sugar over the same model write/read path.
      */
     model<T = Record<string, unknown>>(name: string): ModelClient<T>;
-    /**
-     * Canonical multiplayer participant surface. Joins a structured app
-     * target, derives the transport scope internally, opens a scoped
-     * claim on the existing WebSocket, and returns target-bound presence
-     * + claim helpers.
-     *
-     * ```ts
-     * const participant = await ablo.participants.join({
-     *   type: 'File',
-     *   id: 'src/foo.ts',
-     *   path: 'src/foo.ts',
-     *   range: { startLine: 10, endLine: 40 },
-     * });
-     * participant.presence.editing();
-     * const claim = participant.claims.claim('rewrite imports');
-     * ```
-     */
-    readonly participants: ParticipantManager;
     /**
      * Capture a context-staleness watermark over a set of entities.
      * Returns a flat snapshot with `stamp` (thread into writes as
@@ -991,9 +945,6 @@ export declare namespace Ablo {
     type ClaimLost = _Streams.ClaimLost;
     type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
     namespace Auth {
-        type Principal = _Streams.Principal;
-        type Session = _Streams.SessionRef;
-        type Agent = _Streams.AgentRef;
         type Actor = _Streams.ParticipantRef;
     }
     namespace Participant {