@shware/workflow 0.0.0-stage → 0.1.0

package/dist/cloudflare/runner.cjs

@@ -0,0 +1,225 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contract = require("../contract.cjs");
+const require_runtime = require("../runtime.cjs");
+const require_cloudflare_bindings = require("./bindings.cjs");
+const require_store_facts = require("../store/facts.cjs");
+const require_cloudflare_d1_env = require("./d1-env.cjs");
+const require_cloudflare_router = require("./router.cjs");
+const require_cloudflare_senders = require("./senders.cjs");
+const require_engine_actions = require("../engine/actions.cjs");
+const require_engine_interpreter = require("../engine/interpreter.cjs");
+const require_engine_time_scale = require("../engine/time-scale.cjs");
+let cloudflare_workers = require("cloudflare:workers");
+let cloudflare_workflows = require("cloudflare:workflows");
+//#region src/cloudflare/runner.ts
+/**
+* Adapts CF's WorkflowStep to EngineStep.
+* subscribe/unsubscribe write the subscription table inside durable steps (the
+* router wakes instances from that table); waitForWake parks on CF's
+* waitForEvent, which signals a timeout by throwing — and so does every other
+* failure in there, so only the clock can tell them apart (see wakeExpired).
+*/
+/** Refusals a retry would only repeat: a template's props, an emitted event's payload. */
+const NON_RETRYABLE = /* @__PURE__ */ new Set(["TemplateValidationError", "ContractValidationError"]);
+var CfEngineStep = class {
+	step;
+	store;
+	userId;
+	instanceId;
+	constructor(step, store, userId, instanceId) {
+		this.step = step;
+		this.store = store;
+		this.userId = userId;
+		this.instanceId = instanceId;
+	}
+	/**
+	* A template refusing its props, or the contract refusing an emitted event,
+	* is deterministic — a retry hits the same refusal — so it ends the step at
+	* once instead of burning the retry budget.
+	*/
+	do(name, fn) {
+		return this.step.do(name, async () => {
+			try {
+				return await fn();
+			} catch (error) {
+				if (error instanceof Error && NON_RETRYABLE.has(error.name)) throw new cloudflare_workflows.NonRetryableError(error.message, error.name);
+				throw error;
+			}
+		});
+	}
+	sleep(name, ms) {
+		return this.step.sleep(name, ms);
+	}
+	sleepUntil(name, timestampMs) {
+		return this.step.sleepUntil(name, timestampMs);
+	}
+	subscribe(name, events) {
+		return this.step.do(name, () => this.store.subscribe(this.instanceId, this.userId, events, Date.now()));
+	}
+	unsubscribe(name) {
+		return this.step.do(name, () => this.store.unsubscribe(this.instanceId));
+	}
+	async waitForWake(name, timeoutMs) {
+		const startedAt = Date.now();
+		try {
+			await this.step.waitForEvent(name, {
+				type: require_cloudflare_bindings.WAKE_EVENT_TYPE,
+				timeout: timeoutMs
+			});
+			return "event";
+		} catch (error) {
+			if (await this.step.do(`${name}:timed-out`, async () => require_cloudflare_bindings.wakeExpired(startedAt, timeoutMs, Date.now()))) return "timeout";
+			throw error;
+		}
+	}
+};
+/** Development aid: echo each outbound message before handing it to the real sender. */
+function logging(sender) {
+	return { async send(message) {
+		console.log(`[journey] ${message.channel} ${message.template} → ${message.recipient ?? message.userId} ${JSON.stringify(message.props)}`);
+		return sender.send(message);
+	} };
+}
+/**
+* The generic journey executor: one class runs every workflow, because IR is
+* data. It is loaded from the store by the contentHash pinned at entry —
+* content addressing makes it immutable, so reading it outside a step is
+* replay-safe.
+*/
+var JourneyRunner = class extends cloudflare_workers.WorkflowEntrypoint {
+	/**
+	* The data plane. D1 + KV from the env by default; an app on Postgres
+	* overrides this (and `closeStore` if its client needs closing):
+	*
+	*   protected override createStore() { return new PostgresJourneyStore(client(this.env)); }
+	*/
+	createStore() {
+		return require_cloudflare_d1_env.d1Store(this.env);
+	}
+	/** Called once `run` is over, success or not — release whatever `createStore` opened. */
+	async closeStore(_store) {}
+	/**
+	* Runtime options for this instance — typed configuration, resolved by the app (typically
+	* `resolveRuntime(config.runtime, mode)` over its workflow.config.ts, with the mode coming from
+	* an ENVIRONMENT var). The instance params are passed so the decision can also be per user:
+	* a tester account in production can run in fast-forward while everyone else runs in real
+	* time. Defaults: real time, quiet.
+	*
+	*   protected override runtime({ userId }) {
+	*     return resolveRuntime(workflowConfig.runtime, isTester(userId) ? 'test' : this.env.ENVIRONMENT);
+	*   }
+	*/
+	runtime(_params) {
+		return require_runtime.resolveRuntime(void 0, "production");
+	}
+	/**
+	* Message outlet; an app overrides this to plug in real channels (say
+	* CfEmailSender with a react-email renderer). By default it picks the webhook
+	* or logging sender based on the environment.
+	*/
+	createMessageSender() {
+		return this.env.MESSAGE_WEBHOOK_URL ? new require_cloudflare_senders.WebhookMessageSender(this.env.MESSAGE_WEBHOOK_URL) : new require_cloudflare_senders.LogMessageSender();
+	}
+	/**
+	* Custom-action registry; an app overrides this returning the same
+	* `action(...)` objects its workflows reference (an ActionRef is a
+	* RegisteredAction structurally) — the code plane of the dual-plane model:
+	*
+	*   protected override actions() { return [syncCrm, issueCoupon]; }
+	*/
+	actions() {
+		return [];
+	}
+	/**
+	* The contract events this journey emits (`.sendEvent()`) are checked
+	* against, exactly like ingest; journeyWorker passes its config's.
+	*/
+	contract() {}
+	/**
+	* Template props check before every send; an app overrides this with
+	* `registryValidator({ emails, pushes })` (journeyWorker does it from its
+	* registries). By default props go out as resolved.
+	*/
+	createMessageValidator() {}
+	/**
+	* Reporting hooks: node arrivals, every copy sent, how each instance ended. The host stores
+	* what it needs for its dashboards; by default nothing is reported.
+	*/
+	createObserver(_store) {}
+	/** Override for a different version policy ('warn' by default) or a fully custom invoker (e.g. webhook degradation for hosted tenants). */
+	createActionInvoker() {
+		return new require_engine_actions.RegistryActionInvoker(this.actions());
+	}
+	async run(event, step) {
+		const store = this.createStore();
+		try {
+			return await this.execute(event, step, store);
+		} finally {
+			await this.closeStore(store);
+		}
+	}
+	async execute(event, step, store) {
+		const { workflowId, contentHash, userId } = event.payload;
+		const env = this.env;
+		const stored = await store.getWorkflowIR(contentHash);
+		if (stored === void 0) throw new Error(`WorkflowIR not found: ${workflowId}@${contentHash}`);
+		const runtime = require_runtime.resolveRuntime({ current: this.runtime(event.payload) }, "current");
+		const ir = require_engine_time_scale.scaleDurations(stored, runtime.timeScale);
+		const observer = this.createObserver(store);
+		const finished = (status, convertedAt) => observer?.finished?.({
+			workflow: workflowId,
+			instanceId: event.instanceId,
+			userId,
+			status,
+			at: Date.now(),
+			...convertedAt === void 0 ? {} : { convertedAt }
+		});
+		const messages = runtime.logMessages ? logging(this.createMessageSender()) : this.createMessageSender();
+		const contract = this.contract();
+		const events = { emit: async (name, payload, id) => {
+			let accepted = payload;
+			if (contract !== void 0) {
+				const verdict = require_contract.checkEvent(contract, name, payload);
+				if (!verdict.ok) throw new require_contract.ContractValidationError(name, verdict.issues);
+				accepted = verdict.data;
+			}
+			await require_cloudflare_router.ingestEvent(env, {
+				id,
+				userId,
+				event: name,
+				payload: accepted
+			}, store);
+		} };
+		let outcome;
+		try {
+			outcome = await require_engine_interpreter.runJourney(ir, {
+				userId,
+				instanceId: event.instanceId,
+				enteredAtMs: event.timestamp.getTime(),
+				step: new CfEngineStep(step, store, userId, event.instanceId),
+				facts: new require_store_facts.JourneyFactSource(store, userId),
+				messages,
+				events,
+				actions: this.createActionInvoker(),
+				validator: this.createMessageValidator(),
+				observer
+			});
+		} catch (error) {
+			await step.do("finalize:failed", async () => {
+				await store.setEntryStatus(event.instanceId, "failed");
+				await finished("failed");
+			});
+			throw error;
+		}
+		await step.do("finalize", async () => {
+			await store.setEntryStatus(event.instanceId, outcome.status);
+			await store.unsubscribe(event.instanceId);
+			await finished(outcome.status, outcome.convertedAt);
+		});
+		return outcome;
+	}
+};
+//#endregion
+exports.JourneyRunner = JourneyRunner;
+
+//# sourceMappingURL=runner.cjs.map

package/dist/cloudflare/runner.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.cjs","names":["NonRetryableError","WAKE_EVENT_TYPE","wakeExpired","WorkflowEntrypoint","d1Store","resolveRuntime","WebhookMessageSender","LogMessageSender","RegistryActionInvoker","scaleDurations","checkEvent","ContractValidationError","ingestEvent","runJourney","JourneyFactSource"],"sources":["../../src/cloudflare/runner.ts"],"sourcesContent":["import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from 'cloudflare:workers';\nimport { NonRetryableError } from 'cloudflare:workflows';\nimport { type Contract, ContractValidationError, checkEvent } from '../contract';\nimport { type RegisteredAction, RegistryActionInvoker } from '../engine/actions';\nimport { runJourney } from '../engine/interpreter';\nimport type {\n  ActionInvoker,\n  EngineStep,\n  EventSink,\n  JourneyObserver,\n  JourneyOutcome,\n  MessageSender,\n  MessageValidator,\n} from '../engine/ports';\nimport { scaleDurations } from '../engine/time-scale';\nimport { type JourneyRuntimeOptions, resolveRuntime } from '../runtime';\nimport { JourneyFactSource } from '../store/facts';\nimport type { JourneyStore } from '../store/index';\nimport { type JourneyEnv, type JourneyParams, WAKE_EVENT_TYPE, wakeExpired } from './bindings';\nimport { d1Store } from './d1-env';\nimport { ingestEvent } from './router';\nimport { LogMessageSender, WebhookMessageSender } from './senders';\n\n/**\n * Adapts CF's WorkflowStep to EngineStep.\n * subscribe/unsubscribe write the subscription table inside durable steps (the\n * router wakes instances from that table); waitForWake parks on CF's\n * waitForEvent, which signals a timeout by throwing — and so does every other\n * failure in there, so only the clock can tell them apart (see wakeExpired).\n */\n/** Refusals a retry would only repeat: a template's props, an emitted event's payload. */\nconst NON_RETRYABLE = new Set(['TemplateValidationError', 'ContractValidationError']);\n\nclass CfEngineStep implements EngineStep {\n  constructor(\n    private readonly step: WorkflowStep,\n    private readonly store: JourneyStore,\n    private readonly userId: string,\n    private readonly instanceId: string\n  ) {}\n\n  /**\n   * A template refusing its props, or the contract refusing an emitted event,\n   * is deterministic — a retry hits the same refusal — so it ends the step at\n   * once instead of burning the retry budget.\n   */\n  do<T>(name: string, fn: () => Promise<T>): Promise<T> {\n    return this.step.do(name, async () => {\n      try {\n        return await fn();\n      } catch (error) {\n        if (error instanceof Error && NON_RETRYABLE.has(error.name)) {\n          throw new NonRetryableError(error.message, error.name);\n        }\n        throw error;\n      }\n    });\n  }\n\n  sleep(name: string, ms: number): Promise<void> {\n    return this.step.sleep(name, ms);\n  }\n\n  sleepUntil(name: string, timestampMs: number): Promise<void> {\n    return this.step.sleepUntil(name, timestampMs);\n  }\n\n  subscribe(name: string, events: readonly string[]): Promise<void> {\n    // Idempotent in the store: the interpreter re-subscribes on every wait\n    // attempt (one-shot-callback contract) and registrations persist here.\n    return this.step.do(name, () =>\n      this.store.subscribe(this.instanceId, this.userId, events, Date.now())\n    );\n  }\n\n  unsubscribe(name: string): Promise<void> {\n    return this.step.do(name, () => this.store.unsubscribe(this.instanceId));\n  }\n\n  async waitForWake(name: string, timeoutMs: number): Promise<'event' | 'timeout'> {\n    const startedAt = Date.now();\n    try {\n      await this.step.waitForEvent(name, { type: WAKE_EVENT_TYPE, timeout: timeoutMs });\n      return 'event';\n    } catch (error) {\n      /*\n       * Only the deadline can tell a real timeout from a failure (see\n       * wakeExpired). `startedAt` is not replay-stable, but it is read only\n       * inside the step body below, and a step body runs on the live attempt\n       * alone — a replay returns the persisted verdict without touching the\n       * clock.\n       */\n      const timedOut = await this.step.do(`${name}:timed-out`, async () =>\n        wakeExpired(startedAt, timeoutMs, Date.now())\n      );\n      if (timedOut) return 'timeout';\n      throw error;\n    }\n  }\n}\n\n/** Development aid: echo each outbound message before handing it to the real sender. */\nfunction logging(sender: MessageSender): MessageSender {\n  return {\n    async send(message) {\n      console.log(\n        `[journey] ${message.channel} ${message.template} → ${message.recipient ?? message.userId} ${JSON.stringify(message.props)}`\n      );\n      return sender.send(message);\n    },\n  };\n}\n\n/**\n * The generic journey executor: one class runs every workflow, because IR is\n * data. It is loaded from the store by the contentHash pinned at entry —\n * content addressing makes it immutable, so reading it outside a step is\n * replay-safe.\n */\nexport class JourneyRunner extends WorkflowEntrypoint<JourneyEnv, JourneyParams> {\n  /**\n   * The data plane. D1 + KV from the env by default; an app on Postgres\n   * overrides this (and `closeStore` if its client needs closing):\n   *\n   *   protected override createStore() { return new PostgresJourneyStore(client(this.env)); }\n   */\n  protected createStore(): JourneyStore {\n    return d1Store(this.env);\n  }\n\n  /** Called once `run` is over, success or not — release whatever `createStore` opened. */\n  protected async closeStore(_store: JourneyStore): Promise<void> {}\n\n  /**\n   * Runtime options for this instance — typed configuration, resolved by the app (typically\n   * `resolveRuntime(config.runtime, mode)` over its workflow.config.ts, with the mode coming from\n   * an ENVIRONMENT var). The instance params are passed so the decision can also be per user:\n   * a tester account in production can run in fast-forward while everyone else runs in real\n   * time. Defaults: real time, quiet.\n   *\n   *   protected override runtime({ userId }) {\n   *     return resolveRuntime(workflowConfig.runtime, isTester(userId) ? 'test' : this.env.ENVIRONMENT);\n   *   }\n   */\n  protected runtime(_params: JourneyParams): JourneyRuntimeOptions {\n    return resolveRuntime(undefined, 'production');\n  }\n\n  /**\n   * Message outlet; an app overrides this to plug in real channels (say\n   * CfEmailSender with a react-email renderer). By default it picks the webhook\n   * or logging sender based on the environment.\n   */\n  protected createMessageSender(): MessageSender {\n    return this.env.MESSAGE_WEBHOOK_URL\n      ? new WebhookMessageSender(this.env.MESSAGE_WEBHOOK_URL)\n      : new LogMessageSender();\n  }\n\n  /**\n   * Custom-action registry; an app overrides this returning the same\n   * `action(...)` objects its workflows reference (an ActionRef is a\n   * RegisteredAction structurally) — the code plane of the dual-plane model:\n   *\n   *   protected override actions() { return [syncCrm, issueCoupon]; }\n   */\n  protected actions(): readonly RegisteredAction[] {\n    return [];\n  }\n\n  /**\n   * The contract events this journey emits (`.sendEvent()`) are checked\n   * against, exactly like ingest; journeyWorker passes its config's.\n   */\n  protected contract(): Contract | undefined {\n    return undefined;\n  }\n\n  /**\n   * Template props check before every send; an app overrides this with\n   * `registryValidator({ emails, pushes })` (journeyWorker does it from its\n   * registries). By default props go out as resolved.\n   */\n  protected createMessageValidator(): MessageValidator | undefined {\n    return undefined;\n  }\n\n  /**\n   * Reporting hooks: node arrivals, every copy sent, how each instance ended. The host stores\n   * what it needs for its dashboards; by default nothing is reported.\n   */\n  protected createObserver(_store: JourneyStore): JourneyObserver | undefined {\n    return undefined;\n  }\n\n  /** Override for a different version policy ('warn' by default) or a fully custom invoker (e.g. webhook degradation for hosted tenants). */\n  protected createActionInvoker(): ActionInvoker {\n    return new RegistryActionInvoker(this.actions());\n  }\n\n  async run(event: WorkflowEvent<JourneyParams>, step: WorkflowStep): Promise<JourneyOutcome> {\n    const store = this.createStore();\n    try {\n      return await this.execute(event, step, store);\n    } finally {\n      await this.closeStore(store);\n    }\n  }\n\n  private async execute(\n    event: WorkflowEvent<JourneyParams>,\n    step: WorkflowStep,\n    store: JourneyStore\n  ): Promise<JourneyOutcome> {\n    const { workflowId, contentHash, userId } = event.payload;\n    const env = this.env;\n\n    const stored = await store.getWorkflowIR(contentHash);\n    if (stored === undefined) {\n      throw new Error(`WorkflowIR not found: ${workflowId}@${contentHash}`);\n    }\n    const runtime = resolveRuntime({ current: this.runtime(event.payload) }, 'current');\n    // Development runs the journey in fast-forward; the pinned hash still names the version.\n    const ir = scaleDurations(stored, runtime.timeScale);\n\n    const observer = this.createObserver(store);\n    const finished = (status: JourneyOutcome['status'] | 'failed', convertedAt?: number) =>\n      observer?.finished?.({\n        workflow: workflowId,\n        instanceId: event.instanceId,\n        userId,\n        status,\n        at: Date.now(),\n        ...(convertedAt === undefined ? {} : { convertedAt }),\n      });\n\n    const messages = runtime.logMessages\n      ? logging(this.createMessageSender())\n      : this.createMessageSender();\n\n    // send_event feeds straight back into the router logic — an in-Worker call\n    // forming the event edge between workflows. The step's identity travels as\n    // the event id, so a retried emit records the occurrence once.\n    // An emitted event passes the same contract check as one arriving over HTTP.\n    const contract = this.contract();\n    const events: EventSink = {\n      emit: async (name, payload, id) => {\n        let accepted: Record<string, unknown> = payload;\n        if (contract !== undefined) {\n          const verdict = checkEvent(contract, name, payload);\n          if (!verdict.ok) throw new ContractValidationError(name, verdict.issues);\n          accepted = verdict.data;\n        }\n        await ingestEvent(env, { id, userId, event: name, payload: accepted }, store);\n      },\n    };\n\n    let outcome: JourneyOutcome;\n    try {\n      outcome = await runJourney(ir, {\n        userId,\n        instanceId: event.instanceId,\n        // Trigger-event creation time: replay-stable, unlike Date.now() here\n        enteredAtMs: event.timestamp.getTime(),\n        step: new CfEngineStep(step, store, userId, event.instanceId),\n        facts: new JourneyFactSource(store, userId),\n        messages,\n        events,\n        actions: this.createActionInvoker(),\n        validator: this.createMessageValidator(),\n        observer,\n      });\n    } catch (error) {\n      /*\n       * An error escaping run() ends the instance, and the ledger is the only\n       * place anyone looks afterwards: leaving it at 'running' meant a dead\n       * journey stayed indistinguishable from a waiting one, in the dashboard\n       * and in the once-policy, forever.\n       *\n       * Subscriptions are deliberately left in place. They are cleaned up on\n       * every ordinary ending, but here the wake rows are the only evidence of\n       * what the instance was waiting for, and dropping them would also break\n       * the instance if the platform does re-run it.\n       */\n      await step.do('finalize:failed', async () => {\n        await store.setEntryStatus(event.instanceId, 'failed');\n        await finished('failed');\n      });\n      throw error;\n    }\n\n    await step.do('finalize', async () => {\n      await store.setEntryStatus(event.instanceId, outcome.status);\n      await store.unsubscribe(event.instanceId);\n      await finished(outcome.status, outcome.convertedAt);\n    });\n\n    return outcome;\n  }\n}\n"],"mappings":"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"}

package/dist/cloudflare/runner.d.cts

@@ -0,0 +1,73 @@
+import { ActionInvoker, JourneyObserver, JourneyOutcome, MessageSender, MessageValidator } from "../engine/ports.cjs";
+import { RegisteredAction } from "../engine/actions.cjs";
+import { Contract } from "../contract.cjs";
+import { JourneyRuntimeOptions } from "../runtime.cjs";
+import { JourneyEnv, JourneyParams } from "./bindings.cjs";
+import { JourneyStore } from "../store/index.cjs";
+import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from "cloudflare:workers";
+//#region src/cloudflare/runner.d.ts
+/**
+ * The generic journey executor: one class runs every workflow, because IR is
+ * data. It is loaded from the store by the contentHash pinned at entry —
+ * content addressing makes it immutable, so reading it outside a step is
+ * replay-safe.
+ */
+export declare class JourneyRunner extends WorkflowEntrypoint<JourneyEnv, JourneyParams> {
+  /**
+   * The data plane. D1 + KV from the env by default; an app on Postgres
+   * overrides this (and `closeStore` if its client needs closing):
+   *
+   *   protected override createStore() { return new PostgresJourneyStore(client(this.env)); }
+   */
+  protected createStore(): JourneyStore;
+  /** Called once `run` is over, success or not — release whatever `createStore` opened. */
+  protected closeStore(_store: JourneyStore): Promise<void>;
+  /**
+   * Runtime options for this instance — typed configuration, resolved by the app (typically
+   * `resolveRuntime(config.runtime, mode)` over its workflow.config.ts, with the mode coming from
+   * an ENVIRONMENT var). The instance params are passed so the decision can also be per user:
+   * a tester account in production can run in fast-forward while everyone else runs in real
+   * time. Defaults: real time, quiet.
+   *
+   *   protected override runtime({ userId }) {
+   *     return resolveRuntime(workflowConfig.runtime, isTester(userId) ? 'test' : this.env.ENVIRONMENT);
+   *   }
+   */
+  protected runtime(_params: JourneyParams): JourneyRuntimeOptions;
+  /**
+   * Message outlet; an app overrides this to plug in real channels (say
+   * CfEmailSender with a react-email renderer). By default it picks the webhook
+   * or logging sender based on the environment.
+   */
+  protected createMessageSender(): MessageSender;
+  /**
+   * Custom-action registry; an app overrides this returning the same
+   * `action(...)` objects its workflows reference (an ActionRef is a
+   * RegisteredAction structurally) — the code plane of the dual-plane model:
+   *
+   *   protected override actions() { return [syncCrm, issueCoupon]; }
+   */
+  protected actions(): readonly RegisteredAction[];
+  /**
+   * The contract events this journey emits (`.sendEvent()`) are checked
+   * against, exactly like ingest; journeyWorker passes its config's.
+   */
+  protected contract(): Contract | undefined;
+  /**
+   * Template props check before every send; an app overrides this with
+   * `registryValidator({ emails, pushes })` (journeyWorker does it from its
+   * registries). By default props go out as resolved.
+   */
+  protected createMessageValidator(): MessageValidator | undefined;
+  /**
+   * Reporting hooks: node arrivals, every copy sent, how each instance ended. The host stores
+   * what it needs for its dashboards; by default nothing is reported.
+   */
+  protected createObserver(_store: JourneyStore): JourneyObserver | undefined;
+  /** Override for a different version policy ('warn' by default) or a fully custom invoker (e.g. webhook degradation for hosted tenants). */
+  protected createActionInvoker(): ActionInvoker;
+  run(event: WorkflowEvent<JourneyParams>, step: WorkflowStep): Promise<JourneyOutcome>;
+  private execute;
+}
+//#endregion
+//# sourceMappingURL=runner.d.cts.map

package/dist/cloudflare/runner.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.cts","names":[],"sources":["../../src/cloudflare/runner.ts"],"mappings":";;;;;;;;;;;;;;qBAuHa,sBAAsB,mBAAmB,YAAY;;;;;;;YAOtD,eAAe;;YAKT,WAAW,QAAQ,eAAe;;;;;;;;;;;;YAaxC,QAAQ,SAAS,gBAAgB;;;;;;YASjC,uBAAuB;;;;;;;;YAavB,oBAAoB;;;;;YAQpB,YAAY;;;;;;YASZ,0BAA0B;;;;;YAQ1B,eAAe,QAAQ,eAAe;;YAKtC,uBAAuB;EAI3B,IAAI,OAAO,cAAc,gBAAgB,MAAM,eAAe,QAAQ;UAS9D"}

package/dist/cloudflare/runner.d.mts

@@ -0,0 +1,73 @@
+import { ActionInvoker, JourneyObserver, JourneyOutcome, MessageSender, MessageValidator } from "../engine/ports.mjs";
+import { RegisteredAction } from "../engine/actions.mjs";
+import { Contract } from "../contract.mjs";
+import { JourneyRuntimeOptions } from "../runtime.mjs";
+import { JourneyEnv, JourneyParams } from "./bindings.mjs";
+import { JourneyStore } from "../store/index.mjs";
+import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from "cloudflare:workers";
+//#region src/cloudflare/runner.d.ts
+/**
+ * The generic journey executor: one class runs every workflow, because IR is
+ * data. It is loaded from the store by the contentHash pinned at entry —
+ * content addressing makes it immutable, so reading it outside a step is
+ * replay-safe.
+ */
+export declare class JourneyRunner extends WorkflowEntrypoint<JourneyEnv, JourneyParams> {
+  /**
+   * The data plane. D1 + KV from the env by default; an app on Postgres
+   * overrides this (and `closeStore` if its client needs closing):
+   *
+   *   protected override createStore() { return new PostgresJourneyStore(client(this.env)); }
+   */
+  protected createStore(): JourneyStore;
+  /** Called once `run` is over, success or not — release whatever `createStore` opened. */
+  protected closeStore(_store: JourneyStore): Promise<void>;
+  /**
+   * Runtime options for this instance — typed configuration, resolved by the app (typically
+   * `resolveRuntime(config.runtime, mode)` over its workflow.config.ts, with the mode coming from
+   * an ENVIRONMENT var). The instance params are passed so the decision can also be per user:
+   * a tester account in production can run in fast-forward while everyone else runs in real
+   * time. Defaults: real time, quiet.
+   *
+   *   protected override runtime({ userId }) {
+   *     return resolveRuntime(workflowConfig.runtime, isTester(userId) ? 'test' : this.env.ENVIRONMENT);
+   *   }
+   */
+  protected runtime(_params: JourneyParams): JourneyRuntimeOptions;
+  /**
+   * Message outlet; an app overrides this to plug in real channels (say
+   * CfEmailSender with a react-email renderer). By default it picks the webhook
+   * or logging sender based on the environment.
+   */
+  protected createMessageSender(): MessageSender;
+  /**
+   * Custom-action registry; an app overrides this returning the same
+   * `action(...)` objects its workflows reference (an ActionRef is a
+   * RegisteredAction structurally) — the code plane of the dual-plane model:
+   *
+   *   protected override actions() { return [syncCrm, issueCoupon]; }
+   */
+  protected actions(): readonly RegisteredAction[];
+  /**
+   * The contract events this journey emits (`.sendEvent()`) are checked
+   * against, exactly like ingest; journeyWorker passes its config's.
+   */
+  protected contract(): Contract | undefined;
+  /**
+   * Template props check before every send; an app overrides this with
+   * `registryValidator({ emails, pushes })` (journeyWorker does it from its
+   * registries). By default props go out as resolved.
+   */
+  protected createMessageValidator(): MessageValidator | undefined;
+  /**
+   * Reporting hooks: node arrivals, every copy sent, how each instance ended. The host stores
+   * what it needs for its dashboards; by default nothing is reported.
+   */
+  protected createObserver(_store: JourneyStore): JourneyObserver | undefined;
+  /** Override for a different version policy ('warn' by default) or a fully custom invoker (e.g. webhook degradation for hosted tenants). */
+  protected createActionInvoker(): ActionInvoker;
+  run(event: WorkflowEvent<JourneyParams>, step: WorkflowStep): Promise<JourneyOutcome>;
+  private execute;
+}
+//#endregion
+//# sourceMappingURL=runner.d.mts.map

package/dist/cloudflare/runner.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.mts","names":[],"sources":["../../src/cloudflare/runner.ts"],"mappings":";;;;;;;;;;;;;;qBAuHa,sBAAsB,mBAAmB,YAAY;;;;;;;YAOtD,eAAe;;YAKT,WAAW,QAAQ,eAAe;;;;;;;;;;;;YAaxC,QAAQ,SAAS,gBAAgB;;;;;;YASjC,uBAAuB;;;;;;;;YAavB,oBAAoB;;;;;YAQpB,YAAY;;;;;;YASZ,0BAA0B;;;;;YAQ1B,eAAe,QAAQ,eAAe;;YAKtC,uBAAuB;EAI3B,IAAI,OAAO,cAAc,gBAAgB,MAAM,eAAe,QAAQ;UAS9D"}

package/dist/cloudflare/runner.mjs

@@ -0,0 +1,224 @@
+import { ContractValidationError, checkEvent } from "../contract.mjs";
+import { resolveRuntime } from "../runtime.mjs";
+import { WAKE_EVENT_TYPE, wakeExpired } from "./bindings.mjs";
+import { JourneyFactSource } from "../store/facts.mjs";
+import { d1Store } from "./d1-env.mjs";
+import { ingestEvent } from "./router.mjs";
+import { LogMessageSender, WebhookMessageSender } from "./senders.mjs";
+import { RegistryActionInvoker } from "../engine/actions.mjs";
+import { runJourney } from "../engine/interpreter.mjs";
+import { scaleDurations } from "../engine/time-scale.mjs";
+import { WorkflowEntrypoint } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+//#region src/cloudflare/runner.ts
+/**
+* Adapts CF's WorkflowStep to EngineStep.
+* subscribe/unsubscribe write the subscription table inside durable steps (the
+* router wakes instances from that table); waitForWake parks on CF's
+* waitForEvent, which signals a timeout by throwing — and so does every other
+* failure in there, so only the clock can tell them apart (see wakeExpired).
+*/
+/** Refusals a retry would only repeat: a template's props, an emitted event's payload. */
+const NON_RETRYABLE = /* @__PURE__ */ new Set(["TemplateValidationError", "ContractValidationError"]);
+var CfEngineStep = class {
+	step;
+	store;
+	userId;
+	instanceId;
+	constructor(step, store, userId, instanceId) {
+		this.step = step;
+		this.store = store;
+		this.userId = userId;
+		this.instanceId = instanceId;
+	}
+	/**
+	* A template refusing its props, or the contract refusing an emitted event,
+	* is deterministic — a retry hits the same refusal — so it ends the step at
+	* once instead of burning the retry budget.
+	*/
+	do(name, fn) {
+		return this.step.do(name, async () => {
+			try {
+				return await fn();
+			} catch (error) {
+				if (error instanceof Error && NON_RETRYABLE.has(error.name)) throw new NonRetryableError(error.message, error.name);
+				throw error;
+			}
+		});
+	}
+	sleep(name, ms) {
+		return this.step.sleep(name, ms);
+	}
+	sleepUntil(name, timestampMs) {
+		return this.step.sleepUntil(name, timestampMs);
+	}
+	subscribe(name, events) {
+		return this.step.do(name, () => this.store.subscribe(this.instanceId, this.userId, events, Date.now()));
+	}
+	unsubscribe(name) {
+		return this.step.do(name, () => this.store.unsubscribe(this.instanceId));
+	}
+	async waitForWake(name, timeoutMs) {
+		const startedAt = Date.now();
+		try {
+			await this.step.waitForEvent(name, {
+				type: WAKE_EVENT_TYPE,
+				timeout: timeoutMs
+			});
+			return "event";
+		} catch (error) {
+			if (await this.step.do(`${name}:timed-out`, async () => wakeExpired(startedAt, timeoutMs, Date.now()))) return "timeout";
+			throw error;
+		}
+	}
+};
+/** Development aid: echo each outbound message before handing it to the real sender. */
+function logging(sender) {
+	return { async send(message) {
+		console.log(`[journey] ${message.channel} ${message.template} → ${message.recipient ?? message.userId} ${JSON.stringify(message.props)}`);
+		return sender.send(message);
+	} };
+}
+/**
+* The generic journey executor: one class runs every workflow, because IR is
+* data. It is loaded from the store by the contentHash pinned at entry —
+* content addressing makes it immutable, so reading it outside a step is
+* replay-safe.
+*/
+var JourneyRunner = class extends WorkflowEntrypoint {
+	/**
+	* The data plane. D1 + KV from the env by default; an app on Postgres
+	* overrides this (and `closeStore` if its client needs closing):
+	*
+	*   protected override createStore() { return new PostgresJourneyStore(client(this.env)); }
+	*/
+	createStore() {
+		return d1Store(this.env);
+	}
+	/** Called once `run` is over, success or not — release whatever `createStore` opened. */
+	async closeStore(_store) {}
+	/**
+	* Runtime options for this instance — typed configuration, resolved by the app (typically
+	* `resolveRuntime(config.runtime, mode)` over its workflow.config.ts, with the mode coming from
+	* an ENVIRONMENT var). The instance params are passed so the decision can also be per user:
+	* a tester account in production can run in fast-forward while everyone else runs in real
+	* time. Defaults: real time, quiet.
+	*
+	*   protected override runtime({ userId }) {
+	*     return resolveRuntime(workflowConfig.runtime, isTester(userId) ? 'test' : this.env.ENVIRONMENT);
+	*   }
+	*/
+	runtime(_params) {
+		return resolveRuntime(void 0, "production");
+	}
+	/**
+	* Message outlet; an app overrides this to plug in real channels (say
+	* CfEmailSender with a react-email renderer). By default it picks the webhook
+	* or logging sender based on the environment.
+	*/
+	createMessageSender() {
+		return this.env.MESSAGE_WEBHOOK_URL ? new WebhookMessageSender(this.env.MESSAGE_WEBHOOK_URL) : new LogMessageSender();
+	}
+	/**
+	* Custom-action registry; an app overrides this returning the same
+	* `action(...)` objects its workflows reference (an ActionRef is a
+	* RegisteredAction structurally) — the code plane of the dual-plane model:
+	*
+	*   protected override actions() { return [syncCrm, issueCoupon]; }
+	*/
+	actions() {
+		return [];
+	}
+	/**
+	* The contract events this journey emits (`.sendEvent()`) are checked
+	* against, exactly like ingest; journeyWorker passes its config's.
+	*/
+	contract() {}
+	/**
+	* Template props check before every send; an app overrides this with
+	* `registryValidator({ emails, pushes })` (journeyWorker does it from its
+	* registries). By default props go out as resolved.
+	*/
+	createMessageValidator() {}
+	/**
+	* Reporting hooks: node arrivals, every copy sent, how each instance ended. The host stores
+	* what it needs for its dashboards; by default nothing is reported.
+	*/
+	createObserver(_store) {}
+	/** Override for a different version policy ('warn' by default) or a fully custom invoker (e.g. webhook degradation for hosted tenants). */
+	createActionInvoker() {
+		return new RegistryActionInvoker(this.actions());
+	}
+	async run(event, step) {
+		const store = this.createStore();
+		try {
+			return await this.execute(event, step, store);
+		} finally {
+			await this.closeStore(store);
+		}
+	}
+	async execute(event, step, store) {
+		const { workflowId, contentHash, userId } = event.payload;
+		const env = this.env;
+		const stored = await store.getWorkflowIR(contentHash);
+		if (stored === void 0) throw new Error(`WorkflowIR not found: ${workflowId}@${contentHash}`);
+		const runtime = resolveRuntime({ current: this.runtime(event.payload) }, "current");
+		const ir = scaleDurations(stored, runtime.timeScale);
+		const observer = this.createObserver(store);
+		const finished = (status, convertedAt) => observer?.finished?.({
+			workflow: workflowId,
+			instanceId: event.instanceId,
+			userId,
+			status,
+			at: Date.now(),
+			...convertedAt === void 0 ? {} : { convertedAt }
+		});
+		const messages = runtime.logMessages ? logging(this.createMessageSender()) : this.createMessageSender();
+		const contract = this.contract();
+		const events = { emit: async (name, payload, id) => {
+			let accepted = payload;
+			if (contract !== void 0) {
+				const verdict = checkEvent(contract, name, payload);
+				if (!verdict.ok) throw new ContractValidationError(name, verdict.issues);
+				accepted = verdict.data;
+			}
+			await ingestEvent(env, {
+				id,
+				userId,
+				event: name,
+				payload: accepted
+			}, store);
+		} };
+		let outcome;
+		try {
+			outcome = await runJourney(ir, {
+				userId,
+				instanceId: event.instanceId,
+				enteredAtMs: event.timestamp.getTime(),
+				step: new CfEngineStep(step, store, userId, event.instanceId),
+				facts: new JourneyFactSource(store, userId),
+				messages,
+				events,
+				actions: this.createActionInvoker(),
+				validator: this.createMessageValidator(),
+				observer
+			});
+		} catch (error) {
+			await step.do("finalize:failed", async () => {
+				await store.setEntryStatus(event.instanceId, "failed");
+				await finished("failed");
+			});
+			throw error;
+		}
+		await step.do("finalize", async () => {
+			await store.setEntryStatus(event.instanceId, outcome.status);
+			await store.unsubscribe(event.instanceId);
+			await finished(outcome.status, outcome.convertedAt);
+		});
+		return outcome;
+	}
+};
+//#endregion
+export { JourneyRunner };
+
+//# sourceMappingURL=runner.mjs.map