@pithy-sh/core 0.1.2 → 0.1.3

package/dist/worker/identity.d.ts

@@ -0,0 +1,191 @@
+/**
+ * What a running Worker knows about itself — the three vars every Pithy Worker is scaffolded with, and
+ * the one reader for them.
+ *
+ * The Cloudflare runtime hands a script **nothing** about its own identity. `TraceItem.scriptName` is
+ * what a *tail consumer* sees about someone else, `version_metadata` carries an id, a tag and a
+ * creation time but no name, and `navigator.userAgent` is the constant `"Cloudflare-Workers"` in every
+ * Worker alive. So
+ * identity is stamped, not derived: `pithy init` and `pithy worker add` write `PROJECT`, `ENVIRONMENT`,
+ * and `WORKER` into every environment stanza of the Worker's own `wrangler.jsonc`.
+ *
+ * Stamping also beats deriving even where a value looks recoverable. A host's script name leads with
+ * its project, but `<project>-<env>-<capability>` cannot be parsed back into its parts once a project
+ * name contains a hyphen — and wrangler appends `-staging`/`-prod` at deploy, so the script name is not
+ * even stable across environments while `apps/<name>/` is.
+ *
+ * The names live here because they had already been copied: `ENVIRONMENT_VAR` was declared privately in
+ * both `workflow/host.ts` and `controlPlane/capability.ts`, character for character. A third copy for
+ * `WORKER` would have made the drift structural — the arrangement where a rule stops being one rule.
+ */
+/** The var naming the owning project: the root `pithy.config.ts` `name`, kebabed. */
+export declare const PROJECT_VAR = "PROJECT";
+/** The var naming the environment this deployment serves — `dev`, `staging`, or `prod`. */
+export declare const ENVIRONMENT_VAR = "ENVIRONMENT";
+/**
+ * The var carrying a Worker's **own** dev origin, from `pithy dev` to whatever launches that Worker.
+ *
+ * Not stamped into `wrangler.jsonc` like the three above, and that is the whole point of it. A dev port
+ * is *allocated* — every checkout reserves its own block — so this is the one identity value a file in
+ * the repository cannot state: written down, it is right in the first checkout on a machine and wrong
+ * in every other one (#462).
+ *
+ * It lives here for the reason the others do. `pithy dev` writes it and `@pithy-sh/vite` reads it, and
+ * those two packages cannot import each other — the CLI depends on vite's package, and vite's may not
+ * depend on the CLI. A privately declared copy on each side is the arrangement where one rule quietly
+ * becomes two.
+ *
+ * **A carrier, not a binding.** It reaches a *process*, not a Worker: `process.env` inside workerd is
+ * that script's own vars and nothing else. `@pithy-sh/vite`'s `devWorkerConfig()` is what turns it into
+ * the Worker's `BASE_URL`, which is the binding anything at runtime actually reads.
+ */
+export declare const WORKER_ORIGIN_VAR = "PITHY_WORKER_ORIGIN";
+/**
+ * The var naming the Worker itself: its `apps/<name>` **directory** name, not its deploy name.
+ *
+ * The directory name is the identity everything else already keys on — the `apps/*` registry, the
+ * `--worker` flag, the `.dev.config.json` port block. The deploy name (`<project>-<name>`) would
+ * re-encode the project as noise beside a `project` column that already carries it, and the deployed
+ * script's real name varies by environment where the directory does not.
+ */
+export declare const WORKER_VAR = "WORKER";
+/**
+ * The version-metadata binding Cloudflare injects, naming the exact build that is running.
+ *
+ * Not a var — a binding, declared as `"version_metadata": { "binding": "CF_VERSION_METADATA" }` and
+ * populated by the platform rather than by the scaffold. It belongs beside the three vars anyway,
+ * because it answers the same question they do and is read on the same path: this is what a Worker knows
+ * about itself.
+ *
+ * **The name is the join.** It is what `pithy init` and `pithy worker add` write and what this module
+ * reads; binding a differently-named one creates a binding nothing consumes, which is the failure this
+ * whole thread is repairing — the reader shipped, the template never declared it, and the field was
+ * silently absent in every scaffolded project.
+ */
+export declare const VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+/** Where a Worker is running, as it can state about itself. Every field is `null` when unstamped. */
+export interface WorkerIdentity {
+    /** The owning project, or `null` when the Worker carries no `PROJECT` var. */
+    project: string | null;
+    /** The environment this deployment serves, or `null` when unstamped. */
+    environment: string | null;
+    /** The Worker's `apps/<name>` directory name, or `null` when unstamped. */
+    worker: string | null;
+    /**
+     * The deployed build's Cloudflare version id, or `null` off-platform and wherever the
+     * `CF_VERSION_METADATA` binding is absent.
+     *
+     * Opaque and per-deploy: it identifies *exactly which build* is running, which is the right answer for
+     * forensics, for reproducing a report, and for pinning what an audited action ran against. It carries
+     * no version semantics, so it says nothing about which features a Worker has — that is what the
+     * composed package versions in the control-plane manifest are for.
+     */
+    version: string | null;
+}
+/**
+ * Everything the `CF_VERSION_METADATA` binding carries about the build that is running.
+ *
+ * **Measured, not read off the docs.** A `wrangler dev` (4.120.1 / miniflare 4) against a Worker
+ * declaring `version_metadata` hands the binding as `{ id, tag, timestamp }` — three own keys, every
+ * value a string, `timestamp` an ISO-8601 instant. Every field is independently `null` here, because a
+ * partial binding is what a platform change looks like from inside a Worker and losing the id over a
+ * renamed sibling would be the worse trade.
+ *
+ * **It names a *version*, never a deployment.** That distinction is the whole ceiling on what a client
+ * can conclude from it — see {@link workerVersionMetadata}.
+ */
+export interface WorkerVersionMetadata {
+    /** The version id: opaque, per version, and the answer to "which build". `null` where the binding is. */
+    id: string | null;
+    /**
+     * The version tag, set only by `wrangler versions upload --tag`, or `null`.
+     *
+     * Empty in every local dev and in every deploy nobody tagged, so `""` reads as absent rather than as a
+     * tag to compare against. Read here so this reader mirrors the binding; deliberately **not** stamped
+     * on the control-plane header — it is adopter-authored free text, and the two questions a management
+     * client asks are answered without it.
+     */
+    tag: string | null;
+    /**
+     * When this **version was uploaded**, ISO-8601, verbatim as the platform issued it — or `null`.
+     *
+     * **Cloudflare has two objects here, and this binding describes one of them.** A *version* is an
+     * immutable upload of code and config: an id, a created timestamp and a 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 its own time. `CF_VERSION_METADATA` reports the **version**, faithfully — and
+     * the runtime hands a script **no binding for the deployment at all**.
+     *
+     * Everything else follows from that. A rollback creates a *new deployment* aimed at an *existing
+     * version*, so nothing in this binding moves: not staleness, not ambiguity, a different object. The
+     * same answer covers the next question and the one after — a traffic split, a gradual rollout, which
+     * deployment is serving: a Worker cannot see any of it. An ordinary redeploy is not affected, because
+     * every `wrangler deploy` uploads and so mints a new version, id and all, even for a one-character
+     * change.
+     *
+     * Measured, 2026-08-10, which is what turned that from a reading of the docs into a fact: a probe
+     * Worker on a real account, version `A` uploaded, `B` four seconds later, then a real `wrangler
+     * rollback` to `A`. Two minutes on, the Worker reported `A`'s id **and `A`'s original timestamp**,
+     * unmoved — while wrangler's own rollback output named the new deployment's version list.
+     *
+     * The value is relayed for comparison and never interpreted. A consumer's rule is
+     * `workerBuildChanged` in `controlPlane/wire.ts`: anything that moved is a change, and a direction is
+     * not a meaning — propagation lag alone can make an older version answer for a while after a deploy.
+     *
+     * `null` for anything that is not a parseable instant. That is the one place this reader refuses
+     * rather than relays, and the consumer is the reason: a client does `Date.parse` on it and compares,
+     * an unparseable string is `NaN`, and every `NaN` comparison is false — so garbage would read as
+     * "not newer", which is silently indistinguishable from "unchanged".
+     */
+    createdAt: string | null;
+}
+/**
+ * Read a Worker's stamped identity off its `env`.
+ *
+ * **Never throws, and never guesses.** Both matter on the one call path this exists for: the audit
+ * recorder stamps origin onto every event, and the recorder is contractually non-fatal — a throw here
+ * would turn "this row has no origin" into "there is no row", which is the strictly worse failure. An
+ * absent var is an ordinary, permanent state: a Worker scaffolded before these vars existed carries
+ * none of them and nothing back-fills it, so `null` is reported rather than inferred. An invented
+ * origin would be indistinguishable from a real one for as long as the trail is kept.
+ */
+export declare function workerIdentity(env: unknown): WorkerIdentity;
+/**
+ * Read the whole `CF_VERSION_METADATA` binding: which build is running, and when that build was made.
+ *
+ * **The one reader of the binding**, which is why it returns all of it. The seam used to take the id and
+ * drop the rest, and the module docstring above described a two-field binding — so the field this
+ * function exists for was discarded by a reader that did not know it was there.
+ *
+ * ## What a client can conclude
+ *
+ * Holding the last `(id, createdAt)` it saw, and comparing field by field only where both sides carried
+ * a value: anything that differs is a change. Absence on either side is silence, never change.
+ * `workerBuildChanged` in `controlPlane/wire.ts` is that rule, written once so no client hand-rolls it.
+ *
+ * ## What it cannot see, and why that is a boundary rather than a gap
+ *
+ * **This binding describes a version. Nothing inside a Worker can observe a deployment** — see
+ * {@link WorkerVersionMetadata.createdAt} for the two objects and the measurement. So a rollback, a
+ * traffic split, a gradual rollout: all invisible here, and no field the seam could add would change
+ * that, because the runtime hands a script no binding for the object that carries them. A client that
+ * needs a deployment reads Cloudflare's deployments API, in the customer's own account.
+ *
+ * The temptation is to synthesise one. Isolate boot time is the only in-Worker candidate and it is
+ * worse than nothing: it changes on every cold start, so it would report a redeploy dozens of times a
+ * day, and a false change costs more than a missed one for a client that invalidates a rendered pane on
+ * it. Nothing is stamped.
+ *
+ * Same never-throws, never-guesses contract as {@link workerIdentity}.
+ */
+export declare function workerVersionMetadata(env: unknown): WorkerVersionMetadata;
+/**
+ * The deployed build's version id, off the `CF_VERSION_METADATA` binding, or `null`.
+ *
+ * Kept on its own because four callers want the id and nothing else: the request logger's `version`
+ * correlation field, `/health`, the control-plane manifest, and the seam's response header. Its shape
+ * is unchanged and deliberately so — every one of those compares or records a single opaque string, and
+ * widening it would have rewritten an audit column and a wire field to carry something none of them
+ * asked for. {@link workerVersionMetadata} is where the rest of the binding lives.
+ */
+export declare function workerVersion(env: unknown): string | null;
+//# sourceMappingURL=identity.d.ts.map

package/dist/worker/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/worker/identity.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qFAAqF;AACrF,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC,2FAA2F;AAC3F,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,WAAW,CAAC;AAEnC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAE9D,qGAAqG;AACrG,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,yGAAyG;IACzG,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAW3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CAazE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEzD"}

package/dist/worker/identity.js

@@ -0,0 +1,162 @@
+//#region src/worker/identity.ts
+/**
+* What a running Worker knows about itself — the three vars every Pithy Worker is scaffolded with, and
+* the one reader for them.
+*
+* The Cloudflare runtime hands a script **nothing** about its own identity. `TraceItem.scriptName` is
+* what a *tail consumer* sees about someone else, `version_metadata` carries an id, a tag and a
+* creation time but no name, and `navigator.userAgent` is the constant `"Cloudflare-Workers"` in every
+* Worker alive. So
+* identity is stamped, not derived: `pithy init` and `pithy worker add` write `PROJECT`, `ENVIRONMENT`,
+* and `WORKER` into every environment stanza of the Worker's own `wrangler.jsonc`.
+*
+* Stamping also beats deriving even where a value looks recoverable. A host's script name leads with
+* its project, but `<project>-<env>-<capability>` cannot be parsed back into its parts once a project
+* name contains a hyphen — and wrangler appends `-staging`/`-prod` at deploy, so the script name is not
+* even stable across environments while `apps/<name>/` is.
+*
+* The names live here because they had already been copied: `ENVIRONMENT_VAR` was declared privately in
+* both `workflow/host.ts` and `controlPlane/capability.ts`, character for character. A third copy for
+* `WORKER` would have made the drift structural — the arrangement where a rule stops being one rule.
+*/
+/** The var naming the owning project: the root `pithy.config.ts` `name`, kebabed. */
+const PROJECT_VAR = "PROJECT";
+/** The var naming the environment this deployment serves — `dev`, `staging`, or `prod`. */
+const ENVIRONMENT_VAR = "ENVIRONMENT";
+/**
+* The var carrying a Worker's **own** dev origin, from `pithy dev` to whatever launches that Worker.
+*
+* Not stamped into `wrangler.jsonc` like the three above, and that is the whole point of it. A dev port
+* is *allocated* — every checkout reserves its own block — so this is the one identity value a file in
+* the repository cannot state: written down, it is right in the first checkout on a machine and wrong
+* in every other one (#462).
+*
+* It lives here for the reason the others do. `pithy dev` writes it and `@pithy-sh/vite` reads it, and
+* those two packages cannot import each other — the CLI depends on vite's package, and vite's may not
+* depend on the CLI. A privately declared copy on each side is the arrangement where one rule quietly
+* becomes two.
+*
+* **A carrier, not a binding.** It reaches a *process*, not a Worker: `process.env` inside workerd is
+* that script's own vars and nothing else. `@pithy-sh/vite`'s `devWorkerConfig()` is what turns it into
+* the Worker's `BASE_URL`, which is the binding anything at runtime actually reads.
+*/
+const WORKER_ORIGIN_VAR = "PITHY_WORKER_ORIGIN";
+/**
+* The var naming the Worker itself: its `apps/<name>` **directory** name, not its deploy name.
+*
+* The directory name is the identity everything else already keys on — the `apps/*` registry, the
+* `--worker` flag, the `.dev.config.json` port block. The deploy name (`<project>-<name>`) would
+* re-encode the project as noise beside a `project` column that already carries it, and the deployed
+* script's real name varies by environment where the directory does not.
+*/
+const WORKER_VAR = "WORKER";
+/**
+* The version-metadata binding Cloudflare injects, naming the exact build that is running.
+*
+* Not a var — a binding, declared as `"version_metadata": { "binding": "CF_VERSION_METADATA" }` and
+* populated by the platform rather than by the scaffold. It belongs beside the three vars anyway,
+* because it answers the same question they do and is read on the same path: this is what a Worker knows
+* about itself.
+*
+* **The name is the join.** It is what `pithy init` and `pithy worker add` write and what this module
+* reads; binding a differently-named one creates a binding nothing consumes, which is the failure this
+* whole thread is repairing — the reader shipped, the template never declared it, and the field was
+* silently absent in every scaffolded project.
+*/
+const VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+/** One binding field, or `null` for anything that is not a non-empty string. */
+function carried(meta, field) {
+	const value = meta[field];
+	return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+/** One var, trimmed, or `null` for anything that is not a non-empty string. */
+function stamped(env, name) {
+	const value = env[name];
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed === "" ? null : trimmed;
+}
+/**
+* Read a Worker's stamped identity off its `env`.
+*
+* **Never throws, and never guesses.** Both matter on the one call path this exists for: the audit
+* recorder stamps origin onto every event, and the recorder is contractually non-fatal — a throw here
+* would turn "this row has no origin" into "there is no row", which is the strictly worse failure. An
+* absent var is an ordinary, permanent state: a Worker scaffolded before these vars existed carries
+* none of them and nothing back-fills it, so `null` is reported rather than inferred. An invented
+* origin would be indistinguishable from a real one for as long as the trail is kept.
+*/
+function workerIdentity(env) {
+	if (typeof env !== "object" || env === null || Array.isArray(env)) return {
+		project: null,
+		environment: null,
+		worker: null,
+		version: null
+	};
+	const vars = env;
+	return {
+		project: stamped(vars, PROJECT_VAR),
+		environment: stamped(vars, ENVIRONMENT_VAR),
+		worker: stamped(vars, WORKER_VAR),
+		version: workerVersion(env)
+	};
+}
+/**
+* Read the whole `CF_VERSION_METADATA` binding: which build is running, and when that build was made.
+*
+* **The one reader of the binding**, which is why it returns all of it. The seam used to take the id and
+* drop the rest, and the module docstring above described a two-field binding — so the field this
+* function exists for was discarded by a reader that did not know it was there.
+*
+* ## What a client can conclude
+*
+* Holding the last `(id, createdAt)` it saw, and comparing field by field only where both sides carried
+* a value: anything that differs is a change. Absence on either side is silence, never change.
+* `workerBuildChanged` in `controlPlane/wire.ts` is that rule, written once so no client hand-rolls it.
+*
+* ## What it cannot see, and why that is a boundary rather than a gap
+*
+* **This binding describes a version. Nothing inside a Worker can observe a deployment** — see
+* {@link WorkerVersionMetadata.createdAt} for the two objects and the measurement. So a rollback, a
+* traffic split, a gradual rollout: all invisible here, and no field the seam could add would change
+* that, because the runtime hands a script no binding for the object that carries them. A client that
+* needs a deployment reads Cloudflare's deployments API, in the customer's own account.
+*
+* The temptation is to synthesise one. Isolate boot time is the only in-Worker candidate and it is
+* worse than nothing: it changes on every cold start, so it would report a redeploy dozens of times a
+* day, and a false change costs more than a missed one for a client that invalidates a rendered pane on
+* it. Nothing is stamped.
+*
+* Same never-throws, never-guesses contract as {@link workerIdentity}.
+*/
+function workerVersionMetadata(env) {
+	const absent = {
+		id: null,
+		tag: null,
+		createdAt: null
+	};
+	if (typeof env !== "object" || env === null || Array.isArray(env)) return absent;
+	const meta = env[VERSION_METADATA_BINDING];
+	if (typeof meta !== "object" || meta === null) return absent;
+	const fields = meta;
+	const createdAt = carried(fields, "timestamp");
+	return {
+		id: carried(fields, "id"),
+		tag: carried(fields, "tag"),
+		createdAt: createdAt !== null && Number.isFinite(Date.parse(createdAt)) ? createdAt : null
+	};
+}
+/**
+* The deployed build's version id, off the `CF_VERSION_METADATA` binding, or `null`.
+*
+* Kept on its own because four callers want the id and nothing else: the request logger's `version`
+* correlation field, `/health`, the control-plane manifest, and the seam's response header. Its shape
+* is unchanged and deliberately so — every one of those compares or records a single opaque string, and
+* widening it would have rewritten an audit column and a wire field to carry something none of them
+* asked for. {@link workerVersionMetadata} is where the rest of the binding lives.
+*/
+function workerVersion(env) {
+	return workerVersionMetadata(env).id;
+}
+//#endregion
+export { ENVIRONMENT_VAR, PROJECT_VAR, VERSION_METADATA_BINDING, WORKER_ORIGIN_VAR, WORKER_VAR, workerIdentity, workerVersion, workerVersionMetadata };

package/dist/workflow/bindings.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/workflow/bindings.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,gBAAgB,CAQjF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,eAAe,GAAG,gBAAgB,EAAE,CAE/E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB,CAErF"}

package/dist/workflow/bindings.js

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

package/dist/workflow/dispatch.d.ts

@@ -0,0 +1,98 @@
+import type { Logger } from "../logger/logger";
+import { type LoopbackFetch } from "./loopback";
+import type { WorkflowBinding, WorkflowRegistry } from "./spec";
+/**
+ * Dispatch: start a registered job by its `<capability>/<job>` key.
+ *
+ * Two things happen before the binding is touched, in this order. The key resolves against the
+ * registry, so a typo is `core/unknown_workflow` rather than a `TypeError` on `undefined.create`.
+ * Then the params parse through the spec's schema, so a malformed payload is
+ * `core/invalid_workflow_params` at the call site — with the offending field named — instead of a
+ * failed step inside a running instance, where the only signal is a retry budget burning down and
+ * the payload is no longer in anyone's hands.
+ *
+ * The dispatcher is a closure over the per-request `env`, built once per request by
+ * `createBackend` and served as `c.var.workflows`.
+ */
+/**
+ * The typed dispatcher. `Params` maps each `<capability>/<job>` key to that job's parameter type,
+ * derived by `createBackend` from the composed capabilities — so `trigger` autocompletes the key
+ * set and type-checks the payload against the declaring capability's schema.
+ */
+export interface WorkflowDispatcher<Params extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Start an instance of one job. Resolves once Cloudflare has accepted the instance; it does not
+     * wait for the Workflow to finish. Instance status and termination are deliberately not on this
+     * seam — a Workflow is durable precisely so the caller need not hold its progress.
+     */
+    trigger<Key extends keyof Params & string>(key: Key, params: Params[Key]): Promise<void>;
+}
+/**
+ * Read a binding off the per-request env, narrowed to the one method dispatch needs.
+ *
+ * Exported because the host's dispatch route ({@link ./dispatchRoute.ts}) asks the same question of
+ * the same env, and a second duck-type would be a second answer to "is this a Workflow binding" the
+ * first day one of them learned about a new shape.
+ */
+export declare function workflowBindingFor(env: Record<string, unknown>, name: string): WorkflowBinding | undefined;
+/** What resolving a binding needs to know: which one, whose, and how to reach a sibling. */
+export interface WorkflowBindingRequest {
+    /** The binding name on the caller's own env — `EMAIL_SENDER`. */
+    binding: string;
+    /** The capability that owns the host. Names the origin var, and names the worker in a failure. */
+    capability: string;
+    /** Where a substitution is noted. Defaults to silence. */
+    log?: Logger;
+    /** The loopback transport. Defaults to the runtime's `fetch`; injectable for tests. */
+    fetch?: LoopbackFetch;
+}
+/**
+ * The binding to dispatch on: the real one, or — under `pithy dev` — a loopback stand-in for it.
+ *
+ * ## Why a stand-in exists at all
+ *
+ * A deployed app Worker starts a capability's Workflow through a **cross-script** binding pointing at
+ * `<project>-<env>-email`. `pithy dev` runs no script under that name, so locally that binding cannot
+ * work — it is absent, or it is present and every `create` on it fails — and every dispatch it carried
+ * went nowhere (pithy-sh/pithy#410). What *does* exist locally is the capability host itself, on a
+ * pinned port, with its address in this Worker's own vars as `<STEM>_ORIGIN`. So the seam is filled
+ * rather than left empty, and the call site — `enqueueEmail`, the cron handler, `c.var.workflows` — is
+ * byte-identical either way.
+ *
+ * ## Three rules, and each of them is a refusal
+ *
+ * **In `dev`, a published origin wins over the binding.** The deliberate order, and the one that
+ * closes #410 whatever wrangler decides to hand a local Worker for a script it is not running: a
+ * binding that is present but cannot reach anything is indistinguishable at runtime from one that
+ * works, so preferring it would leave the silence in place and depend on a wrangler behavior nothing
+ * here controls. Preferring the origin costs nothing, because a published origin is not something a
+ * composition can have by accident — see the next rule.
+ *
+ * **A published origin names a host `pithy dev` is running.** The orchestrator writes one `--var` per
+ * *capability host* in the dev set, and never hands a host its own address. So `EMAIL_ORIGIN` on a
+ * Worker's env means exactly one thing: the email host is up, locally, there. An adopter's own
+ * app-owned Workflow — the same-script shape, which `wrangler dev` implements unchanged — is never
+ * published an origin and so is never diverted.
+ *
+ * **Only `dev`.** Not `staging`, not `prod`, and — the case that matters — not a composition that
+ * stamped no environment at all. A gate that reads silence as `dev` opens itself in exactly the
+ * deployment whose `wrangler.jsonc` lost the var.
+ *
+ * **The environment comes off the request env, not off the host's shell.** `--var ENVIRONMENT` is
+ * what puts it on a Worker, and the shell that ran `wrangler dev` does not cross into workerd. The
+ * dispatch *route* reads the ambient env instead, because it is registered before any request exists;
+ * here there is a request env in hand, and it is the truthful one.
+ */
+export declare function resolveWorkflowBinding(env: Record<string, unknown>, request: WorkflowBindingRequest): WorkflowBinding | undefined;
+/**
+ * Start one registered job. The single dispatch path — `createBackend`'s per-request dispatcher and
+ * `createEntrypoint`'s cron handler both route through here, so a scheduled run and a manual one
+ * validate identically.
+ */
+export declare function triggerWorkflow(env: Record<string, unknown>, registry: WorkflowRegistry, key: string, params: unknown, log?: Logger): Promise<void>;
+/**
+ * Build the per-request dispatcher over one registry. A closure rather than a lazily-built registry
+ * object: there is one method and no per-job resource to construct, so there is nothing to defer.
+ */
+export declare function buildWorkflowDispatcher<Params extends Record<string, unknown> = Record<string, unknown>>(env: Record<string, unknown>, registry: WorkflowRegistry, log?: Logger): WorkflowDispatcher<Params>;
+//# sourceMappingURL=dispatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/workflow/dispatch.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,KAAK,aAAa,EAA2B,MAAM,YAAY,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEhE;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClG;;;;OAIG;IACH,OAAO,CAAC,GAAG,SAAS,MAAM,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1F;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAK1G;AAKD,4FAA4F;AAC5F,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,sBAAsB,GAC9B,eAAe,GAAG,SAAS,CAqB7B;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC,IAAI,CAAC,CA0Ef;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtG,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,GAAE,MAAmB,GACvB,kBAAkB,CAAC,MAAM,CAAC,CAI5B"}