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

package/src/env.ts

@@ -10,8 +10,8 @@
  *
  * 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.
+ * instance can capture a stale env. Every Cloudflare service subpath consumes
+ * this one seam.
  */
 
 import {
@@ -19,6 +19,7 @@ import {
   matchesTrailPattern,
   Result,
   filterSurfaceTrails,
+  isLiveTrailVersionEntry,
 } from '@ontrails/core';
 import type {
   AnyResource,
@@ -31,7 +32,8 @@ import type {
 /**
  * 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.
+ * R2 buckets, queues), so they are typed as `unknown` and narrowed by each
+ * subpath.
  */
 export type WorkersEnv = Readonly<Record<string, unknown>>;
 
@@ -110,6 +112,10 @@ export interface BuildEnvResourceOverridesOptions extends Pick<
 > {
   /** Resource IDs already provided explicitly; env resolution skips them. */
   readonly except?: readonly string[] | undefined;
+  /** Worker entrypoint whose reachable resources should be materialized. */
+  readonly entrypoint?: 'fetch' | 'queue' | undefined;
+  /** Physical queue delivered to the current queue entrypoint. */
+  readonly queue?: string | undefined;
 }
 
 const isInternalTrail = (
@@ -134,18 +140,25 @@ const passesIncludeFilter = (
   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.
+ * Mirror of Worker activation eligibility for one entrypoint. Activation
+ * consumers are skipped by `filterSurfaceTrails`, so the bridge selects them
+ * explicitly without making fetch depend on queue-only resources.
  */
-const isEligibleWebhookTrail = (
+const isEligibleWorkerActivationTrail = (
   graphTrail: Trail<unknown, unknown, unknown>,
   options: BuildEnvResourceOverridesOptions
 ): boolean => {
-  const hasWebhookSource = graphTrail.activationSources.some(
-    (activation) => activation.source.kind === 'webhook'
+  const activationKind =
+    (options.entrypoint ?? 'fetch') === 'queue' ? 'queue' : 'webhook';
+  const hasWorkerActivationSource = graphTrail.activationSources.some(
+    (activation) =>
+      activation.source.kind === activationKind &&
+      (activationKind !== 'queue' ||
+        options.queue === undefined ||
+        (typeof activation.source.queue === 'string' &&
+          activation.source.queue.trim() === options.queue))
   );
-  if (!hasWebhookSource) {
+  if (!hasWorkerActivationSource) {
     return false;
   }
   if (
@@ -173,37 +186,58 @@ const collectSurfaceEligibleTrails = (
 ): 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);
+  if ((options.entrypoint ?? 'fetch') === 'fetch') {
+    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)
+      isEligibleWorkerActivationTrail(graphTrail, options)
     ) {
       eligible.set(graphTrail.id, graphTrail);
     }
   }
+  const byId = new Map(trails.map((graphTrail) => [graphTrail.id, graphTrail]));
+  const pending = [...eligible.values()];
+  for (const graphTrail of pending) {
+    const composedIds = [
+      ...graphTrail.composes,
+      ...Object.values(graphTrail.versions ?? {})
+        .filter(isLiveTrailVersionEntry)
+        .flatMap((entry) => entry.composes ?? []),
+    ];
+    for (const reference of composedIds) {
+      const composedId =
+        typeof reference === 'string' ? reference : reference.id;
+      const composed = byId.get(composedId);
+      if (composed !== undefined && !eligible.has(composed.id)) {
+        eligible.set(composed.id, composed);
+        pending.push(composed);
+      }
+    }
+  }
   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.
+ * plus any live fork version entry's own `resources`, since core runs
+ * supported 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 ?? []
-  ),
+  ...Object.values(graphTrail.versions ?? {})
+    .filter(isLiveTrailVersionEntry)
+    .flatMap((entry) => entry.resources ?? []),
 ];
 
 const collectEnvBoundResources = (
@@ -228,8 +262,8 @@ const collectEnvBoundResources = (
 
 /**
  * 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.
+ * trails (including live 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
@@ -260,7 +294,7 @@ export const buildEnvResourceOverrides = (
     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.`,
+          `Worker env is missing binding "${spec.binding}" required by resource "${declared.id}". Declare the binding in your wrangler configuration (for example kv_namespaces, d1_databases, r2_buckets, or queues) or provide an explicit resource override.`,
           { context: { binding: spec.binding, resourceId: declared.id } }
         )
       );

package/src/index.ts

@@ -4,6 +4,10 @@
  * Service subpaths are the primary entry points:
  * - `@ontrails/cloudflare/workers` — HTTP surface materializer (fetch handler)
  * - `@ontrails/cloudflare/kv` — key-value resource
+ * - `@ontrails/cloudflare/d1` — D1-backed store resource
+ * - `@ontrails/cloudflare/r2` — R2 blob/object resource
+ * - `@ontrails/cloudflare/queues` — Queue producer resource and consumer
+ *   materializer
  *
  * The root export re-exports the subpaths for convenience and adapter
  * tooling, and owns the adapter's `trails.lock` overlay overlay
@@ -12,6 +16,17 @@
 
 export { cloudflareOverlay } from './facts.js';
 export type { CloudflareLockFacts } from './facts.js';
+export { cloudflareD1, connectD1 } from './d1/index.js';
+export type {
+  CloudflareD1AllResult,
+  CloudflareD1Connection,
+  CloudflareD1Database,
+  CloudflareD1Options,
+  CloudflareD1PreparedStatement,
+  CloudflareD1Resource,
+  CloudflareD1RunResult,
+  ConnectD1Options,
+} from './d1/index.js';
 export {
   buildEnvResourceOverrides,
   getEnvBinding,
@@ -32,6 +47,46 @@ export type {
   CloudflareKvPutOptions,
   CreateMemoryKvOptions,
 } from './kv/index.js';
+export { cloudflareR2, createMemoryR2, r2ObjectToBlobRef } from './r2/index.js';
+export type {
+  CloudflareR2Bucket,
+  CloudflareR2Conditional,
+  CloudflareR2GetOptions,
+  CloudflareR2HttpMetadata,
+  CloudflareR2ListOptions,
+  CloudflareR2Object,
+  CloudflareR2ObjectBody,
+  CloudflareR2Objects,
+  CloudflareR2Options,
+  CloudflareR2PutBody,
+  CloudflareR2PutOptions,
+  CloudflareR2Range,
+  CloudflareR2StorageClass,
+  MemoryCloudflareR2Bucket,
+  R2ObjectToBlobRefOptions,
+} from './r2/index.js';
+export {
+  cloudflareQueue,
+  createMemoryQueue,
+  createQueueHandler,
+} from './queues/index.js';
+export type {
+  CloudflareQueue,
+  CloudflareQueueBatch,
+  CloudflareQueueHandler,
+  CloudflareQueueMessage,
+  CloudflareQueueMetrics,
+  CloudflareQueueOptions,
+  CloudflareQueueRetryOptions,
+  CloudflareQueueSendBatchOptions,
+  CloudflareQueueSendOptions,
+  CloudflareQueueSendRequest,
+  CloudflareQueueSendResult,
+  CloudflareQueuesContentType,
+  CreateQueueHandlerOptions,
+  MemoryCloudflareQueue,
+  MemoryQueueMessage,
+} from './queues/index.js';
 export { createWorkersHandler } from './workers/index.js';
 export type {
   CloudflareWorker,

package/src/kv/index.ts

@@ -226,7 +226,7 @@ const isKvBinding = (value: unknown): value is CloudflareKv => {
  * 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 });
  *   },