@pithy-sh/core 0.1.1 → 0.1.3

package/dist/workflow/hostEnv.js

@@ -0,0 +1,170 @@
+import { InternalError } from "../error/pithyError.js";
+import { createWorkerLogger } from "../logger/worker.js";
+import { z } from "zod";
+//#region src/workflow/hostEnv.ts
+/**
+* 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. */
+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.");
+/**
+* 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.
+*/
+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.");
+/**
+* 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.
+*/
+function defineHostEnv(declaration) {
+	const unaccounted = Object.keys(declaration.env.shape).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;
+}
+/** The provider reported for a field the declaration never accounted for. Should be unreachable. */
+function undeclaredProvider(field) {
+	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.
+*/
+function checkHostEnv(declaration, env) {
+	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 = /* @__PURE__ */ new Map();
+	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 = [];
+	for (const field of Object.keys(declaration.env.shape)) {
+		const reason = reasons.get(field);
+		if (reason === void 0) continue;
+		problems.push({
+			field,
+			reason,
+			provider: declaration.provided[field] ?? undeclaredProvider(field)
+		});
+	}
+	return {
+		ok: false,
+		value: void 0,
+		problems
+	};
+}
+/** One sentence naming the thing an operator changes, plus the command that writes it where there is one. */
+function hostEnvProviderSentence(provider) {
+	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.
+*/
+function renderHostEnvProblems(capability, problems) {
+	const lines = problems.map((problem) => `  ${problem.field} — ${problem.reason} ${hostEnvProviderSentence(problem.provider)}`);
+	return [`The ${capability} host cannot start. ${problems.length === 1 ? "1 setting is" : `${problems.length} settings are`} 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 = /* @__PURE__ */ new WeakSet();
+/**
+* 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.
+*/
+function requireHostEnv(declaration, env, log = createWorkerLogger()) {
+	const report = checkHostEnv(declaration, env);
+	if (report.ok && report.value !== void 0) 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
+	});
+}
+/**
+* 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.
+*/
+function hostEnvFields(declaration) {
+	return Object.entries(declaration.env.shape).map(([field, schema]) => ({
+		field,
+		description: schema.description,
+		provider: declaration.provided[field] ?? undeclaredProvider(field),
+		optional: schema.safeParse(void 0).success
+	}));
+}
+//#endregion
+export { HostEnvProvider, HostEnvProviderKind, checkHostEnv, defineHostEnv, hostEnvFields, hostEnvProviderSentence, renderHostEnvProblems, requireHostEnv };

package/dist/workflow/loopback.d.ts

@@ -0,0 +1,52 @@
+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;
+}
+/**
+ * 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 declare function loopbackWorkflowBinding(options: LoopbackWorkflowOptions): WorkflowBinding;
+//# sourceMappingURL=loopback.d.ts.map

package/dist/workflow/loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../src/workflow/loopback.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,iGAAiG;AACjG,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElF,mFAAmF;AACnF,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAuBD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,uBAAuB,GAAG,eAAe,CAoEzF"}

package/dist/workflow/loopback.js

@@ -0,0 +1,76 @@
+import { UpstreamError, UpstreamTimeoutError } from "../error/pithyError.js";
+import { workflowDispatchPath } from "./schemas.js";
+//#region src/workflow/loopback.ts
+/** 10 seconds. A loopback dispatch either lands immediately or is not going to. */
+const DEFAULT_TIMEOUT_MS = 1e4;
+/** 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) {
+	const name = cause?.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) {
+	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.
+*/
+function loopbackWorkflowBinding(options) {
+	const origin = options.origin.replace(/\/+$/, "");
+	const url = `${origin}${workflowDispatchPath(options.binding)}`;
+	const owner = options.capability ?? options.binding;
+	const send = options.fetch ?? ((target, init) => 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) {
+		const body = {
+			id: instance?.id,
+			params: instance?.params
+		};
+		let 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)}`
+		});
+		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 });
+		}
+	} };
+}
+//#endregion
+export { loopbackWorkflowBinding };

package/dist/workflow/naming.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 declare const MAX_WORKFLOW_NAME_BYTES: 64;
+/**
+ * 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 declare const MAX_WORKER_NAME_BYTES: 63;
+/** 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 declare function workflowScriptName(parts: WorkflowScriptNameParts): string;
+/**
+ * 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 declare function workflowHostName(parts: WorkflowHostNameParts): string;
+/**
+ * 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 declare function workflowKey(capability: string, job: string): string;
+//# sourceMappingURL=naming.d.ts.map

package/dist/workflow/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/workflow/naming.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,IAAsC,CAAC;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,IAAoC,CAAC;AAmEvE,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACpC,gHAAgH;IAChH,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAKzE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAGrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAInE"}

package/dist/workflow/naming.js

@@ -0,0 +1,138 @@
+import { NAME_SEGMENT } from "../naming/segment.js";
+import { InternalError } from "../error/pithyError.js";
+import { NAMESPACE_LIMITS } from "../naming/limits.js";
+import { assertValidProjectName, kebab } from "../naming/resource.js";
+//#region src/workflow/naming.ts
+/**
+* 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.
+*/
+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.
+*/
+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, role) {
+	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, limit) {
+	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, job) {
+	const tail = `${capability}-${job}`;
+	if (tail.length > 22) throw new InternalError({
+		message: `The job "${capability}/${job}" is ${tail.length} characters. A <capability>-<job> stops at 22.`,
+		action: "Shorten the capability or job name.",
+		detail: `MAX_PROJECT_NAME is derived against a 22-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, env) {
+	assertValidProjectName(project);
+	assertSegment(env, "environment");
+	return `${kebab(project)}-${env}`;
+}
+/**
+* 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.
+*/
+function workflowScriptName(parts) {
+	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.
+*/
+function workflowHostName(parts) {
+	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.
+*/
+function workflowKey(capability, job) {
+	assertSegment(capability, "capability");
+	assertSegment(job, "job");
+	return `${capability}/${job}`;
+}
+//#endregion
+export { MAX_WORKER_NAME_BYTES, MAX_WORKFLOW_NAME_BYTES, workflowHostName, workflowKey, workflowScriptName };

package/dist/workflow/register.d.ts

@@ -0,0 +1,19 @@
+import type { Capability } from "../capability/capability";
+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 declare function composeWorkflows(capabilities: readonly Capability[]): WorkflowRegistry;
+/** Every registered job carrying a cron — what `createEntrypoint` fires on a `scheduled` event. */
+export declare function scheduledWorkflows(registry: WorkflowRegistry): RegisteredWorkflow[];
+//# sourceMappingURL=register.d.ts.map

package/dist/workflow/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/workflow/register.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAG3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEnE;;;;;GAKG;AAEH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,gBAAgB,CAgBtF;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,EAAE,CAEnF"}

package/dist/workflow/register.js

@@ -0,0 +1,40 @@
+import { InternalError } from "../error/pithyError.js";
+import { workflowKey } from "./naming.js";
+//#region src/workflow/register.ts
+/**
+* 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.
+*/
+function composeWorkflows(capabilities) {
+	const registry = {};
+	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. */
+function scheduledWorkflows(registry) {
+	return Object.values(registry).filter((entry) => entry.spec.schedule !== void 0);
+}
+//#endregion
+export { composeWorkflows, scheduledWorkflows };

package/dist/workflow/schemas.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+/**
+ * The request and response contract of the host's dispatch route ({@link ./dispatchRoute.ts}).
+ *
+ * Declared here rather than on the route line for the reason every capability's `http/schemas.ts`
+ * exists (CLAUDE.md §HTTP): the route declares *that* it validates, this declares *what*, and the
+ * loopback dispatcher on the other end of the wire builds its body against the same object.
+ *
+ * **The path is here too, and that is deliberate.** An address is as much of the wire contract as a
+ * body is, and putting it beside the route would make the dispatcher import the route module to know
+ * where to POST — which is the module that imports the dispatcher to resolve a binding. One import
+ * cycle, for a template string neither end owns more than the other.
+ */
+/** The reserved namespace the host's dispatch route lives under, beside `/__pithy/dev-login`. */
+export declare const WORKFLOW_DISPATCH_BASE = "/__pithy/workflows";
+/** The registered path pattern. `:binding` is the host's own Workflow binding name. */
+export declare const WORKFLOW_DISPATCH_ROUTE = "/__pithy/workflows/:binding";
+/** The concrete path for one binding — what the loopback dispatcher POSTs to. */
+export declare function workflowDispatchPath(binding: string): string;
+/** The path segment naming which of the host's own Workflow bindings to start an instance on. */
+export declare const WorkflowDispatchParams: z.ZodObject<{
+    binding: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowDispatchParams = z.infer<typeof WorkflowDispatchParams>;
+/** The body: the instance id and the payload, exactly as `create({ id, params })` takes them. */
+export declare const WorkflowDispatchRequest: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    params: z.ZodUnknown;
+}, z.core.$strip>;
+export type WorkflowDispatchRequest = z.infer<typeof WorkflowDispatchRequest>;
+/**
+ * The answer: which binding was started, under which id.
+ *
+ * A response object rather than an interface, for the reason every admin response is one (CLAUDE.md
+ * §HTTP): the caller is across a process boundary, and a TypeScript interface is erased before it can
+ * help. Nothing here carries a codec — an answer must parse back to exactly what went in.
+ */
+export declare const WorkflowDispatchResponse: z.ZodObject<{
+    binding: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+    started: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type WorkflowDispatchResponse = z.infer<typeof WorkflowDispatchResponse>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/workflow/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/workflow/schemas.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AAEH,iGAAiG;AACjG,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D,uFAAuF;AACvF,eAAO,MAAM,uBAAuB,gCAAuC,CAAC;AAE5E,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,iGAAiG;AACjG,eAAO,MAAM,sBAAsB;;iBAc2B,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,iGAAiG;AACjG,eAAO,MAAM,uBAAuB;;;iBAgByC,CAAC;AAC9E,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;iBAQgC,CAAC;AACtE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}