@abloatai/ablo 0.37.1 → 0.38.0

package/docs/migration.md

@@ -214,10 +214,10 @@ commonly a Data Source handler keyed on `mode`. The mapping is exactly
 source resolvers, so per-project and per-environment traffic can be routed to
 distinct stores.
 
-> **CLI note:** the legacy single-file config that stored `test`/`live` key
-> buckets is no longer auto-migrated. If `ablo status` can't find your keys after
-> upgrading, re-run `ablo login` to write the current `sandbox`/`production`
-> layout.
+> **CLI note:** current login stores one mode-free `mk_` project management
+> credential. Legacy runtime key slots remain readable during the cutover, but
+> re-run `ablo login` before using branch/project commands so the CLI can store
+> the new credential.
 
 ### New (non-breaking): `transport: 'http'`
 

package/docs/projects.md

@@ -30,7 +30,7 @@ projects existed are default-project keys automatically.
 ## Keys belong to exactly one project
 
 A key's project is fixed at mint and can never be changed or overridden —
-the same discipline as its sandbox/production mode. Everything a key mints
+the same discipline as its immutable branch binding. Everything a runtime key mints
 inherits its project: the short-lived session credentials (`ek_`), agent
 keys (`rk_`), everything. There is no way to "switch projects" with an
 existing key; you use a key minted for the project you mean.

package/docs/quickstart.md

@@ -12,7 +12,7 @@ schema** — your migration tool stays in charge of the shape of your database.
 
 > No database yet? Pass an `apiKey` only and Ablo keeps your rows in its own log,
 > so you can build the whole app today — like Stripe test mode. Point it at a
-> separate or local Postgres for a throwaway sandbox, or at your production
+> separate or local Postgres for a development branch, or at your production
 > database when you're ready.
 
 ## 1. Install and initialize
@@ -23,22 +23,23 @@ npx ablo init
 ```
 
 `ablo init` scaffolds your project (next step shows what it creates) and ends
-by signing you in — one browser click, and a `sk_test_` key is saved locally
-for the CLI. Later, `npx ablo push` (step 4) writes `ABLO_API_KEY` into your
-`.env.local` so the SDK finds it too — no manual copy-paste. `npx ablo login`
-also exists standalone. In CI, or to manage the key by hand, set it yourself
-instead:
+by signing you in — one browser click, and a project-scoped `mk_` management
+credential is saved locally. Later, `npx ablo dev` (step 4) prepares an isolated branch and writes
+its temporary `ABLO_API_KEY` into `.env.local`, so the SDK follows your Git
+branch with no manual copy-paste. `npx ablo login` also exists standalone. In
+CI, set project management access explicitly:
 
 ```bash
-export ABLO_API_KEY=sk_test_...
+export ABLO_MANAGEMENT_KEY=mk_...
 ```
 
-Every SDK and CLI call needs a key. Test and live keys work like Stripe's:
-`sk_test_*` for the sandbox, `sk_live_*` for production. In production a key
-points at the database *you* own; in the sandbox you can skip the database
-entirely and let Ablo's test plane host the rows (apiKey only). There is no
-keyless mode — a key is always required. (The public `/sandbox` page is a
-separate hosted demo, not your app.)
+Every runtime call needs a branch-bound API key. `ablo dev` exchanges the
+stored management credential for
+an expiring `sk_test_*` key bound to the current development branch.
+Production runtimes use `sk_live_*`. In production a key points at the database
+*you* own; on a development branch you can skip the database entirely and let
+Ablo host the rows (apiKey only). There is no keyless mode — a key is always
+required. (The public `/sandbox` page is a separate hosted demo, not your app.)
 
 ## 2. Your Ablo schema (init scaffolded it)
 
@@ -166,17 +167,24 @@ The full setup, the honest footprint (publication + slot + the `REPLICATION` and
 writer roles + the `wal_level` restart + slot/WAL retention Ablo monitors), and the
 Preview status are in [Connect Your Database](./data-sources.md).
 
-## 4. Push the schema, then map it to tables
+## 4. Start the branch development loop
 
 ```bash
-npx ablo push      # pushes the schema definition and writes ABLO_API_KEY to
-                   # .env.local. Add --watch to re-push on every save.
+npx ablo dev       # prepare this Git branch, push, and watch ablo/schema.ts
 ```
 
-`ablo push` uploads the schema *definition* — model names, fields, types. That
-metadata is what tells Ablo which models to coordinate. Skipping it makes every
-write to a new or changed model fail with `server_execute_unknown_model` — that
-error literally means "run `npx ablo push`."
+`ablo dev` discovers your Git branch, ensures a matching isolated Ablo branch,
+mints an eight-hour branch credential, writes it to gitignored `.env.local`,
+uploads the schema *definition*, and watches for schema edits. Model names,
+fields, and types tell Ablo which models to coordinate. Skipping the push makes
+every write to a new or changed model fail with
+`server_execute_unknown_model`.
+
+Use `npx ablo dev --no-watch` when you only need to prepare and push once. Use
+`npx ablo push` as the lower-level one-shot command when you deliberately want
+to push with the currently active key, including a reviewed production deploy.
+The complete mental model and CI examples are in
+[Branch-first development](./branch-development.md).
 
 Now map those models to your real Postgres tables. **Your migration tool owns the
 tables** — Ablo reads them, it does not create or migrate them:
@@ -191,8 +199,8 @@ tables** — Ablo reads them, it does not create or migrate them:
 > your schema needs. Once they exist, your own migration tool stays in charge
 > of them — Ablo adopts whatever shape you evolve.
 
-Nothing runs locally — there is no dev server to start. Your app talks to Ablo's
-hosted API; the rows live in your database.
+No Ablo server runs locally. The `ablo dev` process only watches your schema;
+your app talks to Ablo's hosted API, and the rows live in your database.
 
 ## 5. Write through the model
 

package/docs/webhooks.md

@@ -116,10 +116,10 @@ work asynchronously after responding.
 
 ## 2. Test locally
 
-You don't register a `localhost` URL. `npx ablo dev` forwards committed changes
-to your machine with a local signing secret — the same idea as Stripe's
-`stripe listen`. Run your app, run `ablo dev`, and writes flow into your local
-handler.
+`npx ablo dev` prepares an isolated schema branch; it does not forward webhook
+deliveries. Register an HTTPS endpoint that Ablo can reach. For local handler
+development, expose your app with the HTTPS tunnel your team already trusts,
+then register that temporary URL and remove the endpoint when you finish.
 
 ## 3. Register your endpoint
 

package/llms.txt

@@ -23,9 +23,9 @@ The two MCP servers do different jobs and are the most common mix-up: to change
 
 First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla>`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. It scaffolds `ablo/schema.ts`, the `Ablo({ schema, apiKey })` client, and (for Next.js) the browser provider + session route. All on the current API. Edit the generated files rather than hand-writing from this doc. Connecting a database is a SEPARATE step with one path — logical replication via `npx ablo connect` (see Storage Boundary); the signed Data Source endpoint is the fallback when database credentials must stay inside the app.
 
-Second: make sure a key exists — WITHOUT printing it. The key is a secret; it must never appear in your output, your reasoning, or a file you echo (it would live in the conversation history forever). Check PRESENCE only: `[ -n "$ABLO_API_KEY" ] && echo set` and `grep -cq '^ABLO_API_KEY=' .env.local && echo wired` — never `cat .env.local`, never `echo $ABLO_API_KEY`. If neither check passes, ask the HUMAN to run `npx ablo login` once — it opens a browser and saves a `sk_test_` key locally; an agent must NOT run it. You never copy the key by hand: the next step writes it into `.env.local` (and gitignores it) for you.
+Second: make sure a key exists — WITHOUT printing it. The key is a secret; it must never appear in your output, your reasoning, or a file you echo (it would live in the conversation history forever). Check PRESENCE only: `[ -n "$ABLO_API_KEY" ] && echo set` and `grep -cq '^ABLO_API_KEY=' .env.local && echo wired` — never `cat .env.local`, never `echo $ABLO_API_KEY`. If neither check passes, ask the HUMAN to run `npx ablo login` once — it opens a browser and saves a project-scoped branch-management key locally; an agent must NOT run it. You never copy a runtime key by hand: the next step mints one for the development branch, writes it into `.env.local`, and gitignores it.
 
-Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. Run `npx ablo push`: it pushes `ablo/schema.ts` (sandbox) AND writes `ABLO_API_KEY` into `.env.local` from the stored login. Until the schema is pushed, EVERY write to a new or changed model fails with `server_execute_unknown_model`. Re-run it after schema changes. `push` is one-shot; `dev` is the watcher, so use `npx ablo dev --no-watch` only when you intentionally want the dev command to push once and exit.
+Then PREPARE THE BRANCH AND PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. Run `npx ablo dev --no-watch --branch <git-or-ci-ref>`: it ensures an isolated child branch, exchanges the CLI key for an expiring branch-only `sk_test_` key, writes that key to gitignored `.env.local`, pushes `ablo/schema.ts`, and exits. Until the schema is pushed, EVERY write to a new or changed model fails with `server_execute_unknown_model`. Re-run it after schema changes. Plain `dev` watches forever; never run it bare in an agent. `push` is the lower-level one-shot command for an already selected credential, including a reviewed production deployment.
 
 ## Projects (one org, many apps)
 
@@ -182,22 +182,23 @@ claims, stale-write rejection, receipts, and deltas, but it does not use a real
 API key. It also exposes a Claude Code / Codex handoff prompt. Prefer that shape
 when an agent is asked to "make Ablo work" in an existing app.
 
-Authenticated org sandboxes are real test environments. Treat the default
-sandbox like Stripe test mode: it has an isolated sync group prefix and mints
-`sk_test_*` keys. The sandbox CAN host rows in Ablo's test plane, so you can try
-Ablo with NO database — `apiKey` only, nothing else. (In production, your own
-Postgres is the system of record.) Extra sandboxes can start blank or copy live
-configuration. Resetting a sandbox creates a clean future stream without
-touching live data. Use `sk_live_*` only for production.
+Authenticated development branches are real test environments. `ablo dev`
+derives one from Git and mints an expiring `sk_test_*` key bound to its immutable
+branch id. A branch CAN host rows in Ablo's test plane, so you can try Ablo with
+NO database — `apiKey` only, nothing else. (In production, your own Postgres is
+the system of record.) Branch schemas and rows are isolated from siblings and
+production. There is no shared-sandbox escape hatch. Use `sk_live_*` only for
+production.
 
-For coding agents, the sandbox success path is: pick one shared model,
-declare schema, create the Ablo client, replace one direct mutation with a typed
-`ablo.<model>.update(...)`, use selector `useAblo` for live reads, and add a
-two-writer stale/claim smoke test.
+For coding agents, the development success path is: pick one shared model,
+declare schema, prepare an explicit branch with
+`ablo dev --no-watch --branch <git-or-ci-ref>`, create the Ablo client, replace
+one direct mutation with a typed `ablo.<model>.update(...)`, use selector
+`useAblo` for live reads, and add a two-writer stale/claim smoke test.
 
 ## Production
 
-A PLANE is what a credential acts on: `production` is the root, sandboxes sit beside it. Rows, the registered database, and the active schema artifact are all PER PLANE, and a key's plane is fixed at mint by its prefix (`sk_live_` → production, `sk_test_` → sandbox) — there is no runtime override, which is why app code never passes an environment. ONE ASYMMETRY: a sandbox with no schema artifact of its own READS PRODUCTION'S, so a production push reaches sandboxes; a SANDBOX push does NOT reach production — it creates a sandbox artifact that shadows production for that sandbox's readers only. Production gets models when you push to production.
+A PLANE is what a credential acts on: `production` is the root branch and development/preview branches are children. Rows, the registered database, and the active schema artifact are all PER PLANE. A key's immutable branch binding is fixed at mint (`sk_live_` → production; `sk_test_` → one child), so app code never passes an environment. A child copies its parent's active schema at creation and owns its artifact after that. A CHILD push does NOT reach production. Production gets models only when the reviewed deployment pushes to the root.
 
 Going live is three things, each done with a `sk_live_` key: register the production database (`ablo connect apply` — the DIRECT host, never a pooler; a pooler refuses in the words of a wrong password), push the schema AHEAD of the code that needs it, and hold the right credential per runtime (server/serverless `sk_live_`; browser `pk_live_` read-only or an `authEndpoint` minting `ek_`). The live key `ablo login` stores is a RESTRICTED observe-only `rk_live_` and CANNOT push schema — a production push needs a dashboard `sk_live_` in `ABLO_API_KEY`. Gate a deploy on `npx ablo status --json` having an EMPTY `blockers` array; each blocker carries a `problem` and the one `fix`. Your agents do NOT each hold a database connection — they talk to Ablo, and Ablo holds at most 4 connections per plane (`application_name = 'ablo-direct-writer'`) however many callers write behind them, so size the database for that number and not for your agent count. Read `deployment` for the full path.
 
@@ -214,8 +215,9 @@ Import from these public paths only:
 - `@abloatai/ablo/source/drizzle` — `drizzleDataSource`.
 - `@abloatai/ablo/source/kysely` — `kyselyDataSource`.
 - `@abloatai/ablo/source/conformance` — `runDataSourceTests` to prove a custom adapter/handler.
+- `@abloatai/ablo/ai-sdk` — thin AI SDK tools over typed model reads, creates, coordinated updates, and claimed deletes.
 
-Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subpaths. (`/source` IS public — it's the Data Source endpoint surface above.)
+Do not teach `/api`, `/agent`, `/core`, `/realtime`, or internal subpaths. (`/source` and `/ai-sdk` are public.)
 
 ## CLI: agents run it NON-INTERACTIVELY
 
@@ -223,10 +225,10 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 
 - `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage replication|endpoint`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `Ablo({ schema, apiKey })` client. `--storage replication` (the default) pairs with `ablo connect`; `--storage endpoint` also scaffolds the `ablo/data-source.ts` fallback endpoint.
 - `npx ablo connect` connects your database via logical replication — the read path (prints the `wal_level=logical` + publication + `REPLICATION`-role SQL); `npx ablo connect register` registers it, `npx ablo connect check` validates the registered database from Ablo's own side and needs only `ABLO_API_KEY` (no database credential in your environment). `npx ablo connect apply` does the whole setup from a one-time admin connection and leaves your app holding only `ABLO_API_KEY`.
-- Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo push` writes `.env.local`).
+- Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo dev` mints and wires the temporary branch key).
 - Adopt an existing DB: `npx ablo pull prisma [path]` / `npx ablo pull drizzle <module>`.
-- `npx ablo push` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local`. A PRODUCTION push (`sk_live_` key) needs `--yes`: with no TTY it REFUSES rather than deploying unattended, and interactively it demands the destination project typed by name. Destructive steps (dropped model/field, narrowed enum, lossy cast) need `--force`; a new required field on a populated table needs `--backfill model.field=value`. `npx ablo dev --no-watch` is the push-once form of the watcher; `npx ablo logs --no-follow` exits instead of tailing forever; `npx ablo mode sandbox|production` always needs the argument. `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
+- `npx ablo dev --no-watch --branch <git-or-ci-ref>` ensures an isolated branch, mints and wires its temporary key, pushes once, and exits. Plain `dev` watches forever. `npx ablo branch check <id-or-slug>` prints lifecycle, schema/parent compatibility, datasource identity, and readiness. `npx ablo push` pushes with the already selected key and does NOT choose a branch for you. A PRODUCTION push (`sk_live_` key) needs `--yes`: with no TTY it REFUSES rather than deploying unattended, and interactively it demands the destination project typed by name. Destructive steps (dropped model/field, narrowed enum, lossy cast) need `--force`; a new required field on a populated table needs `--backfill model.field=value`. `npx ablo logs --no-follow` exits instead of tailing forever. `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
 
 - `npx ablo docs` lists every documentation page; `npx ablo docs <page>` prints one as markdown. These pages ship INSIDE the installed package, so they describe the version in `node_modules` and need no network. Prefer them over a docs URL whenever the project pins a version: a website always describes the newest release, so on an older pin it will hand you a call your package does not have (`retrieve`/`list` replaced `get`/`getAll`/`getCount` in 0.35.0). One-shot, safe to run unattended.
 
-Canonical docs to read before integrating: `quickstart`, `schema-contract`, `integration-guide`, `deployment`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent` — read each with `npx ablo docs <page>`. When upgrading an existing integration, read `migration` — every breaking change, what to change, and which version introduced it. When the customer's database has row-level-security policies, read `session-settings` — the identity context Ablo sets before every write, and how to map it to the setting names those policies already read.
+Canonical docs to read before integrating: `quickstart`, `branch-development`, `schema-contract`, `integration-guide`, `deployment`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent` — read each with `npx ablo docs <page>`. When upgrading an existing integration, read `migration` — every breaking change, what to change, and which version introduced it. When the customer's database has row-level-security policies, read `session-settings` — the identity context Ablo sets before every write, and how to map it to the setting names those policies already read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.37.1",
+  "version": "0.38.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -70,6 +70,11 @@
       "import": "./dist/coordination.js",
       "default": "./dist/coordination.js"
     },
+    "./ai-sdk": {
+      "types": "./dist/ai-sdk.d.ts",
+      "import": "./dist/ai-sdk.js",
+      "default": "./dist/ai-sdk.js"
+    },
     "./wire": {
       "types": "./dist/wire.d.ts",
       "import": "./dist/wire.js",
@@ -99,6 +104,9 @@
     "test": "vitest run",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",
+    "generate:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts",
+    "lint:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts --check",
+    "validate:openapi": "redocly lint ../../docs/ablo/public/openapi.json --extends=recommended --skip-rule=no-server-example.com",
     "build:docs": "node scripts/build-blume-docs.mjs",
     "lint:docs": "node scripts/check-doc-drift.mjs",
     "lint:pkg": "publint"
@@ -114,13 +122,17 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.37.1",
-    "@abloatai/transaction": "^0.37.1"
+    "@abloatai/humans": "^0.38.0",
+    "@abloatai/transaction": "^0.38.0"
   },
   "peerDependencies": {
+    "ai": "^6.0.0 || ^7.0.0",
     "react": "^19.2.8"
   },
   "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }