@abloatai/ablo 0.58.0 → 0.59.1

package/docs/security.md

@@ -0,0 +1,64 @@
+# Security
+
+> The authority boundaries to preserve when agents, applications, and people coordinate through Ablo.
+
+Ablo carries authenticated participant identity into coordination and writes.
+It does not replace your application's authorization, PostgreSQL constraints, or
+transactional invariants.
+
+## Keep secret credentials on the server
+
+Trusted agents, workers, route handlers, and services use a server-side `sk_`
+credential, normally supplied through `ABLO_API_KEY`. Never include it in a
+browser bundle or agent-generated output.
+
+Browsers use either a publishable read-only `pk_` credential or a short-lived,
+scoped session minted by your backend through `authEndpoint`. See [API
+Keys](./api-keys.md) and [Sessions](./sessions.md) for the credential classes and
+minting flow.
+
+## Give every participant its own identity
+
+Claims are re-entrant for the same participant. Two workers that share one
+credential can therefore appear to Ablo as the same owner. Use separate scoped
+participant credentials when independently operating agents must contend.
+
+The credential also determines project, branch, organization, and allowed
+operations. Callers cannot broaden that authority by adding ids to a request.
+
+## Treat claims as coordination, not authorization
+
+A claim says who currently owns a piece of work. It does not grant permission to
+read or write that resource. Authorization is evaluated independently, and the
+final write must still satisfy the database schema and application invariants.
+
+Claims are leases rather than permanent locks. They expire when their owner
+stops heartbeating. A guarded Ablo write checks ownership again at commit time so
+an expired participant cannot use an old claim handle.
+
+## Keep PostgreSQL authoritative
+
+Ablo coordinates work before and during a write; PostgreSQL remains the durable
+source of truth. Existing constraints, transactions, row-level security, and
+short database locks can remain in place.
+
+A direct database write bypasses Ablo's claims and request ordering. Logical
+replication makes the result visible to Ablo readers, but cannot retroactively
+coordinate the writer. Preserve database constraints for every invariant that
+must also hold for bypass writers.
+
+## Bound external side effects separately
+
+Ablo idempotency covers an Ablo request. It cannot make an email, payment, model
+call, or third-party API mutation exactly once. Give the external provider its
+own idempotency key, or persist an application-owned effect record and reconcile
+ambiguous outcomes.
+
+## Report vulnerabilities privately
+
+Do not put credentials, customer data, or an unpatched vulnerability in a public
+issue. Report it through [GitHub Security
+Advisories](https://github.com/Abloatai/ablo/security/advisories/new).
+
+For operational checks and key rotation, continue to [API Keys](./api-keys.md),
+[Audit Log](./audit.md), and [Operating on Your Database](./operating-on-your-database.md).

package/examples/README.md

@@ -48,6 +48,11 @@ rejected locally.
 heartbeating claim, post-grant model input, durable commit inspection, automatic
 release, and a released-claim fencing check.
 
+`stale-context-agent-turn.ts` owns the standard long-running agent policy:
+subscribe to exact-read changes, abort cancellable work, retain the guarded
+write, rebuild context for bounded retries, and reconcile rather than replay
+after an irreversible side effect.
+
 Import the same schema in every runtime. Use `commits.create` only when several
 typed row operations must land atomically; ordinary writes stay on
 `ablo.<model>.create/update/delete`.
@@ -63,6 +68,7 @@ cd packages/ablo
 ABLO_API_KEY=sk_... npx tsx examples/quickstart.ts
 ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/agent-turn.ts
 ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/expensive-agent-turn.ts
+ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/stale-context-agent-turn.ts
 ```
 
 ## Data Source (customer-owned database)

package/examples/stale-context-agent-turn.ts

@@ -0,0 +1,106 @@
+/**
+ * Canonical stale-context turn: abort early, retain the authoritative write
+ * guard, rebuild context on a bounded retry, and never blindly replay an
+ * irreversible tool side effect.
+ *
+ * The application-owned model and notification functions below are small,
+ * deterministic stand-ins. Keep their cancellation/idempotency contracts when
+ * replacing them with real providers.
+ *
+ * Run: ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/stale-context-agent-turn.ts
+ */
+import { Ablo, AbloStaleContextError } from '@abloatai/ablo';
+import { context } from '@abloatai/ablo/context';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  records: model({
+    title: z.string(),
+    status: z.enum(['pending', 'done']),
+    result: z.string().optional(),
+  }),
+});
+
+const delivered = new Set<string>();
+
+async function callModel(title: string, signal: AbortSignal): Promise<string> {
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, 25);
+    signal.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }, { once: true });
+  });
+  return `Completed: ${title}`;
+}
+
+async function sendResult(operationKey: string, signal: AbortSignal): Promise<void> {
+  signal.throwIfAborted();
+  // Replace with a provider call that accepts operationKey as its idempotency key.
+  delivered.add(operationKey);
+}
+
+async function wasResultSent(operationKey: string): Promise<boolean> {
+  // Replace with the provider's outcome lookup using the same key.
+  return delivered.has(operationKey);
+}
+
+const recordId = process.env.RECORD_ID;
+if (!recordId) throw new Error('RECORD_ID is required');
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+async function completeRecord(id: string): Promise<void> {
+  const operationKey = `complete-record:${id}`;
+  const maxAttempts = 3;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const ctx = await context({
+      ablo,
+      data: { record: ablo.records.read({ id }) },
+    });
+    if (!ctx.data.record) throw new Error(`Record ${id} was not found`);
+
+    const controller = new AbortController();
+    const stop = ctx.onChange((error) => controller.abort(error));
+    let resultMayHaveBeenSent = false;
+
+    try {
+      const result = await callModel(ctx.data.record.title, controller.signal);
+      resultMayHaveBeenSent = true;
+      await sendResult(operationKey, controller.signal);
+
+      await ablo.records.update({
+        id: ctx.data.record.id,
+        data: { status: 'done', result },
+        reads: ctx.reads,
+        idempotencyKey: operationKey,
+      });
+      console.log({ attempt, operationKey, status: 'done' });
+      return;
+    } catch (error) {
+      const stale = error instanceof AbloStaleContextError ||
+        controller.signal.reason instanceof AbloStaleContextError;
+      if (!stale) throw error;
+
+      if (resultMayHaveBeenSent) {
+        const sent = await wasResultSent(operationKey);
+        throw new Error(
+          `Context changed after the external action (sent=${sent}). ` +
+          `Reconcile operation ${operationKey}; do not replay it automatically.`,
+        );
+      }
+      if (attempt === maxAttempts) throw error;
+      // The next iteration assembles new data and new read evidence.
+    } finally {
+      stop();
+    }
+  }
+}
+
+try {
+  await ablo.ready();
+  await completeRecord(recordId);
+} finally {
+  await ablo.dispose();
+}

package/llms.txt

@@ -1,6 +1,6 @@
 # Ablo
 
-Ablo is collaboration infrastructure for AI agents: one API for agents, apps, and services to claim, change, and confirm the same rows.
+Ablo is coordination infrastructure for agents, applications, services, and people working on shared state.
 
 Here is the problem it solves. Two agents reach for `report_stockholm` at once. One claims the row, does slow work (an LLM call, a fetch, a chain of tools), and commits. The second is neither rejected nor allowed to clobber: it waits in line, is handed the row as it now stands, and proceeds. 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 writers serialize instead of colliding. A person editing that row is simply another holder; the agent waits behind them the same way. And a claim is as narrow as its target: name a `path`, a `range`, or a `field` and two claims on non-overlapping parts of the same row are both granted — region locking within one row, with no queueing between regions.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -112,6 +112,7 @@
     "prepack": "npm run build && node scripts/strip-source-condition.mjs",
     "postpack": "node scripts/restore-source-condition.mjs",
     "pack:check": "node scripts/pack-check.mjs",
+    "verify:context-package": "node scripts/verify-context-package.mjs",
     "typecheck": "tsc --noEmit && tsc -p typetests/tsconfig.json && tsc -p examples/tsconfig.json",
     "test": "vitest run",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
@@ -139,8 +140,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.58.0",
-    "@abloatai/transaction": "^0.58.0",
+    "@abloatai/humans": "^0.59.1",
+    "@abloatai/transaction": "^0.59.1",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

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

@@ -1,123 +0,0 @@
-# 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.