@abloatai/ablo 0.37.1 → 0.38.0

package/docs/examples/ai-sdk-tool.md

@@ -1,17 +1,14 @@
-# AI SDK Tool
+# AI SDK Tools
 
-> Put a claim-and-commit loop inside an AI SDK tool call.
+> Give an AI SDK agent safe access to the same typed Ablo resources as your
+> backend.
 
 Use AI SDK for the agent loop and Ablo for the state boundary inside the tool.
 When an agent updates a shared record from inside a tool call you have a
-concurrency problem: another agent may be editing the same row, and a naive write
-silently overwrites it. This is the safe pattern — read the record, claim the row
-so anyone else waits their turn, write through a checked update, and release the
-claim automatically.
-
-Claims don't lock. If another writer holds the row, `claim` waits for them,
-re-reads the fresh row, then hands it to you — so two writers serialize instead
-of clobbering.
+concurrency problem: another agent or a person may be editing the same row, and
+a naive write can overwrite work the model never saw. Ablo's tool adapters put
+the authoritative read, retry, claim, and confirmed-write behavior behind the
+ordinary AI SDK tool contract.
 
 ```ts
 // app/api/chat/route.ts
@@ -20,11 +17,11 @@ import { defineSchema, model, z as schemaZ } from '@abloatai/ablo/schema';
 import { anthropic } from '@ai-sdk/anthropic';
 import {
   streamText,
-  tool,
   convertToModelMessages,
   stepCountIs,
   type UIMessage,
 } from 'ai';
+import { updateTool } from '@abloatai/ablo/ai-sdk';
 import { z } from 'zod';
 
 export const runtime = 'nodejs';
@@ -43,42 +40,19 @@ const ablo = Ablo({
   transport: 'http',
 });
 
-const updateTask = tool({
-  description: 'Update a task in the product database.',
+const updateTask = updateTool(ablo.tasks, {
+  title: 'Update task',
+  description: 'Update a task without overwriting concurrent work.',
   inputSchema: z.object({
     taskId: z.string(),
     status: z.enum(['todo', 'doing', 'done']).optional(),
     summary: z.string().optional(),
   }),
-  execute: async ({ taskId, status, summary }) => {
-    await ablo.ready();
-
-    // retrieve hits the server for the latest row (async — await it).
-    const task = await ablo.tasks.get({ id: taskId });
-    if (!task) return { ok: false, reason: 'not_found' };
-
-    // If another agent already holds this row, claim waits for them to finish,
-    // re-reads the fresh row, then hands it back on `claim.data`. The claim is
-    // released automatically when it goes out of scope.
-    await using claim = await ablo.tasks.claim({
-      id: taskId,
-      description: 'editing',
-      ttl: '2m',
-    });
-
-    // Because you hold the claim, this update is rejected if the row changed
-    // underneath you, instead of silently overwriting it.
-    const updated = await ablo.tasks.update({
-      id: claim.data.id,
-      data: {
-        status: status ?? claim.data.status,
-        summary: summary ?? claim.data.summary,
-      },
-      wait: 'confirmed',
-    });
-
-    return { ok: true, task: updated };
-  },
+  id: ({ taskId }) => taskId,
+  apply: (current, { status, summary }) => ({
+    status: status ?? current.status,
+    summary: summary ?? current.summary,
+  }),
 });
 
 export async function POST(req: Request) {
@@ -100,13 +74,12 @@ export async function POST(req: Request) {
 
 The model provider is interchangeable — swap `anthropic(...)` for any
 server-bound provider instance. What matters is that the route binds the model on
-the server (never trusting one sent in the request body), converts the incoming
-`UIMessage[]` with `convertToModelMessages`, and that the tool:
-
-- reads the latest row with `retrieve` (a server read),
-- claims it for exclusive, ordered access — if someone else holds it, the claim
-  waits for them, then re-reads,
-- writes through the model resource, which is rejected if the row changed
-  underneath you,
-- waits for confirmation with `wait: 'confirmed'`,
-- and auto-releases the claim when the tool returns.
+the server (never trusting one sent in the request body) and converts the
+incoming `UIMessage[]` with `convertToModelMessages`.
+
+`updateTool` defaults to a functional update: Ablo re-reads and reapplies the
+patch if another participant writes first. Use `strategy: 'claim'` when the
+model should skip work already owned by someone else, or `strategy: 'queue'`
+when it should wait in Ablo's server-owned FIFO claim queue. The same entrypoint
+also exports `readTool`, `createTool`, and `deleteTool`; deletes require AI SDK
+approval unless the application explicitly disables it.

package/docs/how-it-works.md

@@ -69,8 +69,9 @@ database differs by environment — the code is identical.
 - **Production:** your Postgres. `ablo connect` sets up a scoped writer role and
   logical replication; your rows live in your database, and Ablo writes to them
   through that role.
-- **Sandbox and local dev:** a separate or local Postgres you can throw away. Same
-  models, same code, a different database behind them.
+- **Development branches and local dev:** a separate or local Postgres, or a
+  branch of the one you already run. Same models, same code, a different
+  database behind them.
 - **Before you connect one.** Ablo keeps state in its own log, so you can build the
   whole app today and point it at a real database when you're ready.
 

package/docs/index.md

@@ -60,11 +60,14 @@ based on a row that has since changed is turned away rather than applied.
     stay in your own migrations.
 
     ```bash
-    npx ablo init && npx ablo push
+    npx ablo init
+    npx ablo dev
     ```
 
-    `push` is the step everything depends on: the server keeps its own copy of the schema, and
-    until it has yours, a write to a new model fails with `server_execute_unknown_model`.
+    `dev` gives the current Git branch an isolated Ablo branch, wires its temporary key,
+    pushes the schema, and watches for changes. Until the server has your schema, a write to
+    a new model fails with `server_execute_unknown_model`. See
+    [Branch-first development](./branch-development.md).
   </Step>
 
   <Step title="Connect the database the rows live in">
@@ -161,6 +164,7 @@ default caller, not a special one.
 
 - [Quickstart](./quickstart.md) — make your first coordinated write.
 - [Integration Guide](./integration-guide.md) — the canonical end-to-end integration.
+- [Integrations](./integrations.md) — long-running tasks, ingestion, and other application-edge runtimes.
 - [CLI & Migrations](./cli.md) — `init` / `connect` / `push` / `migrate` / `generate`.
 - [Connect Your Database](./data-sources.md) — where rows land when your own database is canonical.
 - [Deployment](./deployment.md) — the database, the keys, and the schema push that take an integration to production.

package/docs/integration-guide.md

@@ -66,24 +66,17 @@ deterministic demo; it does not call your API key or mutate hosted Ablo data.
 It is also built for coding agents: copy the sandbox prompt into Claude Code or
 Codex and ask it to wire one real model through the schema model API.
 
-Use the authenticated org dashboard sandbox for real integration work. The
-default sandbox is the equivalent of Stripe test mode:
-
-- it is scoped to the organization,
-- it has an isolated sync group prefix,
-- it mints `sk_test_*` keys,
-- it can be reset without touching live state,
-- additional sandboxes can start blank or from copied live configuration.
-
-Live keys and sandbox keys are separate. Use `sk_test_*` while wiring your app,
-agents, and Data Source endpoint; move to `sk_live_*` only when the same schema
-and write path are ready for production.
+Use `npx ablo dev` for real integration work. It derives an immutable branch
+from Git, inherits the parent schema, and writes a temporary branch credential
+to `.env.local`. Each developer or pull request gets independent schema, rows,
+claims, and logs. Use an explicit `sk_live_*` root credential only in the
+reviewed production deployment.
 
 When handing this to a coding agent, give it a concrete target:
 
 ```txt
 Add Ablo to this app for one model your agents edit.
-Use the org sandbox sk_test_* key. Declare schema, add the Ablo client, replace
+Run npx ablo dev and use its branch-bound key. Declare schema, add the Ablo client, replace
 one write with ablo.<model>.update(..., { readAt, onStale: 'reject',
 wait: 'confirmed' }), and add a smoke test for two concurrent writers.
 ```

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.