@ontrails/cloudflare 1.0.0-beta.39

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @ontrails/cloudflare
+
+## 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,117 @@
+# @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 | ✅ |
+| `/d1` | Store driver | Planned |
+| `/queues` | Activation source + outbound delivery | Planned |
+| `/r2` | Blob/object resource | Planned |
+
+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
+
+`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.
+
+```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', {
+  blaze: 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.
+
+## 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.
+
+## 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 --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.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ontrails/cloudflare",
+  "version": "1.0.0-beta.39",
+  "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",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^1.0.0-beta.39"
+  },
+  "devDependencies": {
+    "@ontrails/adapter-kit": "^1.0.0-beta.39",
+    "@ontrails/testing": "^1.0.0-beta.39",
+    "miniflare": "^4.20250617.4"
+  },
+  "peerDependencies": {
+    "@ontrails/http": "^1.0.0-beta.39",
+    "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapter": {
+      "target": "http"
+    }
+  }
+}

package/src/env.ts

@@ -0,0 +1,275 @@
+/**
+ * The Cloudflare env bridge.
+ *
+ * Worker bindings (KV, D1, R2, queues) arrive per-request on the `env`
+ * argument of the Worker `fetch` handler. Trails resources are authored as
+ * ordinary `resource()` definitions, so this module provides the seam that
+ * connects the two: a subpath registers an {@link EnvBindingSpec} for each
+ * resource definition it authors, and the Workers materializer resolves those
+ * specs against the live `env` into per-materialization resource overrides.
+ *
+ * Overrides are re-resolved whenever a new `env` object arrives, and core
+ * resolves overrides before its singleton resource cache, so no resource
+ * instance can capture a stale env. Every Cloudflare subpath (`/kv` today,
+ * `/d1`, `/queues`, `/r2` later) consumes this one seam.
+ */
+
+import {
+  InternalError,
+  matchesTrailPattern,
+  Result,
+  filterSurfaceTrails,
+} from '@ontrails/core';
+import type {
+  AnyResource,
+  BaseSurfaceOptions,
+  ResourceOverrideMap,
+  Topo,
+  Trail,
+} from '@ontrails/core';
+
+/**
+ * The ambient Worker environment: bindings keyed by their wrangler-configured
+ * names. Values are runtime binding objects (KV namespaces, D1 databases,
+ * queues), so they are typed as `unknown` and narrowed by each subpath.
+ */
+export type WorkersEnv = Readonly<Record<string, unknown>>;
+
+/**
+ * How a resource definition materializes from the Worker env.
+ *
+ * `fromEnv` receives the raw binding value found at `env[binding]` and either
+ * narrows it into the resource instance or explains why the binding does not
+ * match the resource's expectations.
+ */
+export interface EnvBindingSpec {
+  /** The wrangler binding name to read from the Worker env. */
+  readonly binding: string;
+  /** Narrow the raw binding value into the resource instance. */
+  readonly fromEnv: (value: unknown) => Result<unknown, Error>;
+}
+
+const envBindings = new WeakMap<AnyResource, EnvBindingSpec>();
+
+/**
+ * Register an env binding for a resource definition.
+ *
+ * Called by Cloudflare subpaths (and available to apps authoring their own
+ * env-bound resources) so the Workers materializer knows how to build the
+ * resource instance from the per-request env.
+ *
+ * @example
+ * ```ts
+ * import { resource, Result } from '@ontrails/core';
+ * import { registerEnvBinding } from '@ontrails/cloudflare/workers';
+ *
+ * const queue = resource<{ send(body: string): Promise<void> }>('outbox', {
+ *   create: () => Result.err(new Error('outbox is only available on Workers')),
+ *   mock: () => ({ send: () => Promise.resolve() }),
+ * });
+ * registerEnvBinding(queue, {
+ *   binding: 'OUTBOX',
+ *   fromEnv: (value) => Result.ok(value),
+ * });
+ * ```
+ */
+export const registerEnvBinding = (
+  resourceDefinition: AnyResource,
+  spec: EnvBindingSpec
+): void => {
+  envBindings.set(resourceDefinition, spec);
+};
+
+/**
+ * Read the env binding registered for a resource definition, if any.
+ *
+ * @example
+ * ```ts
+ * import { getEnvBinding } from '@ontrails/cloudflare/workers';
+ * import { cloudflareKv } from '@ontrails/cloudflare/kv';
+ *
+ * const flags = cloudflareKv('flags', { binding: 'FLAGS' });
+ * getEnvBinding(flags)?.binding; // 'FLAGS'
+ * ```
+ */
+export const getEnvBinding = (
+  resourceDefinition: AnyResource
+): EnvBindingSpec | undefined => envBindings.get(resourceDefinition);
+
+/**
+ * Options for {@link buildEnvResourceOverrides}.
+ *
+ * `exclude`/`include`/`intent` mirror the fetch kernel's surface selection so
+ * env resolution only considers trails the surface actually exposes — a
+ * filtered-out trail's bindings are never required. `except` names resource
+ * IDs already provided explicitly, which skip env resolution entirely.
+ */
+export interface BuildEnvResourceOverridesOptions extends Pick<
+  BaseSurfaceOptions,
+  'exclude' | 'include' | 'intent'
+> {
+  /** Resource IDs already provided explicitly; env resolution skips them. */
+  readonly except?: readonly string[] | undefined;
+}
+
+const isInternalTrail = (
+  graphTrail: Trail<unknown, unknown, unknown>
+): boolean =>
+  graphTrail.visibility === 'internal' ||
+  graphTrail.meta?.['internal'] === true;
+
+const matchesAnyPattern = (
+  trailId: string,
+  patterns: readonly string[] | undefined
+): boolean =>
+  patterns !== undefined &&
+  patterns.some((pattern) => matchesTrailPattern(trailId, pattern));
+
+const passesIncludeFilter = (
+  trailId: string,
+  include: readonly string[] | undefined
+): boolean =>
+  include === undefined ||
+  include.length === 0 ||
+  matchesAnyPattern(trailId, include);
+
+/**
+ * Mirror of the fetch kernel's webhook trail eligibility: webhook consumers
+ * become HTTP routes even though `filterSurfaceTrails` skips
+ * activation-driven trails, so the bridge applies the same rules here.
+ */
+const isEligibleWebhookTrail = (
+  graphTrail: Trail<unknown, unknown, unknown>,
+  options: BuildEnvResourceOverridesOptions
+): boolean => {
+  const hasWebhookSource = graphTrail.activationSources.some(
+    (activation) => activation.source.kind === 'webhook'
+  );
+  if (!hasWebhookSource) {
+    return false;
+  }
+  if (
+    isInternalTrail(graphTrail) &&
+    !options.include?.includes(graphTrail.id)
+  ) {
+    return false;
+  }
+  if (matchesAnyPattern(graphTrail.id, options.exclude)) {
+    return false;
+  }
+  if (!passesIncludeFilter(graphTrail.id, options.include)) {
+    return false;
+  }
+  return (
+    options.intent === undefined ||
+    options.intent.length === 0 ||
+    options.intent.includes(graphTrail.intent)
+  );
+};
+
+const collectSurfaceEligibleTrails = (
+  graph: Topo,
+  options: BuildEnvResourceOverridesOptions
+): readonly Trail<unknown, unknown, unknown>[] => {
+  const trails = graph.list();
+  const eligible = new Map<string, Trail<unknown, unknown, unknown>>();
+  const filtered = filterSurfaceTrails(trails, {
+    exclude: options.exclude,
+    include: options.include,
+    intent: options.intent,
+  });
+  for (const graphTrail of filtered) {
+    eligible.set(graphTrail.id, graphTrail);
+  }
+  for (const graphTrail of trails) {
+    if (
+      !eligible.has(graphTrail.id) &&
+      isEligibleWebhookTrail(graphTrail, options)
+    ) {
+      eligible.set(graphTrail.id, graphTrail);
+    }
+  }
+  return [...eligible.values()];
+};
+
+/**
+ * All resources a trail can execute with: the current contract's declarations
+ * plus any fork version entry's own `resources`, since core runs historical
+ * forks with the entry's resource set.
+ */
+const declaredTrailResources = (
+  graphTrail: Trail<unknown, unknown, unknown>
+): readonly AnyResource[] => [
+  ...graphTrail.resources,
+  ...Object.values(graphTrail.versions ?? {}).flatMap(
+    (entry) => entry.resources ?? []
+  ),
+];
+
+const collectEnvBoundResources = (
+  graph: Topo,
+  options: BuildEnvResourceOverridesOptions
+): readonly AnyResource[] => {
+  const except = new Set(options.except);
+  const collected = new Map<string, AnyResource>();
+  for (const graphTrail of collectSurfaceEligibleTrails(graph, options)) {
+    for (const declared of declaredTrailResources(graphTrail)) {
+      if (
+        !collected.has(declared.id) &&
+        !except.has(declared.id) &&
+        envBindings.has(declared)
+      ) {
+        collected.set(declared.id, declared);
+      }
+    }
+  }
+  return [...collected.values()];
+};
+
+/**
+ * Resolve every env-bound resource declared by the topo's surface-eligible
+ * trails (including fork-version resources) into a resource override map for
+ * one Worker env.
+ *
+ * Returns `Result.err` when a required binding is missing from the env or a
+ * binding value fails the resource's narrowing check. Trails filtered off the
+ * surface by `exclude`/`include`/`intent` never require their bindings, and
+ * resource IDs listed in `except` are skipped because the caller already
+ * provides them.
+ *
+ * @example
+ * ```ts
+ * import { buildEnvResourceOverrides } from '@ontrails/cloudflare/workers';
+ *
+ * const overrides = buildEnvResourceOverrides(graph, env);
+ * if (overrides.isErr()) throw overrides.error;
+ * ```
+ */
+export const buildEnvResourceOverrides = (
+  graph: Topo,
+  env: WorkersEnv,
+  options: BuildEnvResourceOverridesOptions = {}
+): Result<ResourceOverrideMap, Error> => {
+  const overrides: Record<string, unknown> = {};
+  for (const declared of collectEnvBoundResources(graph, options)) {
+    const spec = envBindings.get(declared);
+    if (spec === undefined) {
+      continue;
+    }
+    const value = env[spec.binding];
+    if (value === undefined) {
+      return Result.err(
+        new InternalError(
+          `Worker env is missing binding "${spec.binding}" required by resource "${declared.id}". Declare the binding in your wrangler configuration (for example a kv_namespaces entry) or provide an explicit resource override.`,
+          { context: { binding: spec.binding, resourceId: declared.id } }
+        )
+      );
+    }
+    const instance = spec.fromEnv(value);
+    if (instance.isErr()) {
+      return instance;
+    }
+    overrides[declared.id] = instance.value;
+  }
+  return Result.ok(overrides);
+};

package/src/facts.ts

@@ -0,0 +1,112 @@
+/**
+ * Cloudflare lock facts.
+ *
+ * The adapter's `trails.lock` overlay overlay: `derive` projects the
+ * topo's env-bound resources (resources with a registered
+ * {@link EnvBindingSpec | env binding}, such as every `cloudflareKv`
+ * definition) into `overlays.cloudflare`, listing the wrangler binding name
+ * each resource resolves from. The import from `@ontrails/adapter-kit` is
+ * type-only — the adapter never depends on the adapter kit at runtime.
+ */
+
+import type { Overlay } from '@ontrails/adapter-kit';
+import type { AnyResource, Topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { getEnvBinding } from './env.js';
+import type { EnvBindingSpec } from './env.js';
+
+const cloudflareFactsSchema = z
+  .object({
+    bindings: z.array(
+      z
+        .object({
+          binding: z.string(),
+          resourceId: z.string(),
+        })
+        .strict()
+    ),
+  })
+  .strict();
+
+/**
+ * The facts embedded at `overlays.cloudflare` in `trails.lock`: one entry
+ * per env-bound resource, pairing the resource ID with its wrangler binding
+ * name.
+ */
+export type CloudflareLockFacts = z.infer<typeof cloudflareFactsSchema>;
+
+/**
+ * Every resource visible on the topo: module-registered resources plus
+ * resources declared on trail contracts (including fork version entries),
+ * which core executes with but `topo()` does not auto-register.
+ */
+const collectTopoResources = (graph: Topo): readonly AnyResource[] => {
+  const collected = new Map<string, AnyResource>();
+  for (const definition of graph.listResources()) {
+    collected.set(definition.id, definition);
+  }
+  for (const graphTrail of graph.list()) {
+    const declared = [
+      ...graphTrail.resources,
+      ...Object.values(graphTrail.versions ?? {}).flatMap(
+        (entry) => entry.resources ?? []
+      ),
+    ];
+    for (const definition of declared) {
+      if (!collected.has(definition.id)) {
+        collected.set(definition.id, definition);
+      }
+    }
+  }
+  return [...collected.values()];
+};
+
+const derive = (graph: Topo): CloudflareLockFacts => {
+  const bindings = collectTopoResources(graph)
+    .map((definition) => ({
+      definition,
+      spec: getEnvBinding(definition),
+    }))
+    .filter(
+      (entry): entry is { definition: AnyResource; spec: EnvBindingSpec } =>
+        entry.spec !== undefined
+    )
+    .map((entry) => ({
+      binding: entry.spec.binding,
+      resourceId: entry.definition.id,
+    }))
+    .toSorted(
+      (a, b) =>
+        a.resourceId.localeCompare(b.resourceId) ||
+        a.binding.localeCompare(b.binding)
+    );
+  return { bindings };
+};
+
+/**
+ * The Cloudflare adapter's `trails.lock` overlay overlay.
+ *
+ * An app opts in by exporting `trailsOverlays` next to its topo export;
+ * `trails compile` then validates `derive(topo)` against the facts schema
+ * and embeds the result as `overlays.cloudflare`, listing every env-bound
+ * resource's wrangler binding. Derivation is deterministic: the same topo
+ * always yields the same facts, sorted by resource ID then binding.
+ *
+ * @example
+ * ```ts
+ * import { cloudflareOverlay, cloudflareKv } from '@ontrails/cloudflare';
+ * import { topo } from '@ontrails/core';
+ *
+ * export const flags = cloudflareKv('flags', { binding: 'FLAGS' });
+ * export const app = topo('my-worker', { flags });
+ * export const trailsOverlays = [cloudflareOverlay];
+ * // `trails compile` embeds overlays.cloudflare:
+ * // { bindings: [{ binding: 'FLAGS', resourceId: 'flags' }] }
+ * ```
+ */
+export const cloudflareOverlay = {
+  derive,
+  namespace: 'cloudflare',
+  schema: cloudflareFactsSchema,
+} satisfies Overlay;

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * `@ontrails/cloudflare` — the Cloudflare adapter collection.
+ *
+ * Service subpaths are the primary entry points:
+ * - `@ontrails/cloudflare/workers` — HTTP surface materializer (fetch handler)
+ * - `@ontrails/cloudflare/kv` — key-value resource
+ *
+ * The root export re-exports the subpaths for convenience and adapter
+ * tooling, and owns the adapter's `trails.lock` overlay overlay
+ * (`cloudflareOverlay`).
+ */
+
+export { cloudflareOverlay } from './facts.js';
+export type { CloudflareLockFacts } from './facts.js';
+export {
+  buildEnvResourceOverrides,
+  getEnvBinding,
+  registerEnvBinding,
+} from './env.js';
+export type {
+  BuildEnvResourceOverridesOptions,
+  EnvBindingSpec,
+  WorkersEnv,
+} from './env.js';
+export { cloudflareKv, createMemoryKv } from './kv/index.js';
+export type {
+  CloudflareKv,
+  CloudflareKvListKey,
+  CloudflareKvListOptions,
+  CloudflareKvListResult,
+  CloudflareKvOptions,
+  CloudflareKvPutOptions,
+  CreateMemoryKvOptions,
+} from './kv/index.js';
+export { createWorkersHandler } from './workers/index.js';
+export type {
+  CloudflareWorker,
+  CreateWorkersHandlerOptions,
+  WorkersExecutionContext,
+  WorkersResourceOverrides,
+} from './workers/index.js';

package/src/kv/index.ts

@@ -0,0 +1,275 @@
+/**
+ * Cloudflare KV resource for Trails.
+ *
+ * `cloudflareKv` authors an ordinary `resource()` definition wrapping a KV
+ * namespace binding. On Workers, the env bridge (see `../env.ts`) resolves
+ * the binding per env so trails read live KV through `flags.from(ctx)`. In
+ * tests, the in-memory mock keeps `testAll(app)` configuration-free.
+ */
+
+import { InternalError, Result, resource } from '@ontrails/core';
+import type { Resource } from '@ontrails/core';
+
+import { registerEnvBinding } from '../env.js';
+
+// ---------------------------------------------------------------------------
+// Client shape
+// ---------------------------------------------------------------------------
+
+/** Options accepted by {@link CloudflareKv.put}. */
+export interface CloudflareKvPutOptions {
+  /** Absolute expiration as a Unix timestamp in seconds. */
+  readonly expiration?: number | undefined;
+  /** Relative expiration in seconds from now. Wins over `expiration`. */
+  readonly expirationTtl?: number | undefined;
+}
+
+/** Options accepted by {@link CloudflareKv.list}. */
+export interface CloudflareKvListOptions {
+  /** Opaque cursor from a previous page's result. */
+  readonly cursor?: string | undefined;
+  /** Maximum keys per page. Defaults to 1000, matching the KV binding. */
+  readonly limit?: number | undefined;
+  /** Restrict results to keys starting with this prefix. */
+  readonly prefix?: string | undefined;
+}
+
+/** One key entry in a {@link CloudflareKvListResult}. */
+export interface CloudflareKvListKey {
+  /** Absolute expiration as a Unix timestamp in seconds, when set. */
+  readonly expiration?: number | undefined;
+  readonly name: string;
+}
+
+/** Result shape of {@link CloudflareKv.list}, matching the KV binding. */
+export interface CloudflareKvListResult {
+  readonly cursor?: string | undefined;
+  readonly keys: readonly CloudflareKvListKey[];
+  readonly list_complete: boolean;
+}
+
+/**
+ * The KV surface trails consume. A real `KVNamespace` binding satisfies this
+ * shape structurally, so the env bridge passes bindings through unchanged.
+ */
+export interface CloudflareKv {
+  delete(key: string): Promise<void>;
+  get(key: string): Promise<string | null>;
+  list(options?: CloudflareKvListOptions): Promise<CloudflareKvListResult>;
+  put(
+    key: string,
+    value: string,
+    options?: CloudflareKvPutOptions
+  ): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// In-memory mock
+// ---------------------------------------------------------------------------
+
+/** Options for {@link createMemoryKv}. */
+export interface CreateMemoryKvOptions {
+  /** Clock override for TTL tests. Defaults to `Date.now`. */
+  readonly now?: (() => number) | undefined;
+}
+
+interface MemoryKvEntry {
+  readonly expiresAtMs: number | undefined;
+  readonly value: string;
+}
+
+const DEFAULT_LIST_LIMIT = 1000;
+const MS_PER_SECOND = 1000;
+
+const isExpired = (entry: MemoryKvEntry, nowMs: number): boolean =>
+  entry.expiresAtMs !== undefined && entry.expiresAtMs <= nowMs;
+
+const resolveExpiresAtMs = (
+  nowMs: number,
+  options: CloudflareKvPutOptions | undefined
+): number | undefined => {
+  if (options?.expirationTtl !== undefined) {
+    return nowMs + options.expirationTtl * MS_PER_SECOND;
+  }
+  if (options?.expiration !== undefined) {
+    return options.expiration * MS_PER_SECOND;
+  }
+  return undefined;
+};
+
+/**
+ * Create an in-memory {@link CloudflareKv} backed by a `Map`.
+ *
+ * This is the mock factory behind every `cloudflareKv` resource, exported for
+ * direct use in tests. TTL semantics mirror the KV binding (lazy expiry,
+ * seconds granularity) but the 60-second minimum TTL is intentionally not
+ * enforced so tests can use short expirations.
+ *
+ * @example
+ * ```ts
+ * import { createMemoryKv } from '@ontrails/cloudflare/kv';
+ *
+ * const kv = createMemoryKv();
+ * await kv.put('color', 'red', { expirationTtl: 60 });
+ * await kv.get('color'); // 'red'
+ * ```
+ */
+export const createMemoryKv = (
+  options: CreateMemoryKvOptions = {}
+): CloudflareKv => {
+  const now = options.now ?? Date.now;
+  const entries = new Map<string, MemoryKvEntry>();
+
+  const liveEntry = (key: string): MemoryKvEntry | undefined => {
+    const entry = entries.get(key);
+    if (entry === undefined) {
+      return undefined;
+    }
+    if (isExpired(entry, now())) {
+      entries.delete(key);
+      return undefined;
+    }
+    return entry;
+  };
+
+  return {
+    delete: (key) => {
+      entries.delete(key);
+      return Promise.resolve();
+    },
+    get: (key) => Promise.resolve(liveEntry(key)?.value ?? null),
+    list: (listOptions) => {
+      const limit = listOptions?.limit ?? DEFAULT_LIST_LIMIT;
+      const prefix = listOptions?.prefix ?? '';
+      const nowMs = now();
+      const names = [...entries.keys()]
+        .filter((name) => {
+          const entry = entries.get(name);
+          return (
+            entry !== undefined &&
+            !isExpired(entry, nowMs) &&
+            name.startsWith(prefix)
+          );
+        })
+        .toSorted();
+      const startIndex =
+        listOptions?.cursor === undefined
+          ? 0
+          : names.findIndex((name) => name > (listOptions.cursor ?? ''));
+      const pageStart = startIndex === -1 ? names.length : startIndex;
+      const page = names.slice(pageStart, pageStart + limit);
+      const listComplete = pageStart + page.length >= names.length;
+      const lastName = page.at(-1);
+      return Promise.resolve({
+        ...(listComplete || lastName === undefined ? {} : { cursor: lastName }),
+        keys: page.map((name) => {
+          const entry = entries.get(name);
+          const expiresAtMs = entry?.expiresAtMs;
+          return {
+            ...(expiresAtMs === undefined
+              ? {}
+              : { expiration: Math.floor(expiresAtMs / MS_PER_SECOND) }),
+            name,
+          };
+        }),
+        list_complete: listComplete,
+      });
+    },
+    put: (key, value, putOptions) => {
+      entries.set(key, {
+        expiresAtMs: resolveExpiresAtMs(now(), putOptions),
+        value,
+      });
+      return Promise.resolve();
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Resource factory
+// ---------------------------------------------------------------------------
+
+/** Options for {@link cloudflareKv}. */
+export interface CloudflareKvOptions {
+  /** The wrangler binding name (a `kv_namespaces` entry's `binding`). */
+  readonly binding: string;
+  readonly description?: string | undefined;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+
+const isKvBinding = (value: unknown): value is CloudflareKv => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const candidate = value as Partial<Record<keyof CloudflareKv, unknown>>;
+  return (
+    typeof candidate.get === 'function' &&
+    typeof candidate.put === 'function' &&
+    typeof candidate.delete === 'function' &&
+    typeof candidate.list === 'function'
+  );
+};
+
+/**
+ * Author a Trails resource wrapping a Cloudflare KV namespace binding.
+ *
+ * The instance arrives through the Workers env bridge — `create` refuses to
+ * run outside a Worker because KV bindings only exist there. The in-memory
+ * mock keeps `testAll(app)` configuration-free.
+ *
+ * @example
+ * ```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', {
+ *   blaze: 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],
+ * });
+ * ```
+ */
+export const cloudflareKv = (
+  id: string,
+  options: CloudflareKvOptions
+): Resource<CloudflareKv> => {
+  const definition = resource<CloudflareKv>(id, {
+    create: () =>
+      Result.err(
+        new InternalError(
+          `Resource "${id}" wraps Cloudflare KV binding "${options.binding}", which only exists on a Workers env. Serve the topo with createWorkersHandler from @ontrails/cloudflare/workers, or rely on the in-memory mock in tests.`,
+          { context: { binding: options.binding, resourceId: id } }
+        )
+      ),
+    description:
+      options.description ??
+      `Cloudflare KV namespace bound to "${options.binding}"`,
+    meta: {
+      ...options.meta,
+      'cloudflare.binding': options.binding,
+      'cloudflare.service': 'kv',
+    },
+    mock: () => createMemoryKv(),
+  });
+  registerEnvBinding(definition, {
+    binding: options.binding,
+    fromEnv: (value) =>
+      isKvBinding(value)
+        ? Result.ok(value)
+        : Result.err(
+            new InternalError(
+              `Worker env binding "${options.binding}" for resource "${id}" is not a KV namespace. Check the kv_namespaces entry in your wrangler configuration.`,
+              { context: { binding: options.binding, resourceId: id } }
+            )
+          ),
+  });
+  return definition;
+};

package/src/workers/index.ts

@@ -0,0 +1,212 @@
+/**
+ * Cloudflare Workers materializer for Trails HTTP routes.
+ *
+ * Produces the `{ fetch(request, env, ctx) }` Worker export by delegating to
+ * the shared HTTP fetch kernel (`createFetchHandler` from `@ontrails/http`),
+ * making Workers the kernel's third consumer after Bun and Hono.
+ *
+ * The env bridge: bindings arrive per-request on `env`, so the kernel handler
+ * is materialized per env identity — a request carrying a new `env` object
+ * re-resolves every env-bound resource before it executes. Resource overrides
+ * are checked before core's singleton resource cache, so no resource instance
+ * can serve a request with a stale env.
+ */
+
+import {
+  projectErrorDiagnostics,
+  projectPublicSurfaceError,
+} from '@ontrails/core';
+import type {
+  BaseSurfaceOptions,
+  Layer,
+  ResourceOverrideMap,
+  Topo,
+  TrailContextInit,
+} from '@ontrails/core';
+import { createFetchHandler } from '@ontrails/http';
+import type { ResolveHttpPermit } from '@ontrails/http';
+
+import { buildEnvResourceOverrides } from '../env.js';
+import type { WorkersEnv } from '../env.js';
+
+export {
+  buildEnvResourceOverrides,
+  getEnvBinding,
+  registerEnvBinding,
+} from '../env.js';
+export type {
+  BuildEnvResourceOverridesOptions,
+  EnvBindingSpec,
+  WorkersEnv,
+} from '../env.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/**
+ * Resource overrides for the Workers surface.
+ *
+ * A static map is applied as-is. A function receives the per-request Worker
+ * env and is re-invoked whenever a new env object arrives, so overrides that
+ * read bindings stay as fresh as the env bridge itself.
+ */
+export type WorkersResourceOverrides =
+  | ResourceOverrideMap
+  | ((env: WorkersEnv) => ResourceOverrideMap);
+
+/**
+ * Options for building a Trails Worker handler.
+ */
+export interface CreateWorkersHandlerOptions extends BaseSurfaceOptions {
+  readonly basePath?: string | undefined;
+  readonly createContext?:
+    | (() => TrailContextInit | Promise<TrailContextInit>)
+    | undefined;
+  readonly layers?: readonly Layer[] | undefined;
+  /** Maximum JSON request body size in bytes. Defaults to 1 MiB. */
+  readonly maxJsonBodyBytes?: number | undefined;
+  readonly resolvePermit?: ResolveHttpPermit | undefined;
+  readonly resources?: WorkersResourceOverrides | undefined;
+}
+
+/**
+ * The `ExecutionContext` shape the Workers runtime passes as the third
+ * `fetch` argument. Declared structurally so the adapter does not require
+ * `@cloudflare/workers-types` at runtime.
+ */
+export interface WorkersExecutionContext {
+  passThroughOnException(): void;
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/**
+ * The Worker module export produced by {@link createWorkersHandler}.
+ */
+export interface CloudflareWorker {
+  fetch(
+    request: Request,
+    env?: WorkersEnv | undefined,
+    executionCtx?: WorkersExecutionContext | undefined
+  ): Promise<Response>;
+}
+
+// ---------------------------------------------------------------------------
+// Error mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a materialization failure (route derivation, env bridge resolution) to
+ * a projected HTTP error response. Route execution errors never reach this
+ * path — the fetch kernel maps those itself.
+ */
+const mapCaughtError = (error: unknown): Response => {
+  const err = error instanceof Error ? error : new Error(String(error));
+  // Materialization failures are host bootstrap problems; surface their
+  // diagnostics to the Worker log while the response stays redacted.
+  console.error(
+    '[ontrails:cloudflare/workers] Failed to materialize request handler',
+    projectErrorDiagnostics(err)
+  );
+  const projection = projectPublicSurfaceError('http', err);
+  return Response.json(
+    {
+      error: {
+        category: projection.category,
+        code: projection.name,
+        message: projection.message,
+      },
+    },
+    { status: projection.code }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// createWorkersHandler
+// ---------------------------------------------------------------------------
+
+const resolveResourceOverrides = (
+  graph: Topo,
+  env: WorkersEnv,
+  options: CreateWorkersHandlerOptions
+): ResourceOverrideMap => {
+  // Explicit overrides are the documented escape hatch, so they resolve
+  // first: an overridden resource never requires its env binding. Surface
+  // filters are forwarded so trails the handler does not expose never
+  // require theirs either.
+  const userOverrides =
+    typeof options.resources === 'function'
+      ? options.resources(env)
+      : (options.resources ?? {});
+  const envOverrides = buildEnvResourceOverrides(graph, env, {
+    except: Object.keys(userOverrides),
+    exclude: options.exclude,
+    include: options.include,
+    intent: options.intent,
+  });
+  if (envOverrides.isErr()) {
+    throw envOverrides.error;
+  }
+  return { ...envOverrides.value, ...userOverrides };
+};
+
+interface MaterializedHandler {
+  readonly env: WorkersEnv | undefined;
+  readonly handle: (request: Request) => Promise<Response>;
+}
+
+/**
+ * Build the `{ fetch }` Worker export for a topo.
+ *
+ * @remarks The kernel fetch handler is materialized lazily per env identity.
+ * The Workers runtime keeps `env` stable within an isolate, so steady-state
+ * requests reuse one materialization; any request carrying a different env
+ * object triggers a fresh resolution of every env-bound resource.
+ *
+ * @example
+ * ```ts
+ * import { createWorkersHandler } from '@ontrails/cloudflare/workers';
+ * import { graph } from './app.js';
+ *
+ * export default createWorkersHandler(graph, { basePath: '/api' });
+ * ```
+ */
+export const createWorkersHandler = (
+  graph: Topo,
+  options: CreateWorkersHandlerOptions = {}
+): CloudflareWorker => {
+  let materialized: MaterializedHandler | undefined;
+
+  const handlerFor = (
+    env: WorkersEnv | undefined
+  ): ((request: Request) => Promise<Response>) => {
+    if (materialized !== undefined && materialized.env === env) {
+      return materialized.handle;
+    }
+    const handle = createFetchHandler(graph, {
+      basePath: options.basePath,
+      configValues: options.configValues,
+      createContext: options.createContext,
+      exclude: options.exclude,
+      include: options.include,
+      intent: options.intent,
+      layers: options.layers,
+      maxJsonBodyBytes: options.maxJsonBodyBytes,
+      resolvePermit: options.resolvePermit,
+      resources: resolveResourceOverrides(graph, env ?? {}, options),
+      validate: options.validate,
+    });
+    materialized = { env, handle };
+    return handle;
+  };
+
+  return {
+    fetch: async (request, env, _executionCtx) => {
+      try {
+        return await handlerFor(env)(request);
+      } catch (error: unknown) {
+        return mapCaughtError(error);
+      }
+    },
+  };
+};