@abloatai/ablo 0.9.1 → 0.9.3

package/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+Ablo lets AI agents and humans safely edit the same typed data without clobbering each other. When two of them touch the same row, a "claim" makes one wait for the other instead of overwriting it. This file shows a coding assistant the one safe pattern: read a row, claim it, then write.
+
+Claims don't lock. If another writer holds the row, `claim` waits for them and re-reads the fresh row before handing it to you — so two writers serialize instead of clobbering.
+
+## Start here — scaffold with `ablo init`
+
+Don't hand-write the integration. Run the CLI; it generates the current-API schema, client, Data Source endpoint, and (for Next.js) the browser provider + session route:
+
+- **Scaffold:** `npx ablo init --yes` — flag-driven, never prompts. Override defaults with `--framework <nextjs|vite|remix|vanilla>`, `--auth <apikey|…>`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`. (Plain `ablo init` needs a TTY and will **HANG** in an agent/CI run — always pass `--yes`.)
+- **Auth:** set `ABLO_API_KEY` in the environment. Do **NOT** run `ablo login` — it opens a browser device flow and blocks an agent.
+- **Provision your DB (Data Source mode):** `npx ablo migrate` creates the tables for your Ablo models plus the adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`). It does **not** touch your other tables — keep your own migrations (drizzle-kit / prisma migrate) for auth and anything not in the Ablo schema.
+- **Adopt an existing DB schema:** `npx ablo pull prisma [path]` / `pull drizzle <module>` (lossless) or `pull` (live DB, lossy). Writes `ablo/schema.ts`.
+- **Push your schema — REQUIRED before any write works.** The server keeps its OWN copy of the schema. After you create or edit `ablo/schema.ts`, run `npx ablo push` (one-shot) — or `npx ablo dev --no-watch`. **Skip this and every write to a new or changed model fails with `server_execute_unknown_model`.** (Plain `ablo dev` watches forever — never run it bare in an agent.)
+- **Other long-running:** `npx ablo logs --no-follow` (default tails forever). `npx ablo mode test|live` ALWAYS pass the argument. `status`, `push`, `pull`, `check`, `generate` are one-shot — safe as-is.
+
+The generated `ablo/data-source.ts` is the whole Data Source endpoint and needs no hand-editing: `dataSourceNext({ schema, apiKey, adapter: prismaDataSource(prisma, schema) })` (or `drizzleDataSource(db, schema)`). The adapter owns commit / idempotency / outbox.
+
+## Rule
+
+Edit the generated files; teach this API only:
+
+```ts
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+```
+
+The schema is the integration contract — it drives typed model clients, React selectors, server and agent writes, the Data Source shape, and schema push. Ablo owns only the models you declare; your auth and other non-synced tables stay in your own ORM schema, side by side in the same database. Don't create a parallel string-keyed write path for rows that belong to a schema model.
+
+Every model verb takes ONE options object. The common loop:
+
+1. **Read** the row — `await ablo.<model>.retrieve({ id })` (async; from the server) or `await ablo.<model>.list({ where })` for many. In React render, read synchronously with `useAblo((a) => a.<model>.get(id))`.
+2. **See who's active** (optional) — `ablo.<model>.claim.state({ id })` (synchronous; never blocks).
+3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, action?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
+4. **Write** — `await ablo.<model>.update({ id: claim.data.id, data })`. Because you hold the claim, the write is rejected if the row changed underneath you.
+
+Keep coding assistants on this schema-backed path.
+
+## Minimal example
+
+```ts
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
+  }),
+});
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+if (!report) throw new Error('Report not found');
+
+// If someone else holds the row, claim waits for them and re-reads the fresh
+// row before resolving. Auto-released at the end of this scope (`await using`).
+await using claim = await ablo.weatherReports.claim({
+  id: 'report_stockholm',
+  action: 'forecasting',
+  ttl: '2m',
+});
+const claimed = claim.data;
+
+// Because we hold the claim, update is rejected if the row changed underneath us.
+await ablo.weatherReports.update({
+  id: claimed.id,
+  data: { status: 'ready', forecast: await getForecast(claimed.location) },
+});
+```
+
+## Coordination surface
+
+Claims live on a callable namespace beside `create` / `update` / `retrieve`. Every member takes an options object:
+
+- `await using claim = await ablo.<model>.claim({ id })` — acquire the row (waits if held); read it via `claim.data`; auto-releases on scope exit (or call `claim.release()`).
+- `ablo.<model>.claim.state({ id })` — who is currently working on the row (synchronous; never blocks).
+- `ablo.<model>.claim.queue({ id })` — who is waiting behind the current holder.
+- `ablo.<model>.claim.release({ id })` — release a claim early.
+- `ablo.<model>.claim.reorder({ id, order })` — reorder the waiting queue.
+
+Most users declare a schema and write through `ablo.<model>.update({ id, data })`.

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.9.3
+
+### Patch Changes
+
+- Onboarding: quickstart leads with your-own-database (Drizzle Data Source), drop Ablo-managed mode, add `ablo push` step; context7 library-claim config.
+
+## 0.9.2
+
+### Patch Changes
+
+- Developer-onboarding overhaul so an LLM or a person gets a working integration on the first try.
+  - **`ablo init` scaffolds a project that builds and is current-API.** The Next.js scaffold now ships `app/providers.tsx` + an `app/api/ablo-session` route, uses `useAblo` (the removed `withSync` is gone), object-param verbs, and never bundles your `sk_` key into the browser. The webhook receiver moved off the `[...all]` catch-all.
+  - **Agent docs are accurate and ship.** `AGENTS.md`, `llms.txt`, and `llms-full.txt` are on the 0.9.x API (object-param `create`/`update`/`delete`/`retrieve`, disposable `await using claim`, `AbloProvider client` prop), lead with `ablo init`, and `AGENTS.md` now ships in the package.
+  - **`ablo push` is self-documenting.** Writing to a model the server hasn't seen now fails with an error that tells you to run `ablo push` (the `server_execute_unknown_model` / `unknown_model` messages), instead of a cryptic "unknown model."
+  - **`intents` is deprecated in favor of `claim`** everywhere the docs and the MCP scaffold/prompts teach or generate coordination; the public `ablo.intents` accessor is marked `@internal`.
+  - Docs say Node 24+, and the `drizzle-orm` peer floor is `>=0.44`.
+
+- a88747a: Remove the `turn` primitive and the agent-work `tasks` resource from the client surface — the SDK is now purely `ablo.<model>` + `claim`.
+
+  **Breaking**
+  - `engine.beginTurn()`, the `Turn` handle interface, and the `Ablo.Turn` type are removed. `AbloApi.beginTurn` and the HTTP client's `beginTurn` are gone too.
+  - `CommitCreateOptions.causedByTaskId` is removed. (Lineage is no longer stamped from the client.)
+  - The engine no longer exposes a `protocol` accessor or a public `tasks` work-unit resource. `ablo.tasks` is, and always was, the schema `tasks` model proxy.
+  - The **`agent().run()` helper and the low-level agent/task type family are removed**: `AbloApi.agent(id, options)` and `AbloApi.tasks` (the `TaskResource`), plus the exported types `Agent`, `AgentOptions`, `AgentRunOptions`, `AgentRunResult`/`Done`/`Failed`/`Cancelled`, `AgentRunStatus`, `AgentRunContext`, `AgentModelClient`, `AgentModelReadOptions`, `AgentModelMutationOptions`, `AgentIntentOptions`, `AgentIntentInput`, `Task`, `TaskResource`, `TaskCreateOptions`, `TaskCloseOptions`, `TaskCloseResult` (and the `Ablo.*` namespace aliases for all of them). The `Ablo.Auth.Agent` principal constructor and the schema-backed `tasks` model are unaffected.
+
+  **Why**
+
+  `turn`/`agent_tasks` was a second coordination-and-attribution mechanism living alongside `claim`. It is redundant on the client:
+  - `claim` already serializes writers **and** carries the causal link — its `intent` id rides on every guarded write.
+  - The server stamps `actor` / `onBehalfOf` / `capabilityId` onto each delta from the auth context.
+  - Per-run token/cost is recorded in Langfuse, not the `agent_tasks` table.
+
+  So the only thing the client lost is the audit pane's "show everything this exact prompt produced" filter, which keyed off `caused_by_task_id`; new writes leave that column null.
+
+  **Migration**
+
+  Agents stop opening/closing tasks — just issue `ablo.<model>` writes (schema-backed) or `ablo.commits.create(...)` (schema-less) under a `claim`. Replace `Ablo({ apiKey }).agent(id, opts).run(prompt, handler)` with: mint a scoped credential via `sessions.create({ agent })`, then `claim` the row and `update` / `commits.create`.
+
+  The **server** `agent_tasks` table, the `caused_by_task_id` delta column, the `/api/sync/commit` wire field, and the `agent_actions_log` compliance hash-chain remain in place but **dormant** (client writes leave the field null) — they are load-bearing for the tamper-evident audit chain and historical-row audit JOINs, so they are intentionally NOT dropped. The dead `/v1/tasks` + `/api/agent/turn` route handlers ARE removed (zero live callers).
+
 ## 0.9.1
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@abloatai/ablo.svg)](https://www.npmjs.com/package/@abloatai/ablo)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 [![types](https://img.shields.io/badge/types-included-blue.svg)](#)
-[![runtime](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](#keys--runtime)
+[![runtime](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](#keys--runtime)
 
 **Let people and AI agents work on the same data without overwriting each other.**
 
@@ -33,27 +33,43 @@ claims are visible while the work is still in progress.
 
 [Get started ↓](#quick-start) · point your coding agent at the shipped `llms.txt`
 
-It works with the auth and database you already have: realtime data is scoped to
-*sync groups* from your own identity, and your database can stay the source of
-truth via a Data Source.
+It works with the auth and database you already have. **Your database is the
+system of record — Ablo never hosts your data.** Ablo is the transaction layer
+on top of it: realtime data is scoped to *sync groups* from your own identity,
+and every committed row lives in your Postgres.
 
 **Built for** collaborative editors, AI agent workflows, and internal tools —
 anywhere people and agents change shared state and everyone has to see it live.
 
 ## Set up
 
+The CLI takes you from nothing to a synced schema — it handles the account,
+the key, and the env file. You bring one thing: a Postgres `DATABASE_URL`
+(local, Neon, RDS — any will do; **your database is the system of record,
+Ablo never hosts your data**).
+
 ```bash
 npm install @abloatai/ablo
+npx ablo login     # opens the browser: sign in (or sign up) → a sk_test_ key is saved locally
+npx ablo init      # scaffolds ablo/schema.ts (offers to log in if you skipped it)
+npx ablo migrate   # creates the synced tables in YOUR Postgres (reads DATABASE_URL)
+npx ablo dev       # pushes your schema (test mode), writes ABLO_API_KEY to .env.local, watches for changes
 ```
 
-**Keys & runtime.** Ablo needs Node 22+ and TypeScript 5+. Grab an `sk_test_*`
-key for a sandbox
-(`export ABLO_API_KEY=sk_test_...`); keep keys in trusted server runtimes only.
+After `ablo dev`, the [Quick Start](#quick-start) below runs as-is —
+`ABLO_API_KEY` is already in `.env.local` (frameworks load it automatically;
+plain Node: `node --env-file=.env.local app.ts`). `npx ablo status` shows
+what's configured at any time.
+
+**Keys & runtime.** Ablo needs Node 24+ and TypeScript 5+. Keys come in two of
+*your* environments — `sk_test_` and `sk_live_`, like Stripe — and `ablo login`
+mints both. Keep the key and the database URL in trusted server runtimes only.
 In the browser, `<AbloProvider>` authenticates with the signed-in user's
-session — never the raw key.
+session — never the raw key, never the database URL. Prefer the connection
+string never leaving your infrastructure? Expose a signed
+[Data Source endpoint](./docs/data-sources.md) instead and omit `databaseUrl`.
 
-Then wire it by hand — the [Quick Start](#quick-start) below is the shape to
-copy. For production (React, an existing backend, Data Source, agents), the
+For production (React, an existing backend, Data Source, agents), the
 [Integration Guide](./docs/integration-guide.md) is the deeper map.
 
 **Prefer to let an agent wire it?** The package ships an `llms.txt` — a precise
@@ -78,7 +94,8 @@ const schema = defineSchema({
 
 const ablo = Ablo({
   schema,
-  apiKey: process.env.ABLO_API_KEY,
+  apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo dev`
+  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
 });
 
 await ablo.ready();
@@ -99,7 +116,7 @@ const forecast = await fetchForecast(report.location); // slow: API or LLM call
 await ablo.weatherReports.update({ id: report.id, data: { status: 'ready', forecast } });
 
 const ready = ablo.weatherReports.get(created.id);
-console.log({ id: ready.id, status: ready.status });
+console.log({ id: ready?.id, status: ready?.status });
 
 await ablo.dispose();
 ```
@@ -218,12 +235,16 @@ provider and read with hooks, from `@abloatai/ablo/react`. Wrap your tree once;
 everything inside is live.
 
 ```tsx
+import Ablo from '@abloatai/ablo';
 import { AbloProvider, useAblo } from '@abloatai/ablo/react';
 import { schema } from './ablo/schema';
 
+// Build the client once — it authenticates via your session route, no key in the browser.
+const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+
 function App() {
   return (
-    <AbloProvider schema={schema}>
+    <AbloProvider client={ablo}>
       <Report id="report_stockholm" />
     </AbloProvider>
   );
@@ -250,8 +271,9 @@ method as the server example above.
 `<AbloProvider>` owns the connection — no API key in the browser. That's the
 whole loop: read with `useAblo(selector)`, write with `ablo.<model>`, and every
 other client (human or agent) on that row sees it in real time. See
-[React](./docs/react.md) for the full `<AbloProvider>` prop surface (`userId`,
-`teamIds`, `syncGroups`, `fallback`, `bootstrapMode`) and status hooks.
+[React](./docs/react.md) for the `<AbloProvider>` prop surface (`client`,
+`userId`, `fallback`, `onError`) — schema, scope, and team membership live on the
+`Ablo({ … })` client you pass it — plus status hooks.
 
 ## Identity & Sync Groups
 
@@ -270,7 +292,10 @@ to sync-group strings.
 `userId` / `teamIds` come from your auth, resolved server-side:
 
 ```tsx
-<AbloProvider schema={schema} userId={user.id} teamIds={user.teamIds}>
+// team membership is asserted server-side when the session route mints the token.
+const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+
+<AbloProvider client={ablo} userId={user.id}>
   <App />
 </AbloProvider>
 ```
@@ -316,18 +341,18 @@ curl https://api.abloatai.com/v1/commits \
 { "object": "commit_receipt", "status": "confirmed", "serverTxId": "tx_…", "lastSyncId": 1042, "ops": 1 }
 ```
 
-## Connect Your Database
+## Your Database
 
-Every schema model has a backing store. By default, Ablo stores rows for the
-models you declare, so `ablo.weatherReports.create({ data })` and `ablo.weatherReports.update({ id, data })`
-write to Ablo-managed state.
+Every schema model is backed by **your own database** — Ablo is the transaction
+layer on top of it, never the home for your rows. Two ways to connect it:
 
-If your existing database stays the source of truth, connect it as a Data
-Source: Ablo sends signed commit requests to an endpoint you host, and your app
-writes its own database. Your `DATABASE_URL` stays in your app — Ablo only ever
-sees the API key.
+| | How Ablo reaches your Postgres | Use when |
+| --- | --- | --- |
+| **Connection string** (default) | `databaseUrl` at init. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
+| **Signed endpoint** | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
 
-See [Connect Your Database](./docs/data-sources.md) for the integration shape.
+Same product, same truth either way: your database is the system of record. See
+[Connect Your Database](./docs/data-sources.md) for both shapes.
 
 ## Configuration
 
@@ -337,6 +362,7 @@ See [Connect Your Database](./docs/data-sources.md) for the integration shape.
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
+| `databaseUrl` | `string \| null` | `process.env.DATABASE_URL` | Your Postgres, registered as the data plane. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead. |
 | `baseURL` | `string` | `wss://api.abloatai.com` | Point at a self-hosted or private API |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
@@ -387,11 +413,11 @@ contract; there are no retry or timeout knobs to tune.
 - [Identity & Sync Groups](./docs/identity.md) — use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
 - [Schema Contract](./docs/schema-contract.md) — one schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
-- [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.
+- [Integration Guide](./docs/integration-guide.md) — integrate React, your database, multiplayer, and agents.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
 - [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
-- [Connect Your Database](./docs/data-sources.md) — keep canonical rows in your app database without giving Ablo database credentials.
+- [Connect Your Database](./docs/data-sources.md) — connect your Postgres by connection string (`databaseUrl`) or signed endpoint; your database is the system of record either way.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.
 - [AI SDK Tool](./docs/examples/ai-sdk-tool.md) — use Ablo inside an AI SDK tool call.
 - [Server Agent](./docs/examples/server-agent.md) — schema-backed worker.

package/dist/BaseSyncedStore.d.ts

@@ -21,7 +21,6 @@ import { QueryProcessor } from './core/QueryProcessor.js';
 import { Model } from './Model.js';
 import { ModelScope } from './ObjectPool.js';
 import type { Schema } from './schema/schema.js';
-import { type ReaderActions } from './mutators/readerActions.js';
 import type { LocalMutation } from './react/context.js';
 import type { AuthCredentialSource } from './auth/credentialSource.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
@@ -224,18 +223,6 @@ export declare function deriveSyncPlanFromSchema(schema: Schema): {
     enrichmentPlan: EnrichmentPlanEntry[];
     foreignKeyIndexes: ForeignKeyIndexSpec[];
 };
-/**
- * Schema-derived accessor namespace exposed on `store.query`. Each key is
- * a model name from the schema and resolves to a `ReaderActions<S, K>`
- * with `findById` / `findMany` / `findFirst` / `count`. Return types are
- * inferred from the schema (`InferModel<S, K>`) so callers don't need to
- * cast or pass class constructors.
- *
- * Prisma / Drizzle / Zero all use this shape: `store.query.<modelKey>.*`.
- */
-export type QueryNamespace<S extends Schema> = {
-    readonly [K in keyof S['models'] & string]: ReaderActions<S, K>;
-};
 export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents, TSchema extends Schema = Schema> {
     syncStatus: SyncStatus;
     protected readonly syncClient: SyncClient;
@@ -244,13 +231,10 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected readonly modelRegistry: ModelRegistry;
     protected readonly auth?: AuthCredentialSource;
     /**
-     * Schema the store was constructed with. Persisted so the `query`
-     * accessor namespace can build typed per-model reader actions lazily
-     * without callers having to pass the schema at every lookup site.
+     * Schema the store was constructed with. Used by the schema-typed
+     * `create(key, data)` factory and model self-healing.
      */
     protected readonly schema?: TSchema;
-    /** Lazily-built `query.<modelKey>.*` accessor namespace. */
-    private _queryProxy?;
     protected syncWebSocket: SyncWebSocket<TCollaboration> | null;
     private _syncServerUrl?;
     /**
@@ -694,24 +678,6 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         id: string;
         archivedAt?: Date | null;
     }>(entity: T): Promise<void>;
-    /**
-     * Schema-keyed accessor namespace — the primary type-safe lookup surface.
-     *
-     * ```ts
-     * const chat = store.query.chats.retrieve(chatId);  // Chat | undefined
-     * const slides = store.query.slides.findMany({ where: { deckId } });  // Slide[]
-     * ```
-     *
-     * Each `query.<modelKey>` is a `ReaderActions<Schema, K>` built lazily on
-     * first access via `createReaderActions`. The returned types are inferred
-     * from the schema (`InferModel<S, K>`), including `InferRelations` — so
-     * `chat.messages`, `slide.layers`, etc. are typed without a cast.
-     *
-     * Throws if the store was constructed without a schema (class-based
-     * subclasses that wire models via `modelRegistry.registerModel` directly
-     * don't have access to schema-derived inference).
-     */
-    get query(): QueryNamespace<TSchema>;
     /** Retrieve a single entity by id. Synchronous pool read. */
     retrieve(_modelClass: ModelConstructor<Model>, id: string): Model | undefined;
     /** Find any entity by ID regardless of type */

package/dist/BaseSyncedStore.js

@@ -22,7 +22,6 @@ import { getContext } from './context.js';
 import { SyncSessionError } from './errors.js';
 import { ModelScope } from './ObjectPool.js';
 import { LazyReferenceCollection } from './LazyReferenceCollection.js';
-import { createReaderActions } from './mutators/readerActions.js';
 /** Bootstrap timeout configuration */
 export const BOOTSTRAP_CONFIG = {
     OVERALL_TIMEOUT_MS: 15_000,
@@ -126,13 +125,10 @@ export class BaseSyncedStore {
     modelRegistry;
     auth;
     /**
-     * Schema the store was constructed with. Persisted so the `query`
-     * accessor namespace can build typed per-model reader actions lazily
-     * without callers having to pass the schema at every lookup site.
+     * Schema the store was constructed with. Used by the schema-typed
+     * `create(key, data)` factory and model self-healing.
      */
     schema;
-    /** Lazily-built `query.<modelKey>.*` accessor namespace. */
-    _queryProxy;
     // ── Real-time sync ──
     syncWebSocket = null;
     _syncServerUrl;
@@ -421,8 +417,12 @@ export class BaseSyncedStore {
      * emit here, so undo is naturally local-only (you can't undo a teammate).
      */
     subscribeLocalMutations(handler) {
-        return this.syncClient.subscribe('transaction:created', (data) => {
-            const tx = data;
+        // Tap the TransactionQueue directly via `onLocalTransaction`. The previous
+        // `syncClient.subscribe('transaction:created', …)` route registered the
+        // handler on SyncClient's OWN emitter, which never fires that event (only
+        // the queue's emitter does) — so undo recorded nothing. See
+        // `SyncClient.onLocalTransaction` for the full rationale.
+        return this.syncClient.onLocalTransaction((tx) => {
             if (!tx || !tx.type || !tx.modelName || !tx.modelId)
                 return;
             handler({
@@ -1785,53 +1785,9 @@ export class BaseSyncedStore {
         this.syncClient.update(model);
     }
     // ── Query API ────────────────────────────────────────────────────────────
-    /**
-     * Schema-keyed accessor namespace — the primary type-safe lookup surface.
-     *
-     * ```ts
-     * const chat = store.query.chats.retrieve(chatId);  // Chat | undefined
-     * const slides = store.query.slides.findMany({ where: { deckId } });  // Slide[]
-     * ```
-     *
-     * Each `query.<modelKey>` is a `ReaderActions<Schema, K>` built lazily on
-     * first access via `createReaderActions`. The returned types are inferred
-     * from the schema (`InferModel<S, K>`), including `InferRelations` — so
-     * `chat.messages`, `slide.layers`, etc. are typed without a cast.
-     *
-     * Throws if the store was constructed without a schema (class-based
-     * subclasses that wire models via `modelRegistry.registerModel` directly
-     * don't have access to schema-derived inference).
-     */
-    get query() {
-        if (!this.schema) {
-            throw new AbloValidationError('store.query requires a schema to be passed to the BaseSyncedStore constructor. ' +
-                'Pass `{ schema }` in the dependencies argument.', { code: 'store_query_schema_missing' });
-        }
-        if (!this._queryProxy) {
-            const schema = this.schema;
-            // BaseSyncedStore satisfies SyncStoreContract structurally via
-            // `findById` / `queryByClass` / `save` / `delete`. Pass `this`
-            // directly — `createReaderActions` accepts the contract shape.
-            const store = this;
-            const cache = new Map();
-            this._queryProxy = new Proxy({}, {
-                get: (_target, prop) => {
-                    if (typeof prop !== 'string')
-                        return undefined;
-                    const cached = cache.get(prop);
-                    if (cached)
-                        return cached;
-                    if (!(prop in schema.models)) {
-                        throw new AbloValidationError(`store.query: unknown model key "${prop}". Known keys: ${Object.keys(schema.models).join(', ')}`, { code: 'store_query_unknown_model' });
-                    }
-                    const actions = createReaderActions(schema, prop, store);
-                    cache.set(prop, actions);
-                    return actions;
-                },
-            });
-        }
-        return this._queryProxy;
-    }
+    // `store.query.<model>.*` was DELETED — `ablo.<model>.get/getAll` is the
+    // one read surface. Custom mutators still read transactionally through
+    // `tx.<model>` (mutators/Transaction.ts), which owns `createReaderActions`.
     /** Retrieve a single entity by id. Synchronous pool read. */
     retrieve(_modelClass, id) {
         return this.objectPool.get(id);

package/dist/NetworkMonitor.js

@@ -9,7 +9,10 @@
 import { EventEmitter } from 'events';
 import { getContext } from './context.js';
 export class NetworkMonitor extends EventEmitter {
-    isOnline = typeof navigator !== 'undefined' ? navigator.onLine : true;
+    // Only `navigator.onLine === false` means offline. Node 18+ exposes a global
+    // `navigator` with `onLine === undefined`, so the naive `navigator.onLine`
+    // would seed `false` (offline) on every server client — start optimistic.
+    isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
     lastOnlineCheck = new Date();
     constructor() {
         super();

package/dist/SyncClient.d.ts

@@ -13,7 +13,7 @@ import { EventEmitter } from 'events';
 import { TransactionQueue } from './transactions/TransactionQueue.js';
 import { type OptimisticEchoMetrics } from './transactions/OptimisticEchoTracker.js';
 import type { Database } from './Database.js';
-import type { MutationOptions } from './interfaces/index.js';
+import type { WriteOptions } from './interfaces/index.js';
 interface SyncObserver {
     onSync?: (event: SyncEvent) => void;
 }
@@ -38,7 +38,6 @@ export interface RehydrationStats {
     healed: number;
     elapsedMs: number;
 }
-type MutationWriteOptions = Pick<MutationOptions, 'readAt' | 'onStale'>;
 export declare class SyncClient extends EventEmitter {
     private objectPool;
     private database;
@@ -114,6 +113,12 @@ export declare class SyncClient extends EventEmitter {
      * Initialize sync client with authentication
      */
     initialize(userId: string, organizationId: string): Promise<void>;
+    /**
+     * The organization this client writes under (set by `initialize`).
+     * Read by the model proxy so `create()` defaults `organizationId` the
+     * same way the mutator path does — `null` until identity is wired.
+     */
+    getOrganizationId(): string | null;
     /**
      * Self-healing helper for individual model records.
      *
@@ -172,9 +177,9 @@ export declare class SyncClient extends EventEmitter {
      */
     private captureModelChanges;
     /** Add new model (CREATE) - works offline */
-    add(model: Model, options?: MutationWriteOptions): void;
+    add(model: Model, options?: WriteOptions): void;
     /** Update existing model (UPDATE) - works offline */
-    update(model: Model, options?: MutationWriteOptions): void;
+    update(model: Model, options?: WriteOptions): void;
     /**
      * Update existing model with pre-computed changes.
      * Used by saveManyOptimized when incoming models have empty change-tracking
@@ -186,7 +191,7 @@ export declare class SyncClient extends EventEmitter {
      *  but still need optimistic pool updates at the sync layer. */
     get gql(): import("./interfaces/index.js").MutationExecutor;
     /** Delete model (DELETE) - works offline */
-    delete(model: Model, options?: MutationWriteOptions): void;
+    delete(model: Model, options?: WriteOptions): void;
     /**
      * Clear all pending mutations for a specific model
      * Called before deletion to prevent "layer not found" errors on the server
@@ -383,6 +388,18 @@ export declare class SyncClient extends EventEmitter {
         error: Error;
         permanent?: boolean;
     }) => void): () => void;
+    /**
+     * Subscribe to LOCAL transaction creation with the full {@link Transaction}
+     * payload (`type`, `modelName`, `modelId`, `data`, `previousData`). This is
+     * the feed `BaseSyncedStore.subscribeLocalMutations` taps for undo recording.
+     *
+     * MUST subscribe to the TransactionQueue's emitter directly — that is the
+     * ONLY emitter that fires `transaction:created`. SyncClient's own emitter
+     * (reached via `subscribe()`) never re-broadcasts it, so routing undo through
+     * `subscribe('transaction:created')` silently records nothing. Mirrors
+     * `onMutationFailure`, which taps the queue for the same reason.
+     */
+    onLocalTransaction(listener: (tx: import('./transactions/TransactionQueue.js').Transaction) => void): () => void;
     /**
      * Wait for the latest in-flight transaction for (modelName, modelId)
      * to be confirmed by the server, or reject if it's rolled back.

package/dist/SyncClient.js

@@ -313,6 +313,14 @@ export class SyncClient extends EventEmitter {
             this.emit('sync:offline');
         }
     }
+    /**
+     * The organization this client writes under (set by `initialize`).
+     * Read by the model proxy so `create()` defaults `organizationId` the
+     * same way the mutator path does — `null` until identity is wired.
+     */
+    getOrganizationId() {
+        return this.organizationId;
+    }
     /**
      * Self-healing helper for individual model records.
      *
@@ -1298,6 +1306,75 @@ export class SyncClient extends EventEmitter {
         this.transactionQueue.on('transaction:failed', listener);
         return () => this.transactionQueue.off('transaction:failed', listener);
     }
+    /**
+     * Subscribe to LOCAL transaction creation with the full {@link Transaction}
+     * payload (`type`, `modelName`, `modelId`, `data`, `previousData`). This is
+     * the feed `BaseSyncedStore.subscribeLocalMutations` taps for undo recording.
+     *
+     * MUST subscribe to the TransactionQueue's emitter directly — that is the
+     * ONLY emitter that fires `transaction:created`. SyncClient's own emitter
+     * (reached via `subscribe()`) never re-broadcasts it, so routing undo through
+     * `subscribe('transaction:created')` silently records nothing. Mirrors
+     * `onMutationFailure`, which taps the queue for the same reason.
+     */
+    onLocalTransaction(listener) {
+        this.transactionQueue.on('transaction:created', listener);
+        // Commit-lane writes (`ablo.commits.create` — the agent/atomic door) ride
+        // their own `commit:created` event: they have no optimistic pool apply,
+        // so they must not feed the echo tracker's `transaction:created` path.
+        // Enrich each operation with previous state captured from the pool HERE
+        // (the queue is pool-free) and hand the synthesized transaction to the
+        // same listener, so undo observes every write door — one stream.
+        const onCommitCreated = (payload) => {
+            const TYPE_BY_WIRE = {
+                CREATE: 'create',
+                UPDATE: 'update',
+                DELETE: 'delete',
+                ARCHIVE: 'archive',
+                UNARCHIVE: 'unarchive',
+            };
+            payload.operations.forEach((op, index) => {
+                const type = TYPE_BY_WIRE[op.type];
+                if (!type || !op.id)
+                    return;
+                const resident = this.objectPool.get(op.id);
+                const snapshot = type === 'create' ? undefined : resident?.toJSON();
+                // A DELETE of a row the local graph never saw is not invertible —
+                // recording it would make undo "restore" an empty husk. Skip it.
+                if (type === 'delete' && !snapshot)
+                    return;
+                // UPDATE inverse must only revert the fields this op actually wrote;
+                // handing undo the FULL row would clobber concurrent edits to
+                // unrelated fields on revert.
+                const previousData = type === 'update' && snapshot && op.input
+                    ? Object.fromEntries(Object.keys(op.input).map((key) => [key, snapshot[key]]))
+                    : snapshot ?? null;
+                listener({
+                    id: `${payload.clientTxId}_op${index}`,
+                    type,
+                    modelName: op.model,
+                    modelId: op.id,
+                    modelKey: op.model,
+                    data: op.input ?? undefined,
+                    previousData,
+                    context: {
+                        userId: this.userId ?? '',
+                        organizationId: this.organizationId ?? '',
+                    },
+                    status: 'pending',
+                    createdAt: Date.now(),
+                    attempts: 0,
+                    priority: 'normal',
+                    priorityScore: 0,
+                });
+            });
+        };
+        this.transactionQueue.on('commit:created', onCommitCreated);
+        return () => {
+            this.transactionQueue.off('transaction:created', listener);
+            this.transactionQueue.off('commit:created', onCommitCreated);
+        };
+    }
     /**
      * Wait for the latest in-flight transaction for (modelName, modelId)
      * to be confirmed by the server, or reject if it's rolled back.