@abloatai/ablo 0.9.9 → 0.9.11

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.9.11
+
+### Patch Changes
+
+- `Model<'name'>` type helper via the `Register` binding — name your model in one parameter (`Model<'tasks'>`) instead of restating `typeof schema`; `Model<S, 'name'>` is also supported and `InferModel` is deprecated. CLI: retire the stale `dev` wording from the login outro and `push` header. Docs: cover the `Register` binding end-to-end and document the `pk_` publishable key + the `/v1/commits` HTTP path.
+- 3024593: Fix `sessions.create({ user })` 403 — user sessions now mint via the sk\_-gated ephemeral-key door
+  - `sessions.create({ user })` mints an `ek_` user session via `/auth/ephemeral-keys` (was wrongly routed through `/auth/capability`, which rejects human participants — writes were being attributed to agents).
+  - Control-plane calls always present your original `sk_`, never the client's exchanged sync credential.
+  - `sessions.create({ agent, can })` no longer requires hand-built `syncGroups` — the org anchor is the server default — and the `can` allowlist is now honored at commit time (model-alias matching).
+  - New: `ablo.organizationId` (resolved after `ready()`), `ablo status --json`, typed sync-group inputs (`SyncGroupInput` + `invalid_sync_group` rejection for malformed groups).
+
+## 0.9.10
+
+### Patch Changes
+
+- README: add a centered brand header (Ablo banner, tagline, doc nav links, and status badges).
+
 ## 0.9.9
 
 ### Patch Changes

package/README.md

@@ -1,11 +1,27 @@
-# Ablo
-
-[![npm](https://img.shields.io/npm/v/@abloatai/ablo.svg)](https://www.npmjs.com/package/@abloatai/ablo)
-[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
-[![types](https://img.shields.io/badge/types-included-blue.svg)](#)
-[![runtime](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](#keys--runtime)
-
-**Let people and AI agents work on the same data without overwriting each other.**
+<p align="center">
+  <a href="https://abloatai.com"><img src="assets/banner.png" alt="Ablo" width="480" /></a>
+</p>
+
+<p align="center">
+  <strong>Let people and AI agents work on the same data without overwriting each other.</strong>
+</p>
+
+<p align="center">
+  <a href="https://abloatai.com">Docs</a> &nbsp;|&nbsp;
+  <a href="https://abloatai.com/quickstart">Quickstart</a> &nbsp;|&nbsp;
+  <a href="https://abloatai.com/api">API</a> &nbsp;|&nbsp;
+  <a href="https://github.com/Abloatai/ablo">GitHub</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@abloatai/ablo"><img src="https://img.shields.io/npm/v/@abloatai/ablo?style=flat-square&color=2563eb" alt="npm" /></a>
+  <a href="https://abloatai.com"><img src="https://img.shields.io/badge/docs-abloatai.com-2563eb?style=flat-square" alt="docs" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-2563eb?style=flat-square" alt="license" /></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A524-22c55e?style=flat-square" alt="node >=24" />
+  <img src="https://img.shields.io/badge/types-included-2563eb?style=flat-square" alt="types included" />
+</p>
+
+---
 
 When an agent and a person change the same thing at once, work gets lost: one
 edit silently clobbers another, or the agent acts on data that already moved.
@@ -85,6 +101,29 @@ instead of guessing:
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
+Register the schema once (init scaffolds this `ablo.d.ts`), and every type
+is one parameter away — no `typeof schema` re-stating, anywhere:
+
+```ts
+// ablo.d.ts — once per project
+import type { schema } from './ablo/schema';
+declare module '@abloatai/ablo' {
+  interface Register { Schema: typeof schema }
+}
+export {};
+```
+
+```ts
+import type { Model } from '@abloatai/ablo/schema';
+
+type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
+```
+
+(The same `Register` binding types every hook and client — it's the
+TanStack-Router pattern: declare the source of truth once, everything
+infers from it.)
+
+
 const schema = defineSchema({
   weatherReports: model({
     location: z.string(),

package/dist/auth/index.d.ts

@@ -11,8 +11,8 @@
  * SDKs hide their internal auth-handshake — the apiKey is the only
  * credential the consumer touches.
  */
-import { type CapabilityExchangeResponse, type IdentityResolveResponse } from './schemas.js';
-export type { CapabilityExchangeResponse, IdentityResolveResponse } from './schemas.js';
+import { type CapabilityExchangeResponse, type EphemeralKeyResponse, type IdentityResolveResponse } from './schemas.js';
+export type { CapabilityExchangeResponse, EphemeralKeyResponse, IdentityResolveResponse, } from './schemas.js';
 export interface ExchangeApiKeyRequest {
     readonly apiKey: string;
     readonly baseUrl: string;
@@ -20,7 +20,6 @@ export interface ExchangeApiKeyRequest {
     readonly participantId?: string;
     readonly syncGroups?: readonly string[];
     readonly operations?: readonly string[];
-    readonly wideScope?: boolean;
     readonly ttlSeconds: number;
     readonly label?: string;
     readonly userMeta?: Record<string, unknown>;
@@ -28,6 +27,29 @@ export interface ExchangeApiKeyRequest {
     readonly timeoutMs?: number;
 }
 export declare function exchangeApiKey(options: ExchangeApiKeyRequest): Promise<CapabilityExchangeResponse>;
+export interface MintUserSessionRequest {
+    /** The ORIGINAL secret (`sk_`) key — control-plane calls always present it,
+     *  never the exchanged sync credential. */
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    /** The end user's external IdP id — becomes the session's `participantId`. */
+    readonly userId: string;
+    readonly syncGroups?: readonly string[];
+    readonly ttlSeconds: number;
+    readonly label?: string;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+/**
+ * Mint an END-USER session key (`ek_`) via `POST /auth/ephemeral-keys` — the
+ * sk_-gated user-session door. This is deliberately a DIFFERENT endpoint from
+ * `/auth/capability`: that route can never mint humans (its
+ * `invalid_participant_kind` gate is what fired in the 2026-06-11 Pulse
+ * cascade, when `sessions.create({ user })` was funneled through the agent
+ * door). The server trusts the `ek_` because a secret key minted it; the
+ * browser presents it as its bearer.
+ */
+export declare function mintUserSessionKey(options: MintUserSessionRequest): Promise<EphemeralKeyResponse>;
 export interface ResolveIdentityRequest {
     readonly baseUrl: string;
     readonly authToken?: string;

package/dist/auth/index.js

@@ -11,7 +11,7 @@
  * SDKs hide their internal auth-handshake — the apiKey is the only
  * credential the consumer touches.
  */
-import { parseCapabilityExchangeResponse, parseIdentityResolveResponse, } from './schemas.js';
+import { parseCapabilityExchangeResponse, parseEphemeralKeyResponse, parseIdentityResolveResponse, } from './schemas.js';
 import { AbloAuthenticationError, hasWireCode, translateHttpError } from '../errors.js';
 export async function exchangeApiKey(options) {
     if (!options.apiKey) {
@@ -75,6 +75,66 @@ export async function exchangeApiKey(options) {
     }
     return parseCapabilityExchangeResponse(await response.json());
 }
+/**
+ * Mint an END-USER session key (`ek_`) via `POST /auth/ephemeral-keys` — the
+ * sk_-gated user-session door. This is deliberately a DIFFERENT endpoint from
+ * `/auth/capability`: that route can never mint humans (its
+ * `invalid_participant_kind` gate is what fired in the 2026-06-11 Pulse
+ * cascade, when `sessions.create({ user })` was funneled through the agent
+ * door). The server trusts the `ek_` because a secret key minted it; the
+ * browser presents it as its bearer.
+ */
+export async function mintUserSessionKey(options) {
+    if (!options.apiKey) {
+        throw new AbloAuthenticationError('No API key found. Set ABLO_API_KEY in your environment or pass `apiKey` ' +
+            'to Ablo({ ... }) directly — user sessions are minted by your backend.', { code: 'apikey_missing' });
+    }
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for user-session mint', { code: 'base_url_missing' });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/ephemeral-keys`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${options.apiKey}`,
+            },
+            body: JSON.stringify({
+                user: { id: options.userId },
+                ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
+                ttlSeconds: options.ttlSeconds,
+                ...(options.label ? { label: options.label } : {}),
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`user-session mint failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'exchange_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore — server returned non-JSON error
+        }
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`user-session mint rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
+    }
+    return parseEphemeralKeyResponse(await response.json());
+}
 /**
  * Resolve the caller's Ablo identity from the authenticated request
  * context. Used by browser/session/capability flows where the SDK should

package/dist/auth/schemas.d.ts

@@ -31,5 +31,22 @@ export declare const IdentityResolveResponseSchema: z.ZodObject<{
     userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$loose>;
 export type IdentityResolveResponse = z.infer<typeof IdentityResolveResponseSchema>;
+/**
+ * Response of `POST /auth/ephemeral-keys` — the sk_-gated END-USER session
+ * mint (`ek_`). Flat shape (no `scope` block): the server stores the scope on
+ * the key row and re-derives it at every verify; the client only needs the
+ * token + identity facts to hand to the browser.
+ */
+export declare const EphemeralKeyResponseSchema: z.ZodObject<{
+    object: z.ZodOptional<z.ZodLiteral<"ephemeral_key">>;
+    id: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodString;
+    organizationId: z.ZodString;
+    participantId: z.ZodString;
+    syncGroups: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
+export type EphemeralKeyResponse = z.infer<typeof EphemeralKeyResponseSchema>;
 export declare function parseCapabilityExchangeResponse(raw: unknown): CapabilityExchangeResponse;
+export declare function parseEphemeralKeyResponse(raw: unknown): EphemeralKeyResponse;
 export declare function parseIdentityResolveResponse(raw: unknown): IdentityResolveResponse;

package/dist/auth/schemas.js

@@ -29,6 +29,23 @@ export const IdentityResolveResponseSchema = z
     userMeta: z.record(z.string(), z.unknown()),
 })
     .passthrough();
+/**
+ * Response of `POST /auth/ephemeral-keys` — the sk_-gated END-USER session
+ * mint (`ek_`). Flat shape (no `scope` block): the server stores the scope on
+ * the key row and re-derives it at every verify; the client only needs the
+ * token + identity facts to hand to the browser.
+ */
+export const EphemeralKeyResponseSchema = z
+    .object({
+    object: z.literal('ephemeral_key').optional(),
+    id: z.string().min(1),
+    token: AuthTokenSchema,
+    expiresAt: z.string().min(1),
+    organizationId: z.string().min(1),
+    participantId: z.string().min(1),
+    syncGroups: z.array(z.string()),
+})
+    .passthrough();
 function formatIssues(error) {
     return error.issues
         .map((issue) => {
@@ -44,6 +61,13 @@ export function parseCapabilityExchangeResponse(raw) {
     }
     return parsed.data;
 }
+export function parseEphemeralKeyResponse(raw) {
+    const parsed = EphemeralKeyResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new AbloAuthenticationError(`user-session mint response was malformed: ${formatIssues(parsed.error)}`, { code: 'exchange_malformed_response', cause: parsed.error });
+    }
+    return parsed.data;
+}
 export function parseIdentityResolveResponse(raw) {
     const parsed = IdentityResolveResponseSchema.safeParse(raw);
     if (!parsed.success) {

package/dist/cli.cjs

@@ -276983,6 +276983,7 @@ var ERROR_CODES = {
   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."),
@@ -280053,7 +280054,7 @@ async function dev(argv) {
     process.exit(1);
   }
   console.log(`
-  ${brand("ablo")} ${import_picocolors6.default.dim("sync engine \u2014 dev")} ${import_picocolors6.default.dim("(sandbox)")}
+  ${brand("ablo")} ${import_picocolors6.default.dim("push")} ${import_picocolors6.default.dim("(sandbox)")}
 `);
   const projectDbUrl = readProjectDatabaseUrl();
   if (projectDbUrl) await ensureScopedRoleInteractive(projectDbUrl);
@@ -280241,7 +280242,7 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
     ...prov.live ? { production: entry(prov.live) } : {}
   });
   s.stop(`Saved keys to ${path}`);
-  Se(`${import_picocolors7.default.green("\u2713")} Logged in ${import_picocolors7.default.dim("(sandbox)")}. Run ${import_picocolors7.default.bold("ablo dev")}, or ${import_picocolors7.default.bold("ablo mode production")} to switch.`);
+  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.`);
 }
 async function login() {
   await deviceLogin();
@@ -280336,10 +280337,23 @@ async function ping(apiUrl) {
     clearTimeout(t);
   }
 }
-async function status() {
+async function status(args = []) {
   const apiUrl = (process.env.ABLO_API_URL ?? DEFAULT_URL).replace(/\/+$/, "");
   const cfg = readConfig();
   const mode2 = getMode();
+  if (args.includes("--json")) {
+    const entry = getKeyEntry(mode2);
+    const out = {
+      mode: mode2,
+      keyPrefix: process.env.ABLO_API_KEY ? process.env.ABLO_API_KEY.slice(0, 12) : entry?.apiKey.slice(0, 12) ?? null,
+      keySource: process.env.ABLO_API_KEY ? "env" : entry ? "stored" : null,
+      organizationId: entry?.organizationId ?? null,
+      apiUrl,
+      reachable: await ping(apiUrl)
+    };
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
   console.log(`
   ${brand("ablo")} ${import_picocolors9.default.dim("status")}
 `);
@@ -281685,7 +281699,7 @@ async function main() {
   } else if (command === "mode") {
     await mode(process.argv.slice(3));
   } else if (command === "status") {
-    await status();
+    await status(process.argv.slice(3));
   } else if (command === "logs") {
     await logs(process.argv.slice(3));
   } else if (command === "webhooks") {
@@ -281735,6 +281749,7 @@ async function main() {
     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 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)`);
     console.log(`    npx ablo webhooks create <url>         Register an outbound webhook endpoint (writes ABLO_WEBHOOK_SECRET)`);
     console.log(`    npx ablo webhooks list|roll|enable|rm  Manage webhook endpoints + delivery health`);

package/dist/client/Ablo.d.ts

@@ -23,6 +23,7 @@ import type { SyncEngineConfig, SyncLogger, MutationExecutor, MutationDispatcher
 import { ObjectPool } from '../ObjectPool.js';
 import type { SyncStoreContract } from '../react/context.js';
 import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
+import type { SyncGroupInput } from '../schema/roles.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
 import type { IntentStream, IntentWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
 import type { ParticipantManager } from '../sync/participants.js';
@@ -577,8 +578,11 @@ export interface CreateUserSessionParams {
     user: {
         id: string;
     };
-    /** Sync groups this session may subscribe to. Omit to inherit the key's scope. */
-    syncGroups?: readonly string[];
+    /** Sync groups this session may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`; build with `syncGroup.org()/user()/of()` from
+     *  `@abloatai/ablo/schema`). Omit for the server default:
+     *  `[org:<your org>, user:<user.id>]`. */
+    syncGroups?: readonly SyncGroupInput[];
     /** Token lifetime in seconds. Defaults to 900 (15m, the Stripe ephemeral default). */
     ttlSeconds?: number;
     /** Opaque identity blob echoed back to the client as `ablo.user`. */
@@ -599,8 +603,11 @@ export interface CreateAgentSessionParams<S extends SchemaRecord> {
     can: {
         [M in keyof S & string]?: readonly SessionOperation[];
     };
-    /** Sync groups this session may subscribe to. Omit to inherit the key's scope. */
-    syncGroups?: readonly string[];
+    /** Sync groups this session may subscribe to — typed (`'default'` or
+     *  `<namespace>:<id>`; build with `syncGroup.org()/user()/of()` from
+     *  `@abloatai/ablo/schema`). Omit for the server default: the org
+     *  anchor (`org:<your org>`) + the agent's own anchor. */
+    syncGroups?: readonly SyncGroupInput[];
     /** Token lifetime in seconds. Defaults to 900 (15m, the Stripe ephemeral default). */
     ttlSeconds?: number;
     /** Opaque identity blob echoed back to the client as `ablo.agent`. */
@@ -611,13 +618,14 @@ export interface CreateAgentSessionParams<S extends SchemaRecord> {
  *  `{ user }` for a full-authority end-user session (`ek_`) or `{ agent, can }`
  *  for a scoped agent session (`rk_`). */
 export type CreateSessionParams<S extends SchemaRecord> = CreateUserSessionParams | CreateAgentSessionParams<S>;
-/** A minted end-user session token — the Stripe ephemeral-key / Supabase
- *  session resource. `token` is the secret the browser presents as its bearer. */
+/** A minted session token — the Stripe ephemeral-key / Supabase session
+ *  resource. `token` is the secret the holder presents as its bearer. */
 export interface AbloSession {
     object: 'session';
     /** Stable id of the minted credential (for revocation). */
     id: string;
-    /** The short-lived `rk_` session token. Hand this to the user's browser. */
+    /** The short-lived session token — `ek_` for a `{ user }` session, `rk_`
+     *  for an `{ agent }` session. Hand this to the participant's runtime. */
     token: string;
     /** ISO-8601 expiry. */
     expiresAt: string;
@@ -716,17 +724,29 @@ export type Ablo<S extends SchemaRecord> = {
      * 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
-     * the scoped `rk_` token via `apiKeyProvider`.
+     * 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_`),
-     * or `{ agent: { id }, can: { Task: ['update'] } }` for a scoped agent
-     * session (mints `rk_`); `can` is typed against your schema's model names.
+     * Pass `{ user: { id } }` for a full-authority end-user session (mints `ek_`,
+     * `actor_kind: 'user'` attribution), 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.
      */
     sessions: {
         create(params: CreateSessionParams<S>): Promise<AbloSession>;
     };
+    /**
+     * The organization this client resolved to — `null` until `ready()`
+     * completes. Use it instead of scraping CLI output or hardcoding env vars:
+     *
+     * ```ts
+     * await ablo.ready();
+     * const org = ablo.organizationId; // 'org_…'
+     * ```
+     */
+    readonly organizationId: string | null;
     /**
      * Destroy every IndexedDB database owned by this engine. Disconnects
      * the WebSocket, releases timers, and deletes all `ablo_*` / `ablo-*`
@@ -810,16 +830,6 @@ export type Ablo<S extends SchemaRecord> = {
      * connection is rotated on `dispose()` but this object is the same.
      */
     readonly presence: PresenceStream;
-    /**
-     * @internal — the public coordination API is `ablo.<model>.claim`. This
-     * accessor is the internal stream `claim` is built on; it is NOT part of the
-     * supported public surface and will be moved off the public type (it currently
-     * stays only because internal SDK modules are still typed against it).
-     *
-     * Cooperative-mutex layer over presence — announce "I'm about to do X on Y" so
-     * peers can yield before colliding. Same socket as entity sync.
-     */
-    readonly intents: IntentResource;
     /**
      * Canonical low-level mutation API. Every untyped model write compiles
      * down to `commits.create(...)`.

package/dist/client/Ablo.js

@@ -25,7 +25,7 @@ import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
 import { alwaysOnline } from '../adapters/alwaysOnline.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
-import { exchangeApiKey } from '../auth/index.js';
+import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
 import { createAuthCredentialSource } from '../auth/credentialSource.js';
 import { createInternalComponents } from './createInternalComponents.js';
 import { resolveParticipantIdentity } from './identity.js';
@@ -860,6 +860,9 @@ export function Ablo(options) {
     //    source of truth. No duplicate closure variables.
     let _readyPromise = null;
     let _refreshScheduler = null;
+    /** Resolved account scope — set once identity resolution completes in
+     *  `ready()`; exposed as the readonly `ablo.organizationId` accessor. */
+    let _resolvedOrganizationId = null;
     async function ready() {
         if (_readyPromise)
             return _readyPromise;
@@ -942,6 +945,7 @@ export function Ablo(options) {
                         '`["org:${orgId}", "user:${userId}"]`) or verify your auth ' +
                         'provider populates them. See packages/sync-engine/src/client/identity.ts.', { participantKind, resolvedSyncGroups });
                 }
+                _resolvedOrganizationId = accountScope;
                 if (resolved.refreshScheduler) {
                     _refreshScheduler = resolved.refreshScheduler;
                 }
@@ -1505,6 +1509,16 @@ export function Ablo(options) {
             },
         };
     }
+    /**
+     * The CONTROL-PLANE credential: always the original configured secret key.
+     * Never reads `authCredentials` — that holds the exchanged sync credential
+     * (a wide-scope `rk_` on the hosted path), which control-plane routes
+     * rightly refuse (e.g. the user-session mint is sk_-gated). Counterpart to
+     * `getAuthToken()`, which resolves the sync-plane token.
+     */
+    async function controlPlaneApiKey() {
+        return resolveApiKeyValue(configuredApiKey);
+    }
     const engine = {
         ...modelProxies,
         ready,
@@ -1523,6 +1537,13 @@ export function Ablo(options) {
         async getAuthToken() {
             // The live short-lived bearer (set via `setAuthToken`/`getToken` refresh)
             // is the canonical credential; fall back to a configured API key.
+            //
+            // This is the SYNC-PLANE token (bootstrap, WS, query HTTP). Control-plane
+            // calls (sessions.create, datasource registration) never use it — they
+            // present the ORIGINAL secret key via `controlPlaneApiKey()` below. The
+            // split matters: after the startup exchange this resolver returns the
+            // derived wide-scope `rk_`, a credential the control-plane routes
+            // correctly refuse (an agent token must never mint humans).
             return (authCredentials.getAuthToken() ??
                 (await resolveApiKeyValue(configuredApiKey)) ??
                 configuredAuthToken ??
@@ -1531,15 +1552,26 @@ export function Ablo(options) {
         setCredentialRefresher(refresher) {
             store.setCredentialRefresher(refresher);
         },
+        // The org this client resolved to — null until `ready()` completes.
+        // Integrators previously had no programmatic way to learn it (the Pulse
+        // agent regex-scraped `ablo status` output); now it's a property.
+        get organizationId() {
+            return _resolvedOrganizationId;
+        },
         nudgeReconnect() {
             store.nudgeReconnect();
         },
         sessions: {
             // Stripe `ephemeralKeys.create` shape: a BACKEND (holding `sk_`) mints a
-            // short-lived scoped token for one end user OR one agent. Thin wrapper over
-            // the `/auth/capability` exchange, reshaped to a Stripe-style resource.
+            // short-lived scoped token for one end user OR one agent.
+            //
+            // CONTROL-PLANE CREDENTIAL RULE: both arms authenticate with the
+            // ORIGINAL secret key (`controlPlaneApiKey()`), never the wide-scope
+            // `rk_` the startup exchange installed as the sync credential. A derived
+            // agent credential silently replacing the secret key on control-plane
+            // calls is how humans get minted as agents — attribution is the product.
             async create(params) {
-                const apiKey = await resolveApiKeyValue(configuredApiKey);
+                const apiKey = await controlPlaneApiKey();
                 if (!apiKey) {
                     throw new AbloAuthenticationError('sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.', { code: 'apikey_missing' });
                 }
@@ -1547,30 +1579,53 @@ export function Ablo(options) {
                     url,
                     bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
                 });
-                // Discriminate the union: `{ user }` → full-authority `ek_` (no op
-                // allowlist); `{ agent, can }` → scoped `rk_`. `can: { Task: ['update'] }`
-                // serializes to the wire allowlist `['task.update']` — the Hub matches
-                // `${model.toLowerCase()}.${op}` (Hub.ts handleCommit).
-                let participantKind;
-                let participantId;
-                let operations;
+                // Discriminate the union onto the server's TWO mint doors:
+                //   `{ user }`  → POST /auth/ephemeral-keys → `ek_` (sk_-gated; the
+                //                 user-session door). Routing this arm through
+                //                 /auth/capability is structurally impossible — that
+                //                 route rejects participantKind 'user' outright
+                //                 (`invalid_participant_kind`, the 2026-06-11 Pulse
+                //                 cascade: the SDK's own blessed pattern 403'd and
+                //                 integrators fell back to minting humans as agents).
+                //   `{ agent }` → POST /auth/capability → scoped `rk_`.
+                //                 `can: { tasks: ['update'] }` serializes to the wire
+                //                 allowlist (`tasks.update`); the Hub matches it
+                //                 against every registered alias of the model.
                 if (params.user) {
-                    participantKind = 'user';
-                    participantId = params.user.id;
-                    operations = undefined;
-                }
-                else {
-                    participantKind = 'agent';
-                    participantId = params.agent.id;
-                    operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
+                    const res = await mintUserSessionKey({
+                        apiKey,
+                        baseUrl,
+                        userId: params.user.id,
+                        ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+                        ttlSeconds: params.ttlSeconds ?? 900,
+                        ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
+                    });
+                    return {
+                        object: 'session',
+                        id: res.id,
+                        token: res.token,
+                        expiresAt: res.expiresAt,
+                        organizationId: res.organizationId,
+                        // The ephemeral mint stores scope on the key row; reshape its flat
+                        // response into the session resource's scope block.
+                        scope: {
+                            organizationId: res.organizationId,
+                            syncGroups: res.syncGroups,
+                            operations: [],
+                            participantKind: 'user',
+                            participantId: res.participantId,
+                        },
+                        userMeta: params.userMeta ?? { id: res.participantId },
+                    };
                 }
+                const operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
                 const res = await exchangeApiKey({
                     apiKey,
                     baseUrl,
-                    participantKind,
-                    participantId,
+                    participantKind: 'agent',
+                    participantId: params.agent.id,
                     ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
-                    ...(operations ? { operations } : {}),
+                    operations,
                     ttlSeconds: params.ttlSeconds ?? 900,
                     ...(params.userMeta ? { userMeta: params.userMeta } : {}),
                     ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),

package/dist/errorCodes.d.ts

@@ -316,6 +316,7 @@ export declare const ERROR_CODES: {
     readonly invalid_request: ErrorCodeSpec;
     readonly capability_not_found: ErrorCodeSpec;
     readonly invalid_participant_kind: ErrorCodeSpec;
+    readonly invalid_sync_group: ErrorCodeSpec;
     readonly narrow_scope_required: ErrorCodeSpec;
     readonly wide_scope_forbidden: ErrorCodeSpec;
     readonly capability_required: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -338,6 +338,7 @@ export const ERROR_CODES = {
     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.'),

package/dist/react/AbloProvider.d.ts

@@ -88,8 +88,6 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
      * Sentry/Datadog. React-only consumers can use `useErrorListener()` instead.
      */
     onError?: (error: Error) => void;
-    /** @internal placeholder so the old WS-URL prop shape doesn't silently leak in. */
-    url?: never;
     /**
      * Rendered in place of `children` during the *first* bootstrap pass —
      * while the engine is actively transitioning from `initial` →

package/dist/schema/index.d.ts

@@ -17,7 +17,7 @@
  *   }),
  * });
  *
- * type Task = InferModel<typeof schema, 'tasks'>;
+ * type Task = Model<typeof schema, 'tasks'>;
  * ```
  */
 export { z } from 'zod';
@@ -29,7 +29,7 @@ export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syn
 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 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, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, 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, } 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';

package/dist/schema/index.js

@@ -17,7 +17,7 @@
  *   }),
  * });
  *
- * type Task = InferModel<typeof schema, 'tasks'>;
+ * type Task = Model<typeof schema, 'tasks'>;
  * ```
  */
 // Re-export Zod for convenience (consumers can also import directly)
@@ -46,7 +46,7 @@ export { model, scopeKindOf, } from './model.js';
 // falls back to sensible defaults. See sugar.ts for the full pattern.
 export { mutable, readOnly } from './sugar.js';
 // Schema definition + type inference
-export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
 // Schema ⇄ JSON (control-plane transport for hosted multi-tenant)
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // Schema projection — derive an app's subset from one canonical schema.

package/dist/schema/roles.d.ts

@@ -35,6 +35,24 @@ export type SyncGroup = z.infer<typeof syncGroupSchema>;
  * it changes here and nowhere else.
  */
 export declare function syncGroup(kind: string, id: string): SyncGroup;
+/**
+ * Caller-facing input form of a sync group. Accepts a constructor-minted
+ * {@link SyncGroup}, a contextually-typed template literal of the right shape
+ * (`` `org:${orgId}` `` checks without importing the constructor), or the
+ * server-reserved `'default'` anchor. A bare colon-less string is a COMPILE
+ * error — it would subscribe to nothing and fail silently (the `['default']`
+ * zero-fan-out ghost made flesh).
+ */
+export type SyncGroupInput = SyncGroup | `${string}:${string}` | 'default';
+/**
+ * Runtime gate for {@link SyncGroupInput} at parse boundaries (capability
+ * mint, ephemeral-key mint). One schema, every door — a malformed group is
+ * rejected loudly (`invalid_sync_group`) instead of stored and silently
+ * subscribed-to-nothing.
+ */
+export declare const syncGroupInputSchema: z.ZodUnion<readonly [z.ZodLiteral<"default">, z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">]>;
+/** Runtime guard matching {@link SyncGroupInput}. */
+export declare function isSyncGroupInput(value: unknown): value is SyncGroupInput;
 /** Validates how a role pulls ids out of a context (identity or record). */
 export declare const roleSourceSchema: z.ZodObject<{
     field: z.ZodString;

package/dist/schema/roles.js

@@ -39,6 +39,17 @@ export const syncGroupSchema = z
 export function syncGroup(kind, id) {
     return `${kind}:${id}`;
 }
+/**
+ * Runtime gate for {@link SyncGroupInput} at parse boundaries (capability
+ * mint, ephemeral-key mint). One schema, every door — a malformed group is
+ * rejected loudly (`invalid_sync_group`) instead of stored and silently
+ * subscribed-to-nothing.
+ */
+export const syncGroupInputSchema = z.union([z.literal('default'), syncGroupSchema]);
+/** Runtime guard matching {@link SyncGroupInput}. */
+export function isSyncGroupInput(value) {
+    return syncGroupInputSchema.safeParse(value).success;
+}
 // ── Role source ─────────────────────────────────────────────────────────────
 /** Validates how a role pulls ids out of a context (identity or record). */
 export const roleSourceSchema = z.object({

package/dist/schema/schema.d.ts

@@ -23,7 +23,7 @@ import { z } from 'zod';
 import type { ModelDef, RelationRecord } from './model.js';
 import type { RelationDef } from './relation.js';
 import type { IdentityRole } from './roles.js';
-export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './roles.js';
+export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './roles.js';
 /** The set of built-in casing conventions supported by `defineSchema`. */
 export type CasingConvention = 'snake_case' | 'camelCase';
 /** Plug point for custom conventions (e.g. mixed legacy databases). */
@@ -115,6 +115,29 @@ export interface Schema<S extends SchemaRecord = SchemaRecord> {
  * type Task = InferModel<typeof schema, 'tasks'>;
  * ```
  */
+/** The schema bound via `declare module … interface Register { Schema: … }`
+ *  (the `ablo.d.ts` the scaffold writes). `never` when not registered. */
+type RegisteredSchema = import('../types/global.js').Register extends {
+    Schema: infer S extends Schema;
+} ? S : never;
+/**
+ * THE model type helper. With the scaffold's `ablo.d.ts` registration in
+ * place, one parameter is all it takes:
+ *
+ * ```ts
+ * type Task = Model<'tasks'>;
+ * ```
+ *
+ * Without registration (or for a second schema), pass the schema explicitly:
+ * `Model<typeof schema, 'tasks'>`.
+ */
+export type Model<A, B = never> = [B] extends [never] ? A extends keyof RegisteredSchema['models'] ? InferModel<RegisteredSchema, A> : never : A extends Schema ? InferModel<A, B extends keyof A['models'] ? B : never> : never;
+/**
+ * @deprecated Use {@link Model} — `type Task = Model<typeof schema, 'tasks'>`
+ * reads as the domain ("the Task model from my schema"), not the machinery.
+ * Drizzle deprecated its own `InferModel` for the same reason. Kept as an
+ * alias; no behavior difference.
+ */
 export type InferModel<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape, infer R, infer C> ? z.infer<z.ZodObject<Shape>> & BaseModelFields & BaseModelMethods & InferComputed<C> & InferRelations<S, R> : never;
 /**
  * Infer relation accessor types from a model's relations record.

package/dist/schema/schema.js

@@ -25,7 +25,7 @@ import { scopeSchema, grantsRefSchema } from './roles.js';
 // Sync-group roles (identity + entity) live in `./roles.js`. Re-exported here
 // so the long-standing `@ablo/schema` / `./schema.js` import paths keep working
 // after the rehome — see roles.ts for the full vocabulary.
-export { identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './roles.js';
+export { identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './roles.js';
 function resolveCasing(fn) {
     if (fn === undefined)
         return (x) => x;

package/dist/server/storage-mode.d.ts

@@ -1,24 +1 @@
-/**
- * `@abloatai/ablo/server` — the storage-mode vocabulary the `DataAdapter`
- * contract supports. Analogous to Better Auth's adapter `id`/`adapterId`: a
- * diagnostic discriminator on the adapter, NOT a routing switch (routing goes
- * through the resolver/factory). The package owns this enum so the contract and
- * every host adapter agree on the closed set:
- *   - `hosted`     — Ablo's control-plane database.
- *   - `selfHosted` — the customer's database, same execution path as hosted.
- *   - `source`     — a customer-owned endpoint (credentialless ingestion).
- *
- * @internal Deployment topology, not product vocabulary. Customers never see a
- * "storage mode" — their story is `Ablo({ schema, apiKey, databaseUrl })` and
- * one `datasource` resource (docs/plans/sync-engine-stripe-story-scope.md).
- * This export exists for the sync-server host only.
- */
-import { z } from 'zod';
-/** @internal See module note — host-deployment vocabulary, never customer-facing. */
-export declare const storageModeSchema: z.ZodEnum<{
-    source: "source";
-    hosted: "hosted";
-    selfHosted: "selfHosted";
-}>;
-/** @internal See module note — host-deployment vocabulary, never customer-facing. */
-export type StorageMode = z.infer<typeof storageModeSchema>;
+export {};

package/docs/api-keys.md

@@ -23,6 +23,22 @@ Use API keys from trusted (server-side) runtimes:
 
 Never ship a secret API key to a browser bundle.
 
+## Publishable key (`pk_`) — browser-safe, read-only
+
+For a read-only browser experience, a publishable key is safe to ship in the
+bundle. Like a Stripe `pk_` or a Supabase anon key, it is long-lived,
+org-scoped, and used **directly as the bearer** — never exchanged, never
+expires, nothing to refresh:
+
+```ts
+const ablo = Ablo({ apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY }); // pk_live_…
+```
+
+A `pk_` grants **read-only** access to the org's data plane: it cannot write and
+cannot reach any control-plane operation. The moment the browser needs to write
+on a specific user's behalf, mint a short-lived `ek_` user session from your
+backend instead (see the Sessions guide).
+
 ## Sandboxes and production
 
 Test and live keys are the same shape; the prefix names the environment:

package/docs/quickstart.md

@@ -50,6 +50,29 @@ export const schema = defineSchema({
 });
 ```
 
+
+Register the schema once (init scaffolds this `ablo.d.ts`), and every type
+is one parameter away — no `typeof schema` re-stating, anywhere:
+
+```ts
+// ablo.d.ts — once per project
+import type { schema } from './ablo/schema';
+declare module '@abloatai/ablo' {
+  interface Register { Schema: typeof schema }
+}
+export {};
+```
+
+```ts
+import type { Model } from '@abloatai/ablo/schema';
+
+type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
+```
+
+(The same `Register` binding types every hook and client — it's the
+TanStack-Router pattern: declare the source of truth once, everything
+infers from it.)
+
 ## 3. Point Ablo at your database
 
 The client takes your schema, your key, and your `DATABASE_URL`. On first

package/llms-full.txt

@@ -19,6 +19,9 @@ Public imports:
 - `@abloatai/ablo/react` — React provider and hooks.
 - `@abloatai/ablo/testing` — test harnesses and mocks.
 
+TYPES: have the project register its schema ONCE via declaration merging (init scaffolds `ablo.d.ts`): `declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema.
+
+
 Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or `internal/*` as public imports. The Data Source surface — `/source`, `/source/next`, `/source/drizzle`, `/source/kysely`, `/source/conformance` — IS public (it's how a customer-owned database is wired).
 
 The canonical integration doc is `integration-guide`. It explains the end-to-end

package/llms.txt

@@ -20,6 +20,9 @@ Then PUSH — this is the step everything depends on. The server keeps its OWN c
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
+TYPES: have the project register its schema ONCE via declaration merging (init scaffolds `ablo.d.ts`): `declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema.
+
+
 const schema = defineSchema({
   weatherReports: model({
     id: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",