@ontrails/cloudflare 1.0.0-beta.39 → 1.0.0-beta.41

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @ontrails/cloudflare
 
+## 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

package/README.md

@@ -6,15 +6,15 @@ The Cloudflare adapter collection for Trails. One package, one subpath per Cloud
 | --- | --- | --- |
 | `@ontrails/cloudflare/workers` | HTTP surface materializer (fetch handler) | ✅ |
 | `@ontrails/cloudflare/kv` | Key-value resource | ✅ |
-| `/d1` | Store driver | Planned |
-| `/queues` | Activation source + outbound delivery | Planned |
-| `/r2` | Blob/object resource | Planned |
+| `@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 fetch-handler materializer
+## `/workers` — the Worker materializer
 
-`createWorkersHandler(graph, options)` produces the `{ fetch(request, env, ctx) }` Worker export by delegating to the shared HTTP fetch kernel from `@ontrails/http` — the same kernel behind the Bun and Hono surfaces, so routes, validation, error projection, and webhook handling behave identically.
+`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 projection, 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
@@ -62,7 +62,7 @@ import { z } from 'zod';
 const flags = cloudflareKv('flags', { binding: 'FLAGS' });
 
 const showFlag = trail('flag.show', {
-  blaze: async (input, ctx) => {
+  implementation: async (input, ctx) => {
     const value = await flags.from(ctx).get(input.key);
     return Result.ok({ value });
   },
@@ -96,9 +96,161 @@ 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 project `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 a real KV namespace, and exercises HTTP, webhook, and KV routes. See `src/__tests__/miniflare.test.ts`. Real-account deploys are manual and never CI-required.
+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
 
@@ -114,4 +266,4 @@ 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 --facts cloudflare` reads them back. Toolchains that predate a overlay's namespace preserve it byte-for-byte — adding a new fact family never edits the lock schema or graph type.
+`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

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/cloudflare",
-  "version": "1.0.0-beta.39",
+  "version": "1.0.0-beta.41",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -14,30 +14,39 @@
     ".": "./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",
+    "test": "bun test --max-concurrency=1",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint ./src",
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.39"
+    "@ontrails/core": "^1.0.0-beta.41"
   },
   "devDependencies": {
-    "@ontrails/adapter-kit": "^1.0.0-beta.39",
-    "@ontrails/testing": "^1.0.0-beta.39",
+    "@ontrails/adapter-kit": "^1.0.0-beta.41",
+    "@ontrails/testing": "^1.0.0-beta.41",
     "miniflare": "^4.20250617.4"
   },
   "peerDependencies": {
-    "@ontrails/http": "^1.0.0-beta.39",
+    "@ontrails/http": "^1.0.0-beta.41",
+    "@ontrails/store": "^1.0.0-beta.41",
     "zod": "^4.3.5"
   },
   "trails": {
     "adapter": {
       "target": "http"
+    },
+    "adapters": {
+      "./d1": {
+        "target": "store"
+      }
     }
   }
 }