@pithy-sh/core 0.1.0

package/src/workflow/bindings.ts

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingSpecInput } from "../capability/bindings";
+import type { RegisteredWorkflow, WorkflowSpec, WorkflowSpecMap } from "./spec";
+
+/**
+ * The one derivation from a durable job to the `workflow` binding that job needs.
+ *
+ * **Every capability that owns a Workflow wrote this by hand, and six of them wrote it wrong.**
+ * `Object.values(map).map((spec) => ({ type: "workflow", name: spec.binding, optional: spec.optional }))`
+ * appeared verbatim in payments, storage, support, vector, testers and media, and once more in
+ * `createBackend`. It drops two fields, and dropping them is not cosmetic: `project/bindingEntries.ts`
+ * needs `job` to compose the deployed Workflow's name and `className` to emit `class_name`, refuses to
+ * write a partial `workflows` entry because wrangler rejects one, and returns `undefined` instead. So
+ * `pithy upgrade` reported adding five bindings it had silently declined to write, and `pithy doctor`
+ * — run seconds later against the same tree — correctly still called them missing (#318).
+ *
+ * **The `job` is the map key.** That is the whole reason `Object.values` was the wrong iterator: the
+ * field the writer needs most is the one a values-only walk cannot see. `Object.entries` is not a
+ * detail to remember at six call sites; it is this function.
+ *
+ * `className` rides through as declared — a spec may honestly omit it, for a job whose host config is
+ * hand-maintained — and `capabilities/requiredBindings.test.ts` is what turns an omission that reaches
+ * a shipped manifest into a build failure rather than a binding nothing writes.
+ */
+export function workflowBinding(job: string, spec: WorkflowSpec): BindingSpecInput {
+  return {
+    type: "workflow",
+    name: spec.binding,
+    job,
+    ...(spec.className === undefined ? {} : { className: spec.className }),
+    optional: spec.optional ?? false,
+  };
+}
+
+/**
+ * Every binding a capability's durable jobs require, derived from the job map itself.
+ *
+ * What a capability's `requiredBindings` spreads, so the declaration is one line that cannot lose a
+ * field. A binding rename, a new job, or a class rename travels from the spec to `wrangler.jsonc`
+ * without anything in between being edited.
+ */
+export function workflowBindings(workflows: WorkflowSpecMap): BindingSpecInput[] {
+  return Object.entries(workflows).map(([job, spec]) => workflowBinding(job, spec));
+}
+
+/**
+ * The same derivation from a {@link RegisteredWorkflow} — a spec already resolved against the
+ * capability that declared it, which is the shape `createBackend`'s composed registry holds.
+ *
+ * It exists so the assembly-time derivation and the capability-time one are the same function rather
+ * than the same four lines twice. `entry.job` is the registry's own copy of the map key, so the
+ * binding it derives is byte-identical to the one the capability declared.
+ */
+export function registeredWorkflowBinding(entry: RegisteredWorkflow): BindingSpecInput {
+  return workflowBinding(entry.job, entry.spec);
+}

package/src/workflow/dispatch.ts

@@ -0,0 +1,240 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import { originVarName } from "../env/stem";
+import { messageOf, PithyError } from "../error/pithyError";
+import type { Logger } from "../logger/logger";
+import { noopLogger } from "../logger/logger";
+import { ENVIRONMENT_VAR } from "../worker/identity";
+import { type LoopbackFetch, loopbackWorkflowBinding } from "./loopback";
+import type { WorkflowBinding, WorkflowRegistry } from "./spec";
+
+/**
+ * Dispatch: start a registered job by its `<capability>/<job>` key.
+ *
+ * Two things happen before the binding is touched, in this order. The key resolves against the
+ * registry, so a typo is `core/unknown_workflow` rather than a `TypeError` on `undefined.create`.
+ * Then the params parse through the spec's schema, so a malformed payload is
+ * `core/invalid_workflow_params` at the call site — with the offending field named — instead of a
+ * failed step inside a running instance, where the only signal is a retry budget burning down and
+ * the payload is no longer in anyone's hands.
+ *
+ * The dispatcher is a closure over the per-request `env`, built once per request by
+ * `createBackend` and served as `c.var.workflows`.
+ */
+
+/**
+ * The typed dispatcher. `Params` maps each `<capability>/<job>` key to that job's parameter type,
+ * derived by `createBackend` from the composed capabilities — so `trigger` autocompletes the key
+ * set and type-checks the payload against the declaring capability's schema.
+ */
+export interface WorkflowDispatcher<Params extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Start an instance of one job. Resolves once Cloudflare has accepted the instance; it does not
+   * wait for the Workflow to finish. Instance status and termination are deliberately not on this
+   * seam — a Workflow is durable precisely so the caller need not hold its progress.
+   */
+  trigger<Key extends keyof Params & string>(key: Key, params: Params[Key]): Promise<void>;
+}
+
+/**
+ * Read a binding off the per-request env, narrowed to the one method dispatch needs.
+ *
+ * Exported because the host's dispatch route ({@link ./dispatchRoute.ts}) asks the same question of
+ * the same env, and a second duck-type would be a second answer to "is this a Workflow binding" the
+ * first day one of them learned about a new shape.
+ */
+export function workflowBindingFor(env: Record<string, unknown>, name: string): WorkflowBinding | undefined {
+  const value = env[name];
+  if (typeof value !== "object" || value === null) return undefined;
+  const create = (value as { create?: unknown }).create;
+  return typeof create === "function" ? (value as WorkflowBinding) : undefined;
+}
+
+/** The one environment a loopback substitution is made in. Verbatim, and the only one. */
+const LOOPBACK_ENVIRONMENT = "dev";
+
+/** What resolving a binding needs to know: which one, whose, and how to reach a sibling. */
+export interface WorkflowBindingRequest {
+  /** The binding name on the caller's own env — `EMAIL_SENDER`. */
+  binding: string;
+  /** The capability that owns the host. Names the origin var, and names the worker in a failure. */
+  capability: string;
+  /** Where a substitution is noted. Defaults to silence. */
+  log?: Logger;
+  /** The loopback transport. Defaults to the runtime's `fetch`; injectable for tests. */
+  fetch?: LoopbackFetch;
+}
+
+/** A non-blank string off the env, or `undefined`. Anything else on that key is not an address. */
+function stringVar(env: Record<string, unknown>, name: string): string | undefined {
+  const value = env[name];
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/**
+ * The binding to dispatch on: the real one, or — under `pithy dev` — a loopback stand-in for it.
+ *
+ * ## Why a stand-in exists at all
+ *
+ * A deployed app Worker starts a capability's Workflow through a **cross-script** binding pointing at
+ * `<project>-<env>-email`. `pithy dev` runs no script under that name, so locally that binding cannot
+ * work — it is absent, or it is present and every `create` on it fails — and every dispatch it carried
+ * went nowhere (pithy-sh/pithy#410). What *does* exist locally is the capability host itself, on a
+ * pinned port, with its address in this Worker's own vars as `<STEM>_ORIGIN`. So the seam is filled
+ * rather than left empty, and the call site — `enqueueEmail`, the cron handler, `c.var.workflows` — is
+ * byte-identical either way.
+ *
+ * ## Three rules, and each of them is a refusal
+ *
+ * **In `dev`, a published origin wins over the binding.** The deliberate order, and the one that
+ * closes #410 whatever wrangler decides to hand a local Worker for a script it is not running: a
+ * binding that is present but cannot reach anything is indistinguishable at runtime from one that
+ * works, so preferring it would leave the silence in place and depend on a wrangler behavior nothing
+ * here controls. Preferring the origin costs nothing, because a published origin is not something a
+ * composition can have by accident — see the next rule.
+ *
+ * **A published origin names a host `pithy dev` is running.** The orchestrator writes one `--var` per
+ * *capability host* in the dev set, and never hands a host its own address. So `EMAIL_ORIGIN` on a
+ * Worker's env means exactly one thing: the email host is up, locally, there. An adopter's own
+ * app-owned Workflow — the same-script shape, which `wrangler dev` implements unchanged — is never
+ * published an origin and so is never diverted.
+ *
+ * **Only `dev`.** Not `staging`, not `prod`, and — the case that matters — not a composition that
+ * stamped no environment at all. A gate that reads silence as `dev` opens itself in exactly the
+ * deployment whose `wrangler.jsonc` lost the var.
+ *
+ * **The environment comes off the request env, not off the host's shell.** `--var ENVIRONMENT` is
+ * what puts it on a Worker, and the shell that ran `wrangler dev` does not cross into workerd. The
+ * dispatch *route* reads the ambient env instead, because it is registered before any request exists;
+ * here there is a request env in hand, and it is the truthful one.
+ */
+export function resolveWorkflowBinding(
+  env: Record<string, unknown>,
+  request: WorkflowBindingRequest,
+): WorkflowBinding | undefined {
+  const origin =
+    stringVar(env, ENVIRONMENT_VAR) === LOOPBACK_ENVIRONMENT
+      ? stringVar(env, originVarName(request.capability))
+      : undefined;
+
+  if (origin) {
+    request.log?.debug("workflow dispatch over loopback", {
+      binding: request.binding,
+      capability: request.capability,
+      origin,
+    });
+    return loopbackWorkflowBinding({
+      origin,
+      binding: request.binding,
+      capability: request.capability,
+      fetch: request.fetch,
+    });
+  }
+
+  return workflowBindingFor(env, request.binding);
+}
+
+/**
+ * Start one registered job. The single dispatch path — `createBackend`'s per-request dispatcher and
+ * `createEntrypoint`'s cron handler both route through here, so a scheduled run and a manual one
+ * validate identically.
+ */
+export async function triggerWorkflow(
+  env: Record<string, unknown>,
+  registry: WorkflowRegistry,
+  key: string,
+  params: unknown,
+  log: Logger = noopLogger,
+): Promise<void> {
+  const entry = registry[key];
+  if (!entry) {
+    const known = Object.keys(registry).sort().join(", ");
+    throw new PithyError({
+      code: "core/unknown_workflow",
+      status: 500,
+      message: `No workflow is registered as "${key}".`,
+      action: "Check the key, and compose the capability that declares the job.",
+      detail: known ? `Registered workflows: ${known}.` : "No capability registered any workflow.",
+    });
+  }
+
+  // Params first: a bad payload is the caller's fault and must not depend on whether the binding
+  // happens to be wired, so the same mistake reports the same way in every environment.
+  const parsed = entry.spec.params.safeParse(params);
+  if (!parsed.success) {
+    throw new PithyError({
+      code: "core/invalid_workflow_params",
+      status: 400,
+      message: `The parameters for workflow "${key}" are not valid.`,
+      action: "Correct the parameters to match the workflow's schema.",
+      detail: (parsed.error as z.ZodError).issues
+        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+        .join("; "),
+    });
+  }
+
+  const binding = resolveWorkflowBinding(env, {
+    binding: entry.spec.binding,
+    capability: entry.capability,
+    log,
+  });
+  if (!binding) {
+    // An optional job is one whose host may not be provisioned yet. Throwing would take down a
+    // request path that works perfectly well without the job — `@pithy-sh/media` finalizes an upload
+    // and merely skips enrichment. So it degrades instead. It degrades *loudly*, though: the previous
+    // shape of this (an `?.create()` in media) made a whole capability silently do nothing, with no
+    // error and no log, which is the harder failure to diagnose by far.
+    if (entry.spec.optional) {
+      log.warn("workflow skipped", {
+        workflow: key,
+        binding: entry.spec.binding,
+        reason: "binding absent — the workflow host is not deployed or not bound",
+      });
+      return;
+    }
+    throw new PithyError({
+      code: "core/missing_workflow_binding",
+      status: 500,
+      message: `The workflow binding "${entry.spec.binding}" is not available.`,
+      action: `Deploy the ${entry.capability} workflow host, then bind ${entry.spec.binding} in wrangler.jsonc.`,
+      detail: `Dispatching "${key}" needs a Workflow binding named ${entry.spec.binding} on the Worker env.`,
+    });
+  }
+
+  try {
+    await binding.create({ params: parsed.data });
+  } catch (error) {
+    // **An optional job degrades on the dispatch too, not only on the binding.** `optional` is a
+    // promise about the caller's request path — it works without this job — and a binding that is
+    // there and will not start anything is the same fact to that path as one that is absent.
+    //
+    // Under `pithy dev` this is the ordinary case rather than the exotic one: the loopback stand-in is
+    // composed the moment `<STEM>_ORIGIN` is published, so the binding is never *absent*, and a host
+    // that has not matched its ready signal yet would otherwise turn a media finalize into a 502.
+    // Loudly, like the other half: the reason is logged, so a skipped job is never silent.
+    if (!entry.spec.optional) throw error;
+    log.warn("workflow skipped", {
+      workflow: key,
+      binding: entry.spec.binding,
+      reason: messageOf(error),
+    });
+  }
+}
+
+/**
+ * Build the per-request dispatcher over one registry. A closure rather than a lazily-built registry
+ * object: there is one method and no per-job resource to construct, so there is nothing to defer.
+ */
+export function buildWorkflowDispatcher<Params extends Record<string, unknown> = Record<string, unknown>>(
+  env: Record<string, unknown>,
+  registry: WorkflowRegistry,
+  log: Logger = noopLogger,
+): WorkflowDispatcher<Params> {
+  return {
+    trigger: (key, params) => triggerWorkflow(env, registry, key, params, log),
+  };
+}

package/src/workflow/dispatchRoute.ts

@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { zValidator } from "@hono/zod-validator";
+import type { Context, Hono, Next } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import { type AmbientEnv, ambientEnv, compositionEnvironment } from "../env/ambient";
+import { ForbiddenError, PithyError } from "../error/pithyError";
+import { validationHook } from "../http/validation";
+import type { VerificationStrategy } from "../http/verification";
+import { workflowBindingFor } from "./dispatch";
+import {
+  WORKFLOW_DISPATCH_ROUTE,
+  WorkflowDispatchParams,
+  WorkflowDispatchRequest,
+  type WorkflowDispatchResponse,
+} from "./schemas";
+import type { RegisteredWorkflow, WorkflowRegistry } from "./spec";
+
+/**
+ * The host's dispatch route — the loopback door `pithy dev` starts an instance through.
+ *
+ * ## Why a host needs an HTTP door at all
+ *
+ * A deployed app Worker starts a capability's Workflow through a **cross-script** binding:
+ * `{ binding: "EMAIL_SENDER", script_name: "<project>-<env>-email" }`. `pithy dev` does not run that
+ * second Worker's script under that name, and CLAUDE.md rules out wrangler's cross-`wrangler dev`
+ * registry, so locally the binding names nothing and the call throws (pithy-sh/pithy#410). What
+ * *does* exist locally is loopback: every worker in the dev set has a pinned port and an
+ * `<STEM>_ORIGIN` in every sibling's env. This route is the other end of that wire.
+ *
+ * The instance is started on the **host's own same-script binding** — the one with no `script_name`,
+ * which `wrangler dev` implements unchanged. So the local path and the deployed path run the same
+ * Workflow class, from the same registry, with the same params schema. Only the hop differs.
+ *
+ * ## The environment gate is the security boundary
+ *
+ * An HTTP door into another Worker's Workflows is not something the kit leaves open. The route is
+ * served in a `dev` composition and refused in every other, by a guard that runs before anything
+ * reads the request.
+ *
+ * **It is a mounted refusal, not an unmounted route** — deliberately the opposite of
+ * `@pithy-sh/auth`'s dev-login, and the difference is what the two routes do. Dev-login mints an
+ * authenticated session with no credential presented, so its existence in a production route table is
+ * itself the finding, and it registers nothing outside `dev`. This route starts a job the host
+ * already runs on its own cron, on a binding the caller must already have, and it starts nothing at
+ * all before the guard has run. What an operator gains from mounting it is the answer: a loopback
+ * dispatcher wired into `staging` by mistake gets `auth/forbidden` naming the binding as the path,
+ * rather than a 404 that reads as a typo and sends them looking at the URL.
+ *
+ * **There is no second CI gate**, and that too is the opposite of dev-login's, on purpose. CI is
+ * precisely where the local loop has to work — `pithy dev` under an integration suite is a `dev`
+ * composition dispatching over loopback — and a gate that shut it there would turn the silence #410
+ * repairs back on in the one place nobody is watching for it.
+ *
+ * ## Contract
+ *
+ * `public` verification and a declared request contract, with the guard ahead of both validators so
+ * a refusal is never downgraded to a 400 that tells a caller which request shapes are well-formed.
+ */
+
+/**
+ * How the route verifies its caller: it does not.
+ *
+ * Stated rather than omitted, because every route declares one (CLAUDE.md §HTTP) and `public` is the
+ * honest answer — there is no credential on this wire. What stands in for one is the environment
+ * gate plus the address: the route answers only in a `dev` composition, and a `dev` composition is a
+ * `wrangler dev` bound to loopback on a port `pithy dev` pinned. Deployed environments reach the same
+ * Workflow through the cross-script binding and never through this.
+ */
+export const WORKFLOW_DISPATCH_VERIFICATION: VerificationStrategy = "public";
+
+/** The environment this route serves in. Verbatim, and the only one. */
+const DISPATCH_ENVIRONMENT = "dev";
+
+/** What the route needs to serve: whose host this is, what it hosts, and where it is running. */
+export interface WorkflowDispatchOptions {
+  /** The capability that owns the host. Named in refusals, so an operator knows which Worker answered. */
+  capability: string;
+  /**
+   * The composed registry this host runs. The route resolves `:binding` against it, so a binding the
+   * host hosts no Workflow for is refused by name — and the params validate against the declaring
+   * spec's own schema rather than against anything restated here.
+   */
+  registry: WorkflowRegistry;
+  /**
+   * The ambient environment the gate reads. Defaults to the process env, which in a Worker is the
+   * script's own vars — where `pithy init` stamps `ENVIRONMENT`. Injectable for tests.
+   */
+  env?: AmbientEnv;
+}
+
+/** The job this host hosts on a given binding, or `undefined`. */
+function specForBinding(registry: WorkflowRegistry, binding: string): RegisteredWorkflow | undefined {
+  return Object.values(registry).find((entry) => entry.spec.binding === binding);
+}
+
+/**
+ * The refusal. `auth/forbidden` (403) rather than a 404: the door exists, it is shut because of
+ * *where* this Worker is running, and pretending otherwise costs the operator the sentence that ends
+ * their search. `action` names the real path and is stripped before it reaches the caller, like every
+ * other action.
+ */
+function refuseOutsideDev(capability: string, environment: string | undefined): ForbiddenError {
+  return new ForbiddenError({
+    message: `Workflow dispatch over HTTP is served only in the ${DISPATCH_ENVIRONMENT} environment.`,
+    action: `Dispatch through the cross-script ${capability} Workflow binding, or run this host under pithy dev.`,
+    detail: `The composition's ENVIRONMENT is ${environment ?? "unstamped"}.`,
+  });
+}
+
+/**
+ * Mount the dispatch route on a host worker's app.
+ *
+ * The guard is registered as middleware ahead of the validators so the order is structural rather
+ * than remembered: outside `dev` nothing reads the path, the body, or the env.
+ */
+export function registerWorkflowDispatchRoute(app: Hono<PithyHonoEnv>, options: WorkflowDispatchOptions): void {
+  const { capability, registry } = options;
+  const ambient = options.env;
+
+  // Read at call time, never captured: a module-scope snapshot freezes the answer for the life of an
+  // isolate and is unstubbable in a test.
+  const guard = async (_c: Context<PithyHonoEnv>, next: Next): Promise<void> => {
+    const environment = compositionEnvironment(ambient ?? ambientEnv());
+    if (environment !== DISPATCH_ENVIRONMENT) throw refuseOutsideDev(capability, environment);
+    await next();
+  };
+
+  app.post(
+    WORKFLOW_DISPATCH_ROUTE,
+    guard,
+    zValidator("param", WorkflowDispatchParams, validationHook),
+    zValidator("json", WorkflowDispatchRequest, validationHook),
+    async (c) => {
+      const { binding } = c.req.valid("param");
+      const { id, params } = c.req.valid("json");
+
+      const entry = specForBinding(registry, binding);
+      if (!entry) {
+        const known = Object.values(registry)
+          .map((registered) => registered.spec.binding)
+          .sort()
+          .join(", ");
+        throw new PithyError({
+          code: "core/unknown_workflow",
+          status: 500,
+          message: `No workflow on this host is bound to "${binding}".`,
+          action: `Check the binding name against the ${capability} capability's declared workflows.`,
+          detail: known ? `This host hosts: ${known}.` : "This host hosts no workflows at all.",
+        });
+      }
+
+      // Params before the binding, exactly as `triggerWorkflow` does it: a malformed payload is the
+      // caller's fault and must report the same way whether or not the binding happens to be wired.
+      const parsed = entry.spec.params.safeParse(params);
+      if (!parsed.success) {
+        throw new PithyError({
+          code: "core/invalid_workflow_params",
+          status: 400,
+          message: `The parameters for workflow "${entry.key}" are not valid.`,
+          action: "Correct the parameters to match the workflow's schema.",
+          detail: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "),
+        });
+      }
+
+      const target = workflowBindingFor(c.env as Record<string, unknown>, binding);
+      if (!target) {
+        throw new PithyError({
+          code: "core/missing_workflow_binding",
+          status: 500,
+          message: `The workflow binding "${binding}" is not available on this host.`,
+          action: `Bind ${binding} in the ${capability} host's wrangler.jsonc, then restart it.`,
+          detail: `Dispatching "${entry.key}" needs a same-script Workflow binding named ${binding}.`,
+        });
+      }
+
+      await target.create({ id, params: parsed.data });
+      // 202, not 200: Cloudflare has accepted the instance, and a Workflow is durable precisely so
+      // nobody holds its progress. `satisfies` binds the body to the response schema at compile time.
+      return c.json({ binding, id, started: true } satisfies WorkflowDispatchResponse, 202);
+    },
+  );
+}