@pithy-sh/core 0.1.0

package/src/workflow/hostEnv.ts

@@ -0,0 +1,258 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { InternalError } from "../error/pithyError";
+import type { Logger } from "../logger/logger";
+import { createWorkerLogger } from "../logger/worker";
+
+/**
+ * What a capability host worker reads out of its env, and what fills each of it.
+ *
+ * A host is a Worker nobody authored: `pithy <capability> provision` resolves a committed template
+ * (see {@link ./host.ts}) and deploys it. Everything it needs therefore arrives as a binding, a var,
+ * a Secrets Store entry or a serialized config blob — and until this module, **none of it was
+ * validated anywhere.** `@pithy-sh/email`'s host read fourteen fields raw: a missing `BASE_URL`
+ * became a magic link to `undefined/…`, an unparseable `EMAIL_THEME` threw inside a render step
+ * three retries deep, and a `SCHEDULER_BATCH_SIZE` somebody typed as `"fifty"` became `NaN`, so the
+ * scheduler claimed nothing, quietly, forever. Every one of those is discovered as a mail that did
+ * not arrive.
+ *
+ * So a host declares its env once, as a Zod object with a `.describe()` per field, and pairs each
+ * field with the thing that provides it. Two consumers read that one declaration:
+ *
+ * - the host itself, at boot, through {@link requireHostEnv} — one legible block naming every
+ *   unusable value and what fills it, then a refusal. A host that cannot work does not wait to be
+ *   asked.
+ * - `pithy doctor`, statically, through {@link hostEnvFields} and {@link checkHostEnv} — the same
+ *   schema, so the check an operator runs and the check the host runs cannot disagree.
+ *
+ * ## Kept importable from the CLI
+ *
+ * No `cloudflare:` import, no Node builtin, no filesystem — the same constraint {@link ./host.ts}
+ * carries, and for the same reason: `pithy doctor` runs under node and imports this to read a
+ * capability's declaration without executing its Worker.
+ */
+
+/** The kinds of thing that can fill a host env field. One of these names is what an operator acts on. */
+export const HostEnvProviderKind = z
+  .enum(["binding", "var", "secret", "config"])
+  .describe(
+    "Where a host env field comes from: a Worker `binding`, a wrangler `var`, a `secret` read through @pithy-sh/secrets, or a `config` key in the adopter's pithy.config.ts.",
+  );
+export type HostEnvProviderKind = z.infer<typeof HostEnvProviderKind>;
+
+/**
+ * What provides one field. The whole point of the declaration: a report that says `BASE_URL is
+ * missing` sends a developer looking, and a report that says `Var BASE_URL in the host's
+ * wrangler.jsonc. Run pithy email provision --env dev.` ends the search.
+ */
+export const HostEnvProvider = z
+  .object({
+    kind: HostEnvProviderKind.describe("Which kind of thing fills this field."),
+    name: z
+      .string()
+      .min(1)
+      .describe("The binding name, var name, secret name, or config key — spelled exactly as it is authored."),
+    command: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("The `pithy` command that fills it, where one does. Rendered as the report's action line."),
+  })
+  .describe("What fills one field of a host worker's env, so a failure names the thing an operator changes.");
+export type HostEnvProvider = z.infer<typeof HostEnvProvider>;
+
+/**
+ * A host's env declaration: the capability that owns it, the schema, and a provider per field.
+ *
+ * **This type is the contract `pithy doctor` reads** (pithy-sh/pithy#411). A capability exports one
+ * of these as an ordinary value, so the CLI can import it, walk the schema, and validate a resolved
+ * configuration against the very object the deployed Worker validates itself against.
+ */
+export interface HostEnvDeclaration<Env extends z.ZodObject = z.ZodObject> {
+  /** The capability that owns the host — the `<capability>` segment of its worker name. */
+  readonly capability: string;
+  /** The env schema. `z.output` is what the host runs on; coercions and JSON parses belong in here. */
+  readonly env: Env;
+  /** Field name → what fills it. Every field of {@link env} has an entry; nothing else may. */
+  readonly provided: Readonly<Record<string, HostEnvProvider>>;
+}
+
+/**
+ * Declare a host's env. The mapped `provided` type makes an unaccounted field a compile error; the
+ * runtime check below makes it an error for a declaration the CLI reads back off a package it never
+ * compiled, which is the case `pithy doctor` is entirely made of.
+ */
+export function defineHostEnv<Env extends z.ZodObject>(declaration: {
+  capability: string;
+  env: Env;
+  provided: { readonly [Field in keyof Env["shape"] & string]: HostEnvProvider };
+}): HostEnvDeclaration<Env> {
+  const fields = Object.keys(declaration.env.shape);
+  const unaccounted = fields.filter((field) => !(field in declaration.provided));
+  if (unaccounted.length > 0) {
+    throw new InternalError({
+      message: `The ${declaration.capability} host env declares fields nothing provides.`,
+      action: "Add a provider for each field: the binding, var, secret, or config key that fills it.",
+      detail: `Unaccounted fields: ${unaccounted.join(", ")}.`,
+    });
+  }
+  return declaration;
+}
+
+/** One field of a host env that is missing or unparseable, with what would fix it. */
+export interface HostEnvProblem {
+  /** The field name, as declared. */
+  field: string;
+  /** Why it is unusable — the Zod issue's own message, unedited. */
+  reason: string;
+  /** What provides it. */
+  provider: HostEnvProvider;
+}
+
+/** The outcome of checking one env against one declaration. `value` is present exactly when `ok`. */
+export interface HostEnvReport<Value> {
+  /** Whether every declared field parsed. */
+  ok: boolean;
+  /** The parsed env — the shape the host runs on — or `undefined` when anything failed. */
+  value: Value | undefined;
+  /** Every unusable field, one entry each, in declaration order. */
+  problems: HostEnvProblem[];
+}
+
+/** The provider reported for a field the declaration never accounted for. Should be unreachable. */
+function undeclaredProvider(field: string): HostEnvProvider {
+  return { kind: "var", name: field };
+}
+
+/**
+ * Check an env against a declaration. Pure: it parses, it reports, and it neither logs nor throws —
+ * which is what lets `pithy doctor` run the host's own check without a Worker.
+ *
+ * One problem per field, even where Zod raises several issues for it: an operator fixes a field, not
+ * an issue, and three lines about `EMAIL_THEME` push the field they have not read yet off the block.
+ */
+export function checkHostEnv<Env extends z.ZodObject>(
+  declaration: HostEnvDeclaration<Env>,
+  env: unknown,
+): HostEnvReport<z.output<Env>> {
+  // An env that is not an object at all — `undefined` in a runtime that never bound one — still has to
+  // report per field rather than as one "expected object": the operator's next move is the same either
+  // way, and it is named in the fields.
+  const subject = typeof env === "object" && env !== null ? env : {};
+  const parsed = declaration.env.safeParse(subject);
+  if (parsed.success) return { ok: true, value: parsed.data, problems: [] };
+
+  const reasons = new Map<string, string>();
+  for (const issue of parsed.error.issues) {
+    const field = issue.path[0];
+    if (typeof field !== "string" || reasons.has(field)) continue;
+    reasons.set(field, issue.message);
+  }
+
+  const problems: HostEnvProblem[] = [];
+  for (const field of Object.keys(declaration.env.shape)) {
+    const reason = reasons.get(field);
+    if (reason === undefined) continue;
+    problems.push({ field, reason, provider: declaration.provided[field] ?? undeclaredProvider(field) });
+  }
+  return { ok: false, value: undefined, problems };
+}
+
+/** One sentence naming the thing an operator changes, plus the command that writes it where there is one. */
+export function hostEnvProviderSentence(provider: HostEnvProvider): string {
+  const where =
+    provider.kind === "binding"
+      ? `Binding ${provider.name} in the host's wrangler.jsonc.`
+      : provider.kind === "var"
+        ? `Var ${provider.name} in the host's wrangler.jsonc.`
+        : provider.kind === "secret"
+          ? `Secret ${provider.name}, read through @pithy-sh/secrets.`
+          : `Config key ${provider.name}.`;
+  return provider.command ? `${where} Run ${provider.command}.` : where;
+}
+
+/**
+ * The block a host logs before it refuses. One headline, then one line per field: the field, why it
+ * is unusable, and what fills it. Brand voice — short sentences, deliberate periods, no decoration
+ * that a log aggregator would have to strip.
+ */
+export function renderHostEnvProblems(capability: string, problems: readonly HostEnvProblem[]): string {
+  const lines = problems.map(
+    (problem) => `  ${problem.field} — ${problem.reason} ${hostEnvProviderSentence(problem.provider)}`,
+  );
+  const count = problems.length === 1 ? "1 setting is" : `${problems.length} settings are`;
+  return [`The ${capability} host cannot start. ${count} missing or unusable.`, ...lines].join("\n");
+}
+
+/**
+ * Every env object this process has already reported on, so a boot path that asks twice logs once.
+ *
+ * A module-scope call in a Worker happens once per isolate and needs no help; a host that validates
+ * inside `fetch` — or a `scheduled` handler firing every minute — would otherwise write the same
+ * block into Workers Logs forever, which is how a legible block becomes noise nobody reads.
+ */
+const reported = new WeakSet<object>();
+
+/**
+ * Validate a host's env, or say exactly what is wrong and refuse.
+ *
+ * Called at boot, before the host serves anything. The block goes to the log (the operator's
+ * audience, so it carries the provider lines) and the refusal is `core/internal`: a host that cannot
+ * parse config *we* generated is our failure, and our logs are where the answer is (CLAUDE.md
+ * §Errors). Nothing about the values themselves is logged — a provider name is a location, never a
+ * secret.
+ */
+export function requireHostEnv<Env extends z.ZodObject>(
+  declaration: HostEnvDeclaration<Env>,
+  env: unknown,
+  log: Logger = createWorkerLogger(),
+): z.output<Env> {
+  const report = checkHostEnv(declaration, env);
+  if (report.ok && report.value !== undefined) return report.value;
+
+  const block = renderHostEnvProblems(declaration.capability, report.problems);
+  if (typeof env !== "object" || env === null || !reported.has(env)) {
+    if (typeof env === "object" && env !== null) reported.add(env);
+    log.error(block, {
+      capability: declaration.capability,
+      fields: report.problems.map((problem) => problem.field),
+    });
+  }
+
+  throw new InternalError({
+    message: `The ${declaration.capability} host is not configured.`,
+    action: "Read the startup log: it names every unusable setting and what fills it.",
+    detail: block,
+  });
+}
+
+/** One declared field, flattened for a reader that never runs the host — `pithy doctor`'s row. */
+export interface HostEnvField {
+  /** The field name, as the env carries it. */
+  field: string;
+  /** The field's own `.describe()`, or `undefined` where the schema carries none. */
+  description: string | undefined;
+  /** What provides it. */
+  provider: HostEnvProvider;
+  /** Whether the host works without it — i.e. whether the field's schema accepts `undefined`. */
+  optional: boolean;
+}
+
+/**
+ * Read a declaration statically: what the host needs, what documents each field, and what fills it.
+ *
+ * The static half of this module, and the one `pithy doctor` builds its report from (#411). Field
+ * order is the schema's, so a report reads in the order the capability chose to explain itself.
+ */
+export function hostEnvFields(declaration: HostEnvDeclaration): HostEnvField[] {
+  return Object.entries(declaration.env.shape).map(([field, schema]) => ({
+    field,
+    description: (schema as z.ZodType).description,
+    provider: declaration.provided[field] ?? undeclaredProvider(field),
+    // Asked of the schema rather than read off its wrapper chain: `.optional()`, `.default()` and a
+    // union with `undefined` all mean the same thing to an operator, and only the parse knows.
+    optional: (schema as z.ZodType).safeParse(undefined).success,
+  }));
+}

package/src/workflow/loopback.ts

@@ -0,0 +1,149 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { UpstreamError, UpstreamTimeoutError } from "../error/pithyError";
+import { type WorkflowDispatchRequest, workflowDispatchPath } from "./schemas";
+import type { WorkflowBinding } from "./spec";
+
+/**
+ * The loopback dispatcher: the one-method dispatch seam, carried over a sibling's origin instead of
+ * a cross-script binding.
+ *
+ * `pithy dev` composes this in place of `env.EMAIL_SENDER` (and its eight siblings). Nothing at the
+ * call site changes — `enqueueEmail` takes a `create({ id, params })` and does not care what is
+ * behind it — which is the whole reason the seam was one method to begin with. The address comes
+ * from `<STEM>_ORIGIN`, which the dev orchestrator exports for every member of the dev set, pinned
+ * at feature-create and stable for the life of the feature.
+ *
+ * ## Failures are the sibling's, and they say so
+ *
+ * A worker that is not up, a port nothing is listening on, a host that refuses the dispatch: every
+ * one of those is a hop into something this process does not control, so it is
+ * `core/upstream_failed` (502) or `core/upstream_timeout` (504) — never `core/internal`, which would
+ * send an operator to read *our* logs about *their* Worker (CLAUDE.md §Errors). The `action` names
+ * the capability and the origin, because "is the email host running?" is the next question and the
+ * terminal already knows the answer.
+ *
+ * The timeout is not decoration. `enqueue` awaits this call on a request path, and a sibling that
+ * accepts a connection and never answers would otherwise hold a sign-in open until the platform
+ * killed it. A timed-out dispatch is reported as one — separately from a failed one — because the
+ * instance may have started regardless, and the scheduler's re-drive asks that question of the
+ * batch id rather than assuming an answer.
+ */
+
+/** How the dispatcher reaches the sibling. Structural, so a test hands over a plain function. */
+export type LoopbackFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+/** What the dispatcher needs to stand in for one cross-script Workflow binding. */
+export interface LoopbackWorkflowOptions {
+  /**
+   * The sibling worker's origin — `http://localhost:8797`, as `<STEM>_ORIGIN` carries it. A trailing
+   * slash is tolerated; nothing else about it is rewritten.
+   */
+  origin: string;
+  /** The Workflow binding to start on, named exactly as the host's own env binds it. */
+  binding: string;
+  /** The capability that owns the host. Named in the action line, so a failure says which worker. */
+  capability?: string;
+  /** The transport. Defaults to the runtime's `fetch`; injectable for tests. */
+  fetch?: LoopbackFetch;
+  /** How long to wait for the sibling. Defaults to 10 s — a local hop, so anything slower is stuck. */
+  timeoutMs?: number;
+}
+
+/** 10 seconds. A loopback dispatch either lands immediately or is not going to. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** How much of a failing answer's body is worth carrying into a log line. */
+const BODY_SNIPPET = 300;
+
+/** Whether a rejection is the deadline rather than the connection. */
+function isTimeout(cause: unknown): boolean {
+  const name = (cause as { name?: unknown } | null | undefined)?.name;
+  return name === "TimeoutError" || name === "AbortError";
+}
+
+/** A short, safe rendering of a failing answer's body. Never thrown from — a failure is already in hand. */
+async function bodySnippet(response: Response): Promise<string> {
+  try {
+    return (await response.text()).slice(0, BODY_SNIPPET);
+  } catch {
+    return "<unreadable>";
+  }
+}
+
+/**
+ * Build a {@link WorkflowBinding} that dispatches over loopback to a sibling worker's dispatch route.
+ *
+ * Returns the plain seam, so it drops into any env slot a cross-script binding occupied — including
+ * `@pithy-sh/email`'s narrower `SendWorkflowBinding`, which is a subtype of this one.
+ */
+export function loopbackWorkflowBinding(options: LoopbackWorkflowOptions): WorkflowBinding {
+  const origin = options.origin.replace(/\/+$/, "");
+  const url = `${origin}${workflowDispatchPath(options.binding)}`;
+  const owner = options.capability ?? options.binding;
+  const send = options.fetch ?? ((target: string, init: RequestInit) => fetch(target, init));
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const running = `Check that the ${owner} host is running under pithy dev at ${origin}.`;
+
+  return {
+    async create(instance?: { id?: string; params?: unknown }): Promise<unknown> {
+      // The body is the route's own request schema, built as that type rather than as a literal, so a
+      // change to the contract is a compile error on both ends of the wire at once.
+      const body: WorkflowDispatchRequest = { id: instance?.id, params: instance?.params };
+
+      let response: Response;
+      try {
+        response = await send(url, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+      } catch (cause) {
+        if (isTimeout(cause)) {
+          throw new UpstreamTimeoutError(
+            {
+              message: "The workflow host did not answer in time.",
+              action: running,
+              detail: `POST ${url} exceeded ${timeoutMs} ms.`,
+            },
+            { cause },
+          );
+        }
+        throw new UpstreamError(
+          {
+            message: "The workflow host could not be reached.",
+            action: running,
+            detail: `POST ${url} failed: ${String(cause)}`,
+          },
+          { cause },
+        );
+      }
+
+      if (!response.ok) {
+        throw new UpstreamError({
+          message: "The workflow host refused the dispatch.",
+          action: running,
+          detail: `POST ${url} answered ${response.status}. ${await bodySnippet(response)}`,
+        });
+      }
+
+      // The host answers `WorkflowDispatchResponse`; it is relayed rather than parsed, because the
+      // seam's own return type is `unknown` and no caller reads it. A body that is not JSON is still
+      // the sibling's fault, so it reports as one.
+      try {
+        return await response.json();
+      } catch (cause) {
+        throw new UpstreamError(
+          {
+            message: "The workflow host answered something that is not a dispatch result.",
+            action: running,
+            detail: `POST ${url} answered ${response.status} with an unreadable body.`,
+          },
+          { cause },
+        );
+      }
+    },
+  };
+}

package/src/workflow/naming.ts

@@ -0,0 +1,170 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "../error/pithyError";
+import { MAX_CAPABILITY_JOB, NAMESPACE_LIMITS } from "../naming/limits";
+import { assertValidProjectName, kebab } from "../naming/resource";
+import { NAME_SEGMENT } from "../naming/segment";
+
+/**
+ * Every name a durable job answers to, in one module. The CLI writes these into a host worker's
+ * resolved `wrangler.jsonc`, the provisioner deploys under them, and the dispatcher resolves
+ * against them — so they are derived here once rather than formatted at three call sites that
+ * would drift.
+ *
+ * The shape is the project-scoped rule from `@pithy-sh/core/src/naming/resource`:
+ * **`<project>-<env>-<capability>`** for a host worker, and that plus `-<job>` for a Workflow.
+ * Worker script names and Workflow names are both **account-scoped** in Cloudflare, so without the
+ * project segment a second Pithy project's deploy does not share a name — it overwrites the first
+ * project's running Worker. The project segment is what makes two projects in one account possible.
+ *
+ * Renaming a Workflow orphans every instance running under the old name, so these names are a
+ * contract once anything is deployed. That is also why an over-long name is **refused rather than
+ * truncated** here: a Workflow whose name silently changed shape is worse than a build error
+ * telling you to shorten a capability name.
+ */
+
+/**
+ * Cloudflare caps a Workflow name at 64 bytes.
+ *
+ * This is the number `WORKFLOW_DERIVED_PROJECT_NAME` comes from: a project is capped at whatever this
+ * leaves after the longest environment and the longest `<capability>-<job>`, so the refusal lands at
+ * `pithy init` rather than here, at the first deploy, with resources already provisioned.
+ * `naming.test.ts` pins the two together.
+ */
+export const MAX_WORKFLOW_NAME_BYTES = NAMESPACE_LIMITS.workflow.maxLength;
+
+/**
+ * A Worker script name is **63**, not 64 — a different resource with a different number.
+ *
+ * Cloudflare allows 255 in general and 63 once a workers.dev subdomain is on. Pithy holds the 63:
+ * it is the only value that stays true after an adopter enables workers.dev, and a script cannot be
+ * renamed once anything points at it. The one-character gap between this and
+ * {@link MAX_WORKFLOW_NAME_BYTES} is real; collapsing the two would loosen this one.
+ */
+export const MAX_WORKER_NAME_BYTES = NAMESPACE_LIMITS.worker.maxLength;
+
+/**
+ * Reject a segment that cannot legally appear in a Cloudflare resource name, attributed to its role.
+ *
+ * The shape is {@link NAME_SEGMENT}, the one segment rule — a Workflow name and a Worker script name
+ * accept exactly what every other composed name does, so this reads the rule rather than restating it.
+ */
+function assertSegment(value: string, role: string): void {
+  if (!NAME_SEGMENT.test(value)) {
+    throw new InternalError({
+      message: `Invalid ${role} "${value}" in a workflow name.`,
+      action: "Use lowercase letters, digits, and single hyphens, starting with a letter.",
+      detail: `A ${role} must match ${NAME_SEGMENT.source} to be a legal Cloudflare resource-name segment.`,
+    });
+  }
+}
+
+/**
+ * Reject a composed name Cloudflare would refuse, naming the limit rather than letting the deploy fail.
+ *
+ * The limit is passed in because the two names this module composes have two different ones: a Workflow
+ * gets 64, the Worker script hosting it gets 63.
+ */
+function assertLength(name: string, limit: number): string {
+  if (new TextEncoder().encode(name).length > limit) {
+    throw new InternalError({
+      message: `The name "${name}" is longer than Cloudflare's ${limit}-byte limit.`,
+      action: "Shorten the project, capability, or job name.",
+    });
+  }
+  return name;
+}
+
+/**
+ * Reject a `<capability>-<job>` tail longer than {@link MAX_CAPABILITY_JOB} — the tail
+ * `MAX_PROJECT_NAME` was derived against.
+ *
+ * The project cap is only true while no registry declares a longer tail than the longest one that
+ * existed when it was computed. A capability that would invalidate it fails here, at the name it
+ * would deploy under, rather than quietly shortening the project name every existing project was
+ * already accepted under — a change that cannot be made after the fact, because a project name is
+ * stable forever once anything is provisioned.
+ */
+function assertCapabilityJob(capability: string, job: string): void {
+  const tail = `${capability}-${job}`;
+  if (tail.length > MAX_CAPABILITY_JOB) {
+    throw new InternalError({
+      message: `The job "${capability}/${job}" is ${tail.length} characters. A <capability>-<job> stops at ${MAX_CAPABILITY_JOB}.`,
+      action: "Shorten the capability or job name.",
+      detail: `MAX_PROJECT_NAME is derived against a ${MAX_CAPABILITY_JOB}-character tail. Raising MAX_CAPABILITY_JOB shortens every adopter's legal project name, and a provisioned project cannot be renamed.`,
+    });
+  }
+}
+
+/**
+ * The `<project>-<env>` head every deployed name shares. The project is held to core's one project rule
+ * — charset *and* length — because it comes from the adopter's `pithy.config.ts` and is the one segment
+ * a human typed; the rest is author-controlled code and is asserted rather than mangled, so a bad
+ * capability name is a build error, not a surprise.
+ */
+function head(project: string, env: string): string {
+  assertValidProjectName(project);
+  assertSegment(env, "environment");
+  return `${kebab(project)}-${env}`;
+}
+
+/** The identity of a capability's deployment in one environment. */
+export interface WorkflowHostNameParts {
+  /** The project name — the root `pithy.config.ts` `name`, resolved by `requireProjectName` and never guessed. */
+  project: string;
+  /** The capability that owns the host worker (e.g. `email`). */
+  capability: string;
+  /** The deployment environment (e.g. `staging`). */
+  env: string;
+}
+
+/** The identity of one durable job's Workflow in one environment. */
+export interface WorkflowScriptNameParts extends WorkflowHostNameParts {
+  /** The job within the capability (e.g. `send`). */
+  job: string;
+}
+
+/**
+ * The deployed name of one job's Workflow in one environment — `<project>-<env>-<capability>-<job>`,
+ * e.g. `acme-staging-media-image-to-text`. This is what the CLI writes as the `name` of a
+ * `workflows` entry, and what `CloudflareWorkflowsClient` addresses when triggering from outside
+ * the Worker.
+ *
+ * Takes an options object rather than positional arguments deliberately: every part is a `string`,
+ * so a swapped project and capability would type-check silently and deploy under a name teardown
+ * could never find again.
+ */
+export function workflowScriptName(parts: WorkflowScriptNameParts): string {
+  assertSegment(parts.capability, "capability");
+  assertSegment(parts.job, "job");
+  assertCapabilityJob(parts.capability, parts.job);
+  return assertLength(`${head(parts.project, parts.env)}-${parts.capability}-${parts.job}`, MAX_WORKFLOW_NAME_BYTES);
+}
+
+/**
+ * The deployed name of a capability's prebuilt host worker in one environment —
+ * `<project>-<env>-<capability>`. Same options-object rationale as {@link workflowScriptName}.
+ *
+ * Held to {@link MAX_WORKER_NAME_BYTES}, one character tighter than the Workflow it hosts: this is a
+ * Worker script name, and a workers.dev subdomain caps those at 63.
+ */
+export function workflowHostName(parts: WorkflowHostNameParts): string {
+  assertSegment(parts.capability, "capability");
+  return assertLength(`${head(parts.project, parts.env)}-${parts.capability}`, MAX_WORKER_NAME_BYTES);
+}
+
+/**
+ * The dispatch key a caller passes to `c.var.workflows.trigger(...)` — `<capability>/<job>`.
+ * Namespaced by capability so two capabilities may each own a job called `sweep`.
+ *
+ * **Deliberately not project-scoped.** This keys the in-Worker registry, and a Worker only ever
+ * hosts one project's capabilities — adding the project would put a value every call site already
+ * knows into a string every call site would have to thread. It is a dispatch key, not a
+ * Cloudflare resource name, so it shares none of the account-flatness problem the names above have.
+ */
+export function workflowKey(capability: string, job: string): string {
+  assertSegment(capability, "capability");
+  assertSegment(job, "job");
+  return `${capability}/${job}`;
+}

package/src/workflow/register.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import { InternalError } from "../error/pithyError";
+import { workflowKey } from "./naming";
+import type { RegisteredWorkflow, WorkflowRegistry } from "./spec";
+
+/**
+ * Registration: every capability's `workflows` map merged into one project-wide registry keyed
+ * `<capability>/<job>`. The peer of `composeDatabases` and `composeKv`, and deliberately simpler —
+ * a job belongs to exactly one capability, so there is no cross-capability merge to arbitrate,
+ * only a duplicate to reject.
+ */
+
+/**
+ * Merge every capability's declared jobs into one registry. A capability declaring the same job
+ * name twice is impossible (it is a map key); two capabilities colliding is impossible (the key is
+ * capability-namespaced). What remains is one real conflict — the same capability `name` composed
+ * twice — which is an assembly-time author error, caught here rather than surfacing as a job that
+ * silently dispatches to the wrong binding.
+ */
+export function composeWorkflows(capabilities: readonly Capability[]): WorkflowRegistry {
+  const registry: WorkflowRegistry = {};
+  for (const capability of capabilities) {
+    for (const [job, spec] of Object.entries(capability.workflows ?? {})) {
+      const key = workflowKey(capability.name, job);
+      if (key in registry) {
+        throw new InternalError({
+          message: `Duplicate workflow "${key}".`,
+          action: "Compose each capability once — two capabilities are registering the same name.",
+          detail: `The capability "${capability.name}" is composed more than once, or two capabilities share the name.`,
+        });
+      }
+      registry[key] = { key, capability: capability.name, job, spec };
+    }
+  }
+  return registry;
+}
+
+/** Every registered job carrying a cron — what `createEntrypoint` fires on a `scheduled` event. */
+export function scheduledWorkflows(registry: WorkflowRegistry): RegisteredWorkflow[] {
+  return Object.values(registry).filter((entry) => entry.spec.schedule !== undefined);
+}