@ontrails/cloudflare 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,160 @@
+# @ontrails/cloudflare
+
+## 0.2.0
+
+### Patch Changes
+
+- [`b3ddf91`](https://github.com/outfitter-dev/trails/commit/b3ddf918ada8211f44983512e2bbdfbc5b66d722): Prepare the first normal Trails release at `0.2.0` on `latest`, replacing the unpublished 1.0.0 source release. The target advances the original `0.1.0` source minor, which was never published under the current package names. Public packages remain in lockstep. Update consumer installation guidance and provide a temporary manifest bridge for old 1.0 beta sources. Published beta versions remain unchanged; minor 0.x releases may carry documented breaking changes.
+
+  The `1.0.0` section retained below records an unpublished preparation, not an npm release. Its accumulated changes are included in `0.2.0`; the section remains as source history alongside the published beta entries.
+
+## 1.0.0
+
+### Minor Changes
+
+- [`9874e0b`](https://github.com/outfitter-dev/trails/commit/9874e0bb034c0f98edeb19833d9d3519c2a07a4c): Add `@ontrails/cloudflare/d1`, an env-bound Cloudflare D1 store resource for `@ontrails/store` definitions. The new subpath exports `cloudflareD1` and `connectD1`, supports the backend-agnostic store accessor contract (`get`, `list`, `upsert`, `remove`), versioned-table optimistic concurrency, fixture/mock seeding, store-derived write signals, Miniflare-backed conformance tests, and Worker env-bridge integration.
+
+  `@ontrails/core` and `@ontrails/store` no longer require the Bun global for signal fire ids or late-bound store signal tokens, so store definitions and store-derived signal emission work inside Worker modules. `@ontrails/warden` now treats `cloudflareD1` as a required Cloudflare public export with `@example` coverage.
+
+- [`1e64ee7`](https://github.com/outfitter-dev/trails/commit/1e64ee7bc270901486c5bb51ac38bf045c924adc): Add first-class queue activation sources with `queue()` in `@ontrails/core`.
+  Queue sources validate their runtime queue name and parse contract, project the
+  queue name into durable topo facts, participate in activation input
+  compatibility, and block established outputs when malformed.
+
+  Add `@ontrails/cloudflare/queues` with `cloudflareQueue`, `createMemoryQueue`,
+  and `createQueueHandler`. Cloudflare Workers now expose both `fetch` and
+  `queue` entrypoints from `createWorkersHandler`, resolve env-bound resources for
+  queue-activated trails, acknowledge successful/skipped/cancelled messages, and
+  acknowledge traced non-retryable Trails errors so permanently invalid messages
+  do not churn through the queue. Failures explicitly marked retryable enter
+  Cloudflare's retry and DLQ flow, with rate-limit delays preserved.
+
+  `@ontrails/warden` now treats queue activation sources as materialized and
+  requires `cloudflareQueue` public export example coverage.
+
+- [`4086b5b`](https://github.com/outfitter-dev/trails/commit/4086b5b2f01b24660924fd8b667523f38caaed29): Add `@ontrails/cloudflare/r2`, an env-bound Cloudflare R2 bucket resource with
+  `cloudflareR2`, `createMemoryR2`, and `r2ObjectToBlobRef`. The resource
+  materializes Worker `r2_buckets` bindings through the shared env bridge, records
+  Cloudflare lock overlay facts, carries an in-memory object mock for
+  configuration-free tests, and documents the supported object operations plus
+  streaming/metadata boundaries.
+
+  `@ontrails/warden` now treats `cloudflareR2` as a required Cloudflare public
+  export with `@example` coverage.
+
+- [`a105127`](https://github.com/outfitter-dev/trails/commit/a105127e5662ed9a6c245125f791fb0182da3f5e): Add the `@ontrails/cloudflare` adapter collection with its first two service subpaths. `@ontrails/cloudflare/workers` exports `createWorkersHandler`, a materializer producing the `{ fetch(request, env, ctx) }` Worker export on the shared HTTP fetch kernel, with an env bridge that re-resolves env-bound resources whenever a new Worker `env` arrives so no resource instance serves a request with a stale env. `@ontrails/cloudflare/kv` exports `cloudflareKv`, a resource definition wrapping a KV namespace binding (`get`/`put`/`delete`/`list` with TTL options) plus an in-memory `createMemoryKv` mock so `testAll` runs configuration-free.
+
+  `@ontrails/core` now guards the default trail context fields: `requestId` falls back to `crypto.randomUUID()` when the `Bun` global is absent, and `cwd`/`env` fall back to `'/'`/`{}` when `process` is absent, so trail execution works on runtimes like Cloudflare Workers.
+
+  `@ontrails/warden` registers the `@ontrails/cloudflare` public barrel in the repo-local `public-export-example-coverage` policy, requiring `@example` TSDoc coverage on `createWorkersHandler` and `cloudflareKv`.
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+- [`cc169e2`](https://github.com/outfitter-dev/trails/commit/cc169e2a9b580036b0c6e4ce77d396db6a34f830): Add `cloudflareOverlay`, the first lock overlay overlay: it derives the app's env-bound resources into `overlays.cloudflare` (wrangler binding name per resource) when the app exports it via `trailsOverlays` and runs `trails compile`.
+
+### Patch Changes
+
+- [`6b75a46`](https://github.com/outfitter-dev/trails/commit/6b75a46ab6210237d306cceade833bf9ce6e7431): The core barrel is now execution-portable: no eager `bun:`/`node:` builtin imports remain on its module graph (TRL-1198). `trails-db`, workspace discovery, and path security load `bun:sqlite`, `node:fs`, `node:os`, and `node:path` lazily through `process.getBuiltinModule` at first use, and signal payload summaries plus per-project store keys use a pure SHA-256 (output-identical to `node:crypto`). A Worker bundle no longer needs a `bun:sqlite` stub plugin or the `nodejs_compat` flag to serve trails; the Cloudflare adapter's miniflare lane now bundles without externals and boots workerd without `nodejs_compat` as the structural regression gate, and its README stub instructions are replaced with the portable posture. Tooling helpers throw a clear `InternalError` naming the missing builtin when called on runtimes without it.
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.50
+
+## 1.0.0-beta.49
+
+## 1.0.0-beta.48
+
+## 1.0.0-beta.47
+
+## 1.0.0-beta.46
+
+## 1.0.0-beta.45
+
+## 1.0.0-beta.44
+
+### Patch Changes
+
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.43
+
+### Minor Changes
+
+- [`88a6a62`](https://github.com/outfitter-dev/trails/commit/88a6a62a9e9e230ca6d368fa78dc3ece6c816204): Complete the v1 classification-first cutover from projection/project vocabulary
+  to derive/derived for contract-owned fact production and render/rendered for
+  surface presentation. Public type, helper, rule, relation, and report names move
+  without compatibility aliases; ordinary repository/project nouns remain
+  explicit preserves or structured review inventory.
+
+## 1.0.0-beta.42
+
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`9874e0b`](https://github.com/outfitter-dev/trails/commit/9874e0bb034c0f98edeb19833d9d3519c2a07a4c): Add `@ontrails/cloudflare/d1`, an env-bound Cloudflare D1 store resource for `@ontrails/store` definitions. The new subpath exports `cloudflareD1` and `connectD1`, supports the backend-agnostic store accessor contract (`get`, `list`, `upsert`, `remove`), versioned-table optimistic concurrency, fixture/mock seeding, store-derived write signals, Miniflare-backed conformance tests, and Worker env-bridge integration.
+
+  `@ontrails/core` and `@ontrails/store` no longer require the Bun global for signal fire ids or late-bound store signal tokens, so store definitions and store-derived signal emission work inside Worker modules. `@ontrails/warden` now treats `cloudflareD1` as a required Cloudflare public export with `@example` coverage.
+
+- [`1e64ee7`](https://github.com/outfitter-dev/trails/commit/1e64ee7bc270901486c5bb51ac38bf045c924adc): Add first-class queue activation sources with `queue()` in `@ontrails/core`.
+  Queue sources validate their runtime queue name and parse contract, project the
+  queue name into durable topo facts, participate in activation input
+  compatibility, and block established outputs when malformed.
+
+  Add `@ontrails/cloudflare/queues` with `cloudflareQueue`, `createMemoryQueue`,
+  and `createQueueHandler`. Cloudflare Workers now expose both `fetch` and
+  `queue` entrypoints from `createWorkersHandler`, resolve env-bound resources for
+  queue-activated trails, acknowledge successful/skipped/cancelled messages, and
+  acknowledge traced non-retryable Trails errors so permanently invalid messages
+  do not churn through the queue. Failures explicitly marked retryable enter
+  Cloudflare's retry and DLQ flow, with rate-limit delays preserved.
+
+  `@ontrails/warden` now treats queue activation sources as materialized and
+  requires `cloudflareQueue` public export example coverage.
+
+- [`4086b5b`](https://github.com/outfitter-dev/trails/commit/4086b5b2f01b24660924fd8b667523f38caaed29): Add `@ontrails/cloudflare/r2`, an env-bound Cloudflare R2 bucket resource with
+  `cloudflareR2`, `createMemoryR2`, and `r2ObjectToBlobRef`. The resource
+  materializes Worker `r2_buckets` bindings through the shared env bridge, records
+  Cloudflare lock overlay facts, carries an in-memory object mock for
+  configuration-free tests, and documents the supported object operations plus
+  streaming/metadata boundaries.
+
+  `@ontrails/warden` now treats `cloudflareR2` as a required Cloudflare public
+  export with `@example` coverage.
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+
+## 1.0.0-beta.39
+
+### Minor Changes
+
+- [`cc169e2`](https://github.com/outfitter-dev/trails/commit/cc169e2a9b580036b0c6e4ce77d396db6a34f830): Add `cloudflareOverlay`, the first lock overlay overlay: it derives the app's env-bound resources into `overlays.cloudflare` (wrangler binding name per resource) when the app exports it via `trailsOverlays` and runs `trails compile`.
+
+### Patch Changes
+
+- [`6b75a46`](https://github.com/outfitter-dev/trails/commit/6b75a46ab6210237d306cceade833bf9ce6e7431): The core barrel is now execution-portable: no eager `bun:`/`node:` builtin imports remain on its module graph (TRL-1198). `trails-db`, workspace discovery, and path security load `bun:sqlite`, `node:fs`, `node:os`, and `node:path` lazily through `process.getBuiltinModule` at first use, and signal payload summaries plus per-project store keys use a pure SHA-256 (output-identical to `node:crypto`). A Worker bundle no longer needs a `bun:sqlite` stub plugin or the `nodejs_compat` flag to serve trails; the Cloudflare adapter's miniflare lane now bundles without externals and boots workerd without `nodejs_compat` as the structural regression gate, and its README stub instructions are replaced with the portable posture. Tooling helpers throw a clear `InternalError` naming the missing builtin when called on runtimes without it.
+
+## 1.0.0-beta.38
+
+### Minor Changes
+
+- [`a105127`](https://github.com/outfitter-dev/trails/commit/a105127e5662ed9a6c245125f791fb0182da3f5e): Add the `@ontrails/cloudflare` adapter collection with its first two service subpaths. `@ontrails/cloudflare/workers` exports `createWorkersHandler`, a materializer producing the `{ fetch(request, env, ctx) }` Worker export on the shared HTTP fetch kernel, with an env bridge that re-resolves env-bound resources whenever a new Worker `env` arrives so no resource instance serves a request with a stale env. `@ontrails/cloudflare/kv` exports `cloudflareKv`, a resource definition wrapping a KV namespace binding (`get`/`put`/`delete`/`list` with TTL options) plus an in-memory `createMemoryKv` mock so `testAll` runs configuration-free.
+
+  `@ontrails/core` now guards the default trail context fields: `requestId` falls back to `crypto.randomUUID()` when the `Bun` global is absent, and `cwd`/`env` fall back to `'/'`/`{}` when `process` is absent, so trail execution works on runtimes like Cloudflare Workers.
+
+  `@ontrails/warden` registers the `@ontrails/cloudflare` public barrel in the repo-local `public-export-example-coverage` policy, requiring `@example` TSDoc coverage on `createWorkersHandler` and `cloudflareKv`.

package/README.md

@@ -0,0 +1,269 @@
+# @ontrails/cloudflare
+
+The Cloudflare adapter collection for Trails. One package, one subpath per Cloudflare service, each connecting a service to the Trails primitive it naturally serves:
+
+| Subpath | Serves | Status |
+| --- | --- | --- |
+| `@ontrails/cloudflare/workers` | HTTP surface materializer (fetch handler) | ✅ |
+| `@ontrails/cloudflare/kv` | Key-value resource | ✅ |
+| `@ontrails/cloudflare/d1` | D1-backed store resource | ✅ |
+| `@ontrails/cloudflare/queues` | Queue producer resource + consumer materializer | ✅ |
+| `@ontrails/cloudflare/r2` | R2 blob/object resource | ✅ |
+
+Adapter composition doctrine applies throughout: subpaths take primitive-authored declarations (a resource definition, a surface config) and never shadow authoring verbs. Bindings arrive ambiently on the Worker `env`, so runtime dependencies are near-zero.
+
+## `/workers` — the Worker materializer
+
+`createWorkersHandler(graph, options)` produces the Worker export for Cloudflare runtime entrypoints. Its `fetch(request, env, ctx)` member delegates to the shared HTTP fetch kernel from `@ontrails/http` — the same kernel behind the Bun and Hono surfaces, so routes, validation, error rendering, and webhook handling behave identically. Its `queue(batch, env, ctx)` member dispatches first-class core `queue()` activation sources through the `/queues` materializer.
+
+```ts
+// src/worker.ts
+import { createWorkersHandler } from '@ontrails/cloudflare/workers';
+import { graph } from './app.js';
+
+export default createWorkersHandler(graph, { basePath: '/api' });
+```
+
+Options mirror the other HTTP surfaces: `basePath`, `createContext`, `layers`, `maxJsonBodyBytes`, `resolvePermit`, plus include/exclude/intent filtering. `resources` accepts either a static override map or a function of the Worker env:
+
+```ts
+export default createWorkersHandler(graph, {
+  resources: (env) => ({ audit: createAuditClient(env['AUDIT_URL']) }),
+});
+```
+
+### The env bridge
+
+Worker bindings (KV, D1, R2, queues) live on `env`, which arrives per request — they cannot be captured at module init. The bridge closes that gap once, for every subpath in this collection:
+
+1. A subpath authors an ordinary `resource()` definition and registers an `EnvBindingSpec` for it (`registerEnvBinding(definition, { binding, fromEnv })`).
+2. `createWorkersHandler` walks the declared resources of the trails the surface actually exposes (honoring `include`/`exclude`/`intent`, and including fork-version resources), and for each env-bound definition resolves `env[binding]` through `fromEnv` into a resource override. Explicitly overridden resource IDs skip env resolution entirely, so an override never requires its binding.
+3. The kernel handler is materialized per env identity. The Workers runtime keeps `env` stable within an isolate, so steady-state requests reuse one materialization — but any request carrying a different env object re-resolves every env-bound resource before it executes.
+
+Because resource overrides are checked before core's singleton resource cache, no resource instance can serve a request with a stale env. This guarantee has a dedicated regression test (`src/workers/__tests__/env-bridge.test.ts`).
+
+Missing or mistyped bindings fail the request with a redacted 500 and log full diagnostics to the Worker log, naming the binding and the resource that needed it.
+
+### Runtime notes
+
+- The core execution path is runtime-portable (TRL-1198): `@ontrails/core` loads `bun:sqlite` and `node:` builtins lazily at first use, so a Worker bundle needs no stub plugin and no `nodejs_compat` flag to serve trails. The integration lane (`src/__tests__/miniflare.test.ts`) bundles the demo Worker with no externals and boots workerd without `nodejs_compat` as the structural regression gate.
+- Tooling helpers on the core barrel (the trails-db store, workspace discovery) still require a Bun or Node runtime when actually called; on workerd they throw a clear `InternalError` naming the missing builtin instead of poisoning the module graph.
+- Explicit `resources` overrides win over env-bound resolution, which is how tests substitute fakes.
+
+## `/kv` — the key-value resource
+
+`cloudflareKv(id, { binding })` authors a resource wrapping a KV namespace binding. Trails declare it with `resources: [...]` and read it with `flags.from(ctx)` — the standard accessor pattern.
+
+```ts
+import { cloudflareKv } from '@ontrails/cloudflare/kv';
+import { trail, Result } from '@ontrails/core';
+import { z } from 'zod';
+
+const flags = cloudflareKv('flags', { binding: 'FLAGS' });
+
+const showFlag = trail('flag.show', {
+  implementation: async (input, ctx) => {
+    const value = await flags.from(ctx).get(input.key);
+    return Result.ok({ value });
+  },
+  input: z.object({ key: z.string() }),
+  intent: 'read',
+  output: z.object({ value: z.string().nullable() }),
+  resources: [flags],
+});
+```
+
+The client surface is `get`/`put`/`delete`/`list`, with TTL options on `put` (`expirationTtl` in seconds, or an absolute `expiration` Unix timestamp) and prefix/limit/cursor pagination on `list`. A real `KVNamespace` binding satisfies the shape structurally, so the env bridge passes it through unchanged.
+
+Declare the binding in wrangler config:
+
+```toml
+kv_namespaces = [
+  { binding = "FLAGS", id = "<namespace-id>" }
+]
+```
+
+### Testing with the mock
+
+Every `cloudflareKv` resource carries an in-memory mock factory, so `testAll(app)` runs configuration-free — no Cloudflare account, no wrangler:
+
+```ts
+import { testAll } from '@ontrails/testing';
+import { graph } from '../src/app.js';
+
+testAll(graph);
+```
+
+`createMemoryKv()` is also exported directly for hand-rolled tests, with an injectable clock for TTL assertions. Two documented divergences from the real binding: the mock does not enforce KV's 60-second minimum TTL, and when both `expiration` and `expirationTtl` are passed the mock prefers `expirationTtl` where the real binding rejects the combination.
+
+## `/d1` — the store resource
+
+`cloudflareD1(definition, { binding, id })` binds an `@ontrails/store` definition to a Cloudflare D1 database. Trails declare the returned resource and use the standard store accessors (`get`, `list`, `upsert`, `remove`) through `db.from(ctx)`.
+
+```ts
+import { cloudflareD1 } from '@ontrails/cloudflare/d1';
+import { trail, Result } from '@ontrails/core';
+import { store } from '@ontrails/store';
+import { z } from 'zod';
+
+const definition = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({ id: z.string(), body: z.string() }),
+  },
+});
+
+const db = cloudflareD1(definition, { binding: 'DB', id: 'notes.store' });
+
+const saveNote = trail('note.save', {
+  implementation: async (input, ctx) =>
+    Result.ok(await db.from(ctx).notes.upsert(input)),
+  input: z.object({ id: z.string(), body: z.string() }),
+  intent: 'write',
+  output: z.object({ id: z.string(), body: z.string() }),
+  resources: [db],
+});
+```
+
+Declare the binding in wrangler config:
+
+```toml
+d1_databases = [
+  { binding = "DB", database_name = "my-worker", database_id = "<database-id>" }
+]
+```
+
+The first implementation stores one JSON entity per D1 row (`id TEXT PRIMARY KEY`, `entity TEXT NOT NULL`, nullable `version INTEGER`) in adapter-owned tables prefixed by the resource id. It preserves the backend-agnostic store contract, including generated identity fields, `createdAt`/`updatedAt` generation, versioned-table optimistic concurrency (`ConflictError` on stale `version`), fixture/mock seeding, and store-derived `created`/`updated`/`removed` signals.
+
+Capability boundaries are explicit:
+
+- `indexed`/`indexes`, `references`, and `search` stay store metadata for this driver; the D1 adapter does not create secondary indexes, foreign keys, or FTS tables yet.
+- `list(filters)` performs simple equality filtering in the adapter after reading table rows, then applies `offset`/`limit`.
+- `connectD1(definition, database, options)` is exported for tests and advanced runtimes that already hold a D1 binding. Schema creation and optional runtime `seed` run lazily before the first accessor call so the Workers env bridge can resolve resources synchronously. Runtime seed rows require explicit stable identities and are insert-only, so rematerializing a Worker cannot overwrite user edits.
+
+Every `cloudflareD1` resource carries an in-memory mock factory seeded from table fixtures or `mockSeed`, so `testAll(app)` remains configuration-free. Miniflare can provide a real D1 binding for local integration tests without a Cloudflare account.
+
+## `/r2` — blob/object resource
+
+`cloudflareR2(id, { binding })` authors a resource wrapping a Cloudflare R2 bucket binding. Trails declare it with `resources: [...]` and use `bucket.from(ctx)` to call the Worker binding's object operations (`put`, `get`, `head`, `delete`, and `list`).
+
+```ts
+import {
+  NotFoundError,
+  Result,
+  blobRefSchema,
+  trail,
+} from '@ontrails/core';
+import { cloudflareR2, r2ObjectToBlobRef } from '@ontrails/cloudflare/r2';
+import { z } from 'zod';
+
+const assets = cloudflareR2('assets', { binding: 'ASSETS' });
+
+const readAsset = trail('asset.read', {
+  implementation: async (input, ctx) => {
+    const object = await assets.from(ctx).get(input.key);
+    if (object === null || !('body' in object)) {
+      return Result.err(new NotFoundError(`Asset "${input.key}" not found`));
+    }
+    return Result.ok(r2ObjectToBlobRef(object));
+  },
+  input: z.object({ key: z.string() }),
+  intent: 'read',
+  output: blobRefSchema,
+  resources: [assets],
+});
+```
+
+Declare the binding in wrangler config:
+
+```toml
+[[r2_buckets]]
+binding = "ASSETS"
+bucket_name = "my-assets"
+```
+
+The resource surface follows the R2 Worker binding structurally. A real R2 bucket binding passes through unchanged, including Cloudflare's conditional operation behavior where `get()` can return metadata without a body and `put()` can return `null` when a precondition fails. `r2ObjectToBlobRef(object)` is the small bridge from a fetched R2 object body to core's `BlobRef` binary-output contract; the HTTP and MCP surfaces already know how to render `blobRefSchema`.
+
+Capability boundaries are explicit:
+
+- The adapter does not expose public bucket URLs, signed URLs, S3 clients, multipart upload helpers, or object-event subscriptions.
+- The in-memory mock implements object bytes, metadata, `put`, `get`, `head`, `delete`, and lexicographic `list` pagination with prefix/cursor/delimiter grouping. It accepts SSE-C option shapes for binding compatibility but does not encrypt objects, validate keys, or emit `ssecKeyMd5`; it also does not model R2 preconditions, range reads, checksums, storage-tier billing behavior, or multipart uploads.
+- For raw HTTP upload/download routes, keep authorization in your own trails or surface layer; the R2 resource only materializes the bucket binding.
+
+Every `cloudflareR2` resource carries an in-memory mock (`createMemoryR2`) so object trails work in `testAll(app)` and focused unit tests without a Cloudflare account or wrangler.
+
+## `/queues` — Queue producer and consumer support
+
+`cloudflareQueue(id, { binding })` authors a resource wrapping a Cloudflare Queue producer binding. Trails declare it with `resources: [...]` and send messages with `jobs.from(ctx).send(...)` or `sendBatch(...)`.
+
+```ts
+import { cloudflareQueue } from '@ontrails/cloudflare/queues';
+import { Result, queue, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+const jobs = cloudflareQueue<{ id: string }>('jobs', { binding: 'JOBS' });
+
+const enqueueJob = trail('job.enqueue', {
+  implementation: async (input, ctx) => {
+    await jobs.from(ctx).send({ id: input.id });
+    return Result.ok({ queued: true });
+  },
+  input: z.object({ id: z.string() }),
+  output: z.object({ queued: z.boolean() }),
+  resources: [jobs],
+});
+```
+
+Queue consumers are authored with the core `queue()` activation source and materialized by `createWorkersHandler`:
+
+```ts
+const consumeJob = trail('job.consume', {
+  implementation: async (input) => Result.ok({ processed: input.id }),
+  input: z.object({ id: z.string() }),
+  on: [
+    queue('queue.jobs', {
+      queue: 'jobs',
+      parse: z.object({ id: z.string() }),
+    }),
+  ],
+  output: z.object({ processed: z.string() }),
+});
+```
+
+Declare the producer binding and consumer in wrangler config:
+
+```toml
+[[queues.producers]]
+binding = "JOBS"
+queue = "jobs"
+
+[[queues.consumers]]
+queue = "jobs"
+max_batch_size = 10
+max_retries = 3
+dead_letter_queue = "jobs-dlq"
+```
+
+The consumer materializer acknowledges each message after all matching Trails queue consumers succeed, skip by `where`, or return `CancelledError`. It also traces and acknowledges non-retryable Trails errors, including validation failures, so permanently invalid messages do not churn through the queue. Errors explicitly marked retryable call `message.retry(...)`; Cloudflare's retry and dead-letter configuration decides when a retried message moves to a DLQ. `RateLimitError.retryAfter` is passed through as `delaySeconds`.
+
+Every `cloudflareQueue` resource carries an in-memory mock (`createMemoryQueue`) so producer trails work in `testAll(app)` and unit tests can inspect sent messages. The local Worker-env regression test exercises a queue-activated trail using KV through the env bridge; the Miniflare lane remains focused on HTTP/webhook/KV/D1 until its queue harness is wired in this repo.
+
+## Local integration testing
+
+Integration runs are local-first via [miniflare](https://miniflare.dev) (workerd in-process): the test lane bundles a demo Worker with `Bun.build`, boots it with real KV and D1 bindings, and exercises HTTP, webhook, KV, and D1 store routes. Queue producer/consumer behavior and R2 object behavior are covered by focused structural tests under `src/queues/__tests__/queues.test.ts` and `src/r2/__tests__/r2.test.ts`. Real-account deploys are manual and never CI-required.
+
+## Lock facts
+
+`cloudflareOverlay` (root export) is the adapter's lock overlay overlay: an `Overlay` pairing the `cloudflare` namespace with an elevated zod fact schema and a deterministic derive over the app's topo. It records every env-bound resource as `{ binding, resourceId }` so the committed `trails.lock` documents which wrangler bindings the app depends on.
+
+An app opts in by exporting the overlay list next to its topo, then compiling:
+
+```ts
+// src/app.ts
+import { cloudflareOverlay } from '@ontrails/cloudflare';
+
+export const app = topo('my-worker', { readFlag });
+export const trailsOverlays = [cloudflareOverlay];
+```
+
+`trails compile` validates the derived facts against the schema and embeds them as `overlays.cloudflare`; `trails wayfind --overlay cloudflare` reads them back. Toolchains that predate an overlay's namespace preserve it byte-for-byte — adding a new fact family never edits the lock schema or graph type.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ontrails/cloudflare",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "adapters/cloudflare"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./workers": "./src/workers/index.ts",
+    "./kv": "./src/kv/index.ts",
+    "./d1": "./src/d1/index.ts",
+    "./r2": "./src/r2/index.ts",
+    "./queues": "./src/queues/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test --max-concurrency=1",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@ontrails/adapter-kit": "^0.2.0",
+    "@ontrails/testing": "^0.2.0",
+    "miniflare": "^4.20250617.4"
+  },
+  "peerDependencies": {
+    "@ontrails/http": "^0.2.0",
+    "@ontrails/store": "^0.2.0",
+    "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapter": {
+      "target": "http"
+    },
+    "adapters": {
+      "./d1": {
+        "target": "store"
+      }
+    }
+  }
+}