@abloatai/ablo 0.11.1 → 0.12.0

package/dist/cli.cjs

@@ -276804,6 +276804,7 @@ var ERROR_CODES = {
   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 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."),
@@ -277119,7 +277121,9 @@ var modelClaimSchema = import_zod3.z.object({
   id: import_zod3.z.string(),
   actor: import_zod3.z.string(),
   participantKind: wireParticipantKindSchema,
-  action: import_zod3.z.string(),
+  /** Human-readable phase (`'editing'`). The public SDK field; the WS/HTTP
+   *  wire carries the same value as `action` (healed on read). */
+  reason: import_zod3.z.string(),
   description: import_zod3.z.string().optional(),
   field: import_zod3.z.string().optional(),
   status: import_zod3.z.enum(["active", "queued"]).optional(),
@@ -279616,6 +279620,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 +279949,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")}).`
@@ -280223,7 +280244,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.`
@@ -281052,7 +281073,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);
   }
@@ -282922,9 +282943,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.
+     * 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.
      */
-    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)`.
-     */
-    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
@@ -353,8 +332,14 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     configOverrides?: Partial<SyncEngineConfig>;
     /**
-     * @deprecated Server derives sync groups from the apiKey's scope.
-     * Required today as a runtime holdover; removed once Phase 3 ships.
+     * Sync groups (entity scopes) this client subscribes to. **Provisional, not
+     * deprecated** — pick the right lane: normally the server derives these from
+     * the apiKey's scope, but passing them is still REQUIRED today in any config
+     * where the key doesn't resolve them (omitting yields a `degenerate
+     * syncGroups` warning and a zero-fan-out client). Keep passing it explicitly
+     * until the server-derived path ships in Phase 3, at which point it becomes a
+     * true no-op and is removed. Build values with `syncGroup(kind, id)` from
+     * `@abloatai/ablo/schema`.
      */
     syncGroups?: string[];
     /**
@@ -385,8 +370,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,30 +379,24 @@ 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 {
 }
 export interface ClaimCreateOptions {
     readonly target: ModelTarget;
-    readonly action: string;
+    /** Human-readable phase shown to peers — `'editing'`, `'writing'`. The same
+     *  word on every claim surface; serialized on the wire as `action`. */
+    readonly reason: string;
     readonly ttl?: Duration;
     /**
      * Join the server's fair FIFO queue when the target is already claimed,
@@ -519,6 +498,20 @@ export interface HttpClaimApi<T> {
     reorder(params: ClaimReorderParams<T>): Promise<void>;
 }
 export interface ModelClient<T = Record<string, unknown>> {
+    /**
+     * Single-row read over HTTP. **Returns an envelope, not the bare row** — the
+     * row is on `.data`, alongside the `.stamp` watermark (for stale-context
+     * guards on the following write) and any active `.claims`. A stateless HTTP
+     * client can't synthesize the watermark from a local snapshot, so the
+     * envelope is load-bearing here (the WebSocket client's `retrieve` returns
+     * `T | undefined` because it reads from the hydrated pool).
+     *
+     * ```ts
+     * const deal = await ablo.deals.retrieve({ id });
+     * deal.data?.recommendation;   // ← the row is on .data
+     * deal.stamp;                  // watermark — pass to the next write's readAt
+     * ```
+     */
     retrieve(params: ModelReadOptions & {
         readonly id: string;
     }): Promise<ModelRead<T>>;
@@ -527,7 +520,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 +553,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 +578,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 +660,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 +668,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 +678,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 +696,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 +816,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 +967,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 {