@abloatai/ablo 0.25.0 → 0.26.0

package/dist/client/Ablo.d.ts

@@ -5,7 +5,7 @@
  * bootstrap, offline queue, DI adapters) behind a single function call.
  *
  * Usage:
- *   import { Ablo } from '@abloatai/ablo/client';
+ *   import { Ablo } from '@abloatai/ablo';
  *   import { schema } from './schema';
  *
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
@@ -18,712 +18,22 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
-import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
-import type { SyncEngineConfig, SyncLogger, MutationExecutor, MutationDispatcher, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
 import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
 export type { ModelTarget, ModelClaim };
 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 { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
-import type { ClaimStream, ClaimWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
-import type { Claim, HeldClaim, Duration } from '../types/streams.js';
+import type { PresenceStream, Snapshot } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiClaims } from './ApiClient.js';
 import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
-/**
- * Async function that resolves an apiKey at request time. Use for
- * credential rotation — rotate from a vault, refresh from session
- * storage, or pull from a Better Auth session. Mirrors Anthropic's
- * `ApiKeySetter` exactly so any rotation pattern that works with
- * `@anthropic-ai/sdk` works here.
- *
- * Re-exported from `./auth` so existing import paths (`@abloatai/ablo`)
- * keep resolving; the canonical definition lives there alongside the
- * resolvers that consume it.
- */
-export type { ApiKeySetter } from './auth.js';
-import type { ApiKeySetter } from './auth.js';
-import { type AbloPersistence } from './persistence.js';
-/**
- * Options for `Ablo({...})`.
- *
- * The only required field is `schema`. The default path is one line:
- *
- * ```ts
- * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * ```
- *
- * `apiKey` itself defaults to `process.env.ABLO_API_KEY`, so in most
- * server setups `Ablo({ schema })` is enough. Every other field is
- * optional tuning (timeouts, retries, custom fetch, persistence) —
- * if you're not sure whether you need one, you don't. Reach for them
- * the way you'd reach for the equivalent option on the Stripe / OpenAI
- * / Anthropic clients: rarely, and deliberately.
- *
- * @see https://docs.abloatai.com — full option reference
- */
-export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
-    /**
-     * TypeScript schema defined with `defineSchema()`. Required — it's what
-     * makes `ablo.weatherReports.update(...)` typed. This is the one field you must
-     * pass; start here.
-     */
-    schema: Schema<S>;
-    /**
-     * API key — **the one auth field most apps set.** Server-side this is your
-     * secret `sk_` (and it defaults to `process.env['ABLO_API_KEY']`, so you
-     * 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 | null>` resolver
-     * — the single credential path. Use the resolver form for two cases:
-     *
-     *  - **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).
-     *
-     * 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.
-     */
-    apiKey?: string | ApiKeySetter | null | undefined;
-    /**
-     * @deprecated The direct connector lets Ablo dial INTO your Postgres and write to
-     * it — the operate-their-database posture we are moving off. Ablo is Stripe-shaped:
-     * it hosts only the transaction log (the ordered sync_deltas) + coordination, never
-     * your data; your rows always live in your own database. Use the signed Data Source
-     * endpoint instead — keep `DATABASE_URL` in your app, expose `dataSource(...)`, and
-     * let your server own the write while Ablo coordinates the sync stream. To keep the
-     * log in your infra too, self-host the engine. See
-     * docs/plans/stripe-shaped-storage-posture.md.
-     *
-     * Still honored at runtime for back-compat. SERVER-ONLY: it carries credentials, so
-     * it is never sent from the browser — constructing a client with `databaseUrl` and
-     * `dangerouslyAllowBrowser` throws. If you use it, provide a NON-superuser,
-     * non-`BYPASSRLS` role; the connector rejects privileged roles that cannot enforce RLS.
-     */
-    databaseUrl?: string | null | undefined;
-    /**
-     * Local persistence mode. Pass `indexeddb` only when you want offline
-     * queueing and a reload-surviving browser cache.
-     *
-     * @default 'memory'
-     */
-    persistence?: AbloPersistence;
-    /**
-     * Transport selector. `'websocket'` (default) is the live client —
-     * persistent socket, local synced pool, `onChange` subscriptions. `'http'`
-     * returns the STATELESS client for server-side actors (agents, workers,
-     * serverless): same `ablo.<model>` surface and coordination plane, but each
-     * call is one HTTP round-trip, identity rides the Bearer credential, and no
-     * socket is ever opened. With `'http'` the return type narrows to
-     * `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;
-    /**
-     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
-     * coordination trace — claims requested / queued / granted / released, agent
-     * handovers, connection state — so you can SEE the human+agent coordination
-     * you built while debugging. Omitted/`false` keeps the quiet default (only
-     * warnings + errors). For a middle ground use {@link logLevel}. Env override:
-     * `ABLO_LOG_LEVEL`. Ignored if a custom logger is supplied.
-     */
-    debug?: boolean | undefined;
-    /**
-     * Log threshold for the default `[Ablo]` logger (takes precedence over
-     * {@link debug}). `'info'` = coordination + connection events without the
-     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
-     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
-     */
-    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined;
-    /**
-     * Bearer auth token. Hosted-cloud consumers pass `apiKey`; self-hosted
-     * deployments may pass a bearer token minted by their own auth layer.
-     */
-    authToken?: string | null | undefined;
-    /**
-     * Override the Ablo API base URL. Defaults to hosted production.
-     */
-    baseURL?: string | null | undefined;
-    /** Custom fetch implementation for tests, proxies, or non-standard runtimes. */
-    fetch?: typeof fetch | undefined;
-    /** Default headers sent with every API request. */
-    defaultHeaders?: Record<string, string | null | undefined> | undefined;
-    /** Default query parameters sent with every API request. */
-    defaultQuery?: Record<string, string | undefined> | undefined;
-    /**
-     * Client-side use is disabled by default because private API keys should
-     * not ship to browsers. Set this only when the browser holds a minted
-     * session token (`ek_`/`rk_`) or you route through a controlled server proxy.
-     */
-    dangerouslyAllowBrowser?: boolean | undefined;
-}
-export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
-    /**
-     * API key used for authentication.
-     *
-     * Accepts a static string (`sk_live_...`) or an async function that
-     * resolves to one. Defaults to `process.env['ABLO_API_KEY']`.
-     *
-     * When a function is provided, it's invoked before each request so
-     * you can rotate or refresh credentials at runtime. The function
-     * must return a non-empty string; otherwise an `AbloAuthenticationError`
-     * is thrown. If the function throws, the error is wrapped with the
-     * original available as `cause`.
-     *
-     * Mirrors Anthropic / OpenAI / Stripe SDK shape exactly.
-     */
-    apiKey?: string | ApiKeySetter | null | undefined;
-    /**
-     * Bearer auth token. Sent as `Authorization: Bearer <token>` on
-     * every request.
-     *
-     * Use this for self-hosted deployments where your auth layer mints
-     * cap tokens directly. Hosted-cloud consumers pass `apiKey` instead;
-     * the server handles cap-mint internally.
-     */
-    authToken?: string | null | undefined;
-    /**
-     * Override the default base URL. Defaults to
-     * `wss://api.abloatai.com` for hosted production; pass an explicit
-     * URL for self-hosted or private deployments.
-     */
-    baseURL?: string | null | undefined;
-    /**
-     * Custom `fetch` implementation. Defaults to `globalThis.fetch`.
-     * Override for testing, custom transports, or runtime shims.
-     */
-    fetch?: typeof fetch | undefined;
-    /**
-     * Default headers to include with every request to the API.
-     * Removed per-request by setting the header to `null` in request
-     * options.
-     */
-    defaultHeaders?: Record<string, string | null | undefined> | undefined;
-    /**
-     * Default query parameters to include with every request.
-     * Removed per-request by setting the param to `undefined`.
-     */
-    defaultQuery?: Record<string, string | undefined> | undefined;
-    /**
-     * Client-side use of this SDK is disabled by default — your apiKey
-     * would ship to every visitor's network tab. Only set this to
-     * `true` if you've understood the risk and have appropriate
-     * mitigations (a minted session token, a server-side proxy, etc).
-     */
-    dangerouslyAllowBrowser?: boolean | undefined;
-    /**
-     * TypeScript schema defined with `defineSchema()`.
-     *
-     * The root `Ablo(...)` client is schema-first so consumers get typed
-     * model clients such as `ablo.weatherReports.update(...)`. Omit `schema`
-     * only for the advanced Model / Claim / Commit client.
-     */
-    schema: Schema<S>;
-    /**
-     * @deprecated Server derives participant kind from the apiKey's
-     * scope. Pass apiKey only; this option will be removed once the
-     * server-internal cap-mint flow lands.
-     */
-    kind?: 'user' | 'agent' | 'system';
-    /**
-     * @deprecated Server derives user identity from the apiKey's
-     * scope (or from `Ablo-Acting-User` request header for B2B2C).
-     * Removed once Phase 3 ships.
-     */
-    user?: {
-        id: string;
-        teamIds?: string[];
-    };
-    /**
-     * @deprecated Server derives agent identity from the apiKey's
-     * scope. Removed once Phase 3 ships.
-     */
-    agentId?: string;
-    /**
-     * @deprecated Cap-mint moves server-internal in Phase 3. Pass
-     * `apiKey` only; the server handles capability issuance.
-     */
-    capabilityToken?: string;
-    /** Custom logger (default: console). Supplying one bypasses {@link debug}/{@link logLevel}. */
-    logger?: SyncLogger;
-    /**
-     * Turn Ablo's diagnostic logging on/off. `true` surfaces the `[Ablo]`
-     * coordination trace — claims acquired / queued / granted / released, agent
-     * handovers, connection state — plus internal lifecycle, so you can SEE the
-     * human+agent coordination you built. Omitted/`false` keeps the quiet default
-     * (only warnings + errors). For a middle ground use {@link logLevel}.
-     * Env override: `ABLO_LOG_LEVEL`. Ignored if a custom {@link logger} is passed.
-     */
-    debug?: boolean;
-    /**
-     * Log threshold for the default `[Ablo]` logger (takes precedence over
-     * {@link debug}). `'info'` = coordination + connection events without the
-     * per-model registration firehose; `'debug'` = everything; `'warn'` (default)
-     * = warnings + errors only; `'silent'` = nothing. Env override: `ABLO_LOG_LEVEL`.
-     */
-    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
-    /** ObjectPool size limit (default: 10000) */
-    maxPoolSize?: number;
-    /**
-     * Local persistence mode. Defaults to `memory` so Ablo behaves like a
-     * point solution for shared state instead of silently bolting IndexedDB
-     * durability onto every browser consumer.
-     *
-     * Pass `persistence: 'indexeddb'` only when you want offline queueing
-     * and a reload-surviving local cache in a browser.
-     */
-    persistence?: AbloPersistence;
-    /** @deprecated Use `persistence: 'indexeddb'` for durable browser storage. */
-    offline?: boolean;
-    /**
-     * @deprecated Internal/testing escape hatch. Use `persistence` in
-     * production code. `true` maps to `memory`; `false` maps to
-     * `indexeddb` in browsers.
-     */
-    inMemory?: boolean;
-    /**
-     * If true, initialization starts immediately in the background so
-     * `sync.reports.findMany()` works after `await sync.ready()`.
-     *
-     * If false (default), the consumer MUST call `await sync.ready()` before
-     * using the engine — any query before that returns empty results.
-     *
-     * Default: false (explicit is better — prevents silent init failures).
-     */
-    autoStart?: boolean;
-    /**
-     * How aggressively this client should pull baseline state at
-     * startup.
-     *
-     *  - `'full'`: pull every delta in the configured sync groups before
-     *    `ready()` resolves. Default for `kind: 'user'`.
-     *  - `'none'`: open the WS and process live deltas only — no baseline
-     *    fetch. Reads round-trip via `model.retrieve()`; subscriptions
-     *    populate the pool lazily via covering deltas. Default for
-     *    `kind: 'agent'` because agent-worker / routine runners don't
-     *    need (or want) a local replica of the org's tenant plane.
-     */
-    bootstrapMode?: 'full' | 'none';
-    /**
-     * Custom observability provider (Sentry, Honeycomb, OTel, etc.).
-     * Default: a noop implementation that drops all breadcrumbs and spans.
-     */
-    observability?: SyncObservabilityProvider;
-    /**
-     * Custom analytics provider (PostHog, Amplitude, Segment, etc.).
-     * Default: a noop implementation that drops all events.
-     */
-    analytics?: SyncAnalytics;
-    /**
-     * Detect whether an error from a mutation/bootstrap response means the
-     * user's session has expired. Used to surface re-auth prompts. Default:
-     * heuristic that matches `401 Unauthorized` and a few common error shapes.
-     */
-    sessionErrorDetector?: SessionErrorDetector;
-    /**
-     * Detect whether the browser is currently online. Default: reads
-     * `navigator.onLine` and listens to the `online`/`offline` events.
-     */
-    onlineStatus?: OnlineStatusProvider;
-    /**
-     * Replace the built-in `MutationExecutor` (which posts a hardcoded
-     * `commit` method against `${url}/graphql`) with one that uses your own
-     * GraphQL client, auth headers, retry policy, and observability hooks.
-     *
-     * Default: a fetch-based executor that targets `${url}/graphql` and sends
-     * the configured bearer (`apiKey` / backend-minted token) as `Authorization`.
-     */
-    mutationExecutor?: MutationExecutor;
-    /**
-     * Replace the built-in `MutationDispatcher` (used by the offline queue
-     * to replay mutations on reconnect). If you override `mutationExecutor`
-     * you almost always want to override this too so the two paths share
-     * the same auth/retry behavior.
-     *
-     * Default: a thin dispatcher that routes to the built-in executor.
-     */
-    mutationDispatcher?: MutationDispatcher;
-    /**
-     * Partial overrides for the auto-derived `SyncEngineConfig`. Merged on
-     * top of `deriveConfigFromSchema(schema)`. Use this when you need
-     * specific `modelCreatePriority`, `batchableModels`, or
-     * `essentialFields` settings that the schema cannot express.
-     */
-    configOverrides?: Partial<SyncEngineConfig>;
-    /**
-     * 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[];
-    /**
-     * Override the bootstrap endpoint base URL. Use this when your sync
-     * server's HTTP API lives on a different host than the WebSocket URL.
-     *
-     * Must include the `/api` prefix — `BootstrapHelper` appends
-     * `/sync/bootstrap` directly. Example:
-     * `'http://api.example.com/api'` → `http://api.example.com/api/sync/bootstrap`.
-     *
-     * Default: `${url.replace(/^ws/, 'http')}/api`.
-     */
-    bootstrapBaseUrl?: string;
-    /**
-     * Ablo-owned account scope. Required for Branch 3 identity resolution
-     * in `identity.ts` — without it the SDK falls through to the
-     * `/api/identity` HTTP-derived path (Branch 2).
-     */
-    organizationId?: string;
-}
-/**
- * Operations available on each model in the sync engine.
- *
- * Naming aligns with Stripe / OpenAI / Anthropic conventions:
- *   `retrieve({ id })` — async single-row server read
- *   `list({ where })` — async collection server read
- *   `get(id)` / `getAll(...)` / `getCount(...)` — local graph snapshots
- *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
- *   `claim({ id })` — durable claim handle for coordinated writes
- */
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, HeldClaim, ModelOperations, } from './createModelProxy.js';
-import type { ModelOperations, ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod, ServerReadOptions } from './createModelProxy.js';
-export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
-export type CommitWait = 'queued' | 'confirmed';
-export interface ModelRead<T = Record<string, unknown>> {
-    /**
-     * The row, or `undefined` when no row matched the id (or it's outside the
-     * caller's scope). A miss is data-absence, not an error — `retrieve` never
-     * throws "not found", mirroring the WebSocket client's `T | undefined`.
-     * Branch on it: `const deal = (await ablo.deals.retrieve({ id })).data; if (!deal) …`.
-     */
-    readonly data: T | undefined;
-    readonly stamp: number;
-    readonly claims: readonly ModelClaim[];
-}
-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; `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;
-}
-export type { ClaimWaitOptions } from '../types/streams.js';
-export interface ModelReadOptions extends ClaimedOptions {
-}
-export interface ClaimCreateOptions {
-    readonly target: ModelTarget;
-    /** Human-readable phase shown to peers — `'editing'`, `'writing'`. The same
-     *  word on every claim surface. */
-    readonly reason: string;
-    readonly ttl?: Duration;
-    /**
-     * Join the server's fair FIFO queue when the target is already claimed,
-     * rather than failing immediately. `create` then resolves only once the
-     * lease is actually ours (the server pushes `claim_acquired` if the target
-     * was free, or `claim_granted` when we reach the head of the line). Without
-     * this, a contended claim throws. Used by `ablo.<model>.claim` so writers
-     * serialize instead of racing.
-     */
-    readonly queue?: boolean;
-    /** Cap on how long to wait for a queued grant before rejecting. */
-    readonly waitTimeoutMs?: number;
-    /**
-     * Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of
-     * waiting if the queue is already `>= maxQueueDepth` when we join.
-     */
-    readonly maxQueueDepth?: number;
-}
-export interface CommitOperationInput {
-    readonly action: ModelOperationAction;
-    /** The model name — matches `ablo.<model>` and the schema's `model()`. */
-    readonly model?: string;
-    readonly target?: ModelTarget;
-    readonly id?: string | null;
-    readonly data?: Record<string, unknown> | null;
-    readonly transactionId?: string | null;
-    readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
-}
-export interface CommitCreateOptions {
-    readonly claimRef?: string | {
-        readonly id: string;
-    } | null;
-    readonly idempotencyKey?: string | null;
-    readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
-    /**
-     * A claim handle from `ablo.<model>.claim({ id })` (or the HTTP claim
-     * surface). Same vocabulary as the per-model writes: the handle's
-     * snapshot watermark becomes the batch `readAt` default and `onStale`
-     * defaults to `'reject'`, so a commit that follows a claim is guarded
-     * against concurrent edits without re-stating the watermark by hand.
-     * Explicit `readAt`/`onStale` on the options win.
-     */
-    readonly claim?: Claim<Record<string, unknown>> | null;
-    readonly operation?: CommitOperationInput;
-    readonly operations?: readonly CommitOperationInput[];
-    readonly wait?: CommitWait;
-    /**
-     * Batch-level read dependencies (the STORM "did anything I looked at change?"
-     * layer). Declare the rows (`{model,id,readAt,fields?}`) or sync groups
-     * (`{group,readAt}`, e.g. `deck:abc`) this batch was premised on; the server
-     * validates none moved since `readAt` and fires the entry's `onStale` over the
-     * batch. Distinct from the write-target `readAt` — this guards what you READ,
-     * not what you write.
-     */
-    readonly reads?: readonly ReadDependency[] | null;
-}
-export interface CommitReceipt {
-    readonly id: string;
-    readonly status: CommitWait;
-    readonly lastSyncId?: number;
-    /**
-     * Stale-context notifications (notify-instead-of-abort, non-coercion). Present
-     * only when this commit guarded a write with `onStale: 'notify' and
-     * the premise moved concurrently — the conflicting field's current value,
-     * handed back as data instead of a forced `AbloStaleContextError`. The engine
-     * surfaces state; the intelligent actor (agent or human) decides how to
-     * resolve. Also fires on `conflict:notified`.
-     */
-    readonly notifications?: readonly StaleNotification[];
-    /**
-     * Ids of UPDATE/DELETE targets in this commit that matched ZERO rows (the row
-     * doesn't exist, or is outside the caller's org). Present (non-empty) only
-     * when a write missed. Typed resource wrappers turn this into a loud
-     * `AbloNotFoundError`; a raw `commits.create` caller can inspect it directly.
-     */
-    readonly missingIds?: readonly string[];
-}
-export interface CommitResource {
-    create(options: CommitCreateOptions): Promise<CommitReceipt>;
-}
-export interface ClaimResource extends ClaimStream {
-    create(options: ClaimCreateOptions): Promise<Claim>;
-    list(target?: Partial<ModelTarget>): readonly ModelClaim[];
-    waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
-}
-export interface ModelMutationOptions extends ClaimedOptions {
-    readonly claimRef?: string | {
-        readonly id: string;
-    } | null;
-    readonly idempotencyKey?: string | null;
-    readonly readAt?: number | null;
-    readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
-    readonly wait?: CommitWait;
-    readonly claim?: Claim | ClaimOptions | null;
-}
-/**
- * The HTTP/stateless claim surface. Normal tools usually put `claim` directly
- * on the write (`update({ id, data, claim })`) and let the SDK release it. Use
- * this namespace for multi-step handles and coordination screens.
- *
- * Same surface as the reactive {@link ClaimApi}, but every read is a server
- * round-trip, so `state`/`queue`/`reorder` are **awaited** here (the WebSocket
- * client resolves them synchronously from its local pool — which is what lets
- * `useAblo((ablo) => ablo.x.claim.state({ id }))` work inside a React render; a
- * stateless client has no pool to read, so the `Promise` is unavoidable).
- *
- * Mechanically DERIVED from `ClaimReadApi` via {@link AwaitedClaimMethod} so the
- * two transports can never drift: the ONLY difference is the uniform `Promise`
- * wrapper that statelessness forces. `claim({ id })` is identical (already async
- * on both); `state`/`queue`/`reorder`/`release` are the awaited form.
- */
-export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<HeldClaim<T>>) & {
-    [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
-};
-export interface ModelClient<T = Record<string, unknown>> {
-    /**
-     * Single-row read over HTTP. **Returns an envelope, not the bare row** — the
-     * 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>>;
-    /**
-     * Collection read over HTTP (server round-trip). Equality `where`, `orderBy`,
-     * `limit`. Present on the stateless protocol client; the store-backed
-     * `.model(name)` accessor omits it (use the typed `ablo.<model>.list` there).
-     */
-    list?(options?: ServerReadOptions<T>): Promise<T[]>;
-    /**
-     * Create a row and return it — the confirmed, authoritative server row (with
-     * framework defaults like `createdAt`/`createdBy`), mirroring the WebSocket
-     * client's `create`. A re-create of an existing caller-supplied id is
-     * idempotent and returns the EXISTING row, not the input.
-     */
-    create(params: ModelMutationOptions & {
-        readonly data: Record<string, unknown>;
-        readonly id?: string | null;
-    }): Promise<T>;
-    update(params: ModelMutationOptions & {
-        readonly id: string;
-        readonly data: Record<string, unknown>;
-    }): Promise<CommitReceipt>;
-    /**
-     * Update under contention with a function of the latest state —
-     * `update(id, current => next)`, the `setState(prev => next)` of the data
-     * layer. The SDK reads the freshest row, runs your updater, writes it as a
-     * compare-and-swap against the row's watermark, and re-reads + re-runs on any
-     * concurrent write. No claim, no identity, no conflict codes surface: the
-     * write either lands or throws {@link AbloContentionError} once its reconcile
-     * budget is spent. Return `null`/`undefined` from the updater to skip the
-     * write (resolves to `undefined`).
-     */
-    update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<CommitReceipt | undefined>;
-    delete(params: ModelMutationOptions & {
-        readonly id: string;
-    }): Promise<CommitReceipt>;
-    /**
-     * Durable lease + FIFO wait-line over HTTP — coordination without a socket.
-     * Present on the stateless protocol client (`Ablo({ schema: null })` /
-     * `createAbloHttpClient`); the store-backed `.model(name)` accessor omits it
-     * (the typed `ablo.<model>.claim` proxy is the full reactive namespace there).
-     */
-    claim?: HttpClaimApi<T>;
-}
-/** A single data operation a scoped **agent** session may perform on a model. */
-export type SessionOperation = 'read' | 'create' | 'update' | 'delete';
-/** Mint params for an **end-user** session — full data authority within the
- *  org (the Stripe `ephemeralKeys.create` / Supabase session shape). Mints an
- *  `ek_` token. `user.id` is your end user's external IdP id (becomes the
- *  session's `participantId`); Ablo does not model your users, so it's an
- *  honest string at the trust boundary. */
-export interface CreateUserSessionParams {
-    /** Your end user. `id` becomes the token's `participantId`. */
-    user: {
-        id: string;
-    };
-    /** Mint the session into THIS organization instead of the key's own org — the
-     *  Stripe Connect `Stripe-Account` pattern, for a platform serving many tenants
-     *  from one backend. Requires the `sk_` to carry the `ephemeral:mint-any-org`
-     *  scope; omit for the normal single-tenant case. */
-    organizationId?: string;
-    /** Sync groups this session may subscribe to — typed (`'default'` or
-     *  `<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[];
-    /** 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`. */
-    userMeta?: Record<string, unknown>;
-    agent?: never;
-    can?: never;
-}
-/** Mint params for a scoped **agent** session — mints a restricted `rk_` token
- *  gated to exactly the operations named in `can`. `can` is typed off your
- *  schema (no magic `'task.update'` strings): `{ Task: ['update'], Deck: ['read'] }`
- *  — the SDK serializes each entry to the wire allowlist (`task.update`). */
-export interface CreateAgentSessionParams<S extends SchemaRecord> {
-    /** Your agent. `id` becomes the token's `participantId`. */
-    agent: {
-        id: string;
-    };
-    /** Per-model operation allowlist, typed against the schema's model names. */
-    can: {
-        [M in keyof S & string]?: readonly SessionOperation[];
-    };
-    /** Sync groups this session may subscribe to — typed (`'default'` or
-     *  `<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[];
-    /** 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`. */
-    userMeta?: Record<string, unknown>;
-    user?: never;
-}
-/** Params for {@link Ablo.sessions}.create — a discriminated union: pass
- *  `{ 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>;
-/** Params for {@link Ablo.agents}.create — a flattened agent descriptor (no
- *  `{ agent }` discriminator: `agents.create` only ever mints an agent). Unlike
- *  {@link CreateSessionParams} it resolves to a connected, scoped {@link Ablo}
- *  client rather than a raw token. */
-export interface CreateAgentClientParams<S extends SchemaRecord> {
-    /** Wire participant identity (`agent:<id>`) — what claim exclusion and the
-     *  FIFO queue gate on. OMIT to get a fresh `crypto.randomUUID()`: a distinct,
-     *  independent participant (the default, and what you want for concurrent
-     *  agents). Pass a STABLE string only when one logical agent must re-attach
-     *  to its own held claims across reconnects/restarts. */
-    id?: string;
-    /** Human-readable label for logs / attribution (carried in `userMeta.name`).
-     *  INDEPENDENT of `id`: two agents that share a `name` still receive distinct
-     *  ids and coordinate as SEPARATE participants — `name` never derives or
-     *  collapses identity. */
-    name?: string;
-    /** Per-model operation allowlist, typed against the schema's model names. */
-    can: {
-        [M in keyof S & string]?: readonly SessionOperation[];
-    };
-    /** Sync groups this agent may subscribe to — typed (`'default'` or
-     *  `<namespace>:<id>`). Omit for the server default (org anchor + the
-     *  agent's own anchor). */
-    syncGroups?: readonly SyncGroupInput[];
-    /** Token lifetime in seconds. Defaults to 900 (15m); the returned client
-     *  auto-re-mints before expiry, so a long-running agent never handles
-     *  rotation itself. */
-    ttlSeconds?: number;
-    /** Extra opaque identity blob echoed on the session scope. Merged with
-     *  `name` (the `name` param wins if you also set `userMeta.name`). */
-    userMeta?: Record<string, unknown>;
-}
-/** 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 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;
-    organizationId: string;
-    scope: {
-        organizationId: string;
-        syncGroups: readonly string[];
-        operations: readonly string[];
-        participantKind: 'user' | 'agent' | 'system';
-        participantId: string;
-    };
-    userMeta: Record<string, unknown>;
-}
+import type { AbloOptions } from './options.js';
+import type { AbloSession, CommitResource, CreateAgentClientParams, CreateSessionParams, ModelClient } from './resourceTypes.js';
+export type { ApiKeySetter, AbloOptions, InternalAbloOptions } from './options.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, HeldClaim, ModelOperations, ModelOperationAction, CommitWait, ModelRead, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, ModelClient, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
+export { computeFKDepthPriority } from './schemaConfig.js';
+import type { ModelOperations } from './createModelProxy.js';
 /** The typed sync engine client — one property per model in the schema */
 export type Ablo<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: ModelOperations<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
@@ -970,9 +280,7 @@ export type Ablo<S extends SchemaRecord> = {
      * await streamText({ messages, signal: snap.signal });
      * ```
      */
-    snapshot<ModelName extends keyof S & string>(entities: {
-        readonly [M in ModelName]: string | readonly string[];
-    }): Snapshot<Schema<S>, ModelName>;
+    snapshot<ModelName extends keyof S & string>(entities: Readonly<Record<ModelName, string | readonly string[]>>): Snapshot<Schema<S>, ModelName>;
     /**
      * The internal BaseSyncedStore. Implements SyncStoreContract — pass to
      * SyncContext.Provider so the SDK's useModel/useModels/useMutations hooks
@@ -987,51 +295,6 @@ export type Ablo<S extends SchemaRecord> = {
      */
     readonly _ws: SyncWebSocket | null;
 };
-/**
- * Compute a create-priority map from schema `belongsTo` relations using
- * Tarjan's strongly-connected-components algorithm.
- *
- * The FK graph has an edge `child → parent` for every `belongsTo`. Tarjan
- * runs a single linear DFS that simultaneously (a) detects cycles by
- * grouping mutually-reachable nodes into SCCs and (b) emits those SCCs
- * in reverse topological order of the condensation graph. In this edge
- * convention a "sink" SCC has no outgoing edges — i.e. no parents — so
- * it is an *FK root* (`organizations`, `themes`, etc.). Tarjan emits
- * roots first and leaves last, exactly the order in which rows must be
- * inserted to satisfy FK constraints.
- *
- * Priorities are assigned by emit order: SCC #0 → 10, SCC #1 → 20, …
- * Members of the same SCC share a priority, so insertion order wins the
- * tiebreak inside a cycle (this matters for cyclic schemas like
- * `slideDecks ↔ layouts`, where one direction is the user's chosen
- * "soft" edge — only the consumer's mutator sequence knows which one).
- *
- * This algorithm is iteration-order-independent: starting the DFS from
- * any node yields the same SCC partitioning, and SCCs always come out
- * in valid topological order. The previous DFS-with-memoization
- * heuristic broke under cycles by treating the back-edge as depth 0,
- * which made priorities depend on which node the walk happened to
- * enter the cycle at.
- *
- * Schema authors can mark one side of a cycle with
- * `belongsTo(target, fk, { defer: true })`. Those edges are excluded
- * from the dependency graph entirely, which deterministically breaks
- * the cycle and turns the SCC into a chain — the marked child gets a
- * strictly higher priority than its parent instead of being tied with
- * it. Pair with a Postgres `DEFERRABLE INITIALLY DEFERRED` constraint
- * if you want the database side of the cycle to also relax. See
- * {@link BelongsToOptions.defer}.
- *
- * The returned map is keyed by {@link ModelDef.typename} (falling back
- * to the schema key), because that is what `Model.getModelName()`
- * returns at transaction time — keying by schema key would silently
- * miss the lookup and every model would fall through to
- * `defaultCreatePriority`.
- *
- * Reference: Tarjan, R. (1972), "Depth-first search and linear graph
- * algorithms." Linear in V + E.
- */
-export declare function computeFKDepthPriority(schema: Schema): ReadonlyMap<string, number>;
 /**
  * Create a sync engine client in one call.
  *
@@ -1042,6 +305,14 @@ export declare function computeFKDepthPriority(schema: Schema): ReadonlyMap<stri
  * await sync.weatherReports.create({ location: 'Stockholm', status: 'pending' });
  * ```
  *
+ * In the browser (or any client that shouldn't hold a secret key), point
+ * `authEndpoint` at your session-mint route instead — the SDK fetches it, keeps the
+ * short-lived token fresh, and re-mints on expiry:
+ *
+ * ```ts
+ * const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+ * ```
+ *
  * Pass `transport: 'http'` for the stateless server-side client (agents,
  * workers, serverless) — same `ablo.<model>` surface, no socket:
  *
@@ -1091,8 +362,8 @@ export declare namespace Ablo {
     type CapabilityRevocation = import('./ApiClient.js').CapabilityRevocation;
     type CapabilityRotateOptions = import('./ApiClient.js').CapabilityRotateOptions;
     type RotatedCapability = import('./ApiClient.js').RotatedCapability;
-    type IfClaimedPolicy = import('./Ablo.js').IfClaimedPolicy;
-    type ClaimedOptions = import('./Ablo.js').ClaimedOptions;
+    type IfClaimedPolicy = import('./resourceTypes.js').IfClaimedPolicy;
+    type ClaimedOptions = import('./resourceTypes.js').ClaimedOptions;
     type ClaimTarget = _Streams.ClaimTarget;
     type PresenceTarget = _Streams.PresenceTarget;
     type TargetRange = _Streams.TargetRange;
@@ -1130,26 +401,26 @@ export declare namespace Ablo {
         type Axis = _Policy.ConflictAxis;
     }
     namespace Commit {
-        type Wait = import('./Ablo.js').CommitWait;
-        type OperationAction = import('./Ablo.js').ModelOperationAction;
-        type OperationInput = import('./Ablo.js').CommitOperationInput;
-        type CreateOptions = import('./Ablo.js').CommitCreateOptions;
-        type Receipt = import('./Ablo.js').CommitReceipt;
-        type Client = import('./Ablo.js').CommitResource;
+        type Wait = import('./resourceTypes.js').CommitWait;
+        type OperationAction = import('./resourceTypes.js').ModelOperationAction;
+        type OperationInput = import('./resourceTypes.js').CommitOperationInput;
+        type CreateOptions = import('./resourceTypes.js').CommitCreateOptions;
+        type Receipt = import('./resourceTypes.js').CommitReceipt;
+        type Client = import('./resourceTypes.js').CommitResource;
     }
     namespace Claim {
-        type Handle = import('./Ablo.js').Claim;
-        type CreateOptions = import('./Ablo.js').ClaimCreateOptions;
-        type WaitOptions = import('./Ablo.js').ClaimWaitOptions;
-        type Client = import('./Ablo.js').ClaimResource;
+        type Handle = import('./resourceTypes.js').Claim;
+        type CreateOptions = import('./resourceTypes.js').ClaimCreateOptions;
+        type WaitOptions = import('./resourceTypes.js').ClaimWaitOptions;
+        type Client = import('./resourceTypes.js').ClaimResource;
     }
     namespace Model {
-        type Target = import('./Ablo.js').ModelTarget;
-        type Claim = import('./Ablo.js').ModelClaim;
-        type Read<T = Record<string, unknown>> = import('./Ablo.js').ModelRead<T>;
-        type Client<T = Record<string, unknown>> = import('./Ablo.js').ModelClient<T>;
-        type ReadOptions = import('./Ablo.js').ModelReadOptions;
-        type MutationOptions = import('./Ablo.js').ModelMutationOptions;
+        type Target = import('./resourceTypes.js').ModelTarget;
+        type Claim = import('./resourceTypes.js').ModelClaim;
+        type Read<T = Record<string, unknown>> = import('./resourceTypes.js').ModelRead<T>;
+        type Client<T = Record<string, unknown>> = import('./resourceTypes.js').ModelClient<T>;
+        type ReadOptions = import('./resourceTypes.js').ModelReadOptions;
+        type MutationOptions = import('./resourceTypes.js').ModelMutationOptions;
     }
     namespace Source {
         type Operation = import('../source/index.js').SourceOperation;