@directive-run/sources 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @directive-run/sources
+
+## 0.2.0
+
+### Minor Changes
+
+- [#52](https://github.com/directive-run/directive/pull/52) [`c31d22d`](https://github.com/directive-run/directive/commit/c31d22d94671ee15cc943bc07946a96848ba64fc) Thanks [@jasoncomes](https://github.com/jasoncomes)! - `@directive-run/sources` — umbrella package with per-vendor subpath exports
+
+  New package wrapping the most common external event streams as typed
+  Directive `source` primitives. One install, optional peerDependencies
+  per vendor.
+
+  **Subpaths shipped in 0.1.0:**
+
+  - `@directive-run/sources/supabase` — `sourceFromSupabaseChannel({ client, channel, events, redactRow? })`.
+    Wraps Supabase realtime channels with declarative event bindings
+    (`{ event, table, filter?, map }`). Optional `redactRow` runs at the
+    payload boundary so PII can be stripped before the `map` callback
+    sees it — defense in depth alongside `createFactPIIGuardrail`.
+  - `@directive-run/sources/cloudflare` — `sourceFromDOAlarm({ storage, intervalMs, eventName, payload? })`
+    and `sourceFromWebSocketMessage({ socket, decode, closeEvent?, errorEvent? })`.
+    DO alarms replace the canonical `setInterval`-inside-`attach` recipe
+    that dies on hibernation; the alarm survives eviction via DO storage.
+    The WebSocket adapter wraps `addEventListener('message' | 'close' | 'error')`
+    with typed Directive events.
+
+  Vendor peerDependencies (`@supabase/supabase-js`, `@cloudflare/workers-types`)
+  are optional and only need to be installed when the consumer imports
+  the matching subpath.
+
+  Future subpaths (`/websocket` for raw browser WebSocket, `/sentry` for
+  production error streams, `/eventsource` for SSE) land additively as
+  single subpath additions.
+
+  Tests: 9 regression tests covering channel binding + redaction + cleanup
+  on stop (Supabase) and alarm scheduling + tick / clear + WebSocket
+  listener teardown (Cloudflare).
+
+  Docs:
+
+  - README in the package surfaces the install, subpath inventory, and
+    three quick-start examples.
+  - `packages/knowledge/ai/ai-sources.md` lists the subpath inventory
+    under "Adapter packages".

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Sizls ∞ Jason Comes
+
+This project is dual-licensed under MIT OR Apache-2.0. You may choose
+either license. See LICENSE-APACHE for the Apache License, Version 2.0.
+
+---
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @directive-run/sources
+
+Source adapters for [Directive](https://directive.run) — wrap external
+event streams (Supabase realtime, Cloudflare DO alarms, WebSocket,
+Sentry, etc.) as typed `source` primitives.
+
+**One package, one install, subpath exports per vendor.** Vendor
+peerDependencies are optional — only the vendors you import need their
+peer-dependency installed.
+
+## Install
+
+```bash
+pnpm add @directive-run/sources
+# Plus whichever vendor SDKs you actually use:
+pnpm add @supabase/supabase-js   # if importing /supabase
+pnpm add @cloudflare/workers-types  # if importing /cloudflare (dev-time only)
+```
+
+## Subpath inventory
+
+| Subpath | Factory | Wraps |
+|---|---|---|
+| `@directive-run/sources/supabase` | `sourceFromSupabaseChannel()` | Supabase realtime channel + per-row event mapping |
+| `@directive-run/sources/cloudflare` | `sourceFromDOAlarm()` | Durable Object alarm as a periodic source |
+| `@directive-run/sources/cloudflare` | `sourceFromWebSocketMessage()` | DO WebSocket message stream |
+
+Future subpaths land additively (`/websocket` for raw browser WebSocket,
+`/sentry` for production error stream, `/eventsource` for SSE, …).
+
+## Quick examples
+
+### Supabase realtime
+
+```ts
+import { createClient } from '@supabase/supabase-js';
+import { createModule, createSystem, t } from '@directive-run/core';
+import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';
+
+const supabase = createClient(url, key);
+
+const gameUpdates = createModule('gameUpdates', {
+  schema: {
+    facts: { snapshot: t.object<GameSnapshot>().nullable() },
+    events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },
+  },
+  init: (f) => { f.snapshot = null; },
+  events: { GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; } },
+  sources: {
+    gameChannel: sourceFromSupabaseChannel({
+      client: supabase,
+      channel: `game:${gameId}`,
+      events: [{
+        table: 'games',
+        filter: `id=eq.${gameId}`,
+        event: 'UPDATE',
+        map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row.new) } }),
+      }],
+    }),
+  },
+});
+
+const system = createSystem({ module: gameUpdates });
+system.start();
+// `system.facts.snapshot` updates automatically on every postgres UPDATE
+```
+
+### Cloudflare DO alarm
+
+```ts
+import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';
+
+const ticker = createModule('ticker', {
+  schema: {
+    facts: { lastTick: t.number() },
+    events: { TICK: { at: t.number() } },
+  },
+  init: (f) => { f.lastTick = 0; },
+  events: { TICK: (f, p) => { f.lastTick = p.at; } },
+  sources: {
+    alarm: sourceFromDOAlarm({
+      storage: this.state.storage,
+      intervalMs: 30_000,
+      eventName: 'TICK',
+      payload: () => ({ at: Date.now() }),
+    }),
+  },
+});
+```
+
+### Cloudflare DO WebSocket
+
+```ts
+import { sourceFromWebSocketMessage } from '@directive-run/sources/cloudflare';
+
+const liveFeed = createModule('liveFeed', {
+  schema: {
+    facts: { lastMessage: t.string() },
+    events: {
+      MESSAGE: { content: t.string() },
+      WEBSOCKET_CLOSED: { code: t.number(), reason: t.string() },
+    },
+  },
+  init: (f) => { f.lastMessage = ''; },
+  events: { MESSAGE: (f, p) => { f.lastMessage = p.content; } },
+  sources: {
+    socket: sourceFromWebSocketMessage({
+      socket: server,                 // from webSocketAccept pair
+      decode: (data) => {
+        if (typeof data !== 'string') return null;
+        return { name: 'MESSAGE', payload: { content: data } };
+      },
+    }),
+  },
+});
+```
+
+## Why an umbrella package
+
+- **One install, one version, one changeset cadence.** No version skew
+  between adapters.
+- **Optional peer-dependencies.** Only consumers that import a vendor
+  subpath need that vendor's peerDep installed.
+- **One discovery surface.** "If I want a source adapter, I look in
+  `@directive-run/sources`."
+- **Cheap to add new vendors.** Each new adapter is a single subpath
+  addition, not a whole new package + GitHub release + npm publish +
+  README boilerplate.
+
+This matches how `@directive-run/core` already uses subpath exports for
+`/internals`, `/plugins`, `/testing`, `/migration`, `/worker`,
+`/adapter-utils`.
+
+## Related
+
+- [`@directive-run/core` source primitive](https://github.com/directive-run/directive/blob/main/packages/knowledge/core/sources.md) — the underlying primitive these adapters wrap.
+- [`@directive-run/ai` AI × Sources recipes](https://github.com/directive-run/directive/blob/main/packages/knowledge/ai/ai-sources.md) — `runStream({ liveContext })`, MCP lifecycle as a source.
+- [Tier 0 PII guardrail](https://github.com/directive-run/directive/blob/main/packages/knowledge/ai/ai-security.md#sources-pii--closing-the-fact-injection-bypass) — `createFactPIIGuardrail` (wire whenever sources feed facts the agent reads).
+
+## License
+
+MIT or Apache-2.0

package/dist/cloudflare.cjs

@@ -0,0 +1,2 @@
+'use strict';function u(i){let{storage:e,intervalMs:r,eventName:n,payload:c=()=>({}),onTickRegistered:a}=i;if(r<1)throw new Error(`[Directive] sourceFromDOAlarm: intervalMs must be >= 1, got ${r}`);let o=null;function s(){o&&(o(n,c()),e.setAlarm(Date.now()+r));}return {attach:t=>(o=t,e.setAlarm(Date.now()+r),a?.(s),()=>{o=null,e.deleteAlarm();}),tick:s,meta:{label:`DO alarm: ${n} every ${r}ms`,tags:["source","cloudflare","alarm"]}}}function m(i){let{socket:e,decode:r,closeEvent:n="WEBSOCKET_CLOSED",errorEvent:c="WEBSOCKET_ERROR"}=i;return {attach:a=>{let o=t=>{let d=r(t.data);d!==null&&a(d.name,d.payload);},s=t=>{n!==null&&a(n,{code:t.code??1e3,reason:t.reason??""});},l=()=>{c!==null&&a(c,{});};return e.addEventListener("message",o),e.addEventListener("close",s),e.addEventListener("error",l),()=>{e.removeEventListener("message",o),e.removeEventListener("close",s),e.removeEventListener("error",l);}},meta:{label:"Cloudflare WebSocket message stream",tags:["source","cloudflare","websocket"]}}}exports.sourceFromDOAlarm=u;exports.sourceFromWebSocketMessage=m;//# sourceMappingURL=cloudflare.cjs.map
+//# sourceMappingURL=cloudflare.cjs.map

package/dist/cloudflare.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cloudflare.ts"],"names":["sourceFromDOAlarm","options","storage","intervalMs","eventName","payload","onTickRegistered","activePublish","tick","publish","sourceFromWebSocketMessage","socket","decode","closeEvent","errorEvent","onMessage","event","decoded","onClose","onError"],"mappings":"aA8GO,SAASA,CAAAA,CACdC,EAC8B,CAC9B,GAAM,CACJ,OAAA,CAAAC,CAAAA,CACA,UAAA,CAAAC,CAAAA,CACA,SAAA,CAAAC,CAAAA,CACA,QAAAC,CAAAA,CAAU,KAAO,EAAC,CAAA,CAClB,gBAAA,CAAAC,CACF,CAAA,CAAIL,CAAAA,CAEJ,GAAIE,CAAAA,CAAa,CAAA,CACf,MAAM,IAAI,KAAA,CACR,CAAA,4DAAA,EAA+DA,CAAU,CAAA,CAC3E,CAAA,CAGF,IAAII,CAAAA,CAAsC,IAAA,CAE1C,SAASC,CAAAA,EAAa,CACfD,CAAAA,GACLA,EAAcH,CAAAA,CAAWC,CAAAA,EAAS,CAAA,CAI7BH,CAAAA,CAAQ,QAAA,CAAS,KAAK,GAAA,EAAI,CAAIC,CAAU,CAAA,EAC/C,CAuBA,OArB0C,CACxC,MAAA,CAASM,CAAAA,GACPF,EAAgBE,CAAAA,CAGXP,CAAAA,CAAQ,SAAS,IAAA,CAAK,GAAA,EAAI,CAAIC,CAAU,CAAA,CAC7CG,CAAAA,GAAmBE,CAAI,CAAA,CAChB,IAAM,CACXD,CAAAA,CAAgB,IAAA,CAGXL,CAAAA,CAAQ,cACf,CAAA,CAAA,CAEF,IAAA,CAAAM,CAAAA,CACA,IAAA,CAAM,CACJ,MAAO,CAAA,UAAA,EAAaJ,CAAS,UAAUD,CAAU,CAAA,EAAA,CAAA,CACjD,KAAM,CAAC,QAAA,CAAU,YAAA,CAAc,OAAO,CACxC,CACF,CAGF,CAyDO,SAASO,CAAAA,CACdT,CAAAA,CACW,CACX,GAAM,CACJ,MAAA,CAAAU,CAAAA,CACA,MAAA,CAAAC,CAAAA,CACA,UAAA,CAAAC,CAAAA,CAAa,mBACb,UAAA,CAAAC,CAAAA,CAAa,iBACf,CAAA,CAAIb,CAAAA,CAEJ,OAAO,CACL,MAAA,CAASQ,CAAAA,EAA2B,CAClC,IAAMM,CAAAA,CAAaC,GAA8B,CAC/C,IAAMC,CAAAA,CAAUL,CAAAA,CAAOI,CAAAA,CAAM,IAAI,EAC7BC,CAAAA,GAAY,IAAA,EAChBR,CAAAA,CAAQQ,CAAAA,CAAQ,IAAA,CAAMA,CAAAA,CAAQ,OAAO,EACvC,CAAA,CACMC,EAAWF,CAAAA,EAA8C,CACzDH,IAAe,IAAA,EACnBJ,CAAAA,CAAQI,CAAAA,CAAY,CAClB,IAAA,CAAMG,CAAAA,CAAM,MAAQ,GAAA,CACpB,MAAA,CAAQA,CAAAA,CAAM,MAAA,EAAU,EAC1B,CAAC,EACH,CAAA,CACMG,CAAAA,CAAU,IAAM,CAChBL,CAAAA,GAAe,IAAA,EACnBL,EAAQK,CAAAA,CAAY,EAAE,EACxB,CAAA,CAEA,OAAAH,CAAAA,CAAO,gBAAA,CAAiB,SAAA,CAAWI,CAAS,CAAA,CAC5CJ,CAAAA,CAAO,iBAAiB,OAAA,CAASO,CAAO,CAAA,CACxCP,CAAAA,CAAO,gBAAA,CAAiB,OAAA,CAASQ,CAAO,CAAA,CAEjC,IAAM,CACXR,CAAAA,CAAO,mBAAA,CAAoB,SAAA,CAAWI,CAAS,CAAA,CAC/CJ,CAAAA,CAAO,oBAAoB,OAAA,CAASO,CAAO,EAC3CP,CAAAA,CAAO,mBAAA,CAAoB,OAAA,CAASQ,CAAO,EAC7C,CACF,EACA,IAAA,CAAM,CACJ,KAAA,CAAO,qCAAA,CACP,IAAA,CAAM,CAAC,SAAU,YAAA,CAAc,WAAW,CAC5C,CACF,CACF","file":"cloudflare.cjs","sourcesContent":["/**\n * @directive-run/sources/cloudflare\n *\n * Bridges Cloudflare-specific runtime primitives into the Directive\n * `source` primitive:\n *\n * - **`sourceFromDOAlarm`** — Durable Object alarms as a typed\n *   periodic source. Replaces hand-rolled `setInterval` inside `attach`\n *   (which dies on hibernation) with a storage-backed alarm that\n *   survives eviction.\n * - **`sourceFromWebSocketMessage`** — DO `WebSocket` connection\n *   (Cloudflare's `webSocketAccept` flow) as a typed message source.\n *\n * Both adapters integrate with the source primitive's lifecycle, so\n * `system.stop()` cleans up via the storage / socket teardown paths.\n *\n * @example DO alarm as a 30-second tick source\n * ```ts\n * import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';\n *\n * export class TickerDO {\n *   constructor(public state: DurableObjectState) {}\n *\n *   async fetch(req: Request) {\n *     const system = createSystem({\n *       module: createModule('ticker', {\n *         schema: {\n *           facts: { lastTick: t.number() },\n *           events: { TICK: { at: t.number() } },\n *         },\n *         init: (f) => { f.lastTick = 0; },\n *         events: { TICK: (f, p) => { f.lastTick = p.at; } },\n *         sources: {\n *           alarm: sourceFromDOAlarm({\n *             storage: this.state.storage,\n *             intervalMs: 30_000,\n *             eventName: 'TICK',\n *             payload: () => ({ at: Date.now() }),\n *           }),\n *         },\n *       }),\n *     });\n *     system.start();\n *     return new Response('ok');\n *   }\n *\n *   // DO runtime calls alarm() on each scheduled tick; the source\n *   // adapter's storage key triggers a publish on the active system.\n *   async alarm() {\n *     // The DO runtime calls this; the source publishes via the\n *     // shared module-level event bus (the active system observes).\n *   }\n * }\n * ```\n */\n\nimport type { SourceDef, SourcePublish } from \"@directive-run/core\";\n\n// ============================================================================\n// Type stubs for the Cloudflare Workers / DO API surface we touch\n// ============================================================================\n\ninterface DurableObjectStorage {\n  setAlarm(scheduledTime: number | Date): Promise<void>;\n  deleteAlarm(): Promise<void>;\n  getAlarm(): Promise<number | null>;\n}\n\n// ============================================================================\n// sourceFromDOAlarm — Durable Object alarm as a periodic source\n// ============================================================================\n\nexport interface DOAlarmSourceOptions {\n  /** The DO's `state.storage` handle. */\n  storage: DurableObjectStorage;\n  /** Tick interval in milliseconds. Minimum 1ms. */\n  intervalMs: number;\n  /**\n   * Event name to publish on every tick. Must match an event declared\n   * on the module's schema (otherwise the engine drops the publish with\n   * `lastDropReason: 'invalid-event-name'` per the R6 telemetry).\n   */\n  eventName: string;\n  /**\n   * Payload factory. Called on every tick. Default: `() => ({})`.\n   */\n  payload?: () => Record<string, unknown>;\n  /**\n   * Optional hook for the consumer to wire the DO's `alarm()` callback\n   * back into this source. The adapter cannot intercept the DO runtime's\n   * `alarm()` call directly (it's a class method); the consumer's\n   * `alarm()` handler should call `adapter.tick()` to drive the publish.\n   *\n   * Returned from `sourceFromDOAlarm.exposeTick(source)` (see below).\n   */\n  onTickRegistered?: (tick: () => void) => void;\n}\n\n/**\n * Build a `SourceDef` that schedules a DO alarm every `intervalMs` and\n * publishes on every tick. The adapter manages alarm scheduling via\n * `state.storage.setAlarm()`; on `system.stop()` it clears the alarm.\n *\n * **Important wiring step:** the DO's `alarm()` instance method MUST\n * call the adapter's tick callback. Capture it via `onTickRegistered`\n * (or by stashing the source in a class field and invoking\n * `source.tick()` from your alarm method).\n *\n * @returns a `SourceDef` to drop into a module's `sources:` map.\n */\nexport function sourceFromDOAlarm(\n  options: DOAlarmSourceOptions,\n): SourceDef & { tick(): void } {\n  const {\n    storage,\n    intervalMs,\n    eventName,\n    payload = () => ({}),\n    onTickRegistered,\n  } = options;\n\n  if (intervalMs < 1) {\n    throw new Error(\n      `[Directive] sourceFromDOAlarm: intervalMs must be >= 1, got ${intervalMs}`,\n    );\n  }\n\n  let activePublish: SourcePublish | null = null;\n\n  function tick(): void {\n    if (!activePublish) return;\n    activePublish(eventName, payload());\n    // Schedule the next alarm. Fire-and-forget — the host runtime\n    // handles delivery; failures land via the source primitive's\n    // observation events.\n    void storage.setAlarm(Date.now() + intervalMs);\n  }\n\n  const def: SourceDef & { tick(): void } = {\n    attach: (publish: SourcePublish) => {\n      activePublish = publish;\n      // Schedule the first alarm. The DO's `alarm()` method must call\n      // `tick()` to drive subsequent publishes.\n      void storage.setAlarm(Date.now() + intervalMs);\n      onTickRegistered?.(tick);\n      return () => {\n        activePublish = null;\n        // Clear any pending alarm so the DO doesn't wake the dead\n        // system after stop.\n        void storage.deleteAlarm();\n      };\n    },\n    tick,\n    meta: {\n      label: `DO alarm: ${eventName} every ${intervalMs}ms`,\n      tags: [\"source\", \"cloudflare\", \"alarm\"],\n    },\n  };\n\n  return def;\n}\n\n// ============================================================================\n// sourceFromWebSocketMessage — DO WebSocket message stream as a source\n// ============================================================================\n\ninterface CloudflareWebSocket {\n  send(data: string | ArrayBuffer): void;\n  close(code?: number, reason?: string): void;\n  addEventListener(\n    type: \"message\" | \"close\" | \"error\",\n    handler: (event: {\n      data?: unknown;\n      code?: number;\n      reason?: string;\n    }) => void,\n  ): void;\n  removeEventListener(\n    type: \"message\" | \"close\" | \"error\",\n    handler: (event: {\n      data?: unknown;\n      code?: number;\n      reason?: string;\n    }) => void,\n  ): void;\n}\n\nexport interface WebSocketMessageSourceOptions {\n  /** The Cloudflare WebSocket (`server` half of the pair from `webSocketAccept`). */\n  socket: CloudflareWebSocket;\n  /**\n   * Decode each `MessageEvent.data` into a typed Directive event.\n   * Return `null` to drop the message (e.g. ping frames).\n   */\n  decode: (\n    data: unknown,\n  ) => { name: string; payload: Record<string, unknown> } | null;\n  /**\n   * Event name to publish when the socket closes. Default `\"WEBSOCKET_CLOSED\"`.\n   * Set `null` to skip publishing on close.\n   */\n  closeEvent?: string | null;\n  /**\n   * Event name to publish on socket errors. Default `\"WEBSOCKET_ERROR\"`.\n   * Set `null` to skip publishing on error.\n   */\n  errorEvent?: string | null;\n}\n\n/**\n * Build a `SourceDef` that listens on a Cloudflare WebSocket and\n * publishes each decoded message as a typed Directive event. Wraps\n * the standard `addEventListener('message' | 'close' | 'error')`\n * surface.\n *\n * @returns a `SourceDef` to drop into a module's `sources:` map.\n */\nexport function sourceFromWebSocketMessage(\n  options: WebSocketMessageSourceOptions,\n): SourceDef {\n  const {\n    socket,\n    decode,\n    closeEvent = \"WEBSOCKET_CLOSED\",\n    errorEvent = \"WEBSOCKET_ERROR\",\n  } = options;\n\n  return {\n    attach: (publish: SourcePublish) => {\n      const onMessage = (event: { data?: unknown }) => {\n        const decoded = decode(event.data);\n        if (decoded === null) return;\n        publish(decoded.name, decoded.payload);\n      };\n      const onClose = (event: { code?: number; reason?: string }) => {\n        if (closeEvent === null) return;\n        publish(closeEvent, {\n          code: event.code ?? 1000,\n          reason: event.reason ?? \"\",\n        });\n      };\n      const onError = () => {\n        if (errorEvent === null) return;\n        publish(errorEvent, {});\n      };\n\n      socket.addEventListener(\"message\", onMessage);\n      socket.addEventListener(\"close\", onClose);\n      socket.addEventListener(\"error\", onError);\n\n      return () => {\n        socket.removeEventListener(\"message\", onMessage);\n        socket.removeEventListener(\"close\", onClose);\n        socket.removeEventListener(\"error\", onError);\n      };\n    },\n    meta: {\n      label: \"Cloudflare WebSocket message stream\",\n      tags: [\"source\", \"cloudflare\", \"websocket\"],\n    },\n  };\n}\n"]}

package/dist/cloudflare.d.cts

@@ -0,0 +1,150 @@
+import { SourceDef } from '@directive-run/core';
+
+/**
+ * @directive-run/sources/cloudflare
+ *
+ * Bridges Cloudflare-specific runtime primitives into the Directive
+ * `source` primitive:
+ *
+ * - **`sourceFromDOAlarm`** — Durable Object alarms as a typed
+ *   periodic source. Replaces hand-rolled `setInterval` inside `attach`
+ *   (which dies on hibernation) with a storage-backed alarm that
+ *   survives eviction.
+ * - **`sourceFromWebSocketMessage`** — DO `WebSocket` connection
+ *   (Cloudflare's `webSocketAccept` flow) as a typed message source.
+ *
+ * Both adapters integrate with the source primitive's lifecycle, so
+ * `system.stop()` cleans up via the storage / socket teardown paths.
+ *
+ * @example DO alarm as a 30-second tick source
+ * ```ts
+ * import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';
+ *
+ * export class TickerDO {
+ *   constructor(public state: DurableObjectState) {}
+ *
+ *   async fetch(req: Request) {
+ *     const system = createSystem({
+ *       module: createModule('ticker', {
+ *         schema: {
+ *           facts: { lastTick: t.number() },
+ *           events: { TICK: { at: t.number() } },
+ *         },
+ *         init: (f) => { f.lastTick = 0; },
+ *         events: { TICK: (f, p) => { f.lastTick = p.at; } },
+ *         sources: {
+ *           alarm: sourceFromDOAlarm({
+ *             storage: this.state.storage,
+ *             intervalMs: 30_000,
+ *             eventName: 'TICK',
+ *             payload: () => ({ at: Date.now() }),
+ *           }),
+ *         },
+ *       }),
+ *     });
+ *     system.start();
+ *     return new Response('ok');
+ *   }
+ *
+ *   // DO runtime calls alarm() on each scheduled tick; the source
+ *   // adapter's storage key triggers a publish on the active system.
+ *   async alarm() {
+ *     // The DO runtime calls this; the source publishes via the
+ *     // shared module-level event bus (the active system observes).
+ *   }
+ * }
+ * ```
+ */
+
+interface DurableObjectStorage {
+    setAlarm(scheduledTime: number | Date): Promise<void>;
+    deleteAlarm(): Promise<void>;
+    getAlarm(): Promise<number | null>;
+}
+interface DOAlarmSourceOptions {
+    /** The DO's `state.storage` handle. */
+    storage: DurableObjectStorage;
+    /** Tick interval in milliseconds. Minimum 1ms. */
+    intervalMs: number;
+    /**
+     * Event name to publish on every tick. Must match an event declared
+     * on the module's schema (otherwise the engine drops the publish with
+     * `lastDropReason: 'invalid-event-name'` per the R6 telemetry).
+     */
+    eventName: string;
+    /**
+     * Payload factory. Called on every tick. Default: `() => ({})`.
+     */
+    payload?: () => Record<string, unknown>;
+    /**
+     * Optional hook for the consumer to wire the DO's `alarm()` callback
+     * back into this source. The adapter cannot intercept the DO runtime's
+     * `alarm()` call directly (it's a class method); the consumer's
+     * `alarm()` handler should call `adapter.tick()` to drive the publish.
+     *
+     * Returned from `sourceFromDOAlarm.exposeTick(source)` (see below).
+     */
+    onTickRegistered?: (tick: () => void) => void;
+}
+/**
+ * Build a `SourceDef` that schedules a DO alarm every `intervalMs` and
+ * publishes on every tick. The adapter manages alarm scheduling via
+ * `state.storage.setAlarm()`; on `system.stop()` it clears the alarm.
+ *
+ * **Important wiring step:** the DO's `alarm()` instance method MUST
+ * call the adapter's tick callback. Capture it via `onTickRegistered`
+ * (or by stashing the source in a class field and invoking
+ * `source.tick()` from your alarm method).
+ *
+ * @returns a `SourceDef` to drop into a module's `sources:` map.
+ */
+declare function sourceFromDOAlarm(options: DOAlarmSourceOptions): SourceDef & {
+    tick(): void;
+};
+interface CloudflareWebSocket {
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "message" | "close" | "error", handler: (event: {
+        data?: unknown;
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    removeEventListener(type: "message" | "close" | "error", handler: (event: {
+        data?: unknown;
+        code?: number;
+        reason?: string;
+    }) => void): void;
+}
+interface WebSocketMessageSourceOptions {
+    /** The Cloudflare WebSocket (`server` half of the pair from `webSocketAccept`). */
+    socket: CloudflareWebSocket;
+    /**
+     * Decode each `MessageEvent.data` into a typed Directive event.
+     * Return `null` to drop the message (e.g. ping frames).
+     */
+    decode: (data: unknown) => {
+        name: string;
+        payload: Record<string, unknown>;
+    } | null;
+    /**
+     * Event name to publish when the socket closes. Default `"WEBSOCKET_CLOSED"`.
+     * Set `null` to skip publishing on close.
+     */
+    closeEvent?: string | null;
+    /**
+     * Event name to publish on socket errors. Default `"WEBSOCKET_ERROR"`.
+     * Set `null` to skip publishing on error.
+     */
+    errorEvent?: string | null;
+}
+/**
+ * Build a `SourceDef` that listens on a Cloudflare WebSocket and
+ * publishes each decoded message as a typed Directive event. Wraps
+ * the standard `addEventListener('message' | 'close' | 'error')`
+ * surface.
+ *
+ * @returns a `SourceDef` to drop into a module's `sources:` map.
+ */
+declare function sourceFromWebSocketMessage(options: WebSocketMessageSourceOptions): SourceDef;
+
+export { type DOAlarmSourceOptions, type WebSocketMessageSourceOptions, sourceFromDOAlarm, sourceFromWebSocketMessage };

package/dist/cloudflare.d.ts

@@ -0,0 +1,150 @@
+import { SourceDef } from '@directive-run/core';
+
+/**
+ * @directive-run/sources/cloudflare
+ *
+ * Bridges Cloudflare-specific runtime primitives into the Directive
+ * `source` primitive:
+ *
+ * - **`sourceFromDOAlarm`** — Durable Object alarms as a typed
+ *   periodic source. Replaces hand-rolled `setInterval` inside `attach`
+ *   (which dies on hibernation) with a storage-backed alarm that
+ *   survives eviction.
+ * - **`sourceFromWebSocketMessage`** — DO `WebSocket` connection
+ *   (Cloudflare's `webSocketAccept` flow) as a typed message source.
+ *
+ * Both adapters integrate with the source primitive's lifecycle, so
+ * `system.stop()` cleans up via the storage / socket teardown paths.
+ *
+ * @example DO alarm as a 30-second tick source
+ * ```ts
+ * import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';
+ *
+ * export class TickerDO {
+ *   constructor(public state: DurableObjectState) {}
+ *
+ *   async fetch(req: Request) {
+ *     const system = createSystem({
+ *       module: createModule('ticker', {
+ *         schema: {
+ *           facts: { lastTick: t.number() },
+ *           events: { TICK: { at: t.number() } },
+ *         },
+ *         init: (f) => { f.lastTick = 0; },
+ *         events: { TICK: (f, p) => { f.lastTick = p.at; } },
+ *         sources: {
+ *           alarm: sourceFromDOAlarm({
+ *             storage: this.state.storage,
+ *             intervalMs: 30_000,
+ *             eventName: 'TICK',
+ *             payload: () => ({ at: Date.now() }),
+ *           }),
+ *         },
+ *       }),
+ *     });
+ *     system.start();
+ *     return new Response('ok');
+ *   }
+ *
+ *   // DO runtime calls alarm() on each scheduled tick; the source
+ *   // adapter's storage key triggers a publish on the active system.
+ *   async alarm() {
+ *     // The DO runtime calls this; the source publishes via the
+ *     // shared module-level event bus (the active system observes).
+ *   }
+ * }
+ * ```
+ */
+
+interface DurableObjectStorage {
+    setAlarm(scheduledTime: number | Date): Promise<void>;
+    deleteAlarm(): Promise<void>;
+    getAlarm(): Promise<number | null>;
+}
+interface DOAlarmSourceOptions {
+    /** The DO's `state.storage` handle. */
+    storage: DurableObjectStorage;
+    /** Tick interval in milliseconds. Minimum 1ms. */
+    intervalMs: number;
+    /**
+     * Event name to publish on every tick. Must match an event declared
+     * on the module's schema (otherwise the engine drops the publish with
+     * `lastDropReason: 'invalid-event-name'` per the R6 telemetry).
+     */
+    eventName: string;
+    /**
+     * Payload factory. Called on every tick. Default: `() => ({})`.
+     */
+    payload?: () => Record<string, unknown>;
+    /**
+     * Optional hook for the consumer to wire the DO's `alarm()` callback
+     * back into this source. The adapter cannot intercept the DO runtime's
+     * `alarm()` call directly (it's a class method); the consumer's
+     * `alarm()` handler should call `adapter.tick()` to drive the publish.
+     *
+     * Returned from `sourceFromDOAlarm.exposeTick(source)` (see below).
+     */
+    onTickRegistered?: (tick: () => void) => void;
+}
+/**
+ * Build a `SourceDef` that schedules a DO alarm every `intervalMs` and
+ * publishes on every tick. The adapter manages alarm scheduling via
+ * `state.storage.setAlarm()`; on `system.stop()` it clears the alarm.
+ *
+ * **Important wiring step:** the DO's `alarm()` instance method MUST
+ * call the adapter's tick callback. Capture it via `onTickRegistered`
+ * (or by stashing the source in a class field and invoking
+ * `source.tick()` from your alarm method).
+ *
+ * @returns a `SourceDef` to drop into a module's `sources:` map.
+ */
+declare function sourceFromDOAlarm(options: DOAlarmSourceOptions): SourceDef & {
+    tick(): void;
+};
+interface CloudflareWebSocket {
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "message" | "close" | "error", handler: (event: {
+        data?: unknown;
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    removeEventListener(type: "message" | "close" | "error", handler: (event: {
+        data?: unknown;
+        code?: number;
+        reason?: string;
+    }) => void): void;
+}
+interface WebSocketMessageSourceOptions {
+    /** The Cloudflare WebSocket (`server` half of the pair from `webSocketAccept`). */
+    socket: CloudflareWebSocket;
+    /**
+     * Decode each `MessageEvent.data` into a typed Directive event.
+     * Return `null` to drop the message (e.g. ping frames).
+     */
+    decode: (data: unknown) => {
+        name: string;
+        payload: Record<string, unknown>;
+    } | null;
+    /**
+     * Event name to publish when the socket closes. Default `"WEBSOCKET_CLOSED"`.
+     * Set `null` to skip publishing on close.
+     */
+    closeEvent?: string | null;
+    /**
+     * Event name to publish on socket errors. Default `"WEBSOCKET_ERROR"`.
+     * Set `null` to skip publishing on error.
+     */
+    errorEvent?: string | null;
+}
+/**
+ * Build a `SourceDef` that listens on a Cloudflare WebSocket and
+ * publishes each decoded message as a typed Directive event. Wraps
+ * the standard `addEventListener('message' | 'close' | 'error')`
+ * surface.
+ *
+ * @returns a `SourceDef` to drop into a module's `sources:` map.
+ */
+declare function sourceFromWebSocketMessage(options: WebSocketMessageSourceOptions): SourceDef;
+
+export { type DOAlarmSourceOptions, type WebSocketMessageSourceOptions, sourceFromDOAlarm, sourceFromWebSocketMessage };

package/dist/cloudflare.js

@@ -0,0 +1,2 @@
+function u(i){let{storage:e,intervalMs:r,eventName:n,payload:c=()=>({}),onTickRegistered:a}=i;if(r<1)throw new Error(`[Directive] sourceFromDOAlarm: intervalMs must be >= 1, got ${r}`);let o=null;function s(){o&&(o(n,c()),e.setAlarm(Date.now()+r));}return {attach:t=>(o=t,e.setAlarm(Date.now()+r),a?.(s),()=>{o=null,e.deleteAlarm();}),tick:s,meta:{label:`DO alarm: ${n} every ${r}ms`,tags:["source","cloudflare","alarm"]}}}function m(i){let{socket:e,decode:r,closeEvent:n="WEBSOCKET_CLOSED",errorEvent:c="WEBSOCKET_ERROR"}=i;return {attach:a=>{let o=t=>{let d=r(t.data);d!==null&&a(d.name,d.payload);},s=t=>{n!==null&&a(n,{code:t.code??1e3,reason:t.reason??""});},l=()=>{c!==null&&a(c,{});};return e.addEventListener("message",o),e.addEventListener("close",s),e.addEventListener("error",l),()=>{e.removeEventListener("message",o),e.removeEventListener("close",s),e.removeEventListener("error",l);}},meta:{label:"Cloudflare WebSocket message stream",tags:["source","cloudflare","websocket"]}}}export{u as sourceFromDOAlarm,m as sourceFromWebSocketMessage};//# sourceMappingURL=cloudflare.js.map
+//# sourceMappingURL=cloudflare.js.map

package/dist/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cloudflare.ts"],"names":["sourceFromDOAlarm","options","storage","intervalMs","eventName","payload","onTickRegistered","activePublish","tick","publish","sourceFromWebSocketMessage","socket","decode","closeEvent","errorEvent","onMessage","event","decoded","onClose","onError"],"mappings":"AA8GO,SAASA,CAAAA,CACdC,EAC8B,CAC9B,GAAM,CACJ,OAAA,CAAAC,CAAAA,CACA,UAAA,CAAAC,CAAAA,CACA,SAAA,CAAAC,CAAAA,CACA,QAAAC,CAAAA,CAAU,KAAO,EAAC,CAAA,CAClB,gBAAA,CAAAC,CACF,CAAA,CAAIL,CAAAA,CAEJ,GAAIE,CAAAA,CAAa,CAAA,CACf,MAAM,IAAI,KAAA,CACR,CAAA,4DAAA,EAA+DA,CAAU,CAAA,CAC3E,CAAA,CAGF,IAAII,CAAAA,CAAsC,IAAA,CAE1C,SAASC,CAAAA,EAAa,CACfD,CAAAA,GACLA,EAAcH,CAAAA,CAAWC,CAAAA,EAAS,CAAA,CAI7BH,CAAAA,CAAQ,QAAA,CAAS,KAAK,GAAA,EAAI,CAAIC,CAAU,CAAA,EAC/C,CAuBA,OArB0C,CACxC,MAAA,CAASM,CAAAA,GACPF,EAAgBE,CAAAA,CAGXP,CAAAA,CAAQ,SAAS,IAAA,CAAK,GAAA,EAAI,CAAIC,CAAU,CAAA,CAC7CG,CAAAA,GAAmBE,CAAI,CAAA,CAChB,IAAM,CACXD,CAAAA,CAAgB,IAAA,CAGXL,CAAAA,CAAQ,cACf,CAAA,CAAA,CAEF,IAAA,CAAAM,CAAAA,CACA,IAAA,CAAM,CACJ,MAAO,CAAA,UAAA,EAAaJ,CAAS,UAAUD,CAAU,CAAA,EAAA,CAAA,CACjD,KAAM,CAAC,QAAA,CAAU,YAAA,CAAc,OAAO,CACxC,CACF,CAGF,CAyDO,SAASO,CAAAA,CACdT,CAAAA,CACW,CACX,GAAM,CACJ,MAAA,CAAAU,CAAAA,CACA,MAAA,CAAAC,CAAAA,CACA,UAAA,CAAAC,CAAAA,CAAa,mBACb,UAAA,CAAAC,CAAAA,CAAa,iBACf,CAAA,CAAIb,CAAAA,CAEJ,OAAO,CACL,MAAA,CAASQ,CAAAA,EAA2B,CAClC,IAAMM,CAAAA,CAAaC,GAA8B,CAC/C,IAAMC,CAAAA,CAAUL,CAAAA,CAAOI,CAAAA,CAAM,IAAI,EAC7BC,CAAAA,GAAY,IAAA,EAChBR,CAAAA,CAAQQ,CAAAA,CAAQ,IAAA,CAAMA,CAAAA,CAAQ,OAAO,EACvC,CAAA,CACMC,EAAWF,CAAAA,EAA8C,CACzDH,IAAe,IAAA,EACnBJ,CAAAA,CAAQI,CAAAA,CAAY,CAClB,IAAA,CAAMG,CAAAA,CAAM,MAAQ,GAAA,CACpB,MAAA,CAAQA,CAAAA,CAAM,MAAA,EAAU,EAC1B,CAAC,EACH,CAAA,CACMG,CAAAA,CAAU,IAAM,CAChBL,CAAAA,GAAe,IAAA,EACnBL,EAAQK,CAAAA,CAAY,EAAE,EACxB,CAAA,CAEA,OAAAH,CAAAA,CAAO,gBAAA,CAAiB,SAAA,CAAWI,CAAS,CAAA,CAC5CJ,CAAAA,CAAO,iBAAiB,OAAA,CAASO,CAAO,CAAA,CACxCP,CAAAA,CAAO,gBAAA,CAAiB,OAAA,CAASQ,CAAO,CAAA,CAEjC,IAAM,CACXR,CAAAA,CAAO,mBAAA,CAAoB,SAAA,CAAWI,CAAS,CAAA,CAC/CJ,CAAAA,CAAO,oBAAoB,OAAA,CAASO,CAAO,EAC3CP,CAAAA,CAAO,mBAAA,CAAoB,OAAA,CAASQ,CAAO,EAC7C,CACF,EACA,IAAA,CAAM,CACJ,KAAA,CAAO,qCAAA,CACP,IAAA,CAAM,CAAC,SAAU,YAAA,CAAc,WAAW,CAC5C,CACF,CACF","file":"cloudflare.js","sourcesContent":["/**\n * @directive-run/sources/cloudflare\n *\n * Bridges Cloudflare-specific runtime primitives into the Directive\n * `source` primitive:\n *\n * - **`sourceFromDOAlarm`** — Durable Object alarms as a typed\n *   periodic source. Replaces hand-rolled `setInterval` inside `attach`\n *   (which dies on hibernation) with a storage-backed alarm that\n *   survives eviction.\n * - **`sourceFromWebSocketMessage`** — DO `WebSocket` connection\n *   (Cloudflare's `webSocketAccept` flow) as a typed message source.\n *\n * Both adapters integrate with the source primitive's lifecycle, so\n * `system.stop()` cleans up via the storage / socket teardown paths.\n *\n * @example DO alarm as a 30-second tick source\n * ```ts\n * import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';\n *\n * export class TickerDO {\n *   constructor(public state: DurableObjectState) {}\n *\n *   async fetch(req: Request) {\n *     const system = createSystem({\n *       module: createModule('ticker', {\n *         schema: {\n *           facts: { lastTick: t.number() },\n *           events: { TICK: { at: t.number() } },\n *         },\n *         init: (f) => { f.lastTick = 0; },\n *         events: { TICK: (f, p) => { f.lastTick = p.at; } },\n *         sources: {\n *           alarm: sourceFromDOAlarm({\n *             storage: this.state.storage,\n *             intervalMs: 30_000,\n *             eventName: 'TICK',\n *             payload: () => ({ at: Date.now() }),\n *           }),\n *         },\n *       }),\n *     });\n *     system.start();\n *     return new Response('ok');\n *   }\n *\n *   // DO runtime calls alarm() on each scheduled tick; the source\n *   // adapter's storage key triggers a publish on the active system.\n *   async alarm() {\n *     // The DO runtime calls this; the source publishes via the\n *     // shared module-level event bus (the active system observes).\n *   }\n * }\n * ```\n */\n\nimport type { SourceDef, SourcePublish } from \"@directive-run/core\";\n\n// ============================================================================\n// Type stubs for the Cloudflare Workers / DO API surface we touch\n// ============================================================================\n\ninterface DurableObjectStorage {\n  setAlarm(scheduledTime: number | Date): Promise<void>;\n  deleteAlarm(): Promise<void>;\n  getAlarm(): Promise<number | null>;\n}\n\n// ============================================================================\n// sourceFromDOAlarm — Durable Object alarm as a periodic source\n// ============================================================================\n\nexport interface DOAlarmSourceOptions {\n  /** The DO's `state.storage` handle. */\n  storage: DurableObjectStorage;\n  /** Tick interval in milliseconds. Minimum 1ms. */\n  intervalMs: number;\n  /**\n   * Event name to publish on every tick. Must match an event declared\n   * on the module's schema (otherwise the engine drops the publish with\n   * `lastDropReason: 'invalid-event-name'` per the R6 telemetry).\n   */\n  eventName: string;\n  /**\n   * Payload factory. Called on every tick. Default: `() => ({})`.\n   */\n  payload?: () => Record<string, unknown>;\n  /**\n   * Optional hook for the consumer to wire the DO's `alarm()` callback\n   * back into this source. The adapter cannot intercept the DO runtime's\n   * `alarm()` call directly (it's a class method); the consumer's\n   * `alarm()` handler should call `adapter.tick()` to drive the publish.\n   *\n   * Returned from `sourceFromDOAlarm.exposeTick(source)` (see below).\n   */\n  onTickRegistered?: (tick: () => void) => void;\n}\n\n/**\n * Build a `SourceDef` that schedules a DO alarm every `intervalMs` and\n * publishes on every tick. The adapter manages alarm scheduling via\n * `state.storage.setAlarm()`; on `system.stop()` it clears the alarm.\n *\n * **Important wiring step:** the DO's `alarm()` instance method MUST\n * call the adapter's tick callback. Capture it via `onTickRegistered`\n * (or by stashing the source in a class field and invoking\n * `source.tick()` from your alarm method).\n *\n * @returns a `SourceDef` to drop into a module's `sources:` map.\n */\nexport function sourceFromDOAlarm(\n  options: DOAlarmSourceOptions,\n): SourceDef & { tick(): void } {\n  const {\n    storage,\n    intervalMs,\n    eventName,\n    payload = () => ({}),\n    onTickRegistered,\n  } = options;\n\n  if (intervalMs < 1) {\n    throw new Error(\n      `[Directive] sourceFromDOAlarm: intervalMs must be >= 1, got ${intervalMs}`,\n    );\n  }\n\n  let activePublish: SourcePublish | null = null;\n\n  function tick(): void {\n    if (!activePublish) return;\n    activePublish(eventName, payload());\n    // Schedule the next alarm. Fire-and-forget — the host runtime\n    // handles delivery; failures land via the source primitive's\n    // observation events.\n    void storage.setAlarm(Date.now() + intervalMs);\n  }\n\n  const def: SourceDef & { tick(): void } = {\n    attach: (publish: SourcePublish) => {\n      activePublish = publish;\n      // Schedule the first alarm. The DO's `alarm()` method must call\n      // `tick()` to drive subsequent publishes.\n      void storage.setAlarm(Date.now() + intervalMs);\n      onTickRegistered?.(tick);\n      return () => {\n        activePublish = null;\n        // Clear any pending alarm so the DO doesn't wake the dead\n        // system after stop.\n        void storage.deleteAlarm();\n      };\n    },\n    tick,\n    meta: {\n      label: `DO alarm: ${eventName} every ${intervalMs}ms`,\n      tags: [\"source\", \"cloudflare\", \"alarm\"],\n    },\n  };\n\n  return def;\n}\n\n// ============================================================================\n// sourceFromWebSocketMessage — DO WebSocket message stream as a source\n// ============================================================================\n\ninterface CloudflareWebSocket {\n  send(data: string | ArrayBuffer): void;\n  close(code?: number, reason?: string): void;\n  addEventListener(\n    type: \"message\" | \"close\" | \"error\",\n    handler: (event: {\n      data?: unknown;\n      code?: number;\n      reason?: string;\n    }) => void,\n  ): void;\n  removeEventListener(\n    type: \"message\" | \"close\" | \"error\",\n    handler: (event: {\n      data?: unknown;\n      code?: number;\n      reason?: string;\n    }) => void,\n  ): void;\n}\n\nexport interface WebSocketMessageSourceOptions {\n  /** The Cloudflare WebSocket (`server` half of the pair from `webSocketAccept`). */\n  socket: CloudflareWebSocket;\n  /**\n   * Decode each `MessageEvent.data` into a typed Directive event.\n   * Return `null` to drop the message (e.g. ping frames).\n   */\n  decode: (\n    data: unknown,\n  ) => { name: string; payload: Record<string, unknown> } | null;\n  /**\n   * Event name to publish when the socket closes. Default `\"WEBSOCKET_CLOSED\"`.\n   * Set `null` to skip publishing on close.\n   */\n  closeEvent?: string | null;\n  /**\n   * Event name to publish on socket errors. Default `\"WEBSOCKET_ERROR\"`.\n   * Set `null` to skip publishing on error.\n   */\n  errorEvent?: string | null;\n}\n\n/**\n * Build a `SourceDef` that listens on a Cloudflare WebSocket and\n * publishes each decoded message as a typed Directive event. Wraps\n * the standard `addEventListener('message' | 'close' | 'error')`\n * surface.\n *\n * @returns a `SourceDef` to drop into a module's `sources:` map.\n */\nexport function sourceFromWebSocketMessage(\n  options: WebSocketMessageSourceOptions,\n): SourceDef {\n  const {\n    socket,\n    decode,\n    closeEvent = \"WEBSOCKET_CLOSED\",\n    errorEvent = \"WEBSOCKET_ERROR\",\n  } = options;\n\n  return {\n    attach: (publish: SourcePublish) => {\n      const onMessage = (event: { data?: unknown }) => {\n        const decoded = decode(event.data);\n        if (decoded === null) return;\n        publish(decoded.name, decoded.payload);\n      };\n      const onClose = (event: { code?: number; reason?: string }) => {\n        if (closeEvent === null) return;\n        publish(closeEvent, {\n          code: event.code ?? 1000,\n          reason: event.reason ?? \"\",\n        });\n      };\n      const onError = () => {\n        if (errorEvent === null) return;\n        publish(errorEvent, {});\n      };\n\n      socket.addEventListener(\"message\", onMessage);\n      socket.addEventListener(\"close\", onClose);\n      socket.addEventListener(\"error\", onError);\n\n      return () => {\n        socket.removeEventListener(\"message\", onMessage);\n        socket.removeEventListener(\"close\", onClose);\n        socket.removeEventListener(\"error\", onError);\n      };\n    },\n    meta: {\n      label: \"Cloudflare WebSocket message stream\",\n      tags: [\"source\", \"cloudflare\", \"websocket\"],\n    },\n  };\n}\n"]}

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var o="0.1.0";exports.VERSION=o;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["VERSION"],"mappings":"aA8EO,IAAMA,CAAAA,CAAU","file":"index.cjs","sourcesContent":["/**\n * @directive-run/sources\n *\n * Source adapters for Directive — wrap external event streams (Supabase\n * realtime, Cloudflare DO alarms, WebSocket, Sentry, etc.) as typed\n * `source` primitives. Import vendor adapters from the per-vendor\n * subpath; only the vendors you import need their peer-dependency\n * installed.\n *\n * @example Supabase realtime channel as a source\n * ```ts\n * import { createClient } from '@supabase/supabase-js';\n * import { createModule, t } from '@directive-run/core';\n * import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';\n *\n * const supabase = createClient(url, key);\n *\n * const gameUpdates = createModule('gameUpdates', {\n *   schema: {\n *     facts: { snapshot: t.object<GameSnapshot>().nullable() },\n *     events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },\n *   },\n *   init: (f) => { f.snapshot = null; },\n *   events: {\n *     GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; },\n *   },\n *   sources: {\n *     gameChannel: sourceFromSupabaseChannel({\n *       client: supabase,\n *       channel: `game:${gameId}`,\n *       events: [\n *         { table: 'games', filter: `id=eq.${gameId}`, event: 'UPDATE',\n *           map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row) } }) },\n *       ],\n *     }),\n *   },\n * });\n * ```\n *\n * @example Cloudflare DO alarm as a source\n * ```ts\n * import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';\n *\n * // Inside your DurableObject class:\n * const ticker = createModule('ticker', {\n *   schema: {\n *     facts: { lastTick: t.number() },\n *     events: { TICK: { at: t.number() } },\n *   },\n *   init: (f) => { f.lastTick = 0; },\n *   events: { TICK: (f, p) => { f.lastTick = p.at; } },\n *   sources: {\n *     alarm: sourceFromDOAlarm({\n *       storage: this.state.storage,\n *       intervalMs: 30_000,\n *       eventName: 'TICK',\n *       payload: () => ({ at: Date.now() }),\n *     }),\n *   },\n * });\n * ```\n *\n * @packageDocumentation\n */\n\n// The umbrella re-exports nothing concrete — adapters live at the\n// per-vendor subpaths so the optional peerDependency isn't pulled\n// transitively into a consumer that only uses one adapter.\n//\n// Import from:\n//   @directive-run/sources/supabase\n//   @directive-run/sources/cloudflare\n//\n// The subpath import is intentional: tree-shakers cannot reliably\n// eliminate Supabase's runtime if it's re-exported from the umbrella,\n// but a direct subpath import lands only the bytes that subpath\n// actually uses.\n\nexport const VERSION = \"0.1.0\";\n"]}

package/dist/index.d.cts

@@ -0,0 +1,67 @@
+/**
+ * @directive-run/sources
+ *
+ * Source adapters for Directive — wrap external event streams (Supabase
+ * realtime, Cloudflare DO alarms, WebSocket, Sentry, etc.) as typed
+ * `source` primitives. Import vendor adapters from the per-vendor
+ * subpath; only the vendors you import need their peer-dependency
+ * installed.
+ *
+ * @example Supabase realtime channel as a source
+ * ```ts
+ * import { createClient } from '@supabase/supabase-js';
+ * import { createModule, t } from '@directive-run/core';
+ * import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';
+ *
+ * const supabase = createClient(url, key);
+ *
+ * const gameUpdates = createModule('gameUpdates', {
+ *   schema: {
+ *     facts: { snapshot: t.object<GameSnapshot>().nullable() },
+ *     events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },
+ *   },
+ *   init: (f) => { f.snapshot = null; },
+ *   events: {
+ *     GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; },
+ *   },
+ *   sources: {
+ *     gameChannel: sourceFromSupabaseChannel({
+ *       client: supabase,
+ *       channel: `game:${gameId}`,
+ *       events: [
+ *         { table: 'games', filter: `id=eq.${gameId}`, event: 'UPDATE',
+ *           map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row) } }) },
+ *       ],
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @example Cloudflare DO alarm as a source
+ * ```ts
+ * import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';
+ *
+ * // Inside your DurableObject class:
+ * const ticker = createModule('ticker', {
+ *   schema: {
+ *     facts: { lastTick: t.number() },
+ *     events: { TICK: { at: t.number() } },
+ *   },
+ *   init: (f) => { f.lastTick = 0; },
+ *   events: { TICK: (f, p) => { f.lastTick = p.at; } },
+ *   sources: {
+ *     alarm: sourceFromDOAlarm({
+ *       storage: this.state.storage,
+ *       intervalMs: 30_000,
+ *       eventName: 'TICK',
+ *       payload: () => ({ at: Date.now() }),
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+declare const VERSION = "0.1.0";
+
+export { VERSION };

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @directive-run/sources
+ *
+ * Source adapters for Directive — wrap external event streams (Supabase
+ * realtime, Cloudflare DO alarms, WebSocket, Sentry, etc.) as typed
+ * `source` primitives. Import vendor adapters from the per-vendor
+ * subpath; only the vendors you import need their peer-dependency
+ * installed.
+ *
+ * @example Supabase realtime channel as a source
+ * ```ts
+ * import { createClient } from '@supabase/supabase-js';
+ * import { createModule, t } from '@directive-run/core';
+ * import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';
+ *
+ * const supabase = createClient(url, key);
+ *
+ * const gameUpdates = createModule('gameUpdates', {
+ *   schema: {
+ *     facts: { snapshot: t.object<GameSnapshot>().nullable() },
+ *     events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },
+ *   },
+ *   init: (f) => { f.snapshot = null; },
+ *   events: {
+ *     GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; },
+ *   },
+ *   sources: {
+ *     gameChannel: sourceFromSupabaseChannel({
+ *       client: supabase,
+ *       channel: `game:${gameId}`,
+ *       events: [
+ *         { table: 'games', filter: `id=eq.${gameId}`, event: 'UPDATE',
+ *           map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row) } }) },
+ *       ],
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @example Cloudflare DO alarm as a source
+ * ```ts
+ * import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';
+ *
+ * // Inside your DurableObject class:
+ * const ticker = createModule('ticker', {
+ *   schema: {
+ *     facts: { lastTick: t.number() },
+ *     events: { TICK: { at: t.number() } },
+ *   },
+ *   init: (f) => { f.lastTick = 0; },
+ *   events: { TICK: (f, p) => { f.lastTick = p.at; } },
+ *   sources: {
+ *     alarm: sourceFromDOAlarm({
+ *       storage: this.state.storage,
+ *       intervalMs: 30_000,
+ *       eventName: 'TICK',
+ *       payload: () => ({ at: Date.now() }),
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+declare const VERSION = "0.1.0";
+
+export { VERSION };

package/dist/index.js

@@ -0,0 +1,2 @@
+var o="0.1.0";export{o as VERSION};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["VERSION"],"mappings":"AA8EO,IAAMA,CAAAA,CAAU","file":"index.js","sourcesContent":["/**\n * @directive-run/sources\n *\n * Source adapters for Directive — wrap external event streams (Supabase\n * realtime, Cloudflare DO alarms, WebSocket, Sentry, etc.) as typed\n * `source` primitives. Import vendor adapters from the per-vendor\n * subpath; only the vendors you import need their peer-dependency\n * installed.\n *\n * @example Supabase realtime channel as a source\n * ```ts\n * import { createClient } from '@supabase/supabase-js';\n * import { createModule, t } from '@directive-run/core';\n * import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';\n *\n * const supabase = createClient(url, key);\n *\n * const gameUpdates = createModule('gameUpdates', {\n *   schema: {\n *     facts: { snapshot: t.object<GameSnapshot>().nullable() },\n *     events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },\n *   },\n *   init: (f) => { f.snapshot = null; },\n *   events: {\n *     GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; },\n *   },\n *   sources: {\n *     gameChannel: sourceFromSupabaseChannel({\n *       client: supabase,\n *       channel: `game:${gameId}`,\n *       events: [\n *         { table: 'games', filter: `id=eq.${gameId}`, event: 'UPDATE',\n *           map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row) } }) },\n *       ],\n *     }),\n *   },\n * });\n * ```\n *\n * @example Cloudflare DO alarm as a source\n * ```ts\n * import { sourceFromDOAlarm } from '@directive-run/sources/cloudflare';\n *\n * // Inside your DurableObject class:\n * const ticker = createModule('ticker', {\n *   schema: {\n *     facts: { lastTick: t.number() },\n *     events: { TICK: { at: t.number() } },\n *   },\n *   init: (f) => { f.lastTick = 0; },\n *   events: { TICK: (f, p) => { f.lastTick = p.at; } },\n *   sources: {\n *     alarm: sourceFromDOAlarm({\n *       storage: this.state.storage,\n *       intervalMs: 30_000,\n *       eventName: 'TICK',\n *       payload: () => ({ at: Date.now() }),\n *     }),\n *   },\n * });\n * ```\n *\n * @packageDocumentation\n */\n\n// The umbrella re-exports nothing concrete — adapters live at the\n// per-vendor subpaths so the optional peerDependency isn't pulled\n// transitively into a consumer that only uses one adapter.\n//\n// Import from:\n//   @directive-run/sources/supabase\n//   @directive-run/sources/cloudflare\n//\n// The subpath import is intentional: tree-shakers cannot reliably\n// eliminate Supabase's runtime if it's re-exported from the umbrella,\n// but a direct subpath import lands only the bytes that subpath\n// actually uses.\n\nexport const VERSION = \"0.1.0\";\n"]}

package/dist/supabase.cjs

@@ -0,0 +1,2 @@
+'use strict';function b(l){let{client:s,channel:i,events:u,onStatus:c,redactRow:o=a=>a}=l;return {attach:a=>{let n=s.channel(i);for(let e of u)n=n.on("postgres_changes",{event:e.event,schema:e.schema??"public",table:e.table,...e.filter!==void 0?{filter:e.filter}:{}},t=>{let p={...t,new:o(t.new),old:o(t.old)},r=e.map(p);r!==null&&a(r.name,r.payload);});return n.subscribe(e=>c?.(e)),()=>{s.removeChannel(n);}},meta:{label:`Supabase realtime: ${i}`,tags:["source","supabase"]}}}exports.sourceFromSupabaseChannel=b;//# sourceMappingURL=supabase.cjs.map
+//# sourceMappingURL=supabase.cjs.map

package/dist/supabase.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/supabase.ts"],"names":["sourceFromSupabaseChannel","options","client","channelName","events","onStatus","redactRow","row","publish","chan","binding","payload","safe","result","status"],"mappings":"aA8IO,SAASA,CAAAA,CACdC,CAAAA,CACW,CACX,GAAM,CACJ,MAAA,CAAAC,CAAAA,CACA,OAAA,CAASC,CAAAA,CACT,MAAA,CAAAC,CAAAA,CACA,QAAA,CAAAC,CAAAA,CACA,SAAA,CAAAC,CAAAA,CAAaC,CAAAA,EAAQA,CACvB,CAAA,CAAIN,CAAAA,CAEJ,OAAO,CACL,MAAA,CAASO,CAAAA,EAA2B,CAIlC,IAAIC,CAAAA,CAAOP,CAAAA,CAAO,OAAA,CAAQC,CAAW,EACrC,IAAA,IAAWO,CAAAA,IAAWN,CAAAA,CACpBK,CAAAA,CAAOA,CAAAA,CAAK,EAAA,CACV,kBAAA,CACA,CACE,KAAA,CAAOC,CAAAA,CAAQ,KAAA,CACf,MAAA,CAAQA,CAAAA,CAAQ,MAAA,EAAU,QAAA,CAC1B,KAAA,CAAOA,CAAAA,CAAQ,KAAA,CACf,GAAIA,CAAAA,CAAQ,MAAA,GAAW,MAAA,CAAY,CAAE,MAAA,CAAQA,CAAAA,CAAQ,MAAO,CAAA,CAAI,EAClE,CAAA,CACCC,GAAY,CAKX,IAAMC,CAAAA,CAAwB,CAC5B,GAAGD,CAAAA,CACH,GAAA,CAAKL,CAAAA,CAAUK,CAAAA,CAAQ,GAAG,CAAA,CAC1B,GAAA,CAAKL,CAAAA,CAAUK,CAAAA,CAAQ,GAAG,CAC5B,CAAA,CACME,CAAAA,CAASH,CAAAA,CAAQ,GAAA,CAAIE,CAAI,CAAA,CAC3BC,CAAAA,GAAW,IAAA,EACfL,CAAAA,CAAQK,CAAAA,CAAO,IAAA,CAAMA,CAAAA,CAAO,OAAO,EACrC,CACF,CAAA,CAOF,OAAAJ,CAAAA,CAAK,SAAA,CAAWK,CAAAA,EAAWT,CAAAA,GAAWS,CAAM,CAAC,CAAA,CAOtC,IAAM,CACNZ,CAAAA,CAAO,aAAA,CAAcO,CAAI,EAChC,CACF,CAAA,CACA,IAAA,CAAM,CACJ,KAAA,CAAO,CAAA,mBAAA,EAAsBN,CAAW,CAAA,CAAA,CACxC,IAAA,CAAM,CAAC,QAAA,CAAU,UAAU,CAC7B,CACF,CACF","file":"supabase.cjs","sourcesContent":["/**\n * @directive-run/sources/supabase\n *\n * Bridges Supabase realtime channels into the Directive `source` primitive.\n * One factory call → one declared source on your module → the engine\n * owns the subscription lifecycle. No `useEffect` bridges, no manual\n * cleanup, no leaked channels.\n *\n * @example Wire a Supabase realtime channel for a single game row\n * ```ts\n * import { createClient } from '@supabase/supabase-js';\n * import { createModule, t } from '@directive-run/core';\n * import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';\n *\n * const supabase = createClient(url, key);\n *\n * const gameUpdates = createModule('gameUpdates', {\n *   schema: {\n *     facts: { snapshot: t.object<GameSnapshot>().nullable() },\n *     events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },\n *   },\n *   init: (f) => { f.snapshot = null; },\n *   events: { GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; } },\n *   sources: {\n *     gameChannel: sourceFromSupabaseChannel({\n *       client: supabase,\n *       channel: `game:${gameId}`,\n *       events: [{\n *         table: 'games',\n *         filter: `id=eq.${gameId}`,\n *         event: 'UPDATE',\n *         map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row) } }),\n *       }],\n *     }),\n *   },\n * });\n * ```\n */\n\nimport type { SourceDef, SourcePublish } from \"@directive-run/core\";\n\n// ============================================================================\n// Type stubs for the Supabase API surface we touch\n// ============================================================================\n\n// We deliberately do NOT import from `@supabase/supabase-js` so this file\n// type-checks without the optional peerDependency installed. The runtime\n// shape matches Supabase's RealtimeChannel + SupabaseClient surfaces;\n// consumers who install the package get full typing through their own\n// `createClient(...)` instance.\n\ninterface SupabasePayload {\n  schema: string;\n  table: string;\n  commit_timestamp?: string;\n  eventType: \"INSERT\" | \"UPDATE\" | \"DELETE\";\n  new: Record<string, unknown>;\n  old: Record<string, unknown>;\n}\n\ntype SupabaseHandler = (payload: SupabasePayload) => void;\n\ninterface SupabaseRealtimeChannel {\n  on(\n    type: \"postgres_changes\",\n    filter: {\n      event: \"INSERT\" | \"UPDATE\" | \"DELETE\" | \"*\";\n      schema?: string;\n      table?: string;\n      filter?: string;\n    },\n    handler: SupabaseHandler,\n  ): SupabaseRealtimeChannel;\n  subscribe(callback?: (status: string) => void): SupabaseRealtimeChannel;\n  unsubscribe(): Promise<\"ok\" | \"timed out\" | \"error\">;\n}\n\ninterface SupabaseRealtimeClient {\n  channel(name: string): SupabaseRealtimeChannel;\n  removeChannel(\n    channel: SupabaseRealtimeChannel,\n  ): Promise<\"ok\" | \"timed out\" | \"error\">;\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Declarative mapping from a Supabase `postgres_changes` event to a typed\n * Directive event publish. `map` runs on every matching payload; return\n * `null` to skip publishing for that row (useful for soft-filters).\n */\nexport interface SupabaseEventBinding {\n  /** Postgres event type. Use `'*'` for any. */\n  event: \"INSERT\" | \"UPDATE\" | \"DELETE\" | \"*\";\n  /** Table to listen on. */\n  table: string;\n  /** Postgres schema. Default `'public'`. */\n  schema?: string;\n  /** Server-side filter expression (e.g. `id=eq.123`). */\n  filter?: string;\n  /**\n   * Map the Supabase payload to a typed Directive event. Return `null` to\n   * skip this publish (e.g. filter out updates that don't affect the\n   * tracked fields).\n   */\n  map: (\n    payload: SupabasePayload,\n  ) => { name: string; payload: Record<string, unknown> } | null;\n}\n\nexport interface SupabaseChannelOptions {\n  /** The Supabase client (`createClient(url, key)`). */\n  client: SupabaseRealtimeClient;\n  /** Channel name. Must be unique per system instance. */\n  channel: string;\n  /** One or more event bindings on this channel. */\n  events: readonly SupabaseEventBinding[];\n  /**\n   * Optional status hook. Fires with Supabase's connection status\n   * (`'SUBSCRIBED'`, `'CHANNEL_ERROR'`, `'TIMED_OUT'`, `'CLOSED'`).\n   * Wire to your logging / health-check telemetry.\n   */\n  onStatus?: (status: string) => void;\n  /**\n   * Optional pii-redaction hook applied to every payload row BEFORE the\n   * `map` callback runs. Useful for blanking columns the schema author\n   * marked as PII when the consumer's `createFactPIIGuardrail` cannot\n   * reach the field shape (e.g. nested Supabase JSON column).\n   *\n   * Default: identity (no redaction).\n   */\n  redactRow?: (row: Record<string, unknown>) => Record<string, unknown>;\n}\n\n/**\n * Build a `SourceDef` that subscribes to a Supabase realtime channel\n * and publishes typed Directive events for each matching row change.\n *\n * @returns a `SourceDef` to drop into a module's `sources:` map.\n */\nexport function sourceFromSupabaseChannel(\n  options: SupabaseChannelOptions,\n): SourceDef {\n  const {\n    client,\n    channel: channelName,\n    events,\n    onStatus,\n    redactRow = (row) => row,\n  } = options;\n\n  return {\n    attach: (publish: SourcePublish) => {\n      // Build the channel + register every binding. Each binding's\n      // `map` runs on every matching row; the source publishes the\n      // returned Directive event.\n      let chan = client.channel(channelName);\n      for (const binding of events) {\n        chan = chan.on(\n          \"postgres_changes\",\n          {\n            event: binding.event,\n            schema: binding.schema ?? \"public\",\n            table: binding.table,\n            ...(binding.filter !== undefined ? { filter: binding.filter } : {}),\n          },\n          (payload) => {\n            // Redact at the row boundary so the `map` callback (which\n            // typically embeds row fields into the event payload) sees\n            // only the redacted version. The fact-level\n            // createFactPIIGuardrail is the second line of defense.\n            const safe: SupabasePayload = {\n              ...payload,\n              new: redactRow(payload.new),\n              old: redactRow(payload.old),\n            };\n            const result = binding.map(safe);\n            if (result === null) return;\n            publish(result.name, result.payload);\n          },\n        );\n      }\n\n      // Open the subscription. `subscribe()` is async on the wire but\n      // returns the channel synchronously — the status callback fires\n      // once the realtime server acknowledges. Our `attach` contract is\n      // sync; we capture the status callback for the consumer.\n      chan.subscribe((status) => onStatus?.(status));\n\n      // Cleanup: unsubscribe via the client so internal channel registry\n      // is cleared. `removeChannel` returns a Promise; the engine's\n      // current `SourceUnsubscribeFn` is sync — we kick off the cleanup\n      // and let it complete in the background. RFC 0009 widens this to\n      // an awaitable signature.\n      return () => {\n        void client.removeChannel(chan);\n      };\n    },\n    meta: {\n      label: `Supabase realtime: ${channelName}`,\n      tags: [\"source\", \"supabase\"],\n    },\n  };\n}\n"]}

package/dist/supabase.d.cts

@@ -0,0 +1,120 @@
+import { SourceDef } from '@directive-run/core';
+
+/**
+ * @directive-run/sources/supabase
+ *
+ * Bridges Supabase realtime channels into the Directive `source` primitive.
+ * One factory call → one declared source on your module → the engine
+ * owns the subscription lifecycle. No `useEffect` bridges, no manual
+ * cleanup, no leaked channels.
+ *
+ * @example Wire a Supabase realtime channel for a single game row
+ * ```ts
+ * import { createClient } from '@supabase/supabase-js';
+ * import { createModule, t } from '@directive-run/core';
+ * import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';
+ *
+ * const supabase = createClient(url, key);
+ *
+ * const gameUpdates = createModule('gameUpdates', {
+ *   schema: {
+ *     facts: { snapshot: t.object<GameSnapshot>().nullable() },
+ *     events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },
+ *   },
+ *   init: (f) => { f.snapshot = null; },
+ *   events: { GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; } },
+ *   sources: {
+ *     gameChannel: sourceFromSupabaseChannel({
+ *       client: supabase,
+ *       channel: `game:${gameId}`,
+ *       events: [{
+ *         table: 'games',
+ *         filter: `id=eq.${gameId}`,
+ *         event: 'UPDATE',
+ *         map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row) } }),
+ *       }],
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+
+interface SupabasePayload {
+    schema: string;
+    table: string;
+    commit_timestamp?: string;
+    eventType: "INSERT" | "UPDATE" | "DELETE";
+    new: Record<string, unknown>;
+    old: Record<string, unknown>;
+}
+type SupabaseHandler = (payload: SupabasePayload) => void;
+interface SupabaseRealtimeChannel {
+    on(type: "postgres_changes", filter: {
+        event: "INSERT" | "UPDATE" | "DELETE" | "*";
+        schema?: string;
+        table?: string;
+        filter?: string;
+    }, handler: SupabaseHandler): SupabaseRealtimeChannel;
+    subscribe(callback?: (status: string) => void): SupabaseRealtimeChannel;
+    unsubscribe(): Promise<"ok" | "timed out" | "error">;
+}
+interface SupabaseRealtimeClient {
+    channel(name: string): SupabaseRealtimeChannel;
+    removeChannel(channel: SupabaseRealtimeChannel): Promise<"ok" | "timed out" | "error">;
+}
+/**
+ * Declarative mapping from a Supabase `postgres_changes` event to a typed
+ * Directive event publish. `map` runs on every matching payload; return
+ * `null` to skip publishing for that row (useful for soft-filters).
+ */
+interface SupabaseEventBinding {
+    /** Postgres event type. Use `'*'` for any. */
+    event: "INSERT" | "UPDATE" | "DELETE" | "*";
+    /** Table to listen on. */
+    table: string;
+    /** Postgres schema. Default `'public'`. */
+    schema?: string;
+    /** Server-side filter expression (e.g. `id=eq.123`). */
+    filter?: string;
+    /**
+     * Map the Supabase payload to a typed Directive event. Return `null` to
+     * skip this publish (e.g. filter out updates that don't affect the
+     * tracked fields).
+     */
+    map: (payload: SupabasePayload) => {
+        name: string;
+        payload: Record<string, unknown>;
+    } | null;
+}
+interface SupabaseChannelOptions {
+    /** The Supabase client (`createClient(url, key)`). */
+    client: SupabaseRealtimeClient;
+    /** Channel name. Must be unique per system instance. */
+    channel: string;
+    /** One or more event bindings on this channel. */
+    events: readonly SupabaseEventBinding[];
+    /**
+     * Optional status hook. Fires with Supabase's connection status
+     * (`'SUBSCRIBED'`, `'CHANNEL_ERROR'`, `'TIMED_OUT'`, `'CLOSED'`).
+     * Wire to your logging / health-check telemetry.
+     */
+    onStatus?: (status: string) => void;
+    /**
+     * Optional pii-redaction hook applied to every payload row BEFORE the
+     * `map` callback runs. Useful for blanking columns the schema author
+     * marked as PII when the consumer's `createFactPIIGuardrail` cannot
+     * reach the field shape (e.g. nested Supabase JSON column).
+     *
+     * Default: identity (no redaction).
+     */
+    redactRow?: (row: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Build a `SourceDef` that subscribes to a Supabase realtime channel
+ * and publishes typed Directive events for each matching row change.
+ *
+ * @returns a `SourceDef` to drop into a module's `sources:` map.
+ */
+declare function sourceFromSupabaseChannel(options: SupabaseChannelOptions): SourceDef;
+
+export { type SupabaseChannelOptions, type SupabaseEventBinding, sourceFromSupabaseChannel };

package/dist/supabase.d.ts

@@ -0,0 +1,120 @@
+import { SourceDef } from '@directive-run/core';
+
+/**
+ * @directive-run/sources/supabase
+ *
+ * Bridges Supabase realtime channels into the Directive `source` primitive.
+ * One factory call → one declared source on your module → the engine
+ * owns the subscription lifecycle. No `useEffect` bridges, no manual
+ * cleanup, no leaked channels.
+ *
+ * @example Wire a Supabase realtime channel for a single game row
+ * ```ts
+ * import { createClient } from '@supabase/supabase-js';
+ * import { createModule, t } from '@directive-run/core';
+ * import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';
+ *
+ * const supabase = createClient(url, key);
+ *
+ * const gameUpdates = createModule('gameUpdates', {
+ *   schema: {
+ *     facts: { snapshot: t.object<GameSnapshot>().nullable() },
+ *     events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },
+ *   },
+ *   init: (f) => { f.snapshot = null; },
+ *   events: { GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; } },
+ *   sources: {
+ *     gameChannel: sourceFromSupabaseChannel({
+ *       client: supabase,
+ *       channel: `game:${gameId}`,
+ *       events: [{
+ *         table: 'games',
+ *         filter: `id=eq.${gameId}`,
+ *         event: 'UPDATE',
+ *         map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row) } }),
+ *       }],
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+
+interface SupabasePayload {
+    schema: string;
+    table: string;
+    commit_timestamp?: string;
+    eventType: "INSERT" | "UPDATE" | "DELETE";
+    new: Record<string, unknown>;
+    old: Record<string, unknown>;
+}
+type SupabaseHandler = (payload: SupabasePayload) => void;
+interface SupabaseRealtimeChannel {
+    on(type: "postgres_changes", filter: {
+        event: "INSERT" | "UPDATE" | "DELETE" | "*";
+        schema?: string;
+        table?: string;
+        filter?: string;
+    }, handler: SupabaseHandler): SupabaseRealtimeChannel;
+    subscribe(callback?: (status: string) => void): SupabaseRealtimeChannel;
+    unsubscribe(): Promise<"ok" | "timed out" | "error">;
+}
+interface SupabaseRealtimeClient {
+    channel(name: string): SupabaseRealtimeChannel;
+    removeChannel(channel: SupabaseRealtimeChannel): Promise<"ok" | "timed out" | "error">;
+}
+/**
+ * Declarative mapping from a Supabase `postgres_changes` event to a typed
+ * Directive event publish. `map` runs on every matching payload; return
+ * `null` to skip publishing for that row (useful for soft-filters).
+ */
+interface SupabaseEventBinding {
+    /** Postgres event type. Use `'*'` for any. */
+    event: "INSERT" | "UPDATE" | "DELETE" | "*";
+    /** Table to listen on. */
+    table: string;
+    /** Postgres schema. Default `'public'`. */
+    schema?: string;
+    /** Server-side filter expression (e.g. `id=eq.123`). */
+    filter?: string;
+    /**
+     * Map the Supabase payload to a typed Directive event. Return `null` to
+     * skip this publish (e.g. filter out updates that don't affect the
+     * tracked fields).
+     */
+    map: (payload: SupabasePayload) => {
+        name: string;
+        payload: Record<string, unknown>;
+    } | null;
+}
+interface SupabaseChannelOptions {
+    /** The Supabase client (`createClient(url, key)`). */
+    client: SupabaseRealtimeClient;
+    /** Channel name. Must be unique per system instance. */
+    channel: string;
+    /** One or more event bindings on this channel. */
+    events: readonly SupabaseEventBinding[];
+    /**
+     * Optional status hook. Fires with Supabase's connection status
+     * (`'SUBSCRIBED'`, `'CHANNEL_ERROR'`, `'TIMED_OUT'`, `'CLOSED'`).
+     * Wire to your logging / health-check telemetry.
+     */
+    onStatus?: (status: string) => void;
+    /**
+     * Optional pii-redaction hook applied to every payload row BEFORE the
+     * `map` callback runs. Useful for blanking columns the schema author
+     * marked as PII when the consumer's `createFactPIIGuardrail` cannot
+     * reach the field shape (e.g. nested Supabase JSON column).
+     *
+     * Default: identity (no redaction).
+     */
+    redactRow?: (row: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Build a `SourceDef` that subscribes to a Supabase realtime channel
+ * and publishes typed Directive events for each matching row change.
+ *
+ * @returns a `SourceDef` to drop into a module's `sources:` map.
+ */
+declare function sourceFromSupabaseChannel(options: SupabaseChannelOptions): SourceDef;
+
+export { type SupabaseChannelOptions, type SupabaseEventBinding, sourceFromSupabaseChannel };

package/dist/supabase.js

@@ -0,0 +1,2 @@
+function b(l){let{client:s,channel:i,events:u,onStatus:c,redactRow:o=a=>a}=l;return {attach:a=>{let n=s.channel(i);for(let e of u)n=n.on("postgres_changes",{event:e.event,schema:e.schema??"public",table:e.table,...e.filter!==void 0?{filter:e.filter}:{}},t=>{let p={...t,new:o(t.new),old:o(t.old)},r=e.map(p);r!==null&&a(r.name,r.payload);});return n.subscribe(e=>c?.(e)),()=>{s.removeChannel(n);}},meta:{label:`Supabase realtime: ${i}`,tags:["source","supabase"]}}}export{b as sourceFromSupabaseChannel};//# sourceMappingURL=supabase.js.map
+//# sourceMappingURL=supabase.js.map

package/dist/supabase.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/supabase.ts"],"names":["sourceFromSupabaseChannel","options","client","channelName","events","onStatus","redactRow","row","publish","chan","binding","payload","safe","result","status"],"mappings":"AA8IO,SAASA,CAAAA,CACdC,CAAAA,CACW,CACX,GAAM,CACJ,MAAA,CAAAC,CAAAA,CACA,OAAA,CAASC,CAAAA,CACT,MAAA,CAAAC,CAAAA,CACA,QAAA,CAAAC,CAAAA,CACA,SAAA,CAAAC,CAAAA,CAAaC,CAAAA,EAAQA,CACvB,CAAA,CAAIN,CAAAA,CAEJ,OAAO,CACL,MAAA,CAASO,CAAAA,EAA2B,CAIlC,IAAIC,CAAAA,CAAOP,CAAAA,CAAO,OAAA,CAAQC,CAAW,EACrC,IAAA,IAAWO,CAAAA,IAAWN,CAAAA,CACpBK,CAAAA,CAAOA,CAAAA,CAAK,EAAA,CACV,kBAAA,CACA,CACE,KAAA,CAAOC,CAAAA,CAAQ,KAAA,CACf,MAAA,CAAQA,CAAAA,CAAQ,MAAA,EAAU,QAAA,CAC1B,KAAA,CAAOA,CAAAA,CAAQ,KAAA,CACf,GAAIA,CAAAA,CAAQ,MAAA,GAAW,MAAA,CAAY,CAAE,MAAA,CAAQA,CAAAA,CAAQ,MAAO,CAAA,CAAI,EAClE,CAAA,CACCC,GAAY,CAKX,IAAMC,CAAAA,CAAwB,CAC5B,GAAGD,CAAAA,CACH,GAAA,CAAKL,CAAAA,CAAUK,CAAAA,CAAQ,GAAG,CAAA,CAC1B,GAAA,CAAKL,CAAAA,CAAUK,CAAAA,CAAQ,GAAG,CAC5B,CAAA,CACME,CAAAA,CAASH,CAAAA,CAAQ,GAAA,CAAIE,CAAI,CAAA,CAC3BC,CAAAA,GAAW,IAAA,EACfL,CAAAA,CAAQK,CAAAA,CAAO,IAAA,CAAMA,CAAAA,CAAO,OAAO,EACrC,CACF,CAAA,CAOF,OAAAJ,CAAAA,CAAK,SAAA,CAAWK,CAAAA,EAAWT,CAAAA,GAAWS,CAAM,CAAC,CAAA,CAOtC,IAAM,CACNZ,CAAAA,CAAO,aAAA,CAAcO,CAAI,EAChC,CACF,CAAA,CACA,IAAA,CAAM,CACJ,KAAA,CAAO,CAAA,mBAAA,EAAsBN,CAAW,CAAA,CAAA,CACxC,IAAA,CAAM,CAAC,QAAA,CAAU,UAAU,CAC7B,CACF,CACF","file":"supabase.js","sourcesContent":["/**\n * @directive-run/sources/supabase\n *\n * Bridges Supabase realtime channels into the Directive `source` primitive.\n * One factory call → one declared source on your module → the engine\n * owns the subscription lifecycle. No `useEffect` bridges, no manual\n * cleanup, no leaked channels.\n *\n * @example Wire a Supabase realtime channel for a single game row\n * ```ts\n * import { createClient } from '@supabase/supabase-js';\n * import { createModule, t } from '@directive-run/core';\n * import { sourceFromSupabaseChannel } from '@directive-run/sources/supabase';\n *\n * const supabase = createClient(url, key);\n *\n * const gameUpdates = createModule('gameUpdates', {\n *   schema: {\n *     facts: { snapshot: t.object<GameSnapshot>().nullable() },\n *     events: { GAME_UPDATED: { snapshot: t.object<GameSnapshot>() } },\n *   },\n *   init: (f) => { f.snapshot = null; },\n *   events: { GAME_UPDATED: (f, p) => { f.snapshot = p.snapshot; } },\n *   sources: {\n *     gameChannel: sourceFromSupabaseChannel({\n *       client: supabase,\n *       channel: `game:${gameId}`,\n *       events: [{\n *         table: 'games',\n *         filter: `id=eq.${gameId}`,\n *         event: 'UPDATE',\n *         map: (row) => ({ name: 'GAME_UPDATED', payload: { snapshot: mapRow(row) } }),\n *       }],\n *     }),\n *   },\n * });\n * ```\n */\n\nimport type { SourceDef, SourcePublish } from \"@directive-run/core\";\n\n// ============================================================================\n// Type stubs for the Supabase API surface we touch\n// ============================================================================\n\n// We deliberately do NOT import from `@supabase/supabase-js` so this file\n// type-checks without the optional peerDependency installed. The runtime\n// shape matches Supabase's RealtimeChannel + SupabaseClient surfaces;\n// consumers who install the package get full typing through their own\n// `createClient(...)` instance.\n\ninterface SupabasePayload {\n  schema: string;\n  table: string;\n  commit_timestamp?: string;\n  eventType: \"INSERT\" | \"UPDATE\" | \"DELETE\";\n  new: Record<string, unknown>;\n  old: Record<string, unknown>;\n}\n\ntype SupabaseHandler = (payload: SupabasePayload) => void;\n\ninterface SupabaseRealtimeChannel {\n  on(\n    type: \"postgres_changes\",\n    filter: {\n      event: \"INSERT\" | \"UPDATE\" | \"DELETE\" | \"*\";\n      schema?: string;\n      table?: string;\n      filter?: string;\n    },\n    handler: SupabaseHandler,\n  ): SupabaseRealtimeChannel;\n  subscribe(callback?: (status: string) => void): SupabaseRealtimeChannel;\n  unsubscribe(): Promise<\"ok\" | \"timed out\" | \"error\">;\n}\n\ninterface SupabaseRealtimeClient {\n  channel(name: string): SupabaseRealtimeChannel;\n  removeChannel(\n    channel: SupabaseRealtimeChannel,\n  ): Promise<\"ok\" | \"timed out\" | \"error\">;\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Declarative mapping from a Supabase `postgres_changes` event to a typed\n * Directive event publish. `map` runs on every matching payload; return\n * `null` to skip publishing for that row (useful for soft-filters).\n */\nexport interface SupabaseEventBinding {\n  /** Postgres event type. Use `'*'` for any. */\n  event: \"INSERT\" | \"UPDATE\" | \"DELETE\" | \"*\";\n  /** Table to listen on. */\n  table: string;\n  /** Postgres schema. Default `'public'`. */\n  schema?: string;\n  /** Server-side filter expression (e.g. `id=eq.123`). */\n  filter?: string;\n  /**\n   * Map the Supabase payload to a typed Directive event. Return `null` to\n   * skip this publish (e.g. filter out updates that don't affect the\n   * tracked fields).\n   */\n  map: (\n    payload: SupabasePayload,\n  ) => { name: string; payload: Record<string, unknown> } | null;\n}\n\nexport interface SupabaseChannelOptions {\n  /** The Supabase client (`createClient(url, key)`). */\n  client: SupabaseRealtimeClient;\n  /** Channel name. Must be unique per system instance. */\n  channel: string;\n  /** One or more event bindings on this channel. */\n  events: readonly SupabaseEventBinding[];\n  /**\n   * Optional status hook. Fires with Supabase's connection status\n   * (`'SUBSCRIBED'`, `'CHANNEL_ERROR'`, `'TIMED_OUT'`, `'CLOSED'`).\n   * Wire to your logging / health-check telemetry.\n   */\n  onStatus?: (status: string) => void;\n  /**\n   * Optional pii-redaction hook applied to every payload row BEFORE the\n   * `map` callback runs. Useful for blanking columns the schema author\n   * marked as PII when the consumer's `createFactPIIGuardrail` cannot\n   * reach the field shape (e.g. nested Supabase JSON column).\n   *\n   * Default: identity (no redaction).\n   */\n  redactRow?: (row: Record<string, unknown>) => Record<string, unknown>;\n}\n\n/**\n * Build a `SourceDef` that subscribes to a Supabase realtime channel\n * and publishes typed Directive events for each matching row change.\n *\n * @returns a `SourceDef` to drop into a module's `sources:` map.\n */\nexport function sourceFromSupabaseChannel(\n  options: SupabaseChannelOptions,\n): SourceDef {\n  const {\n    client,\n    channel: channelName,\n    events,\n    onStatus,\n    redactRow = (row) => row,\n  } = options;\n\n  return {\n    attach: (publish: SourcePublish) => {\n      // Build the channel + register every binding. Each binding's\n      // `map` runs on every matching row; the source publishes the\n      // returned Directive event.\n      let chan = client.channel(channelName);\n      for (const binding of events) {\n        chan = chan.on(\n          \"postgres_changes\",\n          {\n            event: binding.event,\n            schema: binding.schema ?? \"public\",\n            table: binding.table,\n            ...(binding.filter !== undefined ? { filter: binding.filter } : {}),\n          },\n          (payload) => {\n            // Redact at the row boundary so the `map` callback (which\n            // typically embeds row fields into the event payload) sees\n            // only the redacted version. The fact-level\n            // createFactPIIGuardrail is the second line of defense.\n            const safe: SupabasePayload = {\n              ...payload,\n              new: redactRow(payload.new),\n              old: redactRow(payload.old),\n            };\n            const result = binding.map(safe);\n            if (result === null) return;\n            publish(result.name, result.payload);\n          },\n        );\n      }\n\n      // Open the subscription. `subscribe()` is async on the wire but\n      // returns the channel synchronously — the status callback fires\n      // once the realtime server acknowledges. Our `attach` contract is\n      // sync; we capture the status callback for the consumer.\n      chan.subscribe((status) => onStatus?.(status));\n\n      // Cleanup: unsubscribe via the client so internal channel registry\n      // is cleared. `removeChannel` returns a Promise; the engine's\n      // current `SourceUnsubscribeFn` is sync — we kick off the cleanup\n      // and let it complete in the background. RFC 0009 widens this to\n      // an awaitable signature.\n      return () => {\n        void client.removeChannel(chan);\n      };\n    },\n    meta: {\n      label: `Supabase realtime: ${channelName}`,\n      tags: [\"source\", \"supabase\"],\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@directive-run/sources",
+  "version": "0.2.0",
+  "description": "Source adapters for Directive — wrap Supabase realtime, Cloudflare DO alarms, WebSocket, Sentry, etc. as typed `source` primitives. One package, one install, subpath exports per vendor.",
+  "license": "(MIT OR Apache-2.0)",
+  "author": "Jason Comes",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/directive-run/directive",
+    "directory": "packages/sources"
+  },
+  "homepage": "https://directive.run",
+  "bugs": {
+    "url": "https://github.com/directive-run/directive/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "directive",
+    "source",
+    "supabase",
+    "cloudflare",
+    "realtime",
+    "websocket",
+    "state-management"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./supabase": {
+      "types": "./dist/supabase.d.ts",
+      "require": "./dist/supabase.cjs",
+      "import": "./dist/supabase.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "require": "./dist/cloudflare.cjs",
+      "import": "./dist/cloudflare.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@directive-run/core": "^1.2.0",
+    "@supabase/supabase-js": "^2.0.0",
+    "@cloudflare/workers-types": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "@cloudflare/workers-types": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.9",
+    "@directive-run/core": "1.18.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}