@pithy-sh/core 0.1.0

package/src/controlPlane/wire.ts

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The control-plane wire contract: the names both ends of the seam must spell identically, and the one
+ * rule for reading what they carry.
+ *
+ * **This module imports nothing, and that is its whole job.** Per `docs/CONTROL-PLANE.md` §4 a browser
+ * calls the adopter's Worker *directly* — the management client's server mints the token, the browser
+ * sends it — so a DOM-typed module has to name the request header, and has to read the version header
+ * off the response to notice a customer deploying mid-session. Reaching these constants through
+ * `http/verify` drags the verifier in with them: WebCrypto, the replay guard, the seam config. A
+ * program compiled against `lib.dom` then fails on `token/digest.ts` and `token/jws.ts`, where a
+ * `Uint8Array<ArrayBufferLike>` is not the `BufferSource` the DOM lib declares — the Workers and DOM
+ * type libraries meeting, which no amount of care at the call site resolves.
+ *
+ * The alternative was to let each client re-declare the strings. That is what the dashboard did, with
+ * a comment and an assertion holding the copy honest, and two copies of a wire constant is exactly the
+ * drift a constant exists to prevent. `wire.test.ts` asserts the module graph here stays empty, because
+ * the property is only true until someone adds the first convenient import.
+ *
+ * {@link workerBuildChanged} is here for the same reason one level up. The dashboard did not only copy
+ * the header name — it wrote its own rule for reading the value, "invalidate when the id differs", and
+ * that rule was wrong in a way a copied constant could never have caught. A rule both ends must agree on
+ * belongs beside the names both ends must spell.
+ */
+
+/**
+ * The header a control-plane token is presented on.
+ *
+ * Not `Authorization`, deliberately: `@pithy-sh/auth` builds a Better Auth instance for any request
+ * carrying that header, so a management call would drag the whole auth stack in. See `http/verify.ts`.
+ */
+export const CONTROL_PLANE_HEADER = "pithy-control-plane";
+
+/**
+ * The response header carrying the build that answered a control-plane call.
+ *
+ * Set on every control-plane response — allowed and denied alike, and on every capability's admin
+ * routes rather than only the seam's own. A management client reads it to pin each recorded action to
+ * the exact build it hit, and to notice a version changing mid-session, which is the moment a rendered
+ * pane has quietly gone out of date. Absent where the `CF_VERSION_METADATA` binding is, which reads as
+ * "this Worker cannot say" rather than as a value to trust.
+ *
+ * **Carries the id and nothing else, permanently.** Its companion below is a second header rather than
+ * a second field in this one for one reason: a client already deployed compares this whole string. Fold
+ * anything into it and the day the adopter upgrades the kit reads as a version change that never
+ * happened — a false invalidation, which is the failure the pair exists to prevent, arriving from the
+ * fix for it.
+ */
+export const CONTROL_PLANE_VERSION_HEADER = "pithy-worker-version";
+
+/**
+ * The response header carrying **when the running version was uploaded** — ISO-8601, verbatim, off the
+ * same `CF_VERSION_METADATA` binding as the id.
+ *
+ * Read beside {@link CONTROL_PLANE_VERSION_HEADER}, never folded into it, so a client can compare two
+ * values separately. {@link workerBuildChanged} is the rule; do not hand-write one.
+ *
+ * **Cloudflare has two objects, and this is the first of them.** A *version* is an immutable upload of
+ * code and config — id, created timestamp, tag, fixed at upload and never again. A *deployment* points
+ * at one or more versions with traffic percentages, and is its own object with its own id and time. The
+ * `CF_VERSION_METADATA` binding reports the version, and **the runtime hands a Worker no binding for the
+ * deployment**. So this header is the upload moment, and it is fixed for as long as that version exists.
+ *
+ * That mechanism predicts the behavior rather than merely recording it: **a rollback creates a new
+ * deployment aimed at an existing version, so nothing here moves** — the binding is not stale and not
+ * ambiguous, the thing that changed was a different object. It answers the next question too. A traffic
+ * split, a gradual rollout, which deployment is serving: none of it is visible from inside a Worker.
+ *
+ * Measured on a real account, 2026-08-10, which is what made it a fact rather than a reading of the
+ * docs: version `A` uploaded at `22:28:56.762349Z`, `B` four seconds later, `wrangler rollback` to `A`
+ * at ~`22:29:20`. Reading at `22:31:37` returned `A`'s id **and `A`'s original timestamp**, unmoved,
+ * while wrangler's own output named the new deployment's version list. Two details from the same run
+ * that a client will meet:
+ *
+ * - **Every `wrangler deploy` mints a new version**, even for a one-character change — that is why `B`
+ *   exists. An ordinary redeploy therefore always moves the id, and is never invisible.
+ * - **Propagation lags.** Twenty seconds after wrangler reported the rollback at 100%, the URL still
+ *   answered from the older version. A client watching closely sees the pair flip and settle; that is
+ *   the platform converging, not two deploys.
+ */
+export const CONTROL_PLANE_VERSION_CREATED_HEADER = "pithy-worker-version-created";
+
+/**
+ * The pair a client reads off one control-plane response: two `headers.get()` calls, each `string | null`.
+ */
+export interface WorkerBuild {
+  /** {@link CONTROL_PLANE_VERSION_HEADER}, or `null` where the response carried none. */
+  version: string | null;
+  /** {@link CONTROL_PLANE_VERSION_CREATED_HEADER}, or `null` where the response carried none. */
+  createdAt: string | null;
+}
+
+/**
+ * Did the Worker answering now differ from the Worker that answered before?
+ *
+ * **The rule, total over the pair.** A client compares field by field and only where both sides carried
+ * a value; anything that differs is a change. Four states:
+ *
+ * 1. nothing differs — the same build, still answering. Say nothing.
+ * 2. `version` differs — a different build is live, and what is rendered came from one that no longer
+ *    serves.
+ * 3. `version` the same, `createdAt` differs — **the same build was deployed again.** Same consequence.
+ * 4. either side silent on a field — that field says nothing.
+ *
+ * **State 3 is not reachable on today's platform, and it stays anyway.** A version's timestamp
+ * is fixed at upload and a rollback only makes a new deployment, so the pair cannot show a moved time
+ * against an unmoved id (see {@link CONTROL_PLANE_VERSION_CREATED_HEADER}). It is here because a total
+ * comparison over the pair is the correct shape, not because a rollback was expected to trip it — **a
+ * comparison that enumerates which fields are allowed to move is wrong the day the platform moves a
+ * different one**, and it is wrong silently, as "nothing changed". It costs one branch.
+ *
+ * Direction is *not* interpreted. A time that moved is a fact; "it moved backwards, therefore a
+ * rollback" is not, and would be wrong twice over — a rollback moves neither field, and propagation lag
+ * makes an older version answer for a while after a deploy.
+ *
+ * **What no state here reaches: a deployment.** Rollbacks, traffic splits, gradual rollouts — a Worker
+ * has no binding for the object that carries them, so this is a boundary of what the runtime exposes
+ * rather than a gap in the seam. A client that needs a deployment reads Cloudflare's deployments API.
+ *
+ * **Absence is never change**, in every direction: a Worker that declares no `version_metadata` sends
+ * neither header, a call that failed before its headers were read has none, and a client that has not
+ * looked yet holds nulls. A blank value counts as absent too — the seam never sends one, but a proxy in
+ * between can blank a header it does not understand, and an empty string differs from every real id. The
+ * failure this shape refuses is the one that costs an adopter trust: invalidating a rendered pane on a
+ * deploy that never happened.
+ */
+export function workerBuildChanged(before: WorkerBuild, after: WorkerBuild): boolean {
+  return differs(before.version, after.version) || differs(before.createdAt, after.createdAt);
+}
+
+/** One field of the pair: a difference only where both sides actually said something. */
+function differs(before: string | null, after: string | null): boolean {
+  if (typeof before !== "string" || before.trim() === "") return false;
+  if (typeof after !== "string" || after.trim() === "") return false;
+  return before !== after;
+}

package/src/createBackend.ts

@@ -0,0 +1,292 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Hono } from "hono";
+import { noopEmit } from "./audit/recorder";
+import { BindingSpec } from "./capability/bindings";
+import type {
+  Capability,
+  MergedDatabases,
+  MergedKvNamespaces,
+  MergedWorkflowParams,
+  PithyHonoEnv,
+  PithyVars,
+} from "./capability/capability";
+import { recordComposition } from "./capability/composition";
+import { validateBindings } from "./capability/validateBindings";
+import { isControlPlaneCapability } from "./controlPlane/capability";
+import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors";
+import { buildDbRegistry, composeDatabases, type DbRegistry } from "./data/databases";
+import { noEntitlementProvider } from "./entitlement/entitlement";
+import { pithyErrorHandler } from "./error/http";
+import { ValidationError } from "./error/pithyError";
+import { catalogFor, composeMessages } from "./i18n/registry";
+import { bakedTranslator, DEFAULT_LOCALE } from "./i18n/translator";
+import { buildKvRegistry, composeKv, type KvRegistry } from "./kv/namespaces";
+import type { Logger } from "./logger/logger";
+import { bindRequestContext, createWorkerLogger } from "./logger/worker";
+import { HEALTH_PATH } from "./worker/health";
+import { workerVersion } from "./worker/identity";
+import { registeredWorkflowBinding } from "./workflow/bindings";
+import { buildWorkflowDispatcher, type WorkflowDispatcher } from "./workflow/dispatch";
+import { composeWorkflows } from "./workflow/register";
+
+/** Inputs to {@link createBackend}: the capabilities to assemble, plus the app's own capability. */
+export interface CreateBackendOptions<Caps extends readonly Capability[], App extends Capability> {
+  /** Library capabilities (core + each `@pithy-sh/*`), composed in order. */
+  capabilities: Caps;
+  /**
+   * The app itself, as a `Capability` — principle 4: the app is just another capability. Its
+   * databases, KV namespaces, middleware, routes, and bindings compose with the rest; routes last.
+   */
+  app?: App;
+  /**
+   * The base logger bound to `c.var.log`, set **once** here at assembly (the per-request `env`
+   * constraint is honored: correlation fields are bound per request, not at module load). Defaults to
+   * the CF-native Mode 2 worker logger (`info`, structured records to Workers Logs). Pass a configured
+   * one to change the level or attach a tail/Logpush transport.
+   */
+  logger?: Logger;
+  /**
+   * Fallback environment name (`dev` | `staging` | `production`) for the log correlation `env` field.
+   * The primary signal is the per-request `ENVIRONMENT` var (the convention `@pithy-sh/secrets` and
+   * `@pithy-sh/email` already stamp into each deployed Worker); this is only used where that var is
+   * absent — e.g. a non-provisioned local run. Falls through to `unknown` when neither is present.
+   */
+  env?: string;
+}
+
+/** The Hono env `createBackend` returns — `db`/`kv`/`workflows` typed precisely from the merged capabilities. */
+type BackendEnv<Caps extends readonly Capability[]> = {
+  Bindings: Record<string, unknown>;
+  Variables: Omit<PithyVars, "db" | "kv" | "workflows"> & {
+    db: DbRegistry<MergedDatabases<Caps>>;
+    kv: KvRegistry<MergedKvNamespaces<Caps>>;
+    workflows: WorkflowDispatcher<MergedWorkflowParams<Caps>>;
+  };
+};
+
+/**
+ * Collapse duplicate bindings (same `type:name`) — capability and derived specs overlap. A binding
+ * required by **any** source stays required: a derived database/namespace binding (structurally
+ * required — the request context builds a handle on it) must not be masked by an author marking the
+ * same binding `optional`. So `optional` is the AND of every occurrence.
+ */
+function dedupeBindings(specs: BindingSpec[]): BindingSpec[] {
+  const byKey = new Map<string, BindingSpec>();
+  for (const spec of specs) {
+    const key = `${spec.type}:${spec.name}`;
+    const existing = byKey.get(key);
+    if (!existing) byKey.set(key, { ...spec });
+    else if (!spec.optional) existing.optional = false;
+  }
+  return [...byKey.values()];
+}
+
+/**
+ * The deployed Worker version id, for the log record's `version` correlation field.
+ *
+ * Delegates to `workerVersion` rather than re-reading the binding: this used to be a private copy here,
+ * and a second reader of one binding is how the name and the declaration drift apart. `undefined` rather
+ * than `null` because the logger omits an undefined field.
+ */
+function versionOf(env: Record<string, unknown>): string | undefined {
+  return workerVersion(env) ?? undefined;
+}
+
+/**
+ * The environment name for log correlation, resolved from context: the per-request `ENVIRONMENT` var
+ * (the signal `@pithy-sh/secrets`/`@pithy-sh/email` stamp into each deployed Worker), else the explicit
+ * `createBackend({ env })` fallback, else `unknown`. No caller effort where `ENVIRONMENT` is present.
+ */
+function envNameOf(env: Record<string, unknown>, fallback: string | undefined): string {
+  return typeof env.ENVIRONMENT === "string" && env.ENVIRONMENT.length > 0 ? env.ENVIRONMENT : (fallback ?? "unknown");
+}
+
+/**
+ * Assemble capabilities into a deployable Hono app — a valid Worker `fetch` handler.
+ *
+ * Serves `GET /health`; merges every capability's `databases` and `kvNamespaces` into registries
+ * (tables/stores unioned per group); validates that every required binding is present; composes
+ * each capability's middleware; and mounts the capability (then app) routes. On every request
+ * `c.var.db` is the typed database registry — one `Kysely` per named database (`c.var.db.app`) —
+ * and `c.var.kv` the typed namespace registry — one `TypedKv` per store (`c.var.kv.cms.pages`).
+ * `PithyError`s become their declared HTTP status via {@link pithyErrorHandler}.
+ *
+ * Binding validation runs **once on the first request**, not at module load: in Workers `env` is
+ * per-request, so there is no env to check until a request arrives. The result is memoized.
+ *
+ * The return is typed precisely from the capabilities array — `createBackend({ capabilities }).get(
+ * "/x", (c) => c.var.db.app.selectFrom("…"))` gets autocomplete on every registered table.
+ */
+export function createBackend<
+  const Caps extends readonly Capability[],
+  const App extends Capability = Capability<Record<never, never>, Record<never, never>>,
+>(options: CreateBackendOptions<Caps, App>): Hono<BackendEnv<readonly [...Caps, App]>> {
+  // The app is just another capability, composed last so its routes mount after the libraries'.
+  const all: Capability[] = options.app ? [...options.capabilities, options.app] : [...options.capabilities];
+
+  // Fail fast on a missing peer capability: a capability that reads another's seam (e.g. turnstile
+  // reading secrets) must be composed with it, or its requests would only fail one-by-one at runtime.
+  const present = new Set(all.map((cap) => cap.name));
+  for (const cap of all) {
+    for (const dep of cap.dependsOn ?? []) {
+      if (!present.has(dep)) {
+        throw new ValidationError({
+          message: `Capability "${cap.name}" requires the "${dep}" capability, which is not composed.`,
+          action: `Add ${dep}() to createBackend's capabilities (run \`pithy add ${dep}\`).`,
+        });
+      }
+    }
+  }
+
+  // Startup hooks: each capability may wire across the full composed set (e.g. @pithy-sh/secrets
+  // aggregates every capability's secretRegistry into one combined registry). Runs once at assembly,
+  // after dependsOn validation so a hook can rely on its peers being present.
+  for (const cap of all) cap.compose?.({ capabilities: all });
+
+  // Recorded after the hooks, so a capability found later is one whose own wiring is complete. This is
+  // the only way back to a composed seam from a Workflow step, which the runtime constructs with `env`
+  // and nothing else — see `capability/composition.ts` (pithy-sh/pithy#356).
+  recordComposition(all);
+
+  const databases = composeDatabases(all);
+  // Every composed capability's English, merged under the domain rule. Built once at assembly rather
+  // than per request: it is a pure function of the capability set, which cannot change between them.
+  const messages = composeMessages(all);
+  // The seam's behavior with no i18n capability composed — the baked English, no negotiation, no merge.
+  // `@pithy-sh/i18n`'s middleware replaces it per request; nothing else ever does.
+  const defaultTranslator = bakedTranslator(catalogFor(messages, DEFAULT_LOCALE));
+  const namespaces = composeKv(all);
+  const workflows = composeWorkflows(all);
+
+  // Each named database implies its D1 binding; each KV namespace implies its KV binding; each
+  // registered job implies its Workflow binding. Derive them so the fail-fast check covers every
+  // binding the request context will actually build or dispatch to.
+  //
+  // A job's `optional` rides through: `@pithy-sh/media` declares its enrichment Workflows optional
+  // so an app still boots before `pithy media provision` has deployed the host, and `dedupeBindings`
+  // ANDs `optional` across occurrences — deriving these as unconditionally required would override
+  // that and break every project that has not provisioned yet.
+  const required = dedupeBindings([
+    ...all.flatMap((cap) => cap.requiredBindings),
+    ...Object.values(databases).map((db) => BindingSpec.parse({ type: "d1", name: db.binding })),
+    ...Object.values(namespaces).map((ns) => BindingSpec.parse({ type: "kv", name: ns.binding })),
+    ...Object.values(workflows).map((entry) => BindingSpec.parse(registeredWorkflowBinding(entry))),
+  ]);
+
+  // Build internally against the loose base env (db/kv are `unknown`, so `c.set` accepts the merged
+  // registries); the precise types ride on the return below.
+  const app = new Hono<PithyHonoEnv>();
+  app.onError(pithyErrorHandler);
+
+  // Set once at assembly (the per-request `env` constraint holds: correlation binds per request below,
+  // not here). Defaults to the CF-native Mode 2 logger — structured records to Workers Logs, zero-config.
+  const baseLogger = options.logger ?? createWorkerLogger();
+
+  // **CORS first — before this Worker's own base middleware and before every capability's.**
+  //
+  // Hono runs middleware in registration order, so whatever registers first is the only thing that can
+  // put a header on a response somebody else short-circuits. Capabilities short-circuit for real
+  // reasons: `@pithy-sh/vector`'s `provisionGuard` is an `app.use("*")` that throws on every request
+  // when the provision record disagrees with config. Register CORS after that and a misprovisioned
+  // Worker answers a management call with no `Access-Control-Allow-Origin`, so the dashboard sees the
+  // opaque `fetch` TypeError this exists to remove — on precisely the misconfiguration where the
+  // operator most needs to read the real message. Ahead of `validateBindings` for the same reason.
+  //
+  // It lives here rather than in the capability's `middleware` hook because that hook runs inside the
+  // loop below, in the adopter's composition order, and this must not depend on where they listed
+  // `controlplane()`. The surface is every composed capability's `adminRoutes` — `corsSurface` reads
+  // exactly the shape a `Capability` already has — so nothing outside that table gains a header.
+  const controlPlane = all.find(isControlPlaneCapability);
+  if (controlPlane) {
+    const cors = controlPlane.controlPlaneConfig;
+    registerControlPlaneCors(app, corsSurface(all), allowedOriginSet(cors), cors.corsMaxAgeSeconds);
+  }
+
+  let validated = false;
+  app.use("*", async (c, next) => {
+    const env = c.env as Record<string, unknown>;
+    if (!validated) {
+      validateBindings(env, required);
+      validated = true;
+    }
+    if (c.get("auth") === undefined) c.set("auth", null);
+    // Null means nothing negotiated, which is not the same fact as "the default was chosen" — only
+    // `@pithy-sh/i18n` ever sets it, and `c.var.t` works either way.
+    if (c.get("locale") === undefined) c.set("locale", null);
+    // Zero-config like `log`: a real translator is always present, so no capability null-checks one.
+    if (c.get("t") === undefined) c.set("t", defaultTranslator);
+    // Its own variable, never folded into `auth`: a management client is not a user of this app, so a
+    // control-plane call must not satisfy any capability's `requireAuth()`. Null until the seam's
+    // middleware verifies a credential, which is what makes every control-plane route default-denied.
+    if (c.get("controlPlane") === undefined) c.set("controlPlane", null);
+    // Null unless the `controlplane()` capability's middleware publishes one. Every
+    // `requireControlPlane()` gate in the tree denies while it is null, so an admin route in a Worker
+    // that never composed the seam is closed rather than unguarded.
+    if (c.get("controlPlaneVerifier") === undefined) c.set("controlPlaneVerifier", null);
+    // Null unless a capability publishes a gate bound to the origins it resolved. Every
+    // `requireSameOrigin()` denies while it is null — a CSRF check whose policy is missing must refuse,
+    // not wave the request through.
+    if (c.get("sameOrigin") === undefined) c.set("sameOrigin", null);
+    if (c.get("emit") === undefined) c.set("emit", noopEmit);
+    // Fail closed: with no payments capability composed, nothing is held and every gate denies.
+    if (c.get("entitlements") === undefined) c.set("entitlements", noEntitlementProvider);
+    if (c.get("log") === undefined) {
+      c.set(
+        "log",
+        bindRequestContext(baseLogger, {
+          // The CF ray id correlates a request across Cloudflare's logs; fall back to a uuid off-platform.
+          request: c.req.header("cf-ray") ?? crypto.randomUUID(),
+          method: c.req.method,
+          path: c.req.path,
+          env: envNameOf(env, options.env),
+          version: versionOf(env),
+        }),
+      );
+    }
+    if (c.get("db") === undefined) c.set("db", buildDbRegistry(env, databases));
+    if (c.get("kv") === undefined) c.set("kv", buildKvRegistry(env, namespaces, c.var.log));
+    if (c.get("workflows") === undefined) c.set("workflows", buildWorkflowDispatcher(env, workflows, c.var.log));
+
+    // Auto access-log: one record per request carrying the response `status` and `elapsed`, resolved
+    // from context with no caller effort — the completion of the request-correlation seam.
+    const start = Date.now();
+    await next();
+    c.var.log.info("request", { status: c.res.status, elapsed: Date.now() - start });
+  });
+
+  /**
+   * `GET {@link HEALTH_PATH}` — liveness, and **which build is answering**.
+   *
+   * The path is `worker/health.ts`'s, not a literal here. Three other sites need the same string — the
+   * CLI's route allowlist, `pithy deploy`'s post-deploy probe, and the bare home screen a no-auth
+   * scaffold seeds — and that last one is in somebody else's repository, rendering nothing but this
+   * request's answer (#400).
+   *
+   * The version is what turns `pithy deploy`'s post-deploy check from a liveness probe into an
+   * assertion. `status: "ok"` at the declared domain proves *a* Worker is there; it does not prove it is
+   * the one just shipped, and the old version answering happily is exactly the failure worth catching —
+   * a deploy that landed somewhere else while the declared domain kept serving what was already on it.
+   * With the id here, `deploy` compares what it shipped against what replies.
+   *
+   * **Public, deliberately.** A Cloudflare version id is an opaque UUID carrying no version semantics
+   * and no exploitable detail, and most platforms expose a build identifier. The alternative — reporting
+   * it only through the authenticated control-plane manifest — is better for privacy and useless for
+   * deploy verification, since `deploy` holds no control-plane credential.
+   *
+   * `null` where the binding is absent, which is honest rather than misleading: a project scaffolded
+   * before `version_metadata` was declared reports "I cannot tell you", and `deploy` reports the check
+   * as inconclusive instead of failing it.
+   */
+  app.get(HEALTH_PATH, (c) => c.json({ status: "ok", version: workerVersion(c.env) }));
+
+  for (const cap of all) {
+    for (const middleware of cap.middleware ?? []) middleware(app);
+  }
+  for (const cap of all) {
+    cap.routes?.(app);
+  }
+
+  return app as unknown as Hono<BackendEnv<readonly [...Caps, App]>>;
+}

package/src/createEntrypoint.ts

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/workers-types";
+import type { Capability, CapabilityEmailHandler } from "./capability/capability";
+import { type CreateBackendOptions, createBackend } from "./createBackend";
+import { triggerWorkflow } from "./workflow/dispatch";
+import { composeWorkflows, scheduledWorkflows } from "./workflow/register";
+
+/**
+ * A deployable Worker entrypoint: `fetch`, the single inbound `email` handler the runtime permits
+ * per Worker, and the single `scheduled` handler it permits for cron triggers. `createBackend`
+ * already produces the `fetch` side (a Hono app); this wraps it and composes every capability's
+ * inbound-email handler and every cron-carrying durable job behind those two entries, so a Worker
+ * that mounts `@pithy-sh/email` receives bounce/complaint mail — and fires its scheduler — without
+ * the user authoring a handler.
+ */
+export interface PithyEntrypoint {
+  /** The Worker `fetch` handler — the composed Hono app. */
+  fetch: (request: Request, env: Record<string, unknown>, ctx: ExecutionContext) => Response | Promise<Response>;
+  /**
+   * The Worker `email` handler — fans each incoming message to every capability that declares one.
+   * **Present only when at least one capability handles inbound mail.** Omitted otherwise, so a Worker
+   * that no capability wired for email doesn't expose a no-op `email()` that would silently *drop* any
+   * message routed to it (an exported-but-inert handler consumes the message without forwarding or
+   * rejecting it).
+   */
+  email?: (message: ForwardableEmailMessage, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
+  /**
+   * The Worker `scheduled` handler — starts every registered job that declares a `schedule`.
+   *
+   * **Present only when at least one job carries a cron.** The reason differs from `email`'s: an
+   * inert `email()` silently *drops* mail, which is a correctness bug, whereas an inert `scheduled()`
+   * is merely harmless. It is omitted anyway so that the export tracks the composition: a Worker
+   * mounting no scheduled job does not advertise a schedule it has none of.
+   *
+   * The converse does happen and is deliberate. A capability whose cron belongs to its *prebuilt host*
+   * — `@pithy-sh/email`'s every-minute scheduler is the shipped example — still declares that schedule
+   * on its spec, so an app worker composing it exports a `scheduled` handler while its own
+   * `wrangler.jsonc` declares no `triggers.crons`. Nothing ever invokes it, and if something did, the
+   * job's binding lives only on the host, so dispatch degrades with a logged warning. Deriving the
+   * export from "does this deployment declare crons" is not available here: `createEntrypoint` sees
+   * the composed capabilities, never the wrangler config.
+   *
+   * A cron is an *additional* entry point, never the only one: every scheduled job stays dispatchable
+   * through `c.var.workflows.trigger(...)`, because a backfill nobody can run on demand cannot be
+   * tested in staging.
+   */
+  scheduled?: (controller: unknown, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
+}
+
+/**
+ * The raw MIME stream of a `ForwardableEmailMessage` is **single-use** — once one handler reads it,
+ * the next sees an empty stream. When more than one capability handles inbound mail we buffer the
+ * body once and hand each handler a proxy whose `raw` yields a fresh stream over that buffer; every
+ * other property/method delegates to (and stays bound to) the real message.
+ */
+function replayable(message: ForwardableEmailMessage, raw: ArrayBuffer): ForwardableEmailMessage {
+  return new Proxy(message, {
+    get(target, prop, receiver) {
+      if (prop === "raw") return new Response(raw.slice(0)).body as ReadableStream<Uint8Array>;
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+/**
+ * Assemble capabilities into a Worker entrypoint object — `{ fetch, email }`. Use this instead of
+ * `createBackend` directly when any capability handles inbound email (e.g. `@pithy-sh/email`'s bounce
+ * handler). `fetch` is the same Hono app `createBackend` returns; `email` fans each incoming message
+ * to every capability's `email` handler, replaying the single-use raw stream so each sees the full
+ * message. Handlers run sequentially in registration order.
+ */
+export function createEntrypoint<
+  const Caps extends readonly Capability[],
+  const App extends Capability = Capability<Record<never, never>, Record<never, never>>,
+>(options: CreateBackendOptions<Caps, App>): PithyEntrypoint {
+  const app = createBackend(options);
+  const all: Capability[] = options.app ? [...options.capabilities, options.app] : [...options.capabilities];
+  const handlers: CapabilityEmailHandler[] = all.flatMap((cap) => (cap.email ? [cap.email] : []));
+
+  const registry = composeWorkflows(all);
+  const scheduled = scheduledWorkflows(registry);
+
+  const entrypoint: PithyEntrypoint = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+
+  // Cron-carrying jobs get the Worker's one `scheduled` entry. Each is started independently so one
+  // job whose binding is missing cannot stop the rest of the schedule from running; the failure is
+  // rethrown after the pass so the invocation is still recorded as failed.
+  if (scheduled.length > 0) {
+    entrypoint.scheduled = async (_controller, env) => {
+      const failures: unknown[] = [];
+      for (const entry of scheduled) {
+        // A cron supplies no caller input, which is an *empty* parameter object, not an absent one —
+        // `z.object({})` accepts `{}` and rejects `undefined`. A job whose schema requires fields it
+        // can never receive on a schedule therefore fails loudly here, which is the author's bug and
+        // is exactly what should surface.
+        try {
+          await triggerWorkflow(env, registry, entry.key, {});
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      if (failures[0] !== undefined) throw failures[0];
+    };
+  }
+
+  // Only expose an `email` handler when something actually handles inbound mail — an inert one would
+  // silently drop any message Email Routing delivered to this Worker.
+  if (handlers.length > 0) {
+    entrypoint.email = async (message, env, ctx) => {
+      if (handlers.length === 1) {
+        await handlers[0]?.(message, env, ctx);
+        return;
+      }
+      // Multiple consumers: buffer the raw body once, then replay it per handler.
+      const raw = await new Response(message.raw).arrayBuffer();
+      for (const handler of handlers) {
+        await handler(replayable(message, raw), env, ctx);
+      }
+    };
+  }
+  return entrypoint;
+}