@abloatai/ablo 0.3.0

package/dist/client/Ablo.d.ts

@@ -0,0 +1,835 @@
+/**
+ * Ablo — The one-liner consumer API.
+ *
+ * Hides all internal wiring (ObjectPool, Database, SyncClient, WebSocket,
+ * bootstrap, offline queue, DI adapters) behind a single function call.
+ *
+ * Usage:
+ *   import { Ablo } from '@ablo/sync-engine/client';
+ *   import { schema } from './schema';
+ *
+ *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+ *
+ *   const tasks = sync.tasks.list({ where: { status: 'todo' } });
+ *   await sync.tasks.create({ title: 'Fix bug' });
+ *   await sync.tasks.update(taskId, { status: 'done' });
+ *   await sync.tasks.delete(taskId);
+ */
+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 { ObjectPool } from '../ObjectPool.js';
+import type { SyncStoreContract } from '../react/context.js';
+import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
+import { type SyncStatus } from '../BaseSyncedStore.js';
+import type { IntentStream, PresenceStream, Snapshot } from '../types/streams.js';
+import type { ParticipantManager } from '../sync/participants.js';
+import type { ActiveIntent, Duration, TargetRange } from '../types/streams.js';
+import { type AbloApi, type AbloApiClientOptions, type AbloApiIntents } from './ApiClient.js';
+/**
+ * Handle returned by `engine.beginTurn()`. While alive, every commit
+ * automatically carries this turn's id on the wire. Call `close(stats?)`
+ * when the turn finishes, or `dispose()` to abandon without recording
+ * usage. Idempotent.
+ */
+export interface Turn {
+    readonly turnId: string;
+    close(stats?: {
+        readonly costInputTokens?: number;
+        readonly costOutputTokens?: number;
+        readonly costComputeMs?: number;
+    }): Promise<void>;
+    dispose(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * 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 (`@ablo/sync-engine`)
+ * 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';
+export interface AbloOptions<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']`.
+     */
+    apiKey?: string | ApiKeySetter | null | 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 and reads
+     * `process.env['ABLO_BASE_URL']` if unset.
+     */
+    baseURL?: string | null | undefined;
+    /** Per-request timeout in milliseconds. */
+    timeout?: number | undefined;
+    /** Number of retries for transient failures. */
+    maxRetries?: number | 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 using a publishable/browser-safe
+     * key or a controlled server proxy.
+     */
+    dangerouslyAllowBrowser?: boolean | undefined;
+    /**
+     * TypeScript schema defined with `defineSchema()`. This enables typed
+     * resources such as `ablo.tasks.update(...)`.
+     */
+    schema: Schema<S>;
+    /**
+     * Local persistence mode. Defaults to `volatile`. Pass `indexeddb` only
+     * when you want offline queueing and a reload-surviving browser cache.
+     */
+    persistence?: AbloPersistence;
+}
+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. Defaults to `process.env['ABLO_AUTH_TOKEN']`.
+     *
+     * 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://mesh.ablo.finance` for hosted production; pass an explicit
+     * URL for self-hosted or staging (e.g. `wss://mesh-staging.ablo.finance`).
+     * Reads `process.env['ABLO_BASE_URL']` if unset.
+     */
+    baseURL?: string | null | undefined;
+    /**
+     * Maximum amount of time (ms) the client waits for a response
+     * before timing out a single request. Defaults to 10 minutes
+     * (600_000ms). Retried requests can wait longer in worst case.
+     */
+    timeout?: number | undefined;
+    /**
+     * Maximum number of times the client will retry a request on
+     * transient failure (5xx / 429 / network error). Defaults to 2.
+     * Honors `Retry-After` and `retry-after-ms` response headers.
+     */
+    maxRetries?: number | 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 publishable key, 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 resources such as `ablo.tasks.update(...)`. Omit `schema`
+     * only for the advanced Resource / Intent / 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) */
+    logger?: SyncLogger;
+    /** ObjectPool size limit (default: 10000) */
+    maxPoolSize?: number;
+    /**
+     * Local persistence mode. Defaults to `volatile` 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 `volatile`; `false` maps to
+     * `indexeddb` in browsers.
+     */
+    inMemory?: boolean;
+    /**
+     * If true, initialization starts immediately in the background so
+     * `sync.tasks.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 `resource.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` with
+     * `credentials: 'include'` (cookie auth) when no `apiKey` is set.
+     */
+    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>;
+    /**
+     * @deprecated Server derives sync groups from the apiKey's scope.
+     * Required today as a runtime holdover; removed once Phase 3 ships.
+     */
+    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)` — single entity by id (sync, from local pool)
+ *   `list({where})` — collection with filter (sync, from local pool)
+ *   `count({where})` — count (sync, from local pool)
+ *   `load({where})` — async hydrate through pool → IDB → network
+ *   `create / update / delete` — optimistic writes
+ *
+ * The old verb set (`findById`, `findMany`, `findFirst`) is kept as
+ * deprecated aliases for one release cycle so consumers can migrate
+ * without a flag day.
+ */
+export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelEditHandle, ModelEditOptions, ModelOperations, } from './createModelProxy.js';
+import type { ModelOperations } from './createModelProxy.js';
+export type ResourceOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+export type CommitWait = 'queued' | 'confirmed';
+export interface ResourceTarget {
+    readonly resource: string;
+    readonly id: string;
+    readonly path?: string;
+    readonly range?: TargetRange;
+    readonly field?: string;
+    readonly meta?: Record<string, unknown>;
+}
+export interface ResourceIntent {
+    readonly id: string;
+    readonly actor: string;
+    readonly participantKind: ActiveIntent['participantKind'];
+    readonly action: string;
+    readonly field?: string;
+    readonly expiresAt: string;
+    readonly target: ResourceTarget;
+}
+export interface ResourceRead<T = Record<string, unknown>> {
+    readonly data: T;
+    readonly stamp: number;
+    readonly intents: readonly ResourceIntent[];
+}
+export type BusyPolicy = 'return' | 'wait' | 'fail';
+export interface BusyOptions {
+    /**
+     * What to do when another participant has an active intent on the
+     * target. `return` includes the intents in the response, `wait`
+     * resolves after they clear, and `fail` throws `AbloBusyError`.
+     */
+    readonly ifBusy?: BusyPolicy;
+    /** Max time to wait for peer intents to clear, in milliseconds. */
+    readonly busyTimeout?: number;
+    /** HTTP API polling interval while waiting. WebSocket clients ignore it. */
+    readonly busyPollInterval?: number;
+}
+export interface IntentWaitOptions {
+    readonly timeout?: number;
+    readonly pollInterval?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ResourceReadOptions extends BusyOptions {
+}
+export interface IntentCreateOptions {
+    readonly target: ResourceTarget;
+    readonly action: string;
+    readonly ttl?: Duration;
+}
+export interface IntentHandle extends AsyncDisposable {
+    readonly id: string;
+    release(): Promise<void>;
+    revoke(): void;
+}
+export interface CommitOperationInput {
+    readonly action: ResourceOperationAction;
+    readonly resource?: string;
+    readonly target?: ResourceTarget;
+    readonly id?: string | null;
+    readonly data?: Record<string, unknown> | null;
+    readonly transactionId?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+}
+export interface CommitCreateOptions {
+    readonly intent?: string | {
+        readonly id: string;
+    } | null;
+    readonly idempotencyKey?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    readonly operation?: CommitOperationInput;
+    readonly operations?: readonly CommitOperationInput[];
+    readonly wait?: CommitWait;
+    readonly timeout?: number;
+}
+export interface CommitReceipt {
+    readonly id: string;
+    readonly status: CommitWait;
+    readonly lastSyncId?: number;
+}
+export interface CommitResource {
+    create(options: CommitCreateOptions): Promise<CommitReceipt>;
+}
+export interface IntentResource extends IntentStream {
+    create(options: IntentCreateOptions): Promise<IntentHandle>;
+    list(target?: Partial<ResourceTarget>): readonly ResourceIntent[];
+    waitFor(target: Partial<ResourceTarget>, options?: IntentWaitOptions): Promise<void>;
+}
+export interface ResourceMutationOptions extends BusyOptions {
+    readonly intent?: string | {
+        readonly id: string;
+    } | null;
+    readonly idempotencyKey?: string | null;
+    readonly readAt?: number | null;
+    readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    readonly wait?: CommitWait;
+    readonly timeout?: number;
+}
+export interface ResourceClient<T = Record<string, unknown>> {
+    retrieve(id: string, options?: ResourceReadOptions): Promise<ResourceRead<T>>;
+    create(data: Record<string, unknown>, options?: ResourceMutationOptions & {
+        readonly id?: string | null;
+    }): Promise<CommitReceipt>;
+    update(id: string, data: Record<string, unknown>, options?: ResourceMutationOptions): Promise<CommitReceipt>;
+    delete(id: string, options?: ResourceMutationOptions): Promise<CommitReceipt>;
+}
+/** 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>>;
+} & {
+    /**
+     * Wait for the sync engine to finish its initial bootstrap.
+     * Resolves once entity data is loaded and the WebSocket is connected.
+     *
+     * ```ts
+     * const sync = Ablo({ schema, user });
+     * await sync.ready();
+     * const tasks = sync.tasks.findMany(); // data is available
+     * ```
+     *
+     * If bootstrap fails, this rejects with the underlying error (unreachable
+     * server, invalid API key, 500 from bootstrap endpoint, etc.).
+     *
+     * Idempotent — calling it multiple times returns the same promise.
+     */
+    ready(): Promise<void>;
+    /**
+     * Wait for all pending mutations to be confirmed by the server.
+     *
+     * Sync engine mutations (`create`/`update`/`delete`) are optimistic and
+     * resolve immediately. Use this when you need to know the server has
+     * acknowledged everything before continuing — for example, before
+     * navigating away, before triggering a server-side workflow, or in tests.
+     *
+     * Resolves when `syncStatus.pendingChanges` reaches 0. If the engine is
+     * offline, this waits until reconnect + flush completes.
+     *
+     * ```ts
+     * await sync.tasks.create({ title: 'A' });
+     * await sync.tasks.create({ title: 'B' });
+     * await sync.waitForFlush(); // server has both tasks
+     * ```
+     *
+     * @param timeoutMs - Optional timeout. Default: no timeout (wait forever).
+     *                    Throws `Error('Flush timeout')` if reached with pending changes.
+     */
+    waitForFlush(timeoutMs?: number): Promise<void>;
+    /** Disconnect and clean up */
+    dispose(): Promise<void>;
+    /**
+     * Destroy every IndexedDB database owned by this engine. Disconnects
+     * the WebSocket, releases timers, and deletes all `ablo_*` / `ablo-*`
+     * databases. Use on session expiry or explicit logout. Best-effort.
+     */
+    purge(): Promise<void>;
+    /**
+     * Subscribe to session-error events (server rejected the session).
+     * Returns an unsubscribe function. Multiple subscribers supported.
+     * Typically called by `<AbloProvider>`, which calls `purge()` on fire
+     * and forwards to the consumer's `onSessionExpired` callback.
+     */
+    onSessionError(listener: (error: Error) => void): () => void;
+    /**
+     * Subscribe to mutation failures with the full payload (transaction,
+     * error, permanent flag). Use this for user-visible failure surfaces —
+     * toasts keyed by `AbloError.type`, route-level "this entity reverted"
+     * boundaries, telemetry. Fires for both permanent rejections and
+     * `max_retries_exhausted` rollbacks.
+     *
+     * Distinct from `onSessionError` (server killed the session, requires
+     * re-auth) and from the `tx.isPersisted` per-call promise (call-site
+     * await, single transaction). This is the app-wide fan-in.
+     */
+    onMutationFailure(listener: (payload: {
+        transaction: import('../transactions/TransactionQueue.js').Transaction;
+        error: Error;
+        permanent?: boolean;
+    }) => void): () => void;
+    /**
+     * Wait for the most-recent in-flight transaction for (modelName, modelId)
+     * to be confirmed by the server. Rejects with the same error that the
+     * queue's `transaction:failed` event would carry if the mutation is
+     * permanently rolled back. Resolves immediately when no transaction is
+     * in flight (already-confirmed or never-staged).
+     *
+     * Matches the queue's `'confirmed'` status vocabulary (see also
+     * `commits.create({wait:'confirmed'})`). Use this for the routing-
+     * grace-window pattern: stage a write, then
+     * `Promise.race([ablo.waitForConfirmation(...), gracePromise])` before
+     * navigating to a route whose URL depends on the optimistic id.
+     */
+    waitForConfirmation(modelName: string, modelId: string): Promise<void>;
+    /**
+     * Reactive sync status — a MobX observable.
+     *
+     * Single source of truth for "what's the sync engine doing?" Contains:
+     * - `state`: `'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting'`
+     * - `progress`: 0-100 for bootstrap progress
+     * - `error?`: Error object when `state === 'error'`
+     * - `pendingChanges`: Number of unconfirmed mutations in the queue
+     * - `lastSyncAt?`: Timestamp of the last successful delta processing
+     * - `offlineSince?`: When the connection dropped
+     * - `isSessionError`: True when the error requires re-authentication
+     *
+     * React components using `observer()` re-render automatically when
+     * any field changes — no manual subscription or polling needed.
+     *
+     * ```tsx
+     * import { observer } from 'mobx-react-lite';
+     *
+     * const SyncIndicator = observer(() => {
+     *   if (sync.syncStatus.state === 'syncing') return <Spinner />;
+     *   if (sync.syncStatus.state === 'error') return <Error msg={sync.syncStatus.error} />;
+     *   if (sync.syncStatus.state === 'offline') return <OfflineBadge />;
+     *   return null;
+     * });
+     * ```
+     */
+    readonly syncStatus: SyncStatus;
+    /** The underlying schema */
+    readonly schema: Schema<S>;
+    /**
+     * Real-time presence livestream — who else is connected on this
+     * engine's sync groups, what they're doing, and a write surface for
+     * announcing this user's own activity. Rides the engine's existing
+     * WebSocket; opening a participant for presence does NOT open a
+     * second socket. See `PresenceStream` in `types/streams.ts`.
+     *
+     * Stable reference for the engine's lifetime — the underlying
+     * connection is rotated on `dispose()` but this object is the same.
+     */
+    readonly presence: PresenceStream;
+    /**
+     * Cooperative-mutex layer over presence — announce "I'm about to do
+     * X on Y" so peers can yield before colliding. Server enforces the
+     * mutex; rejected announcements surface via `intents.onRejected(...)`.
+     * Same socket as entity sync, no second connection.
+     */
+    readonly intents: IntentResource;
+    /**
+     * Canonical low-level mutation API. Every resource convenience write
+     * compiles down to `commits.create(...)`.
+     */
+    readonly commits: CommitResource;
+    /**
+     * Canonical untyped resource API. This is the portable API shape that maps
+     * cleanly to HTTP/Python/Ruby/Go clients. Typed `ablo.<model>` properties
+     * are schema-powered sugar over the same resource model.
+     */
+    resource<T = Record<string, unknown>>(name: string): ResourceClient<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
+     * + intent 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.intents.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
+     * `readAt`), `signal` (aborts on any captured-entity delta), and
+     * `onChange` (callback form). Reads from the engine's ObjectPool;
+     * subscription is on the engine's existing transport.
+     *
+     * Use before an LLM call to prevent the model from completing
+     * against now-stale data:
+     * ```ts
+     * const snap = engine.snapshot({ slides: deck.slideIds });
+     * await streamText({ messages, signal: snap.signal });
+     * ```
+     */
+    snapshot<ModelName extends keyof S & string>(entities: {
+        readonly [M in ModelName]: string | readonly string[];
+    }): Snapshot<Schema<S>, ModelName>;
+    /**
+     * Open a turn — every commit issued while the returned handle is
+     * alive carries `caused_by_task_id` on the wire so the server
+     * stamps it onto each delta. Powers `agent_tasks` audit trails.
+     * Server: `POST /api/agent/turn` with the capability bearer.
+     */
+    beginTurn(options: {
+        readonly prompt: string;
+        readonly parentTaskId?: string;
+        readonly surface?: string;
+        readonly metadata?: Record<string, unknown>;
+    }): Promise<Turn>;
+    /**
+     * The internal BaseSyncedStore. Implements SyncStoreContract — pass to
+     * SyncContext.Provider so the SDK's useModel/useModels/useMutations hooks
+     * can access it. Also satisfies useSyncStore() consumers during migration.
+     */
+    readonly _store: SyncStoreContract;
+    /** The ObjectPool — for demand loaders and direct pool operations. */
+    readonly _pool: ObjectPool;
+    /**
+     * The SyncWebSocket handle — for collaboration events (slide selection,
+     * cursor broadcast). Null until the engine connects.
+     */
+    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.
+ *
+ * ```ts
+ * const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+ *
+ * const tasks = sync.tasks.list({ where: { status: 'todo' } });
+ * await sync.tasks.create({ title: 'New task' });
+ * ```
+ */
+export declare function Ablo<const S extends SchemaRecord>(options: AbloOptions<S>): Ablo<S>;
+export declare function Ablo(options: AbloApiClientOptions): AbloApi;
+import type * as _Streams from '../types/streams.js';
+import type * as _Participants from '../sync/participants.js';
+import type * as _Policy from '../policy/types.js';
+import type * as _Mutators from '../mutators/defineMutators.js';
+import type * as _Tx from '../mutators/Transaction.js';
+import type * as _Undo from '../mutators/UndoManager.js';
+import type * as _SchemaTypes from '../schema/schema.js';
+/**
+ * Canonical type namespace.
+ *
+ * Locked rules — apply uniformly to every future addition:
+ *
+ *   1. Flat by default.    `Ablo.X`. Fewest dots wins.
+ *   2. Sub-namespace ONLY when (a) 4+ types share a single conceptual
+ *      prefix, AND (b) names read better with the prefix (`Conflict.Kind`
+ *      over `ConflictKind`). If the cluster is heterogeneous (streams +
+ *      data + handles), keep flat.
+ *   3. Only types a consumer would write `: Ablo.X` for. Inferred-only
+ *      types stay un-exported.
+ *   4. Wire shapes never on `Ablo.*`. Engine vocabulary only.
+ *   5. Advanced / framework-integration types stay internal unless they
+ *      graduate into one of the public subpaths.
+ *
+ * Anything not on this list stays internal.
+ */
+export declare namespace Ablo {
+    type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
+    type Api = AbloApi;
+    type ApiIntents = AbloApiIntents;
+    type Agent = import('./ApiClient.js').Agent;
+    type AgentOptions = import('./ApiClient.js').AgentOptions;
+    type AgentRunOptions = import('./ApiClient.js').AgentRunOptions;
+    type AgentRunStatus = import('./ApiClient.js').AgentRunStatus;
+    type AgentRunResult<T> = import('./ApiClient.js').AgentRunResult<T>;
+    type AgentRunContext = import('./ApiClient.js').AgentRunContext;
+    type AgentResourceClient<T = Record<string, unknown>> = import('./ApiClient.js').AgentResourceClient<T>;
+    type AgentResourceReadOptions = import('./ApiClient.js').AgentResourceReadOptions;
+    type AgentResourceMutationOptions = import('./ApiClient.js').AgentResourceMutationOptions;
+    type AgentIntentOptions = import('./ApiClient.js').AgentIntentOptions;
+    type AgentIntentInput = import('./ApiClient.js').AgentIntentInput;
+    type Capability = import('./ApiClient.js').Capability;
+    type CapabilityCreateOptions = import('./ApiClient.js').CapabilityCreateOptions;
+    type CapabilityRecord = import('./ApiClient.js').CapabilityRecord;
+    type CapabilityResource = import('./ApiClient.js').CapabilityResource;
+    type CapabilityRevocation = import('./ApiClient.js').CapabilityRevocation;
+    type Task = import('./ApiClient.js').Task;
+    type TaskCreateOptions = import('./ApiClient.js').TaskCreateOptions;
+    type TaskCloseOptions = import('./ApiClient.js').TaskCloseOptions;
+    type TaskCloseResult = import('./ApiClient.js').TaskCloseResult;
+    type TaskResource = import('./ApiClient.js').TaskResource;
+    type BusyPolicy = import('./Ablo.js').BusyPolicy;
+    type BusyOptions = import('./Ablo.js').BusyOptions;
+    type EntityRef = _Streams.EntityRef;
+    type PresenceTarget = _Streams.PresenceTarget;
+    type TargetRange = _Streams.TargetRange;
+    type Duration = _Streams.Duration;
+    type PresenceStream = _Streams.PresenceStream;
+    type IntentStream = _Streams.IntentStream;
+    type Peer = _Streams.Peer;
+    type Activity = _Streams.Activity;
+    type ActiveIntent = _Streams.ActiveIntent;
+    type Claim = _Streams.Claim;
+    type IntentRejection = _Streams.IntentRejection;
+    type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
+    type Turn = import('./Ablo.js').Turn;
+    namespace Auth {
+        type Principal = _Streams.Principal;
+        type Session = _Streams.SessionRef;
+        type Agent = _Streams.AgentRef;
+        type Actor = _Streams.ParticipantRef;
+    }
+    namespace Participant {
+        type Manager = _Participants.ParticipantManager;
+        type Joined = _Participants.JoinedParticipant;
+        type Scope = _Participants.ParticipantScope;
+        type Status = _Participants.ParticipantStatus;
+        type JoinOptions = _Participants.ParticipantJoinOptions;
+    }
+    type Schema<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord> = _SchemaTypes.Schema<S>;
+    namespace Schema {
+        type InferModel<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferModel<S, K>;
+        type InferCreate<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferCreate<S, K>;
+        type InferModelNames<S extends _SchemaTypes.Schema> = _SchemaTypes.InferModelNames<S>;
+    }
+    type Conflict = _Policy.Conflict;
+    namespace Conflict {
+        type Kind = _Policy.ConflictKind;
+        type Operation = _Policy.ConflictOperation;
+        type Decision = _Policy.ConflictDecision;
+        type Policy = _Policy.ConflictPolicy;
+    }
+    namespace Commit {
+        type Wait = import('./Ablo.js').CommitWait;
+        type OperationAction = import('./Ablo.js').ResourceOperationAction;
+        type OperationInput = import('./Ablo.js').CommitOperationInput;
+        type CreateOptions = import('./Ablo.js').CommitCreateOptions;
+        type Receipt = import('./Ablo.js').CommitReceipt;
+        type Resource = import('./Ablo.js').CommitResource;
+    }
+    namespace Intent {
+        type Handle = import('./Ablo.js').IntentHandle;
+        type CreateOptions = import('./Ablo.js').IntentCreateOptions;
+        type WaitOptions = import('./Ablo.js').IntentWaitOptions;
+        type Resource = import('./Ablo.js').IntentResource;
+    }
+    namespace Resource {
+        type Target = import('./Ablo.js').ResourceTarget;
+        type Intent = import('./Ablo.js').ResourceIntent;
+        type Read<T = Record<string, unknown>> = import('./Ablo.js').ResourceRead<T>;
+        type Client<T = Record<string, unknown>> = import('./Ablo.js').ResourceClient<T>;
+        type ReadOptions = import('./Ablo.js').ResourceReadOptions;
+        type MutationOptions = import('./Ablo.js').ResourceMutationOptions;
+    }
+    namespace Source {
+        type Operation = import('../source/index.js').SourceOperation;
+        type Event = import('../source/index.js').SourceEvent;
+        type EventsResult = import('../source/index.js').SourceEventsResult;
+        type Scope = import('../source/index.js').SourceScope;
+        type Secret = import('../source/index.js').SourceSecret;
+        type Options<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord, TAuth = unknown> = import('../source/index.js').AbloSourceOptions<S, TAuth>;
+        type ModelHandlers<Row, CreateInput, TAuth = unknown> = import('../source/index.js').SourceModelHandlers<Row, CreateInput, TAuth>;
+        type SignatureVerificationResult = import('../source/index.js').SourceSignatureVerificationResult;
+        namespace Commit {
+            type Params<TAuth = unknown> = import('../source/index.js').SourceCommitParams<TAuth>;
+            type Result<Row = Record<string, unknown>> = import('../source/index.js').SourceCommitResult<Row>;
+        }
+    }
+    namespace Mutator {
+        type Fn<S extends _SchemaTypes.Schema, TArgs, TResult = void> = _Mutators.MutatorFn<S, TArgs, TResult>;
+        type Transaction<S extends _SchemaTypes.Schema> = _Tx.Transaction<S>;
+        type UndoEntry = _Undo.UndoEntry;
+        type UndoScope<S extends _SchemaTypes.Schema = _SchemaTypes.Schema> = _Undo.UndoScope<S>;
+        type InverseOp = _Undo.InverseOp;
+    }
+}