@abloatai/ablo 0.36.0 → 0.37.1

package/docs/integration-guide.md

@@ -30,6 +30,7 @@ The normal integration is one client:
 
 ```ts
 import Ablo from '@abloatai/ablo';
+import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 ```
 
@@ -158,7 +159,7 @@ For rows that don't carry `organization_id` themselves but inherit tenancy via a
 foreign key, set `policy: { by: 'parent', fk: '<fk>', parent: '<parentTable>' }`.
 For genuinely global/reference data, `policy: { by: 'none' }`. ⚠ `by: 'none'`
 exposes the whole table cross-tenant, so it's an explicit, named branch — never a
-falsy flag. See `packages/sync-engine/src/schema/model.ts` for the full option set.
+falsy flag. See `packages/transaction/src/schema/model.ts` for the full option set.
 
 ## 2. Create The Client
 
@@ -220,8 +221,18 @@ const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 export async function POST() {
   const session = await auth(); // your own auth — returns the signed-in user
-  const { token } = await sync.sessions.create({ user: { id: session.userId } });
-  return Response.json({ token });
+  const { token, expiresAt } = await sync.sessions.create({
+    user: { id: session.userId },
+    can: { tasks: ['read', 'update'] },
+  });
+  return Response.json(
+    credentialEndpointSuccessSchema.parse({
+      token,
+      expiresAt,
+      credentialKind: 'ephemeral',
+    }),
+    { headers: { 'Cache-Control': 'no-store' } },
+  );
 }
 ```
 
@@ -255,8 +266,8 @@ refreshes before expiry.
 ## 3. Read State
 
 Reads come in two flavors, and you pick based on whether you can wait.
-`retrieve({ id })` and `list({ where })` hit the server (and hydrate the local
-store) — they're async, so you `await` them. `get(id)` (positional),
+`get({ id })` and `list({ where })` hit the server (and hydrate the local
+store) — they're async, so you `await` them. `local.get(id)`,
 `local.list({ where })`, and `local.count({ where })` read the already-synced local
 graph synchronously, so they're the ones you call in render — and the ones you
 use inside a `useAblo` selector, never the async `retrieve`/`list`.
@@ -267,15 +278,15 @@ and waits.
 ```ts
 await ablo.ready();
 
-const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
 if (!report) throw new Error('report not found');
 ```
 
-Use `local.retrieve`, `local.list`, and `local.count` for synchronous local-graph reads after
+Use `local.get`, `local.list`, and `local.count` for synchronous local-graph reads after
 data has synced.
 
 ```ts
-const report = ablo.weatherReports.local.retrieve('report_stockholm');
+const report = ablo.weatherReports.local.get('report_stockholm');
 const activeReports = ablo.weatherReports.local.list({
   where: { projectId: 'proj_123' },
   filter: (report) => report.status !== 'ready',
@@ -296,7 +307,7 @@ export function ReportRow({
 }: {
   report: { id: string; location: string; status: string };
 }) {
-  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.get(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
 
   return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
@@ -387,7 +398,7 @@ The migration can be gradual:
 
 1. Declare schema for one model, such as `reports`.
 2. Keep existing server loads for first paint.
-3. Add `useAblo((ablo) => ablo.weatherReports.local.retrieve(id)) ?? serverReport` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.local.get(id)) ?? serverReport` for live rows.
 4. Add one Data Source endpoint that calls the existing service layer.
 5. Move one mutation button from `fetch('/api/reports/...')` to `ablo.weatherReports.update(...)`.
 6. Add an outbox/events path for writes that still happen outside Ablo.
@@ -516,9 +527,9 @@ them.
 
 | Method                                 | Use it for                                                                       |
 | -------------------------------------- | -------------------------------------------------------------------------------- |
-| `retrieve({ id })`                     | Async read of one row from the server (await it).                                |
+| `get({ id })`                     | Async read of one row from the server (await it).                                |
 | `list({ where })`                      | Async read of many rows from the server (await it).                              |
-| `get(id)`                              | Synchronous local read of one synced row (positional id; use in render).         |
+| `local.get(id)`                   | Synchronous local read of one synced row (use in render).                        |
 | `local.list({ where })`                | Synchronous local read of many synced rows.                                      |
 | `local.count({ where })`               | Synchronous local count of synced rows.                                          |
 | `create({ data, id? })`                | Create through the model client.                                                 |
@@ -528,5 +539,5 @@ them.
 | `claim({ id, description?, ttl? })`    | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
 
 Keep first integrations on the model methods above. Every mutation and
-server-read verb takes one options object; only the synchronous `get(id)` stays
+server-read verb takes one options object; the synchronous `local.get(id)` stays
 positional.

package/docs/internal/README.md

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

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

@@ -0,0 +1,58 @@
+# 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' },
+  },
+  wait: 'confirmed',
+});
+```
+
+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

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

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

package/docs/internal/data-source-reverse-channel.md

@@ -0,0 +1,150 @@
+# Data Source Reverse Channel (local-dev parity)
+
+Maintainer scoping doc. Closes the one real day-one DX gap in Data Source
+mode: the `commit`/`load`/`list` legs are inbound webhooks (Ablo → your
+endpoint), so on `localhost` they need a tunnel (ngrok/cloudflared). This
+scopes a built-in reverse channel so Data Source works on localhost the way
+managed mode already does — the Stripe-CLI `stripe listen` pattern.
+
+## The gap, precisely
+
+Data Source has two directions today:
+
+| Leg | Direction | Transport(s) today | localhost-friendly? |
+|---|---|---|---|
+| `events` (external writes → Ablo) | customer → Ablo | **poll** (`events` handler, Ablo calls you) **+ push** (`createPushQueue` → `POST /api/source/events`, you call Ablo) | ✅ yes, via push |
+| `commit` / `load` / `list` | Ablo → customer | **inbound webhook only** (`dataSource()` route) | ❌ no: needs public URL |
+
+The asymmetry is the whole bug. `events` already ships an outbound transport
+(`src/source/pushQueue.ts`), so external writes reach Ablo from localhost
+without a tunnel. The `commit`/`load`/`list` leg never got one, so Ablo Cloud
+has no way to reach a `localhost:3000` dev server.
+
+Inbound is exactly what localhost cannot receive. Managed mode has no inbound
+leg (the browser/SDK opens the only connection, outbound to Ablo), which is why
+managed mode "just works" locally and Data Source doesn't.
+
+## Prior art
+
+- **Stripe CLI `stripe listen`:** the canonical fix. The CLI opens an
+  *outbound* WebSocket to Stripe; Stripe drains webhook events down it and the
+  CLI forwards them to `localhost`. No public URL, no tunnel. We want the same
+  for the `commit`/`load`/`list` leg.
+- **Our own `createPushQueue`:** already proves the outbound-from-customer
+  pattern for the `events` leg. The reverse channel is the symmetric primitive
+  for the other direction.
+
+## Design
+
+A customer-run **source connector** dials out to Ablo Cloud and serves
+`commit`/`load`/`list` over the open connection, instead of Ablo making inbound
+HTTP calls.
+
+```
+LOCAL DEV (no public URL)
+
+  ablo client ──ws──▶ Ablo Cloud ──┐
+                                   │  (no inbound HTTP to localhost)
+  customer connector ──ws (dial-out)──▶ Ablo Cloud
+       │  drains pending commit/load/list for this source
+       ▼
+  dataSource(options)  ← UNCHANGED handler, fed a synthesized Request
+       ▼
+  local Postgres
+       │  signed response posted back up the same ws
+       └──────────────────────────────────────▶ Ablo Cloud ──ws──▶ ablo client
+```
+
+### Why it's small
+
+`dataSource(options)` is already `(request: Request) => Promise<Response>` in
+`src/source/factory.ts`. The connector does not reimplement any handler logic —
+it:
+
+1. Opens a WS to a new Ablo Cloud endpoint (e.g. `/v1/source/listen`),
+   authenticating with the project API key.
+2. Registers which source/org it serves. Ablo Cloud routes that source's
+   `commit`/`load`/`list` requests to this socket instead of the configured
+   webhook URL (when a live connector is attached).
+3. For each drained request frame: synthesize a `Request` with the same signed
+   headers Ablo would have sent, call the customer's existing `dataSource`
+   handler, and post the `Response` back up the socket.
+
+Customer-side surface is one wrapper around the handler they already wrote:
+
+```ts
+// dev only — same handler object as the deployed route
+import { dataSource, createSourceConnector } from '@abloatai/ablo';
+import { sourceOptions } from './ablo.source'; // shared with route.ts
+
+const connector = createSourceConnector({
+  apiKey: process.env.ABLO_API_KEY!,      // sk_test_*
+  handler: dataSource(sourceOptions),     // the unchanged (Request)=>Response
+});
+await connector.run(abortSignal);
+```
+
+`route.ts` (deployed) and the connector (local) share the same
+`sourceOptions` — zero handler drift.
+
+### Server side (sync-server)
+
+- New WS endpoint `/v1/source/listen`. Auth: project API key → resolves the
+  source. Reject if the key isn't `sk_test_*` unless the source explicitly
+  opts into reverse-channel for production (see "Production" below).
+- Per-source request queue. When a `commit`/`load`/`list` needs the customer
+  and a connector is attached, enqueue + drain down the socket instead of
+  POSTing the webhook URL. Reuse the same signed-envelope shape so the
+  customer handler verifies identically (`verifyAbloSourceRequest` unchanged).
+- Fallback: no connector attached → existing inbound webhook path. The
+  reverse channel is purely additive; nothing changes for deployed apps.
+
+### Signature / security
+
+- The drained frames carry the **same** Standard Webhooks signature
+  (`webhook-id`/`webhook-timestamp`/`webhook-signature`) computed with the
+  project key, so the connector verifies them through the existing
+  `verifyAbloSourceRequest` with no special-casing. The transport changes; the
+  trust model does not.
+- Gate to `sk_test_*` by default. The DB still stays canonical in the
+  customer's process; nothing here gives Ablo the `DATABASE_URL`.
+
+## Test-mode interplay
+
+`SourceRequestContext.mode` (`src/source/types.ts`) already distinguishes
+`test`/`live`. The reverse channel is the natural home for `mode: 'test'`
+traffic: a local connector attached with an `sk_test_*` key receives the
+source's test commits, runs them against the customer's test DB, and the SDK
+sees confirmed rows + fan-out exactly as in production. This is the missing
+piece that makes `sk_test_*` a complete local loop rather than just a data
+namespace.
+
+## Production stance
+
+Keep the inbound webhook as the default deployed transport — it's lower
+latency (no long-lived socket to babysit) and stateless. The reverse channel
+is primarily the **dev** affordance. A secondary, opt-in use is a
+"no-public-URL deploy" mode for customers who cannot expose an inbound
+endpoint at all (locked-down VPCs); that's a follow-on, not the initial scope.
+
+## Scope boundary (what this is NOT)
+
+- Not a generic tunnel — it forwards only signed Ablo source frames for one
+  source, not arbitrary traffic.
+- Not a change to the handler contract — `dataSource` is untouched; the
+  connector wraps its handler.
+- Not a managed-mode change — managed mode has no inbound leg and is unaffected.
+
+## Touch list (when built)
+
+- `packages/transaction/src/source/connector.ts` — `createSourceConnector`
+  (dial-out WS client; synthesize Request → existing handler → post Response).
+- `packages/transaction` export surface — expose `createSourceConnector` next to
+  `createPushQueue`.
+- `apps/sync-server` — `/v1/source/listen` WS endpoint + per-source request
+  queue + "drain to connector if attached, else webhook" branch in the source
+  dispatch path.
+- `docs/data-sources.md` — document the local-dev loop (the current docs only
+  describe the public-HTTPS webhook).
+- Tests: connector round-trip (drained commit → handler → response), signature
+  parity with the webhook path, fallback-to-webhook when no connector attached.