@abloatai/ablo 0.12.0 → 0.14.0

package/llms-full.txt

@@ -1,396 +0,0 @@
-# Ablo Full Context
-
-Ablo is the state coordination layer for apps where humans and agents edit the same data.
-
-Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist to the database, coordinate with concurrent human or agent work, and leave an audit trail.
-
-The product surface should read like Stripe, Turbopuffer, or Reducto: one product-name import, models by dot access, optional subpaths only for schema, React, and tests.
-
-```ts
-import Ablo from '@abloatai/ablo';
-```
-
-## Public Surface
-
-Public imports:
-
-- `@abloatai/ablo` — `Ablo`, errors, typed model clients, claims, `dataSource`, and advanced schema-less protocol models.
-- `@abloatai/ablo/schema` — `defineSchema`, `model`, `z`, relations, schema types.
-- `@abloatai/ablo/react` — React provider and hooks.
-- `@abloatai/ablo/testing` — test harnesses and mocks.
-
-TYPES: the project registers its schema ONCE via declaration merging — `npx ablo init` scaffolds `ablo/register.ts` (a regular `.ts` module beside schema.ts, NOT a hand-authored `.d.ts`): `import type { schema } from './schema'; declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. The top-level `import type` makes `declare module` MERGE (augment) the SDK's Register interface rather than collide — same shape TanStack Router uses in src/router.tsx; any `.ts` file in tsconfig include works, never imported. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema. To NAME the client type (function param, context value), infer from the value: `type Sync = typeof sync` — same idiom as tRPC `typeof appRouter` / Drizzle `typeof db`; it resolves the typed overload at the call site. Do NOT use `ReturnType<typeof Ablo>` (collapses to the untyped last overload) and do NOT import a bespoke client-type generic — there is none.
-
-
-Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or `internal/*` as public imports. The Data Source surface — `/source`, `/source/next`, `/source/drizzle`, `/source/kysely`, `/source/conformance` — IS public (it's how a customer-owned database is wired).
-
-The canonical integration doc is `integration-guide`. It explains the end-to-end
-path for schema, React selectors, your Data Source-backed database, multiplayer,
-and agent workers. Use it before inventing a new setup
-flow.
-
-## Production Guarantees
-
-`wait: 'confirmed'` resolves after the server accepts the write. Schema model
-writes are optimistic; a server rejection rolls back local state and raises a
-typed `AbloError`.
-
-Use `snapshot(...)` and `readAt` when an agent write depends on state it already
-read. `onStale: 'reject'` prevents lost updates by rejecting if the target
-changed after the snapshot.
-
-Claims are live coordination signals, not database locks. Reads never block on a
-claim — to wait for a row to free up, `claim({ id })` it and the claim queues
-fairly behind the current holder.
-
-Agent run bookkeeping is internal. Most users should not create run ledger
-records or scoped access credentials manually.
-
-## Primary App Path
-
-Declare models in a schema, then use typed model clients:
-
-```ts
-import Ablo from '@abloatai/ablo';
-import { defineSchema, model, z } from '@abloatai/ablo/schema';
-
-const schema = defineSchema({
-  weatherReports: model({
-    id: z.string(),
-    location: z.string(),
-    status: z.enum(['pending', 'ready']),
-    forecast: z.string().optional(),
-    updatedAt: z.string(),
-  }),
-  projects: model({
-    id: z.string(),
-    name: z.string(),
-  }),
-});
-
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
-
-const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
-if (!report) throw new Error('Row not found');
-
-await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
-const updated = await ablo.weatherReports.update({
-  id: claim.data.id,
-  data: { status: 'ready', forecast: await getForecast(claim.data) },
-  wait: 'confirmed',
-});
-```
-
-The normal app API (every verb takes ONE options object):
-
-- `ablo.<model>.retrieve({ id })` — async read of one row from the server
-- `ablo.<model>.list({ where })` — async read of many from the server
-- `ablo.<model>.get(id)` / `getAll({ where })` / `getCount({ where })` — synchronous local-graph reads (reactive in React render)
-- `ablo.<model>.create({ data, id? })`
-- `ablo.<model>.update({ id, data })`
-- `ablo.<model>.delete({ id })`
-- `await using claim = await ablo.<model>.claim({ id })` — disposable claim handle; read the fresh row off `claim.data`; auto-releases on scope exit
-- `ablo.<model>.claim.state({ id })` / `claim.queue({ id })` / `claim.release({ id })` / `claim.reorder({ id, order })`
-
-The synchronous reads (`getAll`/`getCount`) accept `where`, `filter`, `orderBy`,
-`limit`, `offset`, and `state`; state defaults to `'live'`, with `'archived'`
-and `'all'` for lifecycle-aware reads.
-
-Use `ablo.model<T>(name)` only when the caller intentionally does not have a schema, such as custom server agents, MCP routes, migration scripts, or generic admin tools.
-
-React reads should use selector `useAblo`:
-
-```tsx
-const report = useAblo((ablo) => ablo.weatherReports.get(id)) ?? serverReport;
-const visibleReports = useAblo((ablo) =>
-  ablo.weatherReports.getAll({ where: { projectId } }),
-);
-```
-
-Use zero-argument `useAblo()` only for callbacks, effects, and writes that need
-the provider-owned client:
-
-```tsx
-const ablo = useAblo();
-await ablo?.weatherReports.update({ id, data: patch, wait: 'confirmed' });
-```
-
-Treat `useQuery`, `useOne`, `useReader`, and `useMutate` as compatibility hooks
-for older string-keyed integrations. Do not teach them as the first React API.
-
-## Multiplayer
-
-Multiplayer is an effect of the normal model API, not a separate setup path.
-When human UI, server actions, and agents use the same
-`Ablo({ schema, apiKey })` client and write through `ablo.<model>`, Ablo
-coordinates the shared model stream:
-
-- confirmed model writes fan out as realtime deltas,
-- React hooks read the latest row and active claims,
-- claims announce active work before a commit,
-- `snapshot(...)` plus `readAt` protects against stale writes.
-
-Direct database writes outside Ablo are not coordinated until the app reports
-them through Data Source events. In Data Source mode, writes made through Ablo
-still coordinate normally because Ablo sends the signed commit request, receives
-canonical rows, and fans out the resulting deltas.
-
-For existing Python backends, keep the Python service layer and database as the
-source of truth. Add one signed Data Source endpoint, keep initial page loads on
-existing APIs if needed, use `useAblo((ablo) => ablo.<model>.get(id)) ?? serverRow`
-for live rows, then migrate buttons one at a time from direct Python endpoint
-writes to `ablo.<model>.update(...)`.
-
-This applies to any API-backed app: Python, Rails, Go, or Node. The backend keeps
-its service layer and DB credentials. Ablo gets a Data Source endpoint and uses
-`ABLO_API_KEY`, not a database URL.
-
-The connection-string path is the PRIMARY one: pass `databaseUrl` explicitly to
-`Ablo({ databaseUrl })`. It is NOT auto-read from the environment — a
-`DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose) is ignored
-unless you pass `databaseUrl`. The typical user ALREADY has a Postgres (often
-Prisma-managed for auth/audit/log tables that are NOT in the Ablo schema); Ablo
-syncs a SUBSET of models against it. Most users do NOT run `ablo migrate` — they
-ADOPT existing tables with `npx ablo pull` / `npx ablo check`, or keep managing
-tables with their own migration tool. Run `npx ablo migrate` only when Ablo
-should OWN the tables. NOTE: Ablo's CLOUD connects to your Postgres over the
-NETWORK, so a localhost / private-range DB is unreachable and rejected — for a
-local dev DB, expose a signed Data Source endpoint (your app proxies to it) or
-use the hosted sandbox (no DB needed).
-
-When the user DOES use the connection-string path: the role must be NON-superuser
-and NON-BYPASSRLS — Ablo enforces row-level security and rejects owner roles with
-`database_role_cannot_enforce_rls`. Neon's and Supabase's default dashboard
-strings use the database OWNER (e.g. `neondb_owner`) and ARE rejected. EASIEST: have the user run `npx ablo migrate` — it detects the unsafe role and creates the scoped one automatically from their machine (owner credential never reaches Ablo; new DATABASE_URL written to the env file). Manual alternative — create a scoped role first (`CREATE ROLE ablo_app LOGIN PASSWORD '...'
-NOSUPERUSER NOBYPASSRLS; GRANT CREATE, CONNECT ON DATABASE <db> TO ablo_app;
-GRANT CREATE, USAGE ON SCHEMA public TO ablo_app;`), then swap user/password
-into the same host/db string.
-
-## Client Behavior
-
-The options that matter: `schema` and `apiKey`. Everything else
-(`persistence`, `logger`, transport tuning) has correct defaults — do NOT set
-`baseURL`; the default already routes to the hosted API, and overriding it
-breaks the connection. It exists only for self-hosted/proxy setups the human
-explicitly asks for.
-
-`databaseUrl` is an OPTIONAL, server-only option on `Ablo(...)`. It is NOT
-auto-read from the environment — pass it EXPLICITLY to register your Postgres
-directly (the primary connection-string path). Omit it when you expose a signed
-Data Source endpoint (so customer-owned app databases stay private), or when
-trying Ablo against the hosted sandbox (apiKey only, no database).
-
-Important per-write options: `wait`, `readAt`, `onStale`,
-`idempotencyKey`, and `timeout`.
-
-Errors: `AbloAuthenticationError`, `AbloPermissionError`, `AbloRateLimitError`,
-`AbloIdempotencyError`, `AbloConnectionError`, `AbloValidationError`,
-`AbloServerError`, `AbloStaleContextError`, and `AbloClaimedError`.
-
-Retry transport failures and 5xx with backoff only when the operation is
-idempotent. Do not blindly retry validation, permission, idempotency, claimed, or
-stale-context errors without changing the request.
-
-## Sandboxes
-
-There are two sandbox surfaces:
-
-- Public `/sandbox` is a deterministic visual playground. It demonstrates shared
-  state, active claims, stale-write rejection, receipts, and deltas without
-  making real Ablo calls. It is agent-first: it should expose a prompt that can
-  be pasted into Claude Code or Codex to wire one real model through Ablo.
-- Authenticated org sandboxes are real test environments. The default sandbox is
-  the Stripe-style sandbox for an org. It has an isolated sync group prefix,
-  can mint `sk_test_*` keys, and can be reset without touching live state. The
-  sandbox CAN host rows in Ablo's test plane, so you can try Ablo with NO
-  database — `apiKey` only, no `databaseUrl` — like Stripe test mode. (In
-  production, your own Postgres is the system of record.)
-
-Additional org sandboxes can start blank or copy live configuration. Keep
-customer production traffic on `sk_live_*`; use `sk_test_*` for app setup, Data
-Source endpoint wiring, and agent integration testing.
-
-The coding-agent handoff should ask for a narrow integration: one schema model,
-one Ablo client module, one React selector read, one typed model write with
-`readAt`/`onStale: 'reject'`/`wait: 'confirmed'`, and one smoke test where two
-writers prove claim/stale behavior.
-
-## Data Sources
-
-Use these public environment names:
-
-- `ABLO_API_KEY` — SDK authentication for app and agent code. Where it comes
-  from: the human runs `npx ablo login` once (browser; an agent must not run
-  it), and `npx ablo push` then writes `ABLO_API_KEY=sk_test_…` into
-  `.env.local` automatically (and gitignores it). Check the environment and
-  `.env.local` for PRESENCE only (`grep -cq '^ABLO_API_KEY=' .env.local`)
-  before asking the human for a key — never print or echo the key value; a
-  secret in agent output lives in the conversation history forever.
-
-Do not ask customers to paste their app database URL into Ablo. If their app
-database is canonical, they expose a Data Source endpoint and keep database
-credentials inside their app.
-
-Every schema model is backed by the customer's own database. The SDK methods
-`ablo.<model>.create/update/delete` produce a signed commit request to the
-customer's Data Source route, and that route writes the app database.
-
-When the customer's database is canonical, expose one signed source route:
-
-```ts
-import { dataSourceNext } from '@abloatai/ablo/source/next';
-import { prismaDataSource } from '@abloatai/ablo/source';
-import { schema } from './ablo.schema';
-import { prisma } from './lib/prisma';
-
-// The adapter owns commit / idempotency / outbox — no hand-written commit.
-export const { POST } = dataSourceNext({
-  schema,
-  apiKey: process.env.ABLO_API_KEY!,
-  adapter: prismaDataSource(prisma, schema), // or drizzleDataSource(db, schema) / kyselyDataSource(db, schema)
-});
-```
-
-Commit request shape:
-
-```ts
-{
-  type: 'commit',
-  clientTxId: 'tx_...',
-  operations: [
-    { type: 'UPDATE', model: 'weatherReports', id: 'report_stockholm', input, readAt, onStale: 'reject' },
-  ],
-  scope: { participantId, participantKind, organizationId, requiredSyncGroups, mode: 'live' },
-}
-```
-
-Return `{ rows }` for normal apps or `{ deltas }` for sources that already
-compute canonical change events. External writes come back through the source
-`events` handler or `POST /api/source/events`.
-
-## Advanced Schema Options
-
-Teach schema as model fields and relations first:
-
-```ts
-const schema = defineSchema({
-  weatherReports: model({
-    id: z.string(),
-    location: z.string(),
-  }),
-});
-```
-
-Advanced helpers such as `mutable`, `readOnly`, `field`, `indexed`, query definitions, `load` strategies, parent metadata, and sync-group formats are still part of the schema package for offline/cache/indexing-heavy apps. Do not put them in the first example unless the user asks for local persistence, offline sync, custom loading, or low-level indexing behavior.
-
-## Server Agent Path
-
-Server agents should import the same schema as the app and use the same model
-methods. Claim the row around slow work, then write through `ablo.<model>`.
-
-```ts
-import Ablo from '@abloatai/ablo';
-
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
-
-await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
-const forecast = await getForecast(claim.data);
-await ablo.weatherReports.update({
-  id: claim.data.id,
-  data: { status: 'ready', forecast },
-  wait: 'confirmed',
-});
-```
-
-Do not require users to manually create protocol bookkeeping objects in the
-common agent path.
-
-## Model
-
-The read shape depends on whether the client has a local graph:
-
-- The stateful `ablo.<model>.retrieve({ id })` returns the BARE row (`T | undefined`), and `list({ where })` returns `T[]`. Read coordination metadata (state watermark, active claims) separately via `ablo.snapshot(...)` and `ablo.<model>.claim.state({ id })`.
-- The stateless HTTP / `.model(name)` `retrieve({ id })` returns a `ModelRead<T>` envelope because it has no local graph to carry the watermark; `list({ where })` still returns `T[]`.
-
-```ts
-type ModelRead<T> = {
-  data: T;
-  stamp: number;
-  claims: ModelClaim[];
-};
-```
-
-`stamp` is the state watermark. Pass it to writes as `readAt` (from `ablo.snapshot(...)` on the stateful client, or from the envelope on the HTTP client).
-
-`claims` lists active work on the target. Reads are allowed while another participant is working. The caller decides whether to return, fail, or wait.
-
-## Claimed Behavior
-
-Claimed behavior is explicit, and there are only two policies:
-
-- `ifClaimed: 'return'` (the default) returns the row plus the current claims with the read.
-- `ifClaimed: 'fail'` throws `AbloClaimedError`.
-
-Reads never block on a claim. To wait for a row to free up, `claim({ id })` it —
-the claim queues fairly behind the current holder and is granted when the row
-frees. Use `ifClaimed: 'fail'` when you'd rather refuse to read a claimed row.
-
-```ts
-// Read a claimed row without blocking, surfacing who holds it:
-await api.model('reports').retrieve({
-  id: 'report_stockholm',
-  ifClaimed: 'return',
-});
-
-// Or wait for it to free up by queueing your own claim:
-await api.model('reports').claim({ id: 'report_stockholm' });
-```
-
-## Write
-
-Use model methods as the normal write path:
-
-```ts
-const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
-const updated = await ablo.weatherReports.update({
-  id: 'report_stockholm',
-  data: { status: 'ready' },
-  readAt: snap.stamp,
-  onStale: 'reject',
-  wait: 'confirmed',
-});
-```
-
-Write checks:
-
-- authorization
-- stale state via `readAt`
-- active claim conflicts
-- idempotency when an idempotency key is provided
-
-Use `commits.create(...)` only for low-level batch writes.
-
-## Receipt
-
-Schema model writes return the updated row. Passing `wait: 'confirmed'` waits for
-the server confirmation before resolving. Lower-level model writes return a
-receipt object for custom runtimes that need protocol-level proof.
-
-## Interaction Model
-
-The common agent run is:
-
-1. Read the row through `ablo.<model>.retrieve({ id })` (or `list({ where })`).
-2. Claim it: `await using claim = await ablo.<model>.claim({ id })` — waits if held, hands you `claim.data`.
-3. Do the slow work from `claim.data`.
-4. Write with `ablo.<model>.update({ id, data })`.
-5. The claim auto-releases when it goes out of scope (`await using`).
-
-The underlying primitives are Model, Claim, Commit, and Receipt. Most schema
-users should not call `commits.create(...)` directly.
-
-## Public HTTP Routes
-
-- `GET    /v1/models/{model}/{id}` — read state plus active claims
-- `POST   /v1/commits` — apply mutations
-Use `Authorization: Bearer <api key>` for platform calls.