@abloatai/ablo 0.37.0 → 0.38.0

package/docs/integrations/inngest.md

@@ -0,0 +1,258 @@
+# Inngest for long-running tasks
+
+> Run event-driven, retryable agent tasks with Inngest while Ablo makes each
+> shared-state effect typed, idempotent, and authoritative.
+
+Inngest and Ablo solve different parts of a durable agent system:
+
+| Concern | Owner |
+|---|---|
+| Events, step checkpoints, retries, sleeps, flow control, cancellation | Inngest |
+| Provider calls, prompts, and model output | AI SDK |
+| Typed reads and writes, mutation idempotency, claims, confirmation | Ablo |
+| Event names, function definitions, effect identity, business behavior | Your application |
+
+The short version is:
+
+> Inngest makes sure the job resumes. Ablo makes sure its changes are safe.
+
+## Keep Ablo calls inside steps
+
+An Inngest function is ordinary application code, but external I/O belongs in
+a retriable `step.run()`. A successful step result is checkpointed and reused;
+a failed step is independently retried.
+
+```ts
+import Ablo from '@abloatai/ablo';
+import { Inngest, eventType } from 'inngest';
+import { z } from 'zod';
+import { schema } from './schema.js';
+
+const inngest = new Inngest({ id: 'orders' });
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
+});
+
+const approvalRequested = eventType('orders/approval.requested', {
+  schema: z.object({
+    operationId: z.string(),
+    orderId: z.string(),
+    approvalNote: z.string(),
+  }),
+});
+
+export const approveOrder = inngest.createFunction(
+  {
+    id: 'approve-order',
+    triggers: [approvalRequested],
+    retries: 4,
+    idempotency: 'event.data.operationId',
+  },
+  async ({ event, step }) => {
+    const { operationId, orderId, approvalNote } = event.data;
+
+    return step.run('write-approved-order', () =>
+      ablo.orders.update({
+        id: orderId,
+        data: { status: 'approved', approvalNote },
+        idempotencyKey: `${operationId}:approve-order:${orderId}`,
+        wait: 'confirmed',
+      }),
+    );
+  },
+);
+```
+
+There is no Inngest-specific Ablo transport. The step calls the same branded
+model API as a route handler, worker, or command-line process.
+
+## Use both idempotency layers
+
+Send a globally scoped event ID and carry a stable business operation ID in the
+event:
+
+```ts
+await inngest.send(
+  approvalRequested.create(
+    {
+      operationId,
+      orderId,
+      approvalNote: 'Approved by the durable function.',
+    },
+    {
+      id: `orders-approval-requested-${operationId}`,
+    },
+  ),
+);
+```
+
+Inngest event IDs and function-level `idempotency` prevent duplicate function
+runs for Inngest's documented 24-hour window. They do not replace the Ablo
+mutation key. Ablo can confirm the write and the process can lose the response
+before Inngest checkpoints the step, causing the step callback to execute
+again.
+
+For every mutating step:
+
+1. Accept a stable business operation ID in the triggering event.
+2. Derive a separate key for each logical effect.
+3. Reuse the key and mutation body for every retry.
+4. Use `wait: 'confirmed'` when later steps depend on the authoritative result.
+5. Treat reuse of a key with another body as an application bug.
+6. Keep the complete retry horizon within Ablo's documented
+   [idempotency retention window](../idempotency.md).
+
+Never put Inngest's `attempt`, a timestamp, or a random value in the key.
+`runId` is suitable only when a newly created function run should represent a
+new effect.
+
+## Compose AI SDK as durable steps
+
+Inngest can checkpoint AI SDK calls with `step.ai.wrap()`. Keep the model call
+and the Ablo mutation as separate steps:
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const { text: approvalNote } = await step.ai.wrap(
+  'review-order',
+  generateText,
+  {
+    model: openai('gpt-4o-mini'),
+    system:
+      'Return only a concise approval note suitable for an audit trail.',
+    prompt,
+  },
+);
+
+await step.run('apply-order-review', () =>
+  ablo.orders.update({
+    id: orderId,
+    data: { status: 'approved', approvalNote },
+    idempotencyKey: `${operationId}:apply-order-review:${orderId}`,
+    wait: 'confirmed',
+  }),
+);
+```
+
+This separation means retrying a write does not spend model tokens again, and
+retrying a model call cannot partially mutate shared state.
+
+For a multi-turn agent loop, checkpoint every model invocation and wrap every
+tool execution in its own `step.run()`. The generic
+`@abloatai/ablo/ai-sdk` helpers may execute inside a step because Inngest does
+not impose Temporal's deterministic Workflow sandbox. Explicit model calls are
+still preferable in the first integration because they make the effect key and
+step boundary visible.
+
+## Claims and cancellation
+
+A claim protects a short shared-state critical section, not an entire Inngest
+function. Acquire, fresh-read, checked-write, and release inside one
+`step.run()`:
+
+```ts
+await step.run('apply-review-with-claim', async () => {
+  const claim = await ablo.orders.claim({
+    id: orderId,
+    description: 'applying an Inngest review',
+  });
+
+  try {
+    return await ablo.orders.update({
+      id: claim.data.id,
+      data: { status: 'approved', approvalNote },
+      claim,
+      idempotencyKey: `${operationId}:apply-review:${orderId}`,
+      wait: 'confirmed',
+    });
+  } finally {
+    await claim.release();
+  }
+});
+```
+
+Do not hold a claim across `step.sleep()`, `step.waitForEvent()`, or an AI
+inference step. Configure `cancelOn` for the function, but do not assume that
+function cancellation aborts an already running Ablo network request. Keep
+claims short, release in `finally`, and rely on bounded claim leases for
+process-loss recovery.
+
+## Expose the application endpoint
+
+Mount Inngest's handler at the conventional `/api/inngest` path. For a plain
+Node application:
+
+```ts
+import { createServer } from 'node:http';
+import { serve } from 'inngest/node';
+
+const handler = serve({
+  client: inngest,
+  functions: [approveOrder],
+});
+
+createServer((request, response) => {
+  const path = new URL(request.url ?? '/', 'http://localhost').pathname;
+  if (path === '/api/inngest') return handler(request, response);
+  response.writeHead(404).end();
+}).listen(3000);
+```
+
+Use the framework-specific `serve` adapter in an existing Next.js, Express,
+Hono, or other supported application.
+
+Start the local app and Inngest Dev Server:
+
+```bash
+npm run dev
+npx --ignore-scripts=false inngest-cli@latest dev \
+  --no-discovery \
+  -u http://localhost:3000/api/inngest
+```
+
+Set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY` in production.
+
+## Test the failure boundary
+
+Use `@inngest/test`'s `InngestTestEngine` for function and step tests. A useful
+integration suite proves:
+
+- the Ablo write happens inside the expected named step;
+- a confirmed write followed by simulated response loss retries with the same
+  key and body and commits once;
+- conflicting reuse of a key fails;
+- checkpointed step state bypasses the Ablo callback;
+- claims release after write failure; and
+- the `/api/inngest` endpoint exposes function metadata without eagerly
+  creating an Ablo connection.
+
+The complete runnable suite lives in `examples/inngest-agent`.
+
+## Package boundary
+
+Inngest remains an application dependency:
+
+```text
+packages/
+  transaction/src/ai-sdk/    reusable model-backed AI SDK tools
+  ablo/src/ai-sdk.ts          @abloatai/ablo/ai-sdk
+
+examples/
+  inngest-agent/              events, functions, steps, endpoint, AI composition
+```
+
+Do not add Inngest to `packages/agent`. A dedicated `@abloatai/inngest` package
+is justified only after multiple real applications reveal substantial
+reusable behavior beyond a small function or step wrapper.
+
+## References
+
+- [Inngest TypeScript SDK v4](https://www.inngest.com/docs/reference/typescript/v4/intro)
+- [Inngest steps](https://www.inngest.com/docs/reference/typescript/functions/step-run)
+- [Inngest idempotency](https://www.inngest.com/docs/guides/handling-idempotency)
+- [Inngest AI inference steps](https://www.inngest.com/docs/features/inngest-functions/steps-workflows/step-ai-orchestration)
+- [Testing Inngest functions](https://www.inngest.com/docs/reference/typescript/v4/testing)

package/docs/integrations/temporal.md

@@ -0,0 +1,187 @@
+# Temporal for long-running tasks
+
+> Run long-lived, retryable agent tasks with Temporal while Ablo makes each
+> shared-state effect typed, idempotent, and authoritative.
+
+Temporal and Ablo solve different parts of a durable agent system:
+
+| Concern | Owner |
+|---|---|
+| Workflow history, replay, timers, retries, cancellation | Temporal |
+| Provider, messages, tools, approval, model loop | AI SDK |
+| Typed reads and writes, idempotency, claims, confirmation | Ablo |
+| Workflow names, task queues, retry policy, business behavior | Your application |
+
+The short version is:
+
+> Temporal makes sure the agent finishes. Ablo makes sure its changes are safe.
+
+## Keep Ablo calls in Activities
+
+Temporal Workflow code must be deterministic. An Ablo model operation performs
+network I/O, so instantiate `Ablo()` and call model resources in an Activity:
+
+```ts
+// activities/orders.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from '../schema.js';
+
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
+});
+
+export interface ApproveOrderInput {
+  orderId: string;
+  approvalNote: string;
+  idempotencyKey: string;
+}
+
+export async function approveOrder(input: ApproveOrderInput) {
+  return ablo.orders.update({
+    id: input.orderId,
+    data: {
+      status: 'approved',
+      approvalNote: input.approvalNote,
+    },
+    idempotencyKey: input.idempotencyKey,
+    wait: 'confirmed',
+  });
+}
+```
+
+The Activity uses the same branded model method as a route handler, job, or
+command-line process. There is no Temporal-specific Ablo transport.
+
+Workflow code creates the stable logical effect identity and schedules the
+Activity:
+
+```ts
+// workflows/approve-order.ts
+import { proxyActivities, workflowInfo } from '@temporalio/workflow';
+import type * as activities from '../activities/orders.js';
+
+const { approveOrder } = proxyActivities<typeof activities>({
+  startToCloseTimeout: '1 minute',
+  retry: { maximumAttempts: 5 },
+});
+
+export async function approveOrderWorkflow(orderId: string) {
+  const { workflowId, runId } = workflowInfo();
+
+  return approveOrder({
+    orderId,
+    approvalNote: 'Approved by the durable workflow.',
+    idempotencyKey: `${workflowId}:${runId}:approve-order:${orderId}`,
+  });
+}
+```
+
+Temporal may retry an Activity after the Ablo write succeeded but before the
+result reached Temporal. Every attempt must therefore send the same
+`idempotencyKey` and the same mutation body. Do not put an Activity attempt
+number, timestamp, or random value in the key.
+
+Using the Workflow Run ID is appropriate when a new run should represent a new
+effect. If an effect must survive Continue-As-New or a newly started Workflow
+run, accept a stable business operation ID as Workflow input instead.
+
+## Compose AI SDK tools through Activities
+
+Temporal's AI SDK integration can make the model interaction durable inside a
+Workflow. Any tool that touches Ablo still delegates to an Activity:
+
+```ts
+import { temporalProvider } from '@temporalio/ai-sdk/workflow';
+import { generateText, stepCountIs, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: temporalProvider.languageModel('gpt-4o-mini'),
+  prompt,
+  tools: {
+    approveOrder: tool({
+      description: 'Approve the order after reviewing it.',
+      inputSchema: z.object({ approvalNote: z.string() }),
+      execute: ({ approvalNote }) =>
+        approveOrder({
+          orderId,
+          approvalNote,
+          idempotencyKey: `${effectPrefix}:approve-order:${orderId}`,
+        }),
+    }),
+  },
+  stopWhen: stepCountIs(5),
+});
+```
+
+Register Temporal's `AiSdkPlugin` on the Worker and pin all
+`@temporalio/*` packages to one compatible version set. The integration is
+experimental, so replay-test Workflow histories before upgrading it.
+The import above matches the example's pinned `1.21.1` release. Follow the
+matching Temporal upgrade guide when changing that version set.
+
+Do not import `@abloatai/ablo/ai-sdk` into Workflow code. Its `readTool`,
+`createTool`, `updateTool`, and `deleteTool` helpers execute Ablo model
+operations directly and are intended for ordinary Node.js AI SDK loops. In a
+Temporal Workflow, define the tool at the application edge and make its
+`execute` function call a proxied Activity.
+
+## Idempotency rules
+
+For every mutating Activity:
+
+1. Create the key in deterministic Workflow code or accept a stable operation
+   ID in the Workflow input.
+2. Reuse the key and mutation body for every retry of the same logical effect.
+3. Use `wait: 'confirmed'` when later Workflow steps depend on the
+   authoritative database result.
+4. Treat reuse of a key with a different body as an application bug.
+5. Keep the Temporal retry horizon within Ablo's documented
+   [idempotency retention window](../idempotency.md).
+
+This gives effective-once composition for the advertised retention window. It
+does not make an external side effect physically execute only once; Temporal
+Activities are intentionally retryable.
+
+## Claims and cancellation
+
+A claim protects a short shared-state operation, not an entire Workflow
+history. Keep claim acquisition, the fresh read, the checked write, and release
+inside one Activity:
+
+```ts
+import { Context } from '@temporalio/activity';
+
+export async function applyReview(orderId: string, note: string) {
+  await using claim = await ablo.orders.claim({
+    id: orderId,
+    description: 'applying review',
+    signal: Context.current().cancellationSignal,
+  });
+
+  return ablo.orders.update({
+    id: claim.data.id,
+    data: { approvalNote: note },
+    claim,
+    wait: 'confirmed',
+  });
+}
+```
+
+For long model reasoning, reason in the Workflow and use a short Activity to
+re-read and apply the result. Do not return from an Activity while assuming a
+held lease will remain valid.
+
+## Complete example
+
+The repository's
+[`examples/temporal-agent`](../../../../examples/temporal-agent/README.md)
+contains a Workflow, Activities, Worker, client, durable AI SDK tool, and a
+simulated lost-response retry. It is a standalone application on purpose:
+Temporal stays out of Ablo's core packages and out of `packages/agent`.
+
+A dedicated `@abloatai/temporal` package should be introduced only after
+multiple production integrations reveal substantial, stable behavior that
+cannot be expressed clearly at this application boundary.

package/docs/integrations.md

@@ -0,0 +1,54 @@
+# Integrations
+
+> Compose Ablo's authoritative shared-state operations with the runtimes that
+> execute, schedule, or ingest work in your application.
+
+Integrations live at the application edge. Ablo continues to own typed reads
+and writes, idempotency, claims, and authoritative confirmation; the external
+runtime keeps owning the job it was designed for.
+
+| Category | Integration | Status | Use it for |
+|---|---|---|---|
+| Long-running tasks | [Temporal](./integrations/temporal.md) | Available | Durable Workflows, Activity retries, timers, cancellation, and durable AI SDK calls |
+| Long-running tasks | [Inngest](./integrations/inngest.md) | Available | Event-driven durable functions, retriable steps, flow control, and checkpointed AI SDK calls |
+| Data ingestion | Connector runtimes | Planned | Bringing external data into Ablo-backed models without creating a second write authority |
+
+An integration gets its own guide when there is runnable application code and
+the boundary has been tested. A dedicated package comes later still: only
+repeated production integrations that reveal substantial reusable behavior
+justify adding another public runtime dependency.
+
+## Long-running tasks
+
+Use [Temporal](./integrations/temporal.md) when work must survive process
+failure, retry Activities, wait on timers, or preserve a durable model loop.
+Temporal owns execution history. Each tool or Activity that touches shared
+state calls the branded Ablo model API at the application edge.
+
+The complete example lives in `examples/temporal-agent` and includes retry,
+replay, cancellation, claim release, and Workflow-bundle tests.
+
+Use [Inngest](./integrations/inngest.md) when durable work starts from events
+and should be expressed as independently retriable steps behind an application
+HTTP endpoint. Inngest owns event delivery, step checkpoints, and flow control.
+Each `step.run()` that touches shared state calls the same branded Ablo model
+API used elsewhere in the application.
+
+The complete example lives in `examples/inngest-agent` and includes
+confirmed-write response-loss replay, key/body conflict, checkpoint reuse,
+claim cleanup, and endpoint-discovery tests.
+
+## Data ingestion
+
+Data ingestion is separate from the Inngest durable-execution integration. A
+connector or ingestion runtime belongs in this section when its public contract
+exists. The same ownership rule will apply:
+
+- the ingestion runtime owns connectors, polling, checkpoints, parsing, and
+  backpressure;
+- Ablo owns validated model writes, idempotency, coordination, and confirmed
+  outcomes;
+- the consuming application owns field mapping and business policy.
+
+Until that contract and a runnable example exist, this page records the
+category without publishing placeholder imports or configuration.

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