@pithy-sh/core 0.1.0

package/src/workflow/faults.ts

@@ -0,0 +1,219 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { d1TransientFault } from "../data/withD1Retry";
+import { PithyError } from "../error/pithyError";
+import { encodeWorkflowStepMessage } from "./stepMessage";
+
+/**
+ * **Every fault that reaches a durable step is classified — retryable or terminal — at a stated site.**
+ *
+ * A Workflow is chosen *because of* its retry semantics: durable execution, a journal, steps that resume,
+ * backoff that survives an eviction. A step that inherits the platform default has not decided; it has
+ * deferred, and the default is retry-everything. So a deterministic refusal — a name that already exists,
+ * a value too large, a payload that will not parse — is answered slowly instead of immediately, the retry
+ * budget burns down on an answer that cannot change, and an instant refusal looks like an outage
+ * (pithy-sh/pithy#338).
+ *
+ * ## The three layers, and which owns what
+ *
+ * 1. **The capability states its own codes.** A {@link WorkflowRetryPolicy} names the `PithyError` codes
+ *    that capability retries, each with the reason a second attempt can answer differently. One statement
+ *    per capability, in one file, the way `@pithy-sh/email`'s `errorMapping.ts` already states the Email
+ *    Service's `E_*` codes.
+ * 2. **Core owns D1.** `withD1Retry` already classifies D1's fault vocabulary, so this asks it rather than
+ *    growing a second copy — and that is also the no-double-retry rule: a fault the inner layer refused to
+ *    retry (a constraint violation, a SQL error) is terminal here too, while a transient one stays
+ *    retryable so the step re-drives it with backoff far longer than the inner loop's.
+ * 3. **Everything else is terminal.** Retry is opted into, never inherited. The platform default is the
+ *    opposite, and it is the wrong way round: a terminal fault wrongly called transient burns the whole
+ *    budget before surfacing, while a transient one wrongly called terminal surfaces immediately with the
+ *    fault written on it. One of those is a diagnosis; the other is a hang.
+ *
+ * ## Where the wrapping happens, and why it cannot be anywhere else
+ *
+ * {@link classifiedSteps} converts a terminal fault **inside** the step callback. The platform's retry loop
+ * lives inside `step.do`: by the time a `step.do` promise rejects, every retry has already been spent. A
+ * wrapper around the call would classify a fault the engine had already re-driven five times — correct
+ * looking, and exactly as slow as doing nothing.
+ */
+
+/** Whether the platform should try a step's body again, or stop with the answer it has. */
+export type WorkflowFaultDisposition = "retry" | "terminal";
+
+/**
+ * One capability's stated retry classification — the whole of what it retries, and why.
+ *
+ * A record rather than a set, because the value is the argument: "what would a second attempt see that
+ * this one did not" is the question that decides, and writing the answer down is what keeps the next code
+ * from being added to the list by reflex.
+ */
+export interface WorkflowRetryPolicy {
+  /** The capability whose Workflows this governs — `secrets`, `payments`, `email`. Named in the fault's reason. */
+  capability: string;
+  /**
+   * `PithyError` code → why a retry can answer differently. **Everything absent is terminal**, including
+   * codes another capability retries: a 502 from a payment rail is worth re-driving, and a 502 from a
+   * store that has already taken the write is not.
+   */
+  retryable: Readonly<Record<string, string>>;
+}
+
+/** One fault, classified: what it was, what happens next, and the stated reason for it. */
+export interface WorkflowFault {
+  /** Retry, or stop. */
+  disposition: WorkflowFaultDisposition;
+  /** The `PithyError` code, `d1/<fault>` for a D1 fault class, or `unclassified`. */
+  code: string;
+  /** Why — the policy's own sentence for a retry, or what made this terminal. */
+  reason: string;
+}
+
+/** The `code` reported for a throw no layer recognizes. */
+const UNCLASSIFIED = "unclassified";
+
+/**
+ * The code a thrown value carries, or `null` when it is not a `PithyError`.
+ *
+ * The structural read is not belt-and-braces: `instanceof` is per module instance, and a bundler that
+ * gives a host worker two copies of core would silently answer `false` for a perfectly good
+ * `PithyError` — which here means classifying a stated retryable fault as terminal. The shape is
+ * checked, not assumed.
+ */
+function pithyCodeOf(error: unknown): string | null {
+  if (error instanceof PithyError) return error.payload.code;
+  if (error && typeof error === "object" && "payload" in error) {
+    const payload = (error as { payload: unknown }).payload;
+    if (payload && typeof payload === "object" && "code" in payload) {
+      const code = (payload as { code: unknown }).code;
+      if (typeof code === "string") return code;
+    }
+  }
+  return null;
+}
+
+/** The public message of a thrown value, for the terminal error's own text. */
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The operator's remedy a thrown value carries, or `undefined` when it states none.
+ *
+ * Read structurally for the same reason {@link pithyCodeOf} is: `instanceof` is per module instance,
+ * and two copies of core in one bundle would answer `false` for a perfectly good `PithyError` — here
+ * meaning a remedy the raising error stated is silently dropped at the boundary. That is the bug this
+ * function exists to end, so it is not reintroduced by the check.
+ *
+ * **`detail` is deliberately not read here, and there is no sibling for it.** `action` is already
+ * operator-facing — the CLI prints it, `operatorError` includes it. `detail` is throw-site context and
+ * stays at the throw site.
+ */
+function pithyActionOf(error: unknown): string | undefined {
+  if (error instanceof PithyError) return error.payload.action;
+  if (error && typeof error === "object" && "payload" in error) {
+    const payload = (error as { payload: unknown }).payload;
+    if (payload && typeof payload === "object" && "action" in payload) {
+      const action = (payload as { action: unknown }).action;
+      if (typeof action === "string") return action;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Classify one fault against a capability's policy. Pure, so a capability's classification is a unit
+ * test rather than a claim — and so the same function decides in a test, in Miniflare, and in production.
+ */
+export function classifyWorkflowFault(error: unknown, policy: WorkflowRetryPolicy): WorkflowFault {
+  const code = pithyCodeOf(error);
+  if (code !== null) {
+    const reason = policy.retryable[code];
+    if (reason !== undefined) return { disposition: "retry", code, reason };
+    return {
+      disposition: "terminal",
+      code,
+      reason: `${policy.capability} does not retry ${code}: a second attempt reaches the same answer.`,
+    };
+  }
+
+  const d1 = d1TransientFault(error);
+  if (d1 !== null) {
+    return {
+      disposition: "retry",
+      code: `d1/${d1}`,
+      reason: `D1 reported a transient ${d1} fault; withD1Retry classifies it retryable.`,
+    };
+  }
+
+  return {
+    disposition: "terminal",
+    code: UNCLASSIFIED,
+    reason: `Nothing classifies this fault, and ${policy.capability} retries only what it states.`,
+  };
+}
+
+/** The half of a Workflow step this kit uses: run a named body, or serve its journalled result. */
+export interface WorkflowStepLike {
+  /** Run a named step, or return its journalled result if this instance already completed it. */
+  do<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * The platform's terminal-error class — `NonRetryableError` from `cloudflare:workflows`, taken as a
+ * parameter.
+ *
+ * Injected rather than imported because `@pithy-sh/core` is bundled into every adopter's Worker *and*
+ * imported by the CLI under node, so it may not import a `cloudflare:` module. The Workflow class is
+ * already inside workerd and already imports one; handing the class in costs it a word and keeps the
+ * classification itself testable anywhere.
+ *
+ * **One argument, deliberately.** `NonRetryableError`'s constructor also takes a `name`, and the engine
+ * recognizes the error *by* that name: measured against a real Workflow in `wrangler dev`, passing any
+ * name but the default turned an instance that failed in 0.7s back into one that retried for 32s and
+ * then failed. The signature is narrowed so nobody can reintroduce that by being helpful.
+ */
+export interface TerminalErrorConstructor {
+  new (message: string): Error;
+}
+
+/**
+ * Wrap a Workflow's step runner so every fault it raises is classified against `policy`, and a terminal
+ * one is re-thrown as the platform's terminal error — **inside the step**, before the retry loop reads it.
+ *
+ * The result is structurally a step runner, so a body that already takes one (`reconcilePayments`,
+ * `runSendBatch`, `runAtRestKeyRotation`) takes this instead with no change: the classification is
+ * declared once, at the entrypoint, and every step below it inherits the decision.
+ */
+export function classifiedSteps(
+  step: WorkflowStepLike,
+  policy: WorkflowRetryPolicy,
+  terminalError: TerminalErrorConstructor,
+): WorkflowStepLike {
+  return {
+    do<T>(name: string, fn: () => Promise<T>): Promise<T> {
+      return step.do(name, async () => {
+        try {
+          return await fn();
+        } catch (error) {
+          const fault = classifyWorkflowFault(error, policy);
+          if (fault.disposition === "retry") throw error;
+          // The one sanctioned non-`PithyError` throw in the kit: a platform contract, at the durable
+          // boundary, carrying the `PithyError` it replaced as its `cause` so nothing is lost in this
+          // process. Across the boundary the text is the whole channel — the engine records it and
+          // discards the throw — so what an operator is owed is encoded into it, at one stated site,
+          // and read back at one (./stepMessage). The `cause` does not travel; `detail` never did.
+          const terminal = new terminalError(
+            encodeWorkflowStepMessage({
+              code: fault.code,
+              message: messageOf(error),
+              action: pithyActionOf(error),
+            }),
+          );
+          terminal.cause = error;
+          throw terminal;
+        }
+      });
+    },
+  };
+}

package/src/workflow/host.ts

@@ -0,0 +1,307 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "../error/pithyError";
+import { ENVIRONMENT_VAR, PROJECT_VAR } from "../worker/identity";
+import { type WorkflowHostNameParts, workflowHostName, workflowScriptName } from "./naming";
+import type { WorkflowRegistry } from "./spec";
+
+/**
+ * The prebuilt-worker host contract.
+ *
+ * A capability that owns Workflows ships a committed `wrangler.jsonc` **template** beside its
+ * worker entry — not an env-stanza file, because staging and production are genuinely separate
+ * Workers. `pithy <capability> provision` resolves that template into one complete config per
+ * environment and deploys each with `wrangler deploy --config <resolved>`. The adopter authors
+ * none of it.
+ *
+ * Email, secrets, and media each grew their own copy of that resolver. This module is the one they
+ * converge on: a template shape wide enough for all three, and a pure resolver that fills it.
+ *
+ * Pure by construction — no filesystem, no Cloudflare, no `cloudflare:workers`. The caller parses
+ * the template and writes the result. That keeps core node-safe (its `.describe()` meta-test
+ * imports every module eagerly under node) and keeps the ordering and idempotency logic unit-
+ * testable without an account.
+ *
+ * **Workflows cannot use remote bindings**, so a host always runs locally in `wrangler dev`. Any
+ * binding it needs that has no local emulation — Vectorize and Workers AI both lack one — must
+ * carry `remote: true`, which is why {@link WorkflowHostParams.remoteBindings} exists rather than
+ * the flag being inferred per binding kind.
+ */
+
+/** A D1 binding in a host template. `database_name` is rewritten only when the caller supplies one. */
+export interface HostD1Binding {
+  binding: string;
+  database_name: string;
+  database_id: string;
+}
+
+/** A KV namespace binding in a host template. */
+export interface HostKvBinding {
+  binding: string;
+  id: string;
+}
+
+/** An R2 bucket binding in a host template. */
+export interface HostR2Binding {
+  binding: string;
+  bucket_name: string;
+  remote?: boolean;
+}
+
+/** A Vectorize index binding in a host template. Always `remote: true` — Vectorize has no local emulation. */
+export interface HostVectorizeBinding {
+  binding: string;
+  index_name: string;
+  remote?: boolean;
+}
+
+/** The Workers AI binding in a host template. Always `remote: true` — Workers AI has no local emulation. */
+export interface HostAiBinding {
+  binding: string;
+  remote?: boolean;
+}
+
+/** A Cloudflare Email Service send binding in a host template. */
+export interface HostSendEmailBinding {
+  name: string;
+  remote?: boolean;
+}
+
+/** A Secrets Store entry in a host template — the master key a host reads its secrets through. */
+export interface HostSecretsStoreBinding {
+  binding: string;
+  store_id: string;
+  secret_name: string;
+}
+
+/** One Workflow the host worker hosts: the binding, the deployed name, and the class that runs it. */
+export interface HostWorkflowBinding {
+  binding: string;
+  name: string;
+  class_name: string;
+}
+
+/**
+ * A capability's committed `wrangler.jsonc` template, typed. Every field is optional but `name` and
+ * `main` — a host that binds no D1 is legal, and email binds no R2. Unknown keys survive
+ * `structuredClone` untouched, so a template may carry fields this contract does not model.
+ */
+export interface WorkflowHostTemplate {
+  name: string;
+  main: string;
+  compatibility_date?: string;
+  compatibility_flags?: string[];
+  workers_dev?: boolean;
+  d1_databases?: HostD1Binding[];
+  kv_namespaces?: HostKvBinding[];
+  r2_buckets?: HostR2Binding[];
+  vectorize?: HostVectorizeBinding[];
+  ai?: HostAiBinding;
+  send_email?: HostSendEmailBinding[];
+  secrets_store_secrets?: HostSecretsStoreBinding[];
+  workflows?: HostWorkflowBinding[];
+  triggers?: { crons: string[] };
+  vars?: Record<string, string>;
+}
+
+/** What one environment's resolution needs. Everything absent is left exactly as the template had it. */
+export interface WorkflowHostParams {
+  /**
+   * The project name — the `<project>` segment every derived name leads with. The root
+   * `pithy.config.ts` `name`, resolved by `requireProjectName` and **never guessed**: Worker script
+   * and Workflow names are account-scoped, so a wrong value here overwrites another project's
+   * running Worker rather than colliding with it.
+   */
+  project: string;
+  /** The capability that owns the host — the `<capability>` segment of every derived name. */
+  capability: string;
+  /** The target environment (`dev` | `staging` | `production`). */
+  env: string;
+  /** D1 binding name → database id. An unlisted binding keeps the template's id. */
+  databaseIds?: Record<string, string>;
+  /**
+   * D1 binding name → database name. Rewritten **only** for the bindings listed here. Email
+   * deliberately lets `pithy-app`/`pithy-secrets` pass through while secrets rewrites its own, so
+   * the choice cannot be a blanket rule.
+   */
+  databaseNames?: Record<string, string>;
+  /** KV binding name → namespace id. */
+  kvNamespaceIds?: Record<string, string>;
+  /** R2 binding name → bucket name. */
+  r2BucketNames?: Record<string, string>;
+  /** Vectorize binding name → index name. */
+  vectorizeIndexNames?: Record<string, string>;
+  /** The Secrets Store id, set on every `secrets_store_secrets` entry. */
+  secretsStoreId?: string;
+  /**
+   * The environment-scoped name of the master-key secret. Passed in rather than derived: core must
+   * not depend on `@pithy-sh/secrets`, which owns that naming.
+   */
+  masterKeySecretName?: string;
+  /** Vars merged over the template's, e.g. the capability's config serialized as one JSON blob. */
+  vars?: Record<string, string>;
+  /**
+   * Binding names that must carry `remote: true`. A Workflow host runs locally in dev, so any
+   * binding without local emulation has to reach the real service.
+   */
+  remoteBindings?: readonly string[];
+  /**
+   * KV binding names to drop. A template declares every binding a capability *might* need; a mode
+   * that does not use one must not ship a binding pointing at a namespace that was never created.
+   */
+  omitKvBindings?: readonly string[];
+  /**
+   * The host's `workflows` array, already derived from the capability's registry by
+   * {@link hostWorkflowsFor}. **Required whenever the template declares any `workflows`.**
+   *
+   * The resolver used to build these by appending `-<env>` to the template's own name, which cannot
+   * produce a project-scoped name: the template says `pithy-email-send`, and the resolver has no way
+   * to recover the job from it. Deriving them from the registry is the only path that knows both the
+   * project and the job, so the textual suffix is gone and its absence is an error rather than a
+   * silent fallback to an unscoped, account-colliding Workflow name.
+   */
+  workflows?: readonly HostWorkflowBinding[];
+}
+
+/** Apply `remote: true` to an entry whose binding the caller listed. */
+function withRemote<T extends { remote?: boolean }>(entry: T, name: string, remote: ReadonlySet<string>): T {
+  return remote.has(name) ? { ...entry, remote: true } : entry;
+}
+
+/**
+ * Resolve a host template into one environment's complete, standalone config.
+ *
+ * Structural, never textual: the template is `structuredClone`d and fields are overwritten by
+ * binding-name lookup. The `<filled-at-provision>` markers in the committed templates are
+ * documentation for whoever reads the file — nothing matches or replaces them, so a template that
+ * spells a placeholder differently still resolves correctly.
+ *
+ * The worker name becomes `<project>-<env>-<capability>` through {@link workflowHostName}, and the
+ * `workflows` array is replaced wholesale by `params.workflows` (derived from the registry by
+ * {@link hostWorkflowsFor}), so the deployed names cannot drift from what the dispatcher and the
+ * CLI compute. `binding` and
+ * `class_name` are never rewritten — they are code references, not deployment identities.
+ */
+export function resolveWorkflowHost(template: WorkflowHostTemplate, params: WorkflowHostParams): WorkflowHostTemplate {
+  const resolved = structuredClone(template);
+  const remote = new Set(params.remoteBindings ?? []);
+
+  resolved.name = workflowHostName({ project: params.project, capability: params.capability, env: params.env });
+
+  if (resolved.d1_databases) {
+    resolved.d1_databases = resolved.d1_databases.map((entry) => ({
+      ...entry,
+      database_name: params.databaseNames?.[entry.binding] ?? entry.database_name,
+      database_id: params.databaseIds?.[entry.binding] ?? entry.database_id,
+    }));
+  }
+
+  if (resolved.kv_namespaces) {
+    const omit = new Set(params.omitKvBindings ?? []);
+    const kept = resolved.kv_namespaces.filter((entry) => !omit.has(entry.binding));
+    // Drop the key entirely when nothing survives — wrangler treats an empty array as a declaration.
+    if (kept.length > 0) {
+      resolved.kv_namespaces = kept.map((entry) => ({
+        ...entry,
+        id: params.kvNamespaceIds?.[entry.binding] ?? entry.id,
+      }));
+    } else {
+      resolved.kv_namespaces = undefined;
+    }
+  }
+
+  if (resolved.r2_buckets) {
+    resolved.r2_buckets = resolved.r2_buckets.map((entry) =>
+      withRemote(
+        { ...entry, bucket_name: params.r2BucketNames?.[entry.binding] ?? entry.bucket_name },
+        entry.binding,
+        remote,
+      ),
+    );
+  }
+
+  if (resolved.vectorize) {
+    resolved.vectorize = resolved.vectorize.map((entry) =>
+      withRemote(
+        { ...entry, index_name: params.vectorizeIndexNames?.[entry.binding] ?? entry.index_name },
+        entry.binding,
+        remote,
+      ),
+    );
+  }
+
+  if (resolved.ai) {
+    resolved.ai = withRemote(resolved.ai, resolved.ai.binding, remote);
+  }
+
+  if (resolved.send_email) {
+    resolved.send_email = resolved.send_email.map((entry) => withRemote(entry, entry.name, remote));
+  }
+
+  if (resolved.secrets_store_secrets && params.secretsStoreId !== undefined) {
+    const storeId = params.secretsStoreId;
+    const masterKey = params.masterKeySecretName;
+    resolved.secrets_store_secrets = resolved.secrets_store_secrets.map((entry) => ({
+      ...entry,
+      store_id: storeId,
+      // Only the master key is environment-scoped; every other entry keeps its declared name.
+      secret_name:
+        masterKey !== undefined && entry.binding === "SECRETS_ENCRYPTION_KEYS" ? masterKey : entry.secret_name,
+    }));
+  }
+
+  if (resolved.workflows) {
+    if (!params.workflows) {
+      throw new InternalError({
+        message: `The ${params.capability} host template declares workflows but none were derived.`,
+        action: "Pass `workflows` from hostWorkflowsFor(registry, { project, capability, env }).",
+        detail:
+          "A Workflow name is account-scoped and must carry the project; the template name alone cannot produce one.",
+      });
+    }
+    resolved.workflows = params.workflows.map((entry) => ({ ...entry }));
+  }
+
+  // Identity last: a caller's vars can add anything, but never restate who this worker is.
+  resolved.vars = {
+    ...resolved.vars,
+    ...params.vars,
+    [ENVIRONMENT_VAR]: params.env,
+    [PROJECT_VAR]: params.project,
+  };
+
+  return resolved;
+}
+
+/**
+ * Derive a host's `workflows` array and `triggers.crons` from the registry, so a capability's specs
+ * — not a hand-maintained block in its template — are the source of both. A spec without a
+ * `className` cannot be hosted: there would be no class for wrangler to instantiate.
+ */
+export function hostWorkflowsFor(
+  registry: WorkflowRegistry,
+  parts: WorkflowHostNameParts,
+): { workflows: HostWorkflowBinding[]; crons: string[] } {
+  const { project, capability, env } = parts;
+  const owned = Object.values(registry).filter((entry) => entry.capability === capability);
+  const workflows: HostWorkflowBinding[] = [];
+  const crons: string[] = [];
+
+  for (const entry of owned) {
+    if (!entry.spec.className) {
+      throw new InternalError({
+        message: `Workflow "${entry.key}" cannot be hosted without a className.`,
+        action: "Add className to the spec, naming the exported WorkflowEntrypoint class.",
+      });
+    }
+    workflows.push({
+      binding: entry.spec.binding,
+      name: workflowScriptName({ project, capability, job: entry.job, env }),
+      class_name: entry.spec.className,
+    });
+    if (entry.spec.schedule) crons.push(entry.spec.schedule);
+  }
+
+  return { workflows, crons };
+}

package/src/workflow/hostEntry.ts

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { HttpError } from "../error/http";
+import { NotFoundError } from "../error/pithyError";
+
+/**
+ * The default export of a Workflow host that serves nothing over HTTP (#426).
+ *
+ * ## Why a host needs a default export at all
+ *
+ * wrangler infers a worker's **module format** from one thing: whether the entry has a default export. A
+ * module that exports only classes is read as a service worker, and a service worker may not import
+ * `cloudflare:workers` — so the build does not warn and continue, it fails:
+ *
+ *     ▲ [WARNING] The entrypoint … has exports like an ES Module, but hasn't defined a default export
+ *               like a module worker normally would. Building the worker using "service-worker" format...
+ *     ✘ [ERROR] Unexpected external import of "cloudflare:workers" and "cloudflare:workflows".
+ *
+ * `pithy dev` builds each worker separately and carries on past one that fails, so the whole of what an
+ * adopter sees is a host that is not there. `support`, `media` and `vector` each shipped that way, and every
+ * host that did not was a host with a cron — `export default { async scheduled(…) }`, written for the cron,
+ * making the module an ES module by accident. The four authors who satisfied the rule had a reason unrelated
+ * to it, and the three who did not had no reason at all. `cli/src/ci/workflowModuleFormat.test.ts` is what
+ * now asks the question of the class rather than of the author.
+ *
+ * ## Why it refuses rather than being empty
+ *
+ * `export default {}` would build. It would also say nothing: an operator who reaches this Worker in a
+ * browser or with a stray `curl` gets an empty 200-shaped nothing from a Worker they were told hosts a job.
+ * A Workflow host has no request surface — an app Worker starts its jobs through a cross-script Workflow
+ * binding, and a host with a cron fires its own `scheduled` — so an HTTP request arriving at one is a
+ * misconfiguration, and the refusal is the sentence that ends the operator's search. `core/not_found`,
+ * because that is the truth: this Worker has no HTTP resources. The `action` names the path that does work
+ * and is stripped before the body goes out, like every other action.
+ *
+ * ## The one host this is not for
+ *
+ * A host that *does* serve HTTP mounts `registerWorkflowDispatchRoute` (./dispatchRoute) and exports its own
+ * handler. `@pithy-sh/email` is the case, and its door is the loopback dispatch `pithy dev` knocks on
+ * (#410). The other hosts have not been given that door yet; when one is, its `export default` becomes the
+ * Hono app and this refusal becomes that app's fallthrough. Nothing here has to change for that.
+ */
+
+/** What a refusing host exports: a `fetch`, and nothing else. Every other entry a Worker has is absent. */
+export interface WorkflowHostEntry {
+  /** Refuse the request. The platform passes a request, an env and a context; none is read, so none is declared. */
+  fetch(): Promise<Response>;
+}
+
+/**
+ * Build the default export for a Workflow host with no HTTP surface.
+ *
+ * Takes the capability so the refusal says which Worker answered — an operator holding a port number and a
+ * 404 needs that before anything else.
+ */
+export function workflowHostEntry(capability: string): WorkflowHostEntry {
+  return {
+    async fetch(): Promise<Response> {
+      const refusal = new NotFoundError({
+        message: `The ${capability} workflow host serves no HTTP requests.`,
+        action: `Start its Workflows through the ${capability} Workflow binding, not over HTTP.`,
+        detail: "This Worker hosts Workflow classes and registers no routes.",
+      });
+      return new Response(JSON.stringify({ error: HttpError.encode(refusal.payload) }), {
+        status: refusal.payload.status,
+        headers: { "content-type": "application/json" },
+      });
+    },
+  };
+}