@abloatai/ablo 0.56.0 → 0.58.0

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAE5E,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAI5E,MAAM,WAAW,cAAc,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7E,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED,wBAAsB,OAAO,CAAC,KAAK,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACjF,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,GAC7B,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAgB/B"}

package/dist/context/index.js

@@ -0,0 +1,26 @@
+/**
+ * Assemble the values selected for one action and retain the exact Ablo reads
+ * they contain. Each read keeps its own `readAt`; context does not collapse
+ * those independent premises into another watermark.
+ */
+import { z } from 'zod';
+import { awaitDeep } from './await.js';
+import { bindContextEvidence } from './evidence.js';
+import { createContextOnChange } from './onChange.js';
+const contextDataSchema = z.record(z.string(), z.unknown());
+export async function context(options) {
+    const evidenceBinding = bindContextEvidence(options.ablo);
+    const data = await awaitDeep(options.data);
+    const parsed = contextDataSchema.safeParse(data);
+    if (!parsed.success) {
+        throw new TypeError('context() requires `data` to be an object.', { cause: parsed.error });
+    }
+    const evidence = evidenceBinding.collect(data);
+    const dependencies = evidence.map((item) => item.entry);
+    return {
+        data: data,
+        reads: evidence.map((item) => item.row),
+        onChange: createContextOnChange(dependencies, evidenceBinding.onChange),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAwB,MAAM,eAAe,CAAC;AAK5E,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAoB5D,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAA8B;IAE9B,MAAM,eAAe,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,4CAA4C,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAExD,OAAO;QACL,IAAI,EAAE,IAA0B;QAChC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAkB,CAAC;QACtD,QAAQ,EAAE,qBAAqB,CAAC,YAAY,EAAE,eAAe,CAAC,QAAQ,CAAC;KACxE,CAAC;AACJ,CAAC"}

package/dist/context/onChange.d.ts

@@ -0,0 +1,9 @@
+import type { ReadDependency } from '@abloatai/transaction/coordination';
+import type { AbloStaleContextError } from '@abloatai/transaction';
+export type ContextChangeListener = (error: AbloStaleContextError) => void;
+export type ContextOnChange = (listener: ContextChangeListener) => () => void;
+type StartOnChange = (reads: readonly ReadDependency[], listener: ContextChangeListener) => () => void;
+/** Share one transport subscription for every listener on one context. */
+export declare function createContextOnChange(reads: readonly ReadDependency[], start: StartOnChange | undefined): ContextOnChange;
+export {};
+//# sourceMappingURL=onChange.d.ts.map

package/dist/context/onChange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onChange.d.ts","sourceRoot":"","sources":["../../src/context/onChange.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC3E,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,qBAAqB,KAAK,MAAM,IAAI,CAAC;AAE9E,KAAK,aAAa,GAAG,CACnB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,QAAQ,EAAE,qBAAqB,KAC5B,MAAM,IAAI,CAAC;AAEhB,0EAA0E;AAC1E,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,KAAK,EAAE,aAAa,GAAG,SAAS,GAC/B,eAAe,CAoCjB"}

package/dist/context/onChange.js

@@ -0,0 +1,37 @@
+/** Share one transport subscription for every listener on one context. */
+export function createContextOnChange(reads, start) {
+    const listeners = new Set();
+    let stop;
+    let stale;
+    const changed = (error) => {
+        if (stale)
+            return;
+        stale = error;
+        stop?.();
+        stop = undefined;
+        for (const listener of [...listeners])
+            listener(error);
+    };
+    return (listener) => {
+        if (stale) {
+            listener(stale);
+            return () => undefined;
+        }
+        listeners.add(listener);
+        if (reads.length > 0 && !stop) {
+            if (!start) {
+                listeners.delete(listener);
+                throw new TypeError('This Ablo client does not support context().onChange.');
+            }
+            stop = start(reads, changed);
+        }
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0) {
+                stop?.();
+                stop = undefined;
+            }
+        };
+    };
+}
+//# sourceMappingURL=onChange.js.map

package/dist/context/onChange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onChange.js","sourceRoot":"","sources":["../../src/context/onChange.ts"],"names":[],"mappings":"AAWA,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CACnC,KAAgC,EAChC,KAAgC;IAEhC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;IACnD,IAAI,IAA8B,CAAC;IACnC,IAAI,KAAwC,CAAC;IAE7C,MAAM,OAAO,GAAG,CAAC,KAA4B,EAAQ,EAAE;QACrD,IAAI,KAAK;YAAE,OAAO;QAClB,KAAK,GAAG,KAAK,CAAC;QACd,IAAI,EAAE,EAAE,CAAC;QACT,IAAI,GAAG,SAAS,CAAC;QACjB,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC;YAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzD,CAAC,CAAC;IAEF,OAAO,CAAC,QAAQ,EAAE,EAAE;QAClB,IAAI,KAAK,EAAE,CAAC;YACV,QAAQ,CAAC,KAAK,CAAC,CAAC;YAChB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;QACzB,CAAC;QAED,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxB,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAC3B,MAAM,IAAI,SAAS,CAAC,uDAAuD,CAAC,CAAC;YAC/E,CAAC;YACD,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO,GAAG,EAAE;YACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC3B,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACzB,IAAI,EAAE,EAAE,CAAC;gBACT,IAAI,GAAG,SAAS,CAAC;YACnB,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/source-conformance.d.ts

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/conformance';
+export * from '@abloatai/transaction/source/adapters';
 //# sourceMappingURL=source-conformance.d.ts.map

package/dist/source-conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-conformance.d.ts","sourceRoot":"","sources":["../src/source-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,0CAA0C,CAAC"}
+{"version":3,"file":"source-conformance.d.ts","sourceRoot":"","sources":["../src/source-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC"}

package/dist/source-conformance.js

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/conformance';
+export * from '@abloatai/transaction/source/adapters';
 //# sourceMappingURL=source-conformance.js.map

package/dist/source-conformance.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-conformance.js","sourceRoot":"","sources":["../src/source-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,0CAA0C,CAAC"}
+{"version":3,"file":"source-conformance.js","sourceRoot":"","sources":["../src/source-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC"}

package/dist/source-drizzle.d.ts

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/drizzle';
+export * from '@abloatai/transaction/source/adapters/drizzle';
 //# sourceMappingURL=source-drizzle.d.ts.map

package/dist/source-drizzle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-drizzle.d.ts","sourceRoot":"","sources":["../src/source-drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAC"}
+{"version":3,"file":"source-drizzle.d.ts","sourceRoot":"","sources":["../src/source-drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,+CAA+C,CAAC"}

package/dist/source-drizzle.js

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/drizzle';
+export * from '@abloatai/transaction/source/adapters/drizzle';
 //# sourceMappingURL=source-drizzle.js.map

package/dist/source-drizzle.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-drizzle.js","sourceRoot":"","sources":["../src/source-drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAC"}
+{"version":3,"file":"source-drizzle.js","sourceRoot":"","sources":["../src/source-drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,+CAA+C,CAAC"}

package/dist/source-kysely.d.ts

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/kysely';
+export * from '@abloatai/transaction/source/adapters/kysely';
 //# sourceMappingURL=source-kysely.d.ts.map

package/dist/source-kysely.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-kysely.d.ts","sourceRoot":"","sources":["../src/source-kysely.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"source-kysely.d.ts","sourceRoot":"","sources":["../src/source-kysely.ts"],"names":[],"mappings":"AAAA,cAAc,8CAA8C,CAAC"}

package/dist/source-kysely.js

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/kysely';
+export * from '@abloatai/transaction/source/adapters/kysely';
 //# sourceMappingURL=source-kysely.js.map

package/dist/source-kysely.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-kysely.js","sourceRoot":"","sources":["../src/source-kysely.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"source-kysely.js","sourceRoot":"","sources":["../src/source-kysely.ts"],"names":[],"mappings":"AAAA,cAAc,8CAA8C,CAAC"}

package/dist/source-next.d.ts

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/next';
+export * from '@abloatai/transaction/source/endpoint';
 //# sourceMappingURL=source-next.d.ts.map

package/dist/source-next.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-next.d.ts","sourceRoot":"","sources":["../src/source-next.ts"],"names":[],"mappings":"AAAA,cAAc,mCAAmC,CAAC"}
+{"version":3,"file":"source-next.d.ts","sourceRoot":"","sources":["../src/source-next.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC"}

package/dist/source-next.js

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/next';
+export * from '@abloatai/transaction/source/endpoint';
 //# sourceMappingURL=source-next.js.map

package/dist/source-next.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-next.js","sourceRoot":"","sources":["../src/source-next.ts"],"names":[],"mappings":"AAAA,cAAc,mCAAmC,CAAC"}
+{"version":3,"file":"source-next.js","sourceRoot":"","sources":["../src/source-next.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC"}

package/docs/agent-integration-decision-guide.md

@@ -0,0 +1,123 @@
+# Agent Integration Decision Guide
+
+> Choose one integration route before reading an example. Most existing products should coordinate one existing operation first; they should not copy the document pipeline.
+
+## Start with the operation you already own
+
+Name one existing application operation, such as `completeTask`, `approveInvoice`,
+or `publishReport`. Keep its authorization, database transaction, constraints,
+and public API in place. Add Ablo at that operation boundary.
+
+Use this routing table for the decisions that are easy to conflate:
+
+| Question | Choose | When |
+|---|---|---|
+| What is being coordinated? | Identifier-only claim | Work has a stable business identity, but the authoritative row and final write remain in the existing service or Postgres. |
+|  | Row-backed claim | The coordinated row is an Ablo schema model and the final write goes through that model resource. |
+| Did the decision depend on previously read rows? | Captured reads | Read the premises with `read(...)`, then pass those returned rows through `reads`. Use this even when the written row is different from a premise row. |
+| Must several Ablo mutations either all land or none land? | Atomic commit | Put the mutations, captured reads, and any typed claim handles in one `commits.create(...)`. Separate mutation calls are independently successful or failed. |
+| Where should the final write happen? | Existing database write | Keep it when the current service owns the transaction, constraints, or rollout switch. Ablo's lease does not join a transaction running in another process. Re-read and validate inside the database transaction. |
+|  | Ablo-routed write | Use it for declared schema models after the database connection and server schema are configured. Guard decision-dependent writes with a held claim or captured reads. |
+| Who is participating? | Stateless HTTP client | Agents, jobs, and request/response server handlers. Give each concurrent participant its own scoped credential. |
+|  | Reactive WebSocket client | Human-facing applications that need live state, presence, or local reactive reads. This transport is not required for worker coordination. |
+
+These choices compose. For example, a stateless worker can take an
+identifier-only claim, perform slow work, and then call an existing Postgres
+operation. Another worker can take a row-backed claim and submit an atomic Ablo
+commit guarded by captured premise rows.
+
+## Choose the smallest example
+
+### Coordinate existing work
+
+Start with
+[`examples/graphql-existing-backend`](../../../examples/graphql-existing-backend/README.md)
+when an application already owns its API, operation, and Postgres write.
+
+It demonstrates:
+
+- GraphQL delegating to a named application operation;
+- an identifier lease around expensive work;
+- the existing service retaining its authoritative transaction and re-read;
+- an operation-level switch between existing and coordinated paths; and
+- recovery and contract parity without replacing the application's API.
+
+Use
+[`examples/coordination-conformance`](../../../examples/coordination-conformance/README.md)
+alongside it to verify real hosted lease behavior independently of the domain.
+
+### Build evidence-backed document state
+
+Read
+[`examples/existing-document-pipeline`](../../../examples/existing-document-pipeline/README.md)
+only when the feature genuinely needs versioned source evidence, citations,
+guarded review decisions, atomic multi-row review writes, and retained search
+projections.
+
+That example is an advanced reference application. Its document ingestion,
+search, review, projection-retention, and append-only event policies are not
+prerequisites for adopting Ablo.
+
+## Know which owner makes each promise
+
+| Ablo responsibility | Application responsibility |
+|---|---|
+| Participant-scoped claims, lease expiry, wait/skip behavior, heartbeat, release, and commit-time fencing | Choosing the business claim identity and issuing distinct participant credentials |
+| Capturing model-row versions returned by `read(...)` and rejecting a guarded write when those premises are stale | Choosing every row that is a premise of the decision |
+| Atomicity among mutations submitted in one Ablo commit | Database transactions and constraints outside that commit; never presenting separate writes as an atomic batch |
+| Request idempotency within the documented identity, retention, and identical-request rules | Durable workflow idempotency and deduplication of external effects |
+| Synchronizing declared model rows and serving reactive state | Uploads, search semantics, projections, workflow execution, review policy, and external APIs |
+| Credentials, participant attribution, and schema-declared scope enforcement | Existing application authentication and authorization at the operation boundary |
+
+Claims coordinate cooperative participants; they are leases, not absolute locks.
+A writer outside the coordinated path can still change Postgres. Database
+constraints and a commit-time guarded re-read remain the final backstop.
+
+## Minimum integration contract
+
+Write down these answers next to the operation before implementing it:
+
+1. **Existing operation:** Which named operation and public API remain stable?
+2. **Claim identity:** Which stable model row or business identifier represents the contested work?
+3. **Participant identity:** Which distinct scoped credential does each concurrent human, agent, or worker use?
+4. **Premises:** Which exact rows does the decision depend on, and which of them must use `read(...)`?
+5. **Atomic boundary:** Which writes must all succeed together? Are they one Ablo commit, one existing database transaction, or deliberately independent?
+6. **Persistence owner:** What remains in Postgres and which writes, if any, are routed through Ablo?
+7. **Failure behavior:** What happens on contention, lease expiry, stale evidence, request retry, partial completion, and an external side-effect failure?
+8. **Proof:** Which local contract test and which hosted or staging test proves each claimed guarantee?
+
+If an answer is unknown, keep the existing write path available. Do not broaden
+the schema or copy an advanced example to hide the missing decision.
+
+## Guarantee-to-test matrix
+
+The examples prove different layers. A local fixture proves application behavior;
+it does not prove hosted infrastructure. Conversely, hosted claim conformance
+does not prove a domain transition or a real Postgres transaction.
+
+| Statement | Proof level | Executable evidence |
+|---|---|---|
+| GraphQL keeps the same result while the named operation changes implementation | Local application contract | `examples/graphql-existing-backend/tests/graphql.test.ts` and `tests/pilot.test.ts` — `the GraphQL resolver delegates one typed input to the named operation`; `the operation switch preserves the uncontended GraphQL contract` |
+| Coordination moves expensive work outside the retained database critical section | Local application contract; real DB timing requires staging | `examples/graphql-existing-backend/tests/pilot.test.ts` — `coordination moves expensive work outside the retained critical section`; optional `npm run test:live:postgres` |
+| Contenders do not duplicate expensive work, and failure releases the path | Local application contract | `examples/graphql-existing-backend/tests/pilot.test.ts` — `two coordinated workers pay for expensive work once`; `a failed owner releases coordination so the existing path remains available` |
+| Distinct hosted participants exclude one another, heartbeat, release, and recover after expiry | Hosted infrastructure | `examples/coordination-conformance`: `npm run test:live`; its live runner also executes the exit-without-release expiry probe |
+| A decision based on changed source evidence is rejected | Local application contract using Ablo-shaped guards | `examples/existing-document-pipeline/tests/processDocument.test.ts` — `a source change rejects stale extracted output`; `tests/review.test.ts` — `guarded mutations reject stale evidence and release claims for retry` |
+| Several review records submitted as one commit are atomic; separate calls can partially complete | Local application contract | `examples/existing-document-pipeline/tests/review.test.ts` — `requesting review atomically creates durable issue state and an event`; `independent review writes expose partial completion and retry only the stale target` |
+| Rebuilding search does not remove a complete snapshot referenced by durable review evidence | Local application policy | `examples/existing-document-pipeline/tests/search.test.ts` — `publishing a rebuild retains the complete projection snapshot referenced by review`; `an unreferenced superseded projection becomes removable as one snapshot` |
+| The documented ownership tree, public exports, dependency direction, and lack of cycles match disk | Local structure contract | Each focused example's `tests/structure.test.ts`; the document fixture additionally validates exact inventory and dependency direction from `structure.json` |
+| Authorization, latency, database locking, and external-effect behavior match the production application | Partner staging | Run the operation against the real auth, Postgres schema, workload, and provider sandbox. No repository fixture can establish this claim. |
+
+## Safe first adoption
+
+For an existing product, the default sequence is:
+
+1. Wrap one named operation without changing its public API.
+2. Use an identifier-only claim if the existing database remains authoritative.
+3. Keep the Postgres transaction, lock, validation, and constraints in place.
+4. Verify participant-scoped lease behavior with coordination conformance.
+5. Add captured reads or an atomic Ablo commit only when the operation actually needs them.
+6. Move more persistence through Ablo only after the guarded hosted write path and staging behavior are proven for that operation.
+
+Continue with the [Integration Guide](./integration-guide.md) for setup and API
+details, or [Concurrency Convention](./concurrency-convention.md) for the exact
+guarding rules.

package/docs/agents.md

@@ -34,7 +34,7 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http"
 // `get` resolves to the row, or `undefined` when none matches.
 const open = await ablo.records.list({ where: { status: "todo" } });
 
-const record = await ablo.records.get({ id: open[0].id });
+const record = await ablo.records.read({ id: open[0].id });
 if (!record) throw new Error("record not found");
 
 console.log(record.title);
@@ -42,9 +42,68 @@ await ablo.records.update({ id: record.id, data: { status: "done" } });
 ```
 
 It exposes `get` / `list` / `create` / `update` / `delete`, plus `commits`
-and `claim`. It does **not** expose stateful-only `local` reads or `onChange`
-subscriptions. Those need a live connection, so with `transport: 'http'` they
-are compile errors rather than runtime surprises.
+and `claim`. It does **not** expose stateful-only `local` reads or model
+`onChange` subscriptions. Those need a WebSocket, so with `transport: 'http'`
+they are compile errors. `context().onChange` is separate: while its listener
+is active, it holds one HTTP response open until the context changes or the
+listener stops.
+
+## Managed scoped agents
+
+When this process owns the secret client and also runs the agent, prefer
+`agents.create`. It mints the restricted credential, returns a schema-typed
+client, and renews that credential for a long run. `sessions.create({ agent })`
+is the raw-token path for handing identity to another runtime.
+
+Derive identity and groups from the run row or trusted job payload—not from
+model output or an HTTP request body. A serverless handler normally creates and
+disposes one child per invocation:
+
+```ts
+const run = await control.runs.read({ id: verifiedRunId });
+if (!run) throw new Error('run not found');
+
+const agent = await control.agents.create({
+  id: `run:${run.id}`,
+  name: 'run-worker',
+  can: { records: ['read', 'update'] },
+  syncGroups: [`workspace:${run.workspaceId}`],
+});
+try {
+  await executeRun(agent, run);
+} finally {
+  await agent.dispose();
+}
+```
+
+Use a stable id only when one logical run is serialized; two concurrent workers
+that share an id appear as the same participant. For independent concurrent
+work, omit `id` and let Ablo create distinct identities.
+
+A long-running worker may cache one managed client per stable scope, but the
+cache owns lifecycle: evict idle clients, call `dispose()` on eviction, and
+dispose every client during graceful shutdown. Never cache a client and later
+reuse it for a different workspace or capability set.
+
+```ts
+const agents: Record<
+  string,
+  Awaited<ReturnType<typeof control.agents.create>> | undefined
+> = {};
+
+async function agentFor(run: Run) {
+  const key = `${run.workspaceId}:${run.workerSlot}`;
+  const cached = agents[key];
+  if (cached) return cached;
+  const created = await control.agents.create({
+    id: `worker:${key}`,
+    can: { records: ['read', 'update'] },
+    syncGroups: [`workspace:${run.workspaceId}`],
+  });
+  agents[key] = created;
+  return created;
+}
+```
 
 ## AI SDK tools
 
@@ -147,19 +206,21 @@ default caller here, not a bolt-on.
 
 ```text
 something happens ──▶ your agent (HTTP, no socket)
-  (a job, a webhook,     read context (list/get)
+  (a job, a webhook,     read context (list/get/read)
    a queue message)      claim → work → commit
                          done — no held connection
 ```
 
-Because it holds nothing open, an agent is a **stateless worker**: deploys and
-restarts are free, and you scale by adding workers. A long-running fleet of idle
-agents costs nothing on the live plane — that capacity stays for humans.
+Without `context().onChange`, an agent holds nothing open and remains a
+**stateless worker**: deploys and restarts are free, and you scale by adding
+workers. Each active context listener is explicit connection capacity and must
+be stopped when its work ends.
 
 ## What stays on the live (human) plane
 
-`onChange` (live subscriptions) and the `local` reads (local synced-pool
-reads) require a WebSocket and a local store — they're for interactive UIs, not
-stateless agents. An agent reacts to an external trigger (a job/queue/webhook),
-then reads with `list`/`get`. See [client behavior](/client-behavior) for
-the full surface and [guarantees](/guarantees) for the coordination semantics.
+Model `onChange` and `local` reads require a WebSocket and a local store —
+they're for interactive UIs. An HTTP agent normally reacts to an external
+trigger, then reads with `list`/`get`. For costly work, `context().onChange` can
+stop that one run early while the final write still uses `context().reads`.
+See [client behavior](/client-behavior) for the full surface and
+[guarantees](/guarantees) for the coordination semantics.

package/docs/api-keys.md

@@ -23,9 +23,9 @@ and remap them before each command.
 
 | Job | Credential | How you get it |
 |---|---|---|
-| Manage a project or its branches | `mk_` | `npx ablo login --project <slug>` stores it for the CLI. |
+| Manage a project or its branches | `mk_` | `npx ablo login` stores it for the CLI; pick the project in the terminal, or name it with `--project <slug>`. |
 | Develop locally | expiring `sk_` bound to the current branch | `npx ablo dev` writes it as `ABLO_API_KEY` in gitignored `.env.local`. |
-| Prepare a branch once, including CI | expiring `sk_` bound to that branch | `npx ablo dev --no-watch --branch <ref>`; CI supplies `ABLO_MANAGEMENT_KEY`. |
+| Prepare a branch once, including CI | expiring `sk_` bound to that branch | `npx ablo dev --no-watch --branch <ref>`; headless CI supplies an `mk_` credential through `ABLO_API_KEY`. |
 | Run the production backend | `sk_` bound to the production root | Store it as the deployment's `ABLO_API_KEY`. |
 | Read in a browser | `pk_` | Publishable, read-only key. |
 | Write in a browser as a user | short-lived `ek_` | Your backend exposes `authEndpoint` and mints it. |
@@ -33,9 +33,9 @@ and remap them before each command.
 The everyday loop is therefore:
 
 ```bash
-npx ablo login --project <project>  # once per project
-npx ablo dev                        # follows Git, mints and wires this branch
-npx ablo status                     # broad readiness report
+npx ablo login    # once per project: approve in the browser, pick the project
+npx ablo dev      # follows Git, mints and wires this branch
+npx ablo status   # broad readiness report
 ```
 
 Application code and agents still read one variable:
@@ -91,7 +91,7 @@ The credential class lives in the prefix:
 
 | Prefix | Purpose | Stored where |
 |---|---|---|
-| `mk_` | project and branch management | CLI credential store or `ABLO_MANAGEMENT_KEY` |
+| `mk_` | project and branch management | CLI credential store; `ABLO_API_KEY` only in headless automation |
 | `sk_` | trusted runtime, full branch authority | server-side `ABLO_API_KEY` |
 | `rk_` | restricted runtime or agent | trusted runtime that needs the delegated scope |
 | `pk_` | publishable, browser-safe read access | browser bundle |