@abloatai/ablo 0.47.0 → 0.49.0

package/examples/agent-turn.ts

@@ -0,0 +1,37 @@
+/**
+ * Canonical cheap turn: explicitly attach the exact rows used to decide the
+ * write. Ablo keeps their watermarks opaque and checks them at commit time.
+ *
+ * Run: ABLO_API_KEY=sk_... TASK_ID=task_... npx tsx examples/agent-turn.ts
+ */
+import { Ablo } from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  tasks: model({
+    title: z.string(),
+    status: z.enum(['pending', 'done']),
+    result: z.string().optional(),
+  }),
+});
+
+const taskId = process.env.TASK_ID;
+if (!taskId) throw new Error('TASK_ID is required');
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+try {
+  await ablo.ready();
+  const task = await ablo.tasks.get({ id: taskId });
+  if (!task) throw new Error(`Task ${taskId} was not found`);
+  const commitId = `task:${taskId}:cheap`;
+  await ablo.tasks.update({
+    id: task.id,
+    data: { status: 'done', result: `Completed: ${task.title}` },
+    reads: [task],
+    idempotencyKey: commitId,
+  });
+  const record = await ablo.commits.get({ id: commitId });
+  console.log({ identity: ablo.identity, commit: record });
+} finally {
+  await ablo.dispose();
+}

package/examples/data-source/ablo-driver.ts

@@ -18,8 +18,8 @@
 
 import {
   signAbloSourceRequest,
-  type Ablo,
-} from '@ablo/ablo';
+  type SourceOperation,
+} from '@abloatai/ablo/source';
 
 export interface AbloDriverOptions {
   /**
@@ -40,11 +40,11 @@ export class AbloDriver {
     return this.send({ type: 'load', model, id });
   }
 
-  async list(model: string, query?: Ablo.Source.Operation['input']) {
+  async list(model: string, query?: SourceOperation['input']) {
     return this.send({ type: 'list', model, query: query ?? {} });
   }
 
-  async commit(operations: readonly Ablo.Source.Operation[], clientTxId?: string) {
+  async commit(operations: readonly SourceOperation[], clientTxId?: string) {
     return this.send({
       type: 'commit',
       operations,

package/examples/data-source/customer-server.ts

@@ -15,7 +15,12 @@
  * inside a transaction. The shape of the handlers stays identical.
  */
 
-import Ablo, { dataSource, sourceEventForOperation } from '@ablo/ablo';
+import {
+  dataSource,
+  sourceEventForOperation,
+  type SourceEvent,
+  type SourceOperation,
+} from '@abloatai/ablo/source';
 import { schema } from './schema';
 
 type TaskRow = {
@@ -32,7 +37,7 @@ const taskStore = new Map<string, TaskRow>();
 // populated in the same transaction as the app-row write. Ablo polls `events`
 // to fan out changes that bypassed Ablo, and to repair SDK-origin writes if
 // Ablo's immediate post-commit append failed.
-const outbox: Ablo.Source.Event[] = [];
+const outbox: SourceEvent[] = [];
 let outboxSequence = 0;
 
 // Seed one row so the example's first `load` returns something.
@@ -138,7 +143,7 @@ export const handleAbloSource = dataSource({
 });
 
 function applyOperation(
-  op: Ablo.Source.Operation,
+  op: SourceOperation,
   clientTxId: string | undefined,
 ): TaskRow | null {
   if (op.model !== 'tasks') return null;
@@ -180,7 +185,7 @@ function applyOperation(
 }
 
 function appendOutbox(input: {
-  operation: Ablo.Source.Operation;
+  operation: SourceOperation;
   entityId: string;
   data: TaskRow | null;
   clientTxId: string | undefined;

package/examples/data-source/schema.ts

@@ -12,7 +12,7 @@
  * side without the other is a compile error.
  */
 
-import { defineSchema, model, z } from '@ablo/ablo/schema';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
   tasks: model({

package/examples/expensive-agent-turn.ts

@@ -0,0 +1,76 @@
+/**
+ * Canonical expensive turn: live claim, heartbeat,
+ * post-grant model input, ordinary guarded update, durable commit retrieval,
+ * automatic release, and an explicit lost-claim fencing proof.
+ *
+ * Run: ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/expensive-agent-turn.ts
+ */
+import { Ablo, AbloClaimedError } from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  researchJobs: model({
+    prompt: z.string(),
+    status: z.enum(['pending', 'complete']),
+    answer: z.string().optional(),
+  }),
+});
+
+async function callExpensiveModel(prompt: string): Promise<string> {
+  // Replace this deterministic stand-in with the model provider used by the app.
+  await new Promise((resolve) => setTimeout(resolve, 25));
+  return `Model answer for: ${prompt}`;
+}
+
+const jobId = process.env.JOB_ID;
+if (!jobId) throw new Error('JOB_ID is required');
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+try {
+  await ablo.ready();
+  const commitId = `research:${jobId}:expensive`;
+  await using claim = await ablo.researchJobs.claim({
+    id: jobId,
+    description: 'expensive model turn',
+    ttl: '30s',
+    heartbeat: { every: '10s' },
+  });
+  const answer = await callExpensiveModel(claim.data.prompt);
+  await claim.heartbeat({ details: { phase: 'writing' } });
+  await ablo.researchJobs.update({
+    id: claim.data.id,
+    data: { status: 'complete', answer },
+    claim,
+    idempotencyKey: commitId,
+  });
+
+  const durable = await ablo.commits.get({ id: commitId });
+  if (!durable) throw new Error(`Commit ${commitId} was not retained`);
+  console.log({
+    identity: ablo.identity,
+    readSet: durable.readSet,
+    attempts: durable.attempts,
+    claims: durable.claims,
+    authority: durable.authority,
+    status: durable.status,
+    confirmationMs: Date.parse(durable.statusAt) - Date.parse(durable.createdAt),
+  });
+
+  const lost = await ablo.researchJobs.claim({ id: jobId, ttl: '30s' });
+  await lost.release();
+  try {
+    await ablo.researchJobs.update({
+      id: lost.data.id,
+      data: { status: 'complete', answer: 'must not land' },
+      claim: lost,
+      idempotencyKey: `research:${jobId}:lost-claim-proof`,
+    });
+    throw new Error('A released claim was not fenced');
+  } catch (error) {
+    if (!(error instanceof AbloClaimedError) || error.code !== 'claim_lost') throw error;
+    console.log('lost claim fenced', error.code);
+  }
+} finally {
+  await ablo.dispose();
+}

package/examples/quickstart.ts

@@ -6,8 +6,8 @@
  *   ABLO_API_KEY=sk_... npx tsx examples/quickstart.ts
  */
 
-import Ablo from '@ablo/ablo';
-import { defineSchema, model, z } from '@ablo/ablo/schema';
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
   weatherReports: model({
@@ -29,13 +29,15 @@ async function main() {
     await ablo.ready();
 
     const created = await ablo.weatherReports.create({
-      location,
-      status: 'pending',
+      data: { location, status: 'pending' },
     });
 
-    const updated = await ablo.weatherReports.update(created.id, {
-      status: 'ready',
-      forecast: await getWeather(created.location),
+    const updated = await ablo.weatherReports.update({
+      id: created.id,
+      data: {
+        status: 'ready',
+        forecast: await getWeather(created.location),
+      },
     });
 
     console.log('updated', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -83,7 +83,9 @@
   },
   "files": [
     "dist",
-    "docs",
+    "docs/*.md",
+    "docs/examples",
+    "docs/integrations",
     "examples",
     "assets",
     "AGENTS.md",
@@ -110,6 +112,7 @@
     "lint:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts --check",
     "validate:openapi": "redocly lint ../../docs/ablo/public/openapi.json --extends=recommended --skip-rule=no-server-example.com",
     "build:docs": "node scripts/build-blume-docs.mjs",
+    "lint:docs-site": "node scripts/build-blume-docs.mjs --check",
     "lint:docs": "node scripts/check-doc-drift.mjs",
     "lint:pkg": "publint"
   },
@@ -124,8 +127,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.47.0",
-    "@abloatai/transaction": "^0.47.0"
+    "@abloatai/humans": "^0.49.0",
+    "@abloatai/transaction": "^0.49.0"
   },
   "peerDependencies": {
     "ai": "^6.0.0 || ^7.0.0",

package/docs/internal/README.md

@@ -1,18 +0,0 @@
-# Internal Architecture Notes
-
-These documents explain implementation and protocol decisions for contributors.
-They are not extra public import paths.
-
-The ownership rule is:
-
-- transaction owns transport-neutral and HTTP contracts;
-- humans owns reactive state, WebSockets, presence, browser persistence, and React;
-- agent owns agent-specific behavior and perception;
-- the branded `@abloatai/ablo` package maps stable public entrypoints to those
-  owners;
-- `apps/sync-server` owns backend execution.
-
-Consumer code should import `@abloatai/ablo` and its documented subpaths.
-Contributor code should import the narrow owner package or module it actually
-uses. Do not add forwarding compatibility packages or duplicate contract
-definitions.

package/docs/internal/agent-fleet-coordination-design.md

@@ -1,171 +0,0 @@
-# Coordination as Eyes and Ears for Agent Fleets
-
-The design intent behind claims, presence, and stale-context — stated as one
-picture so it can be argued about and built against, not re-derived each time
-someone asks "how do the coordination agents work?"
-
-## The thesis
-
-Humans coordinating in a shared document already have everything they need:
-they *see* each other's cursors, they *hover* to highlight the region they're
-touching, and they *say* what they're doing ("I'm rewriting the intro"). Nobody
-overwrites anybody because everybody has eyes and ears.
-
-Agents don't. They work directly and silently, at machine speed, in fleets — say
-100 agents across 10 groups, each group on its own area of the data. The
-coordination layer's job is to give that fleet the same social awareness a room
-of humans has, expressed as a protocol: **see who is working where, learn what
-they are doing, and take a turn instead of a collision.**
-
-At fleet scale the load-bearing property is that this stays *local*. The layer
-does not lock "the fleet." It coordinates per row. 100 agents over 10
-non-overlapping areas are 100 parallel tracks that only ever meet on the
-handful of rows two agents genuinely both want. Cost is paid at the overlap, not
-across the fleet — which is why adding agents on separate areas adds no
-coordination cost.
-
-## The one principle: two channels, never crossed
-
-Awareness and safety are different channels, and keeping them apart is what makes
-this safe *and* loop-free at machine speed.
-
-- **Safety is pull, at write time.** An agent acts on its best read and its write
-  is rejected if the row moved underneath it. The rejection is the signal, and it
-  only ever fires when an agent actually chooses to write. A pull channel cannot
-  loop — nothing is being pushed.
-- **Awareness is push, and it is the only channel that can storm.** So it is the
-  only channel we coalesce and rate-limit. Hot data that changes every
-  millisecond lives entirely on the safe *pull* side and therefore generates zero
-  awareness traffic — an agent that cares about a fast-ticking value just tries
-  its write and re-reads if it lost, rather than being woken on every tick.
-
-Collapse the two channels — "notify every reader on every change" — and a
-millisecond-ticking field produces read → notify → re-read → act → notify →
-forever. Keeping them separate is the whole reason that loop can't form.
-
-## The six behaviors
-
-### 1. Eyes: see who is working where
-
-Presence broadcasts, live, which agent holds which row. Before an agent commits
-to work, it can see the area is already taken. This is advisory: it informs, it
-forces nothing.
-
-```ts
-const who = ablo.tasks.claim.state({ id: 'task_123' }); // holder or null
-// who.heldBy      === 'agent:forecaster'
-// who.description === 'rewriting the risk section to match Q3'
-```
-
-### 2. Ears: learn *what* they are doing
-
-A claim carries a single `description` — the machine version of the
-hover-highlight plus the spoken "what I'm doing," in one field. It is the
-sentence a peer reads to decide whether to wait, work elsewhere, or move on. It
-defaults to `'editing'` when a claim is taken without one.
-
-```ts
-await using claim = await ablo.tasks.claim({
-  id: 'task_123',
-  description: 'rewriting the risk section to match Q3 numbers',
-});
-```
-
-### 3. Reject *before* the tokens are spent
-
-The claim is a **cheap pre-flight, taken before the generation, not before the
-write.** A human wastes nothing by starting to type into a locked paragraph; an
-agent wastes a whole expensive completion. So the discipline is:
-
-```txt
-claim (cheap)  ->  if granted: generate the block  ->  write
-             \->   if held:    never generate anything
-```
-
-An agent that is told "no" at the claim never produced the write that would have
-lost — the large token spend simply did not happen. This is the single most
-important reason the claim exists before the work, not after it.
-
-### 4. Reject *with* the description, so the blocked agent can decide
-
-A bare "taken" forces a blind retry. The rejection carries the holder's
-`description`, and the SDK renders it into the `AbloClaimedError` message:
-*"Claimed by agent:forecaster: rewriting the risk section to match Q3."* So the
-blocked agent reasons on real information: wait for the turn, go work somewhere
-else, or drop the task because the work is already being done. "No, because
-someone is rewriting the risk section" is actionable in a way "no" is not.
-
-### 5. Queue: take a turn, with an opt-out if the line is long
-
-Contention is a fair FIFO queue: the blocked agent waits its turn and is
-*notified* the moment it arrives (push, not poll — it does not sit and spin).
-When promoted, it re-reads so it works from the latest, with the previous
-holder's change already in place. And the queue has an opt-out: past a depth
-bound, an agent is told the area is too busy and moves on rather than joining a
-long line.
-
-```ts
-await using claim = await ablo.tasks.claim({
-  id: 'task_123',
-  description: '...',
-  maxQueueDepth: 3, // don't join a line deeper than this
-});
-```
-
-### 6. Notify on change: without acting on stale data, without looping
-
-An agent that read a row and is about to act on it is stopped if the row moved
-since the read; it re-reads instead of acting stale. Where a genuine
-notification is wanted, it is **coalesced** (one settled signal, not a stream)
-and **relevance-gated** (only the fields a decision depends on can wake the
-agent). A fast-ticking value never wakes anyone; a rarely-changing value that
-matters can push one settled signal. Same primitive, two behaviors, chosen by
-whether reacting is worth it — see the two-channel principle above.
-
-## The three layers, as a rising scale
-
-The behaviors above compose into three layers of increasing firmness. An agent
-climbs only as high as the situation needs.
-
-| Layer | Kind | What it does | Forces anything? |
-| --- | --- | --- | --- |
-| **Presence** | awareness (push) | Shows who holds what, and why, live. | No: informs only. |
-| **Stale-context** | safety (pull) | Rejects a write built on a read the row has moved past. | Yes: at write time. |
-| **Claim + queue** | reservation (push) | Reserves a row across a slow gap; contenders take turns. | Yes: mutual exclusion. |
-
-Most work is a quick write and needs only the safety layer. An agent reaches for
-a claim only when it will *hold* a row across a slow gap (read → LLM → write) —
-the case where taking a turn beats colliding.
-
-## What's shipped, and the one open point
-
-One piece of the fleet story that once read as future design work is already
-built; one is genuinely still open. Both are called out so neither is misjudged.
-
-1. **Rich work surfaced at reject time — shipped.** A claim carries a single
-   `description` (behavior 2) as a first-class field on the wire. It rides the
-   presence broadcast, comes back inside the rejection's holder summary
-   (`heldByClaim`), and the SDK's `formatClaimedErrorMessage` renders it into the
-   `AbloClaimedError`. So "no" already becomes "no, because someone is rewriting
-   the risk section" (behavior 4) — the piece that prevents the wasteful blind
-   retry works today.
-
-2. **Coalesced, relevance-gated notify — open.** The anti-loop guarantee
-   (behavior 6) depends on the awareness channel being coalesced and gated by
-   relevance, and on hot data staying on the pull side. This is the sharp one,
-   and it is the one not yet built: what exists is the write-time pull guard
-   (`onStale`) and operation-level batching, not a coalesced, relevance-gated
-   *push* on the presence broadcast. Get it wrong and a millisecond-ticking field
-   storms the fleet. The rule to hold: an agent is *rejected at write time* on
-   hot data, never *subscribed-and-woken* by it.
-
-## Related
-
-- [`coordination.md`](../coordination.md) — the public claim/queue/stale-context
-  reference this note motivates.
-- [`agent-orchestration.md`](./agent-orchestration.md) — parent/child agent work
-  modeled through claimed job rows; this note is the coordination substrate under
-  it.
-- ADR 0009 (`docs/decisions/0009-claim-durability-two-reclaim-clocks.md`) — what a
-  claim survives when a holder vanishes, and why liveness can be best-effort while
-  correctness is fenced at commit.

package/docs/internal/agent-orchestration.md

@@ -1,57 +0,0 @@
-# Agent Orchestration
-
-Do not model parent and child agents as directly talking to each other over WebSocket.
-
-Model them as actors coordinating through models:
-
-```txt
-parent creates job -> child claims job -> child commits result -> parent reads result
-```
-
-The WebSocket is delivery infrastructure. The product model is shared state.
-
-## Model Shape
-
-A parent creates a job through its typed model client:
-
-```ts
-const jobId = `forecast:${runId}`;
-await ablo.agentJobs.create({
-  id: jobId,
-  idempotencyKey: `job:${runId}`,
-  data: {
-    status: 'open',
-    kind: 'forecast_report',
-    target: { model: 'weatherReports', id: 'report_stockholm', field: 'forecast' },
-  },
-});
-```
-
-The child claims the job. If another worker holds it, the claim waits fairly,
-then returns the fresh row:
-
-```ts
-await using claim = await ablo.agentJobs.claim({
-  id: jobId,
-  description: 'complete',
-  ttl: '5m',
-});
-const job = claim.data;
-
-await ablo.agentJobs.update({
-  id: job.id,
-  data: {
-    status: 'completed',
-    result: { text },
-  },
-});
-```
-
-The child commits completion through the normal `update`, which is stale-guarded
-under the held claim. The claim releases when its scope exits.
-
-The parent retrieves the job result by model ID. Later, `ablo.events` can make that reactive, but the state model does not change.
-
-## Rule
-
-Nested agents should create or complete models. They should not require a separate agent-to-agent protocol for normal work.

package/docs/internal/commit-identifiers.md

@@ -1,91 +0,0 @@
-# Commit identifiers: the two axes
-
-Maintainer reference. A commit carries several ids, and they are easy to
-conflate because they travel together and are all "some number attached to a
-write." They are not interchangeable. Each answers a different question, and
-they split cleanly along **one line**: does this id help decide whether the
-write *wins*, or does it only help *identify* the write after the fact?
-
-Keeping the two axes separate is what lets each id be reasoned about — and
-audited — on its own. This doc is the single place they sit side by side.
-
-## The line
-
-| axis | the question it answers | when it acts | if it's absent |
-|---|---|---|---|
-| **Conflict resolution** | *should this write land, given what else happened?* | at the commit chokepoint, before the row is written | the write is unguarded (last-writer-wins) |
-| **Correlation / audit** | *which write is this, and have I seen it before?* | on receipt (dedup) and after the fact (attribution) | the write still lands; you just can't dedup or trace it as precisely |
-
-A conflict-resolution id can **reject** a commit. A correlation id never does —
-at most it makes a retried commit a no-op (idempotency). Never reach for one to
-do the other's job: a correlation id can't fence a stale write, and a fence
-can't dedup a retry.
-
-## Axis 1: conflict resolution (does this write win?)
-
-Evaluated inside `executeCommit`'s transaction, atomic with the delta write.
-Three independent fences, each catching what the others can't; the full
-narrative is [ADR 0009 §6](../../../../docs/decisions/0009-claim-durability-two-reclaim-clocks.md)
-and the [coordination reference](../coordination.md).
-
-| id | wire field | persisted to | what it asserts | rejects when |
-|---|---|---|---|---|
-| **read basis** | per-op `readAt` | `sync_deltas.read_at_sync_id` | "the state I reasoned **from**": a version watermark | the row moved since `readAt` (version-CAS), under `onStale: 'reject'` |
-| **fencing token** | per-op `fenceToken` | `sync_deltas.fence_token` **and** `claim_fence_watermark.fence_token` | "the lease generation I was authorized **at**": a monotonic per-entity high-water | the token is below the entity's persisted high-water: a lapsed holder writing after its successor already claimed, wrote, and released |
-| **claim / lease** | `claimId`, `heldBy` on the `WireClaim` | the coordination store (Redis), not `sync_deltas` | "I hold this row right now": live mutual exclusion | a non-holder writes a row another participant holds |
-
-`onStale` (`notify` / `reject` / `overwrite`) is **not** an id — it's the
-disposition that decides what a stale `readAt` *does*. It rides with the read
-basis but is policy, not evidence, so it isn't persisted.
-
-Why the token is a distinct id from `readAt`, and not just reused `sync_id`:
-`readAt` advances on every **write** and asserts *from what data*; the token
-advances on every **grant** and asserts *at what lease generation*. Their events
-differ, so one can't stand in for the other — a lapsed holder that skips
-version-CAS (no `readAt`, a blind write) is invisible to the read basis but
-still carries a stale token. That is precisely fence (c) closing what (a) can't.
-The reasoning in full lives in
-[the fencing-token scope doc](../../../../docs/plans/claim-fencing-token-option-b-scope.md).
-
-## Axis 2: correlation / audit (which write is this?)
-
-Never decides a conflict. These are how a write is recognized — as a duplicate,
-as your own echo, or as one row in a signed history.
-
-| id | wire field | persisted to | purpose |
-|---|---|---|---|
-| **idempotency key** | batch `clientTxId` (public alias `idempotencyKey`) | dedup ledger keyed by it | a retried batch commits **once**: the second attempt is recognized and folded to a no-op, not re-applied |
-| **per-op transaction id** | per-op `transactionId` | `sync_deltas.transaction_id` | echo detection: the broadcast delta arrives at the originating client carrying the **same** id its queue marked pending, so it reconciles its optimistic write instead of double-applying |
-| **sync id** | assigned server-side (`next_sync_id`) | `sync_deltas.id` | the monotonic total order: the serialization order every reader tails and every `readAt` names. It is *assigned*, never client-supplied |
-| **attribution** | actor / capability / delegation on the frame | `sync_deltas` actor columns + the signed audit chain | who acted, on whose behalf, under which key: the [audit log](../audit.md)'s who/when |
-
-The batch key and the per-op id are deliberately separate: a multi-row commit is
-**one** idempotent unit (one `clientTxId`) made of **many** individually-echoable
-ops (each its own `transactionId`). Collapsing them would make echo detection
-batch-coarse and break optimistic reconciliation for multi-op commits.
-
-## The evidence tuple on a `sync_deltas` row
-
-Both axes leave their mark on the delta, which is what makes a delta a complete,
-self-describing audit record — you can reconstruct the full justification of a
-write from the row alone, never from a live lease that has since vanished:
-
-- **who:** `actor_id` / `capability_id` (+ the signed chain)
-- **what:** `data` / `previous_data`
-- **when:** `id` (`sync_id`) / `created_at`
-- **from what known state:** `read_at_sync_id` (the read basis)
-- **at what lease generation:** `fence_token` (the token the commit fenced)
-- **as which client operation:** `transaction_id` (echo identity)
-
-`read_at_sync_id` and `fence_token` are companions: the first records the data
-version the write reasoned against, the second the lease generation it was
-authorized at. Both are `NULL` when the write carried none (an unclaimed write, a
-human `user` committer exempt under Law 7, or a legacy row) — **never fabricated
-server-side**. The evidence derives only from what the write actually presented,
-so the audit row can't drift from what the fence enforced.
-
-## One-line test for "which id is this?"
-
-> If removing it could turn an accepted commit into a rejected one, it's
-> **Axis 1**. If removing it only costs you dedup, echo reconciliation, or
-> traceability — while the write still lands — it's **Axis 2**.

package/docs/internal/concurrency-open-decisions.md

@@ -1,37 +0,0 @@
-# Concurrency Convention: Open Decisions
-
-Maintainer notes for [`concurrency-convention.md`](../concurrency-convention.md).
-These are decisions the team has deliberately not made yet. They change public
-behaviour, so they are tracked here rather than in the public contract, where an
-unmade decision reads as an unsettled guarantee.
-
-## Default disposition for agents
-
-Should an agent-participant guarded write default to `notify` (philosophy
-aligned: surface, do not overwrite) instead of `reject` (back-compat)?
-
-The trade-off is alignment against a behaviour change for existing agent
-callers. Today a guarded write with `readAt` but no `onStale` defaults to
-`reject` for every participant kind.
-
-## Batch premises through the policy seam
-
-Should premise conflicts also pass through `ConflictPolicy`, or stay on the
-direct `onStale` mapping?
-
-Routing them through the seam requires a group-aware conflict shape, because a
-batch premise can name a sync group rather than a row. Custom `ConflictPolicy`
-functions currently see write-target conflicts only (`stale_context` /
-`claim_held`); batch-premise conflicts resolve directly through each entry's
-`onStale`.
-
-## The serializability floor
-
-A batch premise is a sound check, not a full precedence-graph guarantee: it
-catches only what the caller declared. A caller that declares nothing gets no
-check at all, because write-target checking needs a `readAt` to check against,
-and a plain write is last-writer-wins.
-
-The floor is therefore zero, and closing that gap is the subject of ADR 0018.
-The public page states the resulting behaviour as a limit; the framing of it as
-a gap to be closed belongs here.