@abloatai/ablo 0.3.0

package/docs/examples/nextjs.md

@@ -0,0 +1,88 @@
+# Next.js Example
+
+A production-shaped Next.js + Ablo Sync app. App Router, Server Actions, React
+Server Components, and live client subscriptions.
+
+## Structure
+
+```txt
+app/
+  tasks/
+    [id]/
+      page.tsx          # RSC: retrieve + render
+      actions.ts        # Server Action: schema update with stale-state check
+      TaskEditor.tsx    # Client: live updates
+  lib/
+    ablo.ts             # Schema-backed Ablo client for server actions
+```
+
+## RSC Initial Render
+
+```tsx
+// app/tasks/[id]/page.tsx
+import { ablo } from '@/lib/ablo';
+
+export default async function TaskPage({
+  params,
+}: { params: { id: string } }) {
+  await ablo.ready();
+  const [task] = await ablo.tasks.load({ where: { id: params.id } });
+  if (!task) return null;
+
+  return <TaskEditor task={task} />;
+}
+```
+
+## Server Action Commit
+
+```ts
+// app/tasks/[id]/actions.ts
+'use server';
+
+import { ablo } from '@/lib/ablo';
+
+export async function markDone(id: string) {
+  const busy = ablo.intents.list({ resource: 'tasks', id });
+  if (busy.length > 0) return { status: 'busy', intents: busy };
+
+  const snap = ablo.snapshot({ tasks: id });
+  const task = await ablo.tasks.update(
+    id,
+    { status: 'done' },
+    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+  );
+
+  return { status: 'done', task };
+}
+```
+
+If another participant commits between the read and the write, the commit
+rejects. The action can re-fetch and ask the user to retry.
+
+## Live Client
+
+```tsx
+'use client';
+
+import { useAblo } from '@ablo/sync-engine/react';
+
+export function TaskEditor({ task: serverTask }: Props) {
+  const data = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
+  const intents = useAblo((ablo) =>
+    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
+  ) ?? [];
+  const busy = intents.length > 0;
+
+  return (
+    <button disabled={busy || data.status === 'done'}>
+      {busy ? 'Someone is editing' : 'Mark done'}
+    </button>
+  );
+}
+```
+
+## More
+
+- [Next.js landing](/nextjs) — the product overview.
+- [React reference](/docs/react) — every option on `useAblo`.
+- [API reference](/docs/api) — every option on the write path.

package/docs/examples/server-agent.md

@@ -0,0 +1,86 @@
+# Server Agent
+
+Most server agents should import the app schema and use the same model methods
+as the product UI.
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+
+const schema = defineSchema({
+  tasks: model({
+    title: z.string(),
+    status: z.enum(['todo', 'doing', 'done']),
+    summary: z.string().optional(),
+  }),
+});
+
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+
+export async function completeTask(taskId: string) {
+  await ablo.ready();
+
+  const [task] = await ablo.tasks.load({ where: { id: taskId } });
+  if (!task) return { status: 'not_found' };
+
+  const busy = ablo.intents.list({ resource: 'tasks', id: taskId });
+  if (busy.length > 0) {
+    return { status: 'busy', intents: busy };
+  }
+
+  const snap = ablo.snapshot({ tasks: taskId });
+  const updated = await ablo.tasks.update(
+    taskId,
+    { status: 'done' },
+    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+  );
+
+  return { status: 'done', task: updated };
+}
+```
+
+## Advanced Schema-Less Run
+
+Use `agent.run(...)` when the worker intentionally cannot import the app schema.
+It creates the run envelope and returns `done`, `failed`, or `cancelled`.
+
+```ts
+const api = Ablo({ apiKey: process.env.ABLO_API_KEY });
+
+const result = await api.agent('task-writer', {
+  can: ['tasks.retrieve', 'tasks.update'],
+  syncGroups: ['workspace:acme'],
+}).run(
+  {
+    prompt: 'Mark task_123 done.',
+    surface: 'agent_worker',
+  },
+  async ({ resource }) => {
+    const tasks = resource<{ title: string; status: string }>('tasks');
+
+    const { data, stamp, intents } = await tasks.retrieve('task_123', {
+      ifBusy: 'return',
+    });
+
+    if (intents.length > 0) {
+      return { skipped: true, reason: 'busy' };
+    }
+
+    return tasks.update(
+      'task_123',
+      { status: 'done' },
+      { readAt: stamp, onStale: 'reject', wait: 'confirmed' },
+    );
+  },
+);
+
+if (result.status === 'failed') throw result.error;
+if (result.status === 'cancelled') return;
+```
+
+Use the schema-backed version first. The schema-less version is for generic
+agent infrastructure, MCP routes, and platform code.
+

package/docs/guarantees.md

@@ -0,0 +1,148 @@
+# Guarantees
+
+This page is the short contract for what Ablo Sync guarantees at the state
+boundary.
+
+## Confirmed Writes
+
+`wait: 'confirmed'` resolves only after the server accepts the write and returns
+the authoritative sync cursor.
+
+```ts
+const updated = await ablo.tasks.update(
+  'task_123',
+  { status: 'done' },
+  { wait: 'confirmed' },
+);
+```
+
+If the call resolves, the write was accepted by the server. If it rejects, the
+error explains whether the write was rejected for auth, validation, stale state,
+active intent conflict, idempotency, rate limit, or transport failure.
+
+Schema model writes return the updated model row. Advanced resource writes and
+`commits.create(...)` return a receipt with the commit status and sync cursor.
+
+## Optimistic Local State
+
+Schema model writes update local state optimistically. This keeps UI and agent
+tools responsive while the commit is sent to the server.
+
+- With `wait: 'queued'` or omitted, the promise resolves after the local mutation
+  is queued.
+- With `wait: 'confirmed'`, the promise waits for server confirmation.
+- If the server rejects the write, the SDK rolls back the optimistic change and
+  raises a typed error.
+
+The server remains the source of truth.
+
+## Stale-Write Protection
+
+Use `snapshot(...)` and `readAt` when a write depends on state the agent already
+read:
+
+```ts
+const snap = ablo.snapshot({ tasks: 'task_123' });
+
+await ablo.tasks.update(
+  'task_123',
+  { status: 'done' },
+  { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+);
+```
+
+`onStale: 'reject'` prevents lost updates. If the target changed after the
+snapshot, the server rejects the write instead of applying stale reasoning.
+
+Advanced policies exist for controlled product flows:
+
+- `reject` fails the write when state moved.
+- `force` applies the write without stale protection.
+- `flag` accepts the write and marks it for product review.
+- `merge` is reserved for server-defined merge behavior.
+
+## Intent Coordination
+
+Intents are live coordination signals. They are not database locks.
+
+When another human or agent is active on the same target, the caller chooses the
+behavior:
+
+- `ifBusy: 'return'` returns active intents immediately.
+- `ifBusy: 'wait'` waits until the matching intent clears.
+- `ifBusy: 'fail'` throws `AbloBusyError` with the active intents attached.
+
+Schema clients wait from the realtime intent stream. Schema-less HTTP callers
+must pass an explicit `busyPollInterval` if they choose `ifBusy: 'wait'`; Ablo
+does not hide a hard-coded polling loop. `busyTimeout` is only a maximum wait.
+
+## Agent Runs
+
+`agent.run(...)` is the advanced schema-less run envelope for workers that cannot
+import the app schema. It returns one of three statuses:
+
+- `done` — the handler returned successfully.
+- `failed` — the handler threw or the commit failed.
+- `cancelled` — the run signal aborted.
+
+Normal schema-backed agents should import the same schema as the app and write
+through `ablo.<model>.update(...)`. The lower-level run envelope exists for
+platform runtimes that need capability and task management without app code.
+
+## Capabilities and Tasks
+
+Capabilities scope what an agent is allowed to do. Tasks group a run for audit
+and cost attribution.
+
+Most users do not create either one manually. The SDK and hosted API manage the
+common case. Manual capability and task APIs are for platform builders, custom
+agent runtimes, and internal infrastructure.
+
+Use `lease` as a crash cleanup window. A successful agent run still closes when
+the handler returns, fails, or is cancelled.
+
+## Audit Trail
+
+Accepted writes can be attributed to:
+
+- the actor that wrote,
+- the human or system the actor worked on behalf of,
+- the capability that scoped the write,
+- the task or run that caused it,
+- the resource, operation, and state cursor.
+
+For agent work, this is what lets an audit surface answer: "what changed, who
+authorized it, which run did it, and what state was it based on?"
+
+## Persistence
+
+Ablo defaults to volatile local persistence. That keeps the SDK focused on
+coordination and audit instead of silently becoming a browser storage product.
+
+Opt into durable browser cache and offline queueing when you need it:
+
+```ts
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  persistence: 'indexeddb',
+});
+```
+
+Node, SSR, tests, and agents use volatile in-memory persistence automatically.
+
+## Storage Boundary
+
+Ablo does not need a customer database URL. When your own database is canonical,
+Ablo calls a signed Data Source endpoint and records the coordination result for
+receipts, realtime fanout, and audit. See [Connect Your Database](./data-sources.md).
+
+## Batches
+
+Most apps should use `ablo.<model>.create/update/delete`. Use
+`commits.create(...)` only when you need a low-level batch or a schema-less
+runtime.
+
+Each operation in the commit carries its own target, data, stale policy, and
+idempotency context. The server validates authorization, stale state, active
+intent conflicts, and idempotency before accepting the commit.

package/docs/index.md

@@ -0,0 +1,97 @@
+# Ablo Docs
+
+Ablo is a state control API for **humans and AI agents editing the same
+typed state in real time, with attribution, conflict handling, and
+fast cutoff**.
+
+It gives agents a narrow way to write production state: declare models, load current state, coordinate active work, and write with stale-state checks. Capabilities, tasks, commits, and receipts are the protocol underneath, not first-integration ceremony.
+
+Multiplayer is not a separate product mode. If humans, server actions, and agents
+use the same `Ablo({ schema, apiKey })` client and write through
+`ablo.<model>`, Ablo fans out confirmed deltas, exposes active intents, and
+rejects stale writes for every participant.
+
+## What you get, in three commitments
+
+These commitments drive every design choice in the rest of the docs; if
+they don't match what you're building, the trade-offs land elsewhere
+(Replicache, ElectricSQL, PowerSync for human-only real-time; Zero for
+query-shaped sync).
+
+- **One model API for every actor.** `ablo.<model>.update(...)` is the
+  call from React components, server actions, background workers, and
+  AI agents alike. No separate "agent SDK," no parallel mutation path.
+  Attribution comes from the credential, not the call site.
+- **Server owns the scope convention.** Tenancy / per-entity scope
+  prefixes (`org:`, `deck:`, or your own `region:` / `customer:`) are
+  declared once on the schema's `identityRoles`. Consumer code never
+  composes group strings. Same boundary Liveblocks (`prepareSession`),
+  PowerSync (named streams), and Zero (synced queries) settled on.
+- **Capabilities, not API keys, for agents.** Per-run, per-scope, leased
+  credentials with per-request signature verification and instant
+  revocation. The 2025-26 AI-agent auth consensus (OAuth 2.1 / MCP,
+  AWS STS, Vault leases, Auth0 Token Vault) converged on this shape;
+  capabilities are Ablo's instance. See
+  [Capabilities](./capabilities.md#why-capabilities-not-api-keys) for
+  the design rationale.
+
+## Start here
+
+- [Quickstart](./quickstart.md) — Make your first schema-backed write.
+- [Integration Guide](./integration-guide.md) — Choose Ablo-managed state, Data Source, React, multiplayer, and agent patterns.
+- [Guarantees](./guarantees.md) — What confirmed writes, stale checks, and intents guarantee.
+- [Interaction Model](./interaction-model.md) — The commit plane and control plane.
+- [API Reference](./api.md) — Resource-by-resource method shape.
+- [Client Behavior](./client-behavior.md) — Options, errors, retries, timeouts, and imports.
+- [Connect Your Database](./data-sources.md) — Keep canonical rows in your app database without giving Ablo database credentials.
+- [API Keys](./api-keys.md) — Bearer tokens for the public API.
+
+## API shape
+
+| Plane | Primitives | Purpose |
+|---|---|---|
+| State | `Schema`, `Model`, `Intent`, `Receipt` | The product path. Load, coordinate, write, confirm. |
+| Commit | `Resource`, `Commit` | Advanced protocol path for custom runtimes and batches. |
+| Control | `Capability`, `Task`, `Usage` | The authority path. Scope, attribute, meter, audit. |
+| Storage | `Managed State`, `Data Source` | Ablo stores declared models by default; existing app tables use a signed Data Source. |
+
+## Use cases
+
+- **Let agents write to shared state** — Give an AI agent scoped, revocable write access to your typed data.
+- **Coordinate multiple actors** — Use intents to broadcast pre-write declarations across humans and agents.
+- **Audit every agent action** — Trace any write back to a human in one query.
+- **Build collaborative editors** — Humans and agents on the same record, with realtime updates and stale-read protection.
+- **Meter and gate API usage** — Per-key, per-team usage reports and quota enforcement.
+- **Integrate with A2A and MCP** — Speak the same protocols as Claude, Cursor, Gemini.
+
+## Concepts
+
+- [Model Methods](./api.md#model-methods) — Load and write typed state.
+- [Integration Guide](./integration-guide.md) — The normal app path and optional pieces.
+- [Guarantees](./guarantees.md) — Confirmed writes, optimistic state, stale-write protection, and agent lifecycle.
+- [Intent](./api.md#intent) — Broadcast proposed work before committing.
+- [Advanced Commit API](./api.md#advanced-commit-api) — Apply custom batch mutations.
+- [Connect Your Database](./data-sources.md) — Where data lands when your app database is canonical.
+- [Receipt](./api.md#receipt) — Confirm what landed.
+- [Capability](./api.md#capability) — Signed credentials for a bounded actor, operation set, sync group, and lease.
+- [Task](./api.md#task) — One agent run; the audit envelope for commits and cost.
+- [Usage](./api.md#usage) — Metering and audit dimensions.
+
+## Examples
+
+- [AI SDK Tool](./examples/ai-sdk-tool.md) — Put Ablo inside an AI SDK tool call.
+- [Existing Python Backend](./examples/existing-python-backend.md) — Add multiplayer and future agent writes without replacing a Python API server.
+- [Agent + Human](./examples/agent-human.md) — Yield when a human is editing the same task.
+- [Server Agent](./examples/server-agent.md) — Schema-backed worker plus advanced schema-less run.
+- [Next.js](./examples/nextjs.md) — App-router setup with React bindings.
+
+## Runtime builds
+
+- `@ablo/sync-engine` — schema-powered sync client for typed model operations, realtime, intents, and receipts.
+- `Ablo({ apiKey })` — advanced resource client for runtimes that intentionally cannot import a schema.
+
+## More
+
+- [README](../README.md) — product overview and first example.
+- [AGENTS.md](../AGENTS.md) — short installation guidance for coding assistants.
+- [Changelog](../CHANGELOG.md) — what shipped recently.