@abloatai/ablo 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,208 @@
+# Changelog
+
+## Unreleased
+
+Schema-driven identity sync-group composition, plus a terser capability surface.
+
+The convention for deriving a participant's allowed sync-groups from its identity is now declared on the consumer's schema as an open registration. Consumers with a `{ regionId, customerId }` identity shape declare their own roles instead of receiving any built-in prefixes from the SDK.
+
+Capability fields shed their redundant `allowed` prefix to match the surrounding vocabulary — capability inputs always describe what the bearer *can* touch, so the prefix was doing no disambiguation work for the consumer.
+
+### Added
+
+- `DefineSchemaOptions.identityRoles?: readonly IdentityRole[]` — open registration of identity-anchored sync-group roles on `defineSchema(...)`. Each `IdentityRole` declares `{ kind, template, extract }`: a diagnostic label, a `'<prefix>:{id}'` template, and a pure extractor function from an opaque identity context to zero-or-more ids. No closed enum; consumers fully control both the template strings and the extraction logic.
+- `composeIdentitySyncGroups(identity, schema)` exported from `@ablo/sync-engine/schema` — walks the schema's registered `identityRoles`, calls each extractor, and substitutes ids into templates. Stable, deduped output. Returns `[]` when no roles are registered.
+- `Schema.identityRoles: readonly IdentityRole[]` — the registered list, accessible on every `defineSchema(...)` result.
+- New exported types: `IdentityRole`, `IdentityContext`.
+
+### Breaking
+
+- `capabilities.create({ allowedSyncGroups, allowedOperations })` → `capabilities.create({ syncGroups, operations })`. Both fields renamed at every public surface — capability create input, capability retrieve response, capability record, Identity returned from `AuthProvider`. Hard rename, no alias. Update the call sites; the field semantics are unchanged.
+
+  ```ts
+  // Before
+  await api.capabilities.create({
+    allowedSyncGroups: ['org:acme'],
+    allowedOperations: ['tasks.update'],
+    lease: '10m',
+  });
+
+  // After
+  await api.capabilities.create({
+    syncGroups: ['org:acme'],
+    operations: ['tasks.update'],
+    lease: '10m',
+  });
+  ```
+
+### Changed
+
+- `docs/integration-guide.md` §1 now shows `identityRoles` in the canonical `defineSchema` example plus a "Declaring scope on a model" subsection covering `orgScoped` / `scopedVia` / `syncGroupFormat`. `docs/capabilities.md`, `docs/api.md`, `docs/mcp.md`, and `AGENTS.md` cross-reference the `identityRoles` section and use the renamed fields throughout.
+
+## 0.3.0 (2026-04-22)
+
+Umbrella `<AbloProvider>` for React apps. One provider component now owns the full lifecycle — singleton rotation on auth change, Strict-Mode-safe bootstrap, `beforeunload` cleanup, session-expiry IndexedDB wipe, post-bootstrap hooks, mesh client construction. Replaces the ad-hoc provider glue every consumer had to write themselves.
+
+Declarative props absorb every class of lifecycle glue; the status hook returns a tagged union so impossible states are unrepresentable. The reference integration shrank from 515 LOC of hand-rolled singleton/AbortController/beforeunload/reaction-bridge wiring to a 60-LOC thin wrapper that just passes props through.
+
+### Added
+
+- `<AbloProvider>` — umbrella provider at `@ablo/sync-engine/react`. Props include data config (`schema`, `url`, `userId`, `organizationId`), auth (`capabilityToken` / `apiKey` / session cookie fallback), declarative behavior (`preventUnsavedChanges`, `lostConnectionTimeout`, `postBootstrap`), callbacks (`onSessionExpired`, `onError`, `resolveUsers`), and DI escape hatches.
+- `<SyncGroupProvider id="matter:...">` + `useSyncGroup()` — per-entity scope context.
+- `<ClientSideSuspense fallback={...}>` — gate renders until the engine reports `connected`. Phase-1 non-Suspense; phase-2 upgrades to real Suspense.
+- `useSyncStatus()` rewritten as a tagged union: `{ name: 'initial' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'needs-auth', ... }`. Impossible states are unrepresentable.
+- `useCurrentUserId()` — returns the `userId` prop. Replaces downstream consumers' defineProperty hacks on the store.
+- `useErrorListener(cb)` — imperative error callback (Sentry/Datadog).
+- `useSync<R>()` and `useSyncStore<T>()` accept generic parameters so consumers can widen to their concrete schema types without `as unknown` casts at call sites.
+- `BaseSyncedStore.purge()` / `SyncEngine.purge()` — disconnect + wipe every `ablo_*` / `ablo-*` IndexedDB. Called automatically on session expiry.
+- `SyncEngine.onSessionError(listener)` — subscribe to session-error events. Multiple subscribers supported.
+- Commit payload projection built into `TransactionQueue`. Mutations are automatically projected onto the model's schema-declared fields (dropping framework internals `__class` / `__typename` / `clientId` / `syncStatus` and anything not declared), with `field.json()` values auto-stringified for TEXT columns and `undefined` dropped on updates. No config port, no consumer hook — the SDK derives correct wire payloads from the schema alone. Apps that previously maintained hand-rolled extractor tables can delete them entirely.
+
+### Breaking (continued)
+
+- Removed `SyncEngineConfig.extractCreateInput` and `SyncEngineConfig.buildUpdateInput`. The SDK's built-in projection replaces them. Consumers who passed these in `configOverrides` should delete the override; the default now covers 100% of identity-column mutations. The `configOverrides` prop still exists but its remaining fields are all deprecated (see below) and scheduled for removal in v0.4.
+
+### Deprecated (vestigial — removal in v0.4)
+
+- `SyncEngineConfig.modelCreatePriority`, `defaultCreatePriority`, `defaultNonCreatePriority` — never read at runtime.
+- `SyncEngineConfig.batchableModels` — never read at runtime.
+- `SyncEngineConfig.dedicatedDeleteModels` — never read at runtime.
+- `SyncEngineConfig.preserveCaseModels` — never read at runtime.
+- `SyncEngineConfig.essentialFields` — used only in debug logging, no behavioral effect.
+- `SyncEngineConfig.classNameFallbackMap` — dead path; `ModelRegistry.registerModelsFromSchema` registers by constructor identity, bypassing the class-name fallback entirely.
+
+### Breaking
+
+- Removed `<SyncProvider>` — folded into `<AbloProvider>`. Migrate by swapping the provider and passing `userId`/`organizationId`/`url` instead of a pre-constructed store.
+- Removed `createAbloContext()` factory and its returned `AbloProvider` / `useAblo` / `useParticipant` triple. Mesh is now always-on inside `<AbloProvider>`; `useAblo()` and `useParticipant(opts)` are always available. Schema-typed mesh hooks are on the roadmap.
+- Removed `withSync` (no-op alias of `observer`). Import `observer` from `mobx-react-lite` directly if needed.
+- Removed `useSyncContext` from the public surface (never used outside the SDK's test helpers).
+- `useSyncStatus()` return shape changed from six booleans to a tagged union. Migration: `const { isReady } = useSyncStatus()` → `const status = useSyncStatus(); const isReady = status.name === 'connected'`.
+- `SyncStoreContract` gained six sync-status getters and a `syncStatus` field. Third-party classes implementing the contract must add these (additive for callers).
+
+### Migration
+
+```tsx
+// Before (0.2.x)
+const { AbloProvider, useAblo, useParticipant } = createAbloContext<typeof schema>();
+
+function Root() {
+  const sync = createSyncEngine({ url, schema, user });
+  const ablo = new Ablo({ schema });
+  return (
+    <SyncProvider store={sync._store} organizationId={orgId}>
+      <AbloProvider ablo={ablo}>
+        <App />
+      </AbloProvider>
+    </SyncProvider>
+  );
+}
+
+// After (0.3.0)
+function Root() {
+  return (
+    <AbloProvider
+      schema={schema}
+      url={url}
+      userId={userId}
+      organizationId={orgId}
+      preventUnsavedChanges
+      onSessionExpired={() => router.replace('/signin')}
+    >
+      <ClientSideSuspense fallback={<Skeleton />}>
+        <App />
+      </ClientSideSuspense>
+    </AbloProvider>
+  );
+}
+```
+
+No breaking change to `useQuery` / `useOne` / `useMutate` / `useReader` / `useMutators` / `useUndoScope` / `usePresence` / `useIntent` — call sites remain source-compatible.
+
+## 0.2.1 (2026-04-22)
+
+React bindings hardening. Fixes two infinite-loop classes that surfaced in downstream apps as React error #185 ("Maximum update depth exceeded"), and exposes sync-status reactivity as a first-class observable + hook.
+
+### Fixed
+
+- **`useQuery` / `useOne` no longer loop on `getSnapshot`.** The `useSyncExternalStore` adapter was returning a fresh `view.results.slice()` on every call, which React's post-commit consistency check interpreted as "store updated mid-render" — scheduling another render, another snapshot, another mismatch, ad infinitum. The snapshot is now cached in a ref and only refreshed inside the subscribe callback right before `onChange()` fires. Affected every tree with multiple simultaneous `useQuery` subscribers.
+
+### Added
+
+- **`BaseSyncedStore` sync status is now properly observable.** `syncStatus` and `dataReady` are annotated `observable`; `isReady`, `isSyncing`, `isOffline`, `isReconnecting`, `isError`, `hasUnsyncedChanges` are `computed`. Before, these were plain getters over plain fields — `reaction(() => store.isReady, ...)` silently never fired. Existing `observer` / `reaction` call sites that relied on the implicit `pool.size` trigger will continue to work; new call sites should read these observables directly.
+- **`useSyncStatus()` React hook.** Returns `{ isReady, isSyncing, isOffline, isReconnecting, isError, hasUnsyncedChanges }` as a reactive snapshot, bridged via `useSyncExternalStore` with a correctly-cached snapshot. Replaces hand-rolled `reaction` bridges in consumer providers. See `docs/react.md`.
+- **`SyncStoreContract` surfaces the status getters** so TypeScript autocomplete works from the `useSyncContext()` return value without a cast.
+
+### Documentation
+
+- **`llms.txt` and `docs/react.md`** gained a "Common pitfalls" section covering the three traps this release addresses: don't wrap providers in `observer()`, `getSnapshot` must return a cached reference, and sync-status fields are real observables (don't watch `pool.size` as a proxy).
+
+### Migration
+
+No breaking changes. Optional: replace any local `reaction(() => store.isReady, setReady, { fireImmediately: true })` bridges in your own providers with `const { isReady } = useSyncStatus()` for consumers below the store provider.
+
+## 0.2.0 (2026-04-21)
+
+Mesh SDK — the canonical agent-multiplayer surface. Locked at this release; further work is consolidation, not expansion.
+
+### What's frozen
+
+The SDK covers exactly three integration shapes. Each has a canonical example in [`examples/`](./examples/):
+
+1. **Server agent** — `new Ablo({ schema })` reads `ABLO_API_KEY`, joins and works. ([`examples/server-agent.ts`](./examples/server-agent.ts))
+2. **Browser app** — server mints a scoped capability, browser holds it via `new Ablo({ schema, capabilityToken })`. No API key in bundle, no session cookies, no allowed-origins registration required. Stripe `client_secret` shape. ([`examples/browser-app.ts`](./examples/browser-app.ts))
+3. **Sub-agent** — `parent.join(child, opts)` attenuates from the parent's capability. ([`examples/sub-agent.ts`](./examples/sub-agent.ts))
+
+### Ergonomics (package-wide)
+
+- **`Ablo` class** — `import Ablo from '@ablo/sync-engine'` / `new Ablo({ schema })`. Matches `new Stripe()` / `new OpenAI()` / `new Anthropic()` pattern. `createMesh(opts)` stays available as the functional alias.
+- **Model-scoped joins** — `ablo.matters.join(id, { label })` desugars to the generic `join`. Proxy-based so the namespace adapts to any schema. Collisions with reserved admin fields (`roles`, `members`, `audit`, `capabilities`) throw at construction time.
+- **Flat scope form** — `scope: { matters: id }` alongside the array form.
+- **`as` alias** — `{ as: session({...}) }` replaces the security-jargon `onBehalfOf`; both still accepted.
+- **Auto-connect** — `join()` returns a connected participant. `autoConnect: false` to opt out.
+- **Duration strings** — `ttl: '3m'`, `ttlSeconds: '24h'` accepted alongside numbers.
+- **Descriptive generics** — every public type uses `TSchema` / `TAgent` / `ModelName` instead of `S` / `A` / `K`. Zero `unknown` in public types.
+
+### Coordination primitives
+
+- **Presence verbs** — `participant.presence.editing(target)` / `viewing(target)` / `idle()`. Plus `update({...})` escape hatch for custom actions.
+- **Intent verbs** — `participant.intents.editing(target, opts)` / `writing(target, opts)`. Returns an `IntentHandle` with `Symbol.asyncDispose` so `await using work = ...` auto-revokes.
+- **Snapshots** — `const snap = await participant.snapshot({ clauses: [id] })`. Flat shape: `snap.clauses[id]` (typed from schema via `InferModel`, not `unknown`), `snap.stamp`, `snap.signal` (AbortSignal).
+- **Async iterables** — `for await (const peers of participant.presence)`, `for await (const openIntents of participant.intents)`, `for await (const delta of participant.deltas)`.
+
+### Env / config
+
+- `ABLO_API_KEY` — required for server-side use.
+- `ABLO_BASE_URL` — optional override for staging / local-dev (defaults to `https://mesh.ablo.finance`). Not a customer-facing self-hosting path.
+- `organizationId` — **no longer required** in `createMesh`. The API key or session binds the caller to one org; the capability mint response echoes it back.
+- `createMeshFromEnv` — removed. `new Ablo({ schema })` auto-reads env.
+
+### Test coverage
+
+- 53 mesh unit tests across 8 suites (`__tests__/unit/mesh/`)
+- New E2E test `e2e-browser-capability-token.ts` proves the server-mints / browser-holds flow end-to-end
+- Existing 12 mesh E2E tests (token refresh, watermark, chinese wall, etc.) still pass
+
+---
+
+## 0.1.0 (2026-04-10)
+
+Initial release.
+
+### Features
+
+- **Schema DSL**: Zero-codegen schema definition with full TypeScript inference (`defineSchema`, `field`, `relation`)
+- **React Hooks**: `useModels`, `useModel`, `useMutations`, `withSync` for reactive data binding
+- **Consumer API**: `createSyncEngine()` — one-liner setup that hides all internal wiring
+- **Offline-first**: IndexedDB persistence with automatic offline mutation queue and FK-safe flush
+- **Real-time sync**: WebSocket delta streaming with optimistic updates and rollback
+- **AI Agent SDK**: `SyncAgent` for backend/AI agent participation as first-class sync citizens
+- **Pluggable auth**: `AuthProvider` interface with built-in API key, JWT, and session providers
+- **Security**: IndexedDB cleanup on session expiry and sync group revocation
+- **Testing utilities**: `@ablo/sync-engine/testing` subpath with mocks, fixtures, and harness
+
+### Test Coverage
+
+- 231 unit/integration/property/contract tests
+- 50 E2E tests against real Go server + PostgreSQL + Redis
+- Property-based testing via fast-check

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025-2026 Fablo Innovation AB
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+@ablo/sync-engine
+Copyright 2025-2026 Fablo Innovation AB
+
+This product includes software developed by Fablo Innovation AB
+(https://ablo.finance).
+
+"Ablo" is a trademark of Fablo Innovation AB. This license does not grant
+permission to use the Ablo name, logo, or trademarks. Third parties
+may describe their use of or compatibility with Ablo factually (e.g.,
+"built with @ablo/sync-engine") but may not use the Ablo name in a way
+that suggests endorsement, affiliation, or origin without written
+permission.

package/README.md

@@ -0,0 +1,230 @@
+# Ablo
+
+Ablo Sync is a schema-first state control layer for AI agents and collaborative apps.
+
+Use it when human UI, server actions, and AI agents need to edit the same typed
+state with realtime fanout, stale-write protection, active-work coordination,
+and audit.
+
+```txt
+schema -> ablo.<model>.create/load/edit/update(...)
+```
+
+## Install
+
+```bash
+npm install @ablo/sync-engine
+```
+
+Requires Node 22+ and TypeScript 5+.
+
+## Get a Test Key
+
+Create an Ablo sandbox and copy an `sk_test_*` API key. Keep API keys in trusted
+server runtimes only.
+
+```bash
+export ABLO_API_KEY=sk_test_...
+```
+
+Browser apps should use a scoped capability/session route through the React
+provider. Do not ship `ABLO_API_KEY` in a browser bundle.
+
+## Quick Start
+
+```ts
+import Ablo from '@ablo/sync-engine';
+import { defineSchema, model, z } from '@ablo/sync-engine/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,
+});
+
+await ablo.ready();
+
+const created = await ablo.weatherReports.create({
+  location: 'Stockholm',
+  status: 'pending',
+});
+
+const updated = await ablo.weatherReports.update(created.id, {
+  status: 'ready',
+  forecast: 'Light rain, 13C',
+});
+
+console.log({ id: updated.id, status: updated.status });
+
+await ablo.dispose();
+```
+
+Expected output:
+
+```txt
+{ id: '...', status: 'ready' }
+```
+
+Pass `schema` for typed model resources. Omit it only for advanced server-side
+resource clients such as custom agents and MCP routes.
+
+Run the package example from this directory:
+
+```bash
+cd examples
+ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+```
+
+For a production integration with React, an existing backend, Data Source, and
+future agents, read [Integration Guide](./docs/integration-guide.md).
+
+## AI Activity on Existing State
+
+Use `edit` when AI or background work will touch an existing row for more than a
+quick write. Other participants can see the activity while your code runs. The
+activity is cleared when `update` finishes; call `release` if the work ends
+without a write.
+
+```ts
+const edit = await ablo.weatherReports.edit('weather_stockholm', {
+  activity: 'checking_weather',
+  field: 'forecast',
+  ttl: '2m',
+});
+
+// Your existing weather tool or agent call. While this runs, other clients see
+// that weather_stockholm is being checked.
+const weather = await weatherAgent.getWeather(edit.current.location, {
+  signal: edit.signal,
+});
+
+await edit.update({
+  status: 'ready',
+  forecast: weather.summary,
+});
+```
+
+Ablo does not fetch the weather. It keeps the activity visible, gives the agent
+call an abort signal if the row changes, and clears the activity when
+`edit.update(...)` finishes.
+
+## Multiplayer
+
+There is no separate multiplayer mode. When human UI, server actions, and agent
+workers use the same schema client and write through `ablo.<model>`, they are on
+the same shared resource stream.
+
+- `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
+- `useAblo(...)` gives React clients the live row plus active intents.
+- `ablo.<model>.edit(...)` lets humans and agents see active work before a write lands.
+- `ablo.intents` remains available for custom lower-level coordination.
+
+If a team writes directly to its own database outside Ablo, that write bypasses
+the multiplayer stream until the app reports it through Data Source events.
+
+Under the hood, capabilities, tasks, leases, intents, commits, and receipts are
+real protocol primitives. They exist so agent work is scoped, coordinated,
+attributable, and cleaned up if a runtime disappears. They should not be
+ceremony in the first integration.
+
+## Load vs Retrieve
+
+For schema clients, `load` and `retrieve` are intentionally different:
+
+- `ablo.weatherReports.load({ where })` is async. It hydrates matching rows from the
+  local store and server, then returns them.
+- `ablo.weatherReports.retrieve(id)` is sync. It reads one already-loaded row from the
+  local pool and returns `undefined` if it is not loaded yet.
+- `ablo.resource('weatherReports').retrieve(id)` is the lower-level resource API. It
+  returns `{ data, stamp, intents }` for custom runtimes that need raw read
+  stamps and receipts.
+
+## Activity and Busy State
+
+Model edit activity is the live coordination signal. If another participant is
+reading, editing, or updating an entity, Ablo can return that state, wait for it
+to clear, or fail fast with `AbloBusyError`.
+
+```ts
+const busy = ablo.intents.list({
+  resource: 'weatherReports',
+  id: 'weather_stockholm',
+});
+
+if (busy.length > 0) {
+  console.log(`${busy[0].actor} is ${busy[0].action}`);
+}
+
+await ablo.intents.waitFor(
+  { resource: 'weatherReports', id: 'weather_stockholm' },
+);
+```
+
+Policy names are literal:
+
+- `ifBusy: 'return'` returns immediately with `intents`.
+- `ifBusy: 'wait'` waits on the live intent stream. Plain HTTP callers must
+  provide their own explicit polling policy instead of getting hidden SDK polling.
+- `ifBusy: 'fail'` throws `AbloBusyError` with the active intents attached.
+
+## Persistence
+
+Ablo defaults to volatile local persistence. That keeps the SDK focused on shared
+state coordination instead of silently adding an IndexedDB storage product to
+every browser app.
+
+Opt into browser durable local 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.
+
+## Connect Your Database
+
+Every schema model has a backing store. By default, Ablo stores rows for the
+models you declare, so `ablo.weatherReports.create(...)` and `ablo.weatherReports.update(...)`
+write to Ablo-managed state.
+
+If your existing database remains the source of truth, connect it with a signed
+Data Source endpoint. Your app keeps the database credentials; Ablo sends signed
+commit requests to your route.
+
+```bash
+ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+```
+
+See [Connect Your Database](./docs/data-sources.md) for the route and commit shape.
+
+## Agent Runs
+
+Most agent workers should import the same schema and use
+`ablo.<model>.load(...)` plus `ablo.<model>.update(...)`. The schema-less
+`agent.run(...)` wrapper exists for advanced workers that intentionally cannot
+import the app schema.
+
+## Production Reference
+
+- [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, intent coordination, and agent lifecycle.
+- [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.
+- [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.
+- [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 plus advanced schema-less run.
+
+## License
+
+Apache License 2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).