@pithy-sh/core 0.9.0 → 0.10.0

package/dist/text/literals.js

@@ -0,0 +1,293 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/text/literals.ts
+/**
+* **Every string a source file writes, as it reads at run time near enough to scan (#711)** — each quoted or
+* template literal's text, quotes off, escapes resolved to the character they stand for, and every `${…}` blanked
+* to `<x>`.
+*
+* Gates that read what the code *says* — `packages/cli/src/ci/runnableCommands.test.ts` reads every `pithy …` a
+* line names — used one regular expression for "a string or template literal", and it has a measured false
+* reading: a template whose interpolation holds a template of its own, `` `${path}${detail ? ` — ${detail}` :
+* ""}` ``, closed at the inner backtick, and everything after it was read as a literal that opened there. The
+* scan then reported text the file does not contain, and missed the text it does. So this walks the source and
+* keeps a stack: a `${` opens an expression, whose own literals are read as literals in their turn, and its
+* matching `}` resumes the template it interrupted.
+*
+* Comments must be blanked first (`./comments`), as every caller here already does. A regex literal is stepped
+* over by the same rule `./comments` uses — a `/` where a value may begin opens one — so a quote inside a pattern
+* does not open a string.
+*/
+function literalTexts(source, options = {}) {
+	return literalSpans(source, options).map((span) => span.text);
+}
+/**
+* {@link literalTexts}, with where each one sits — so a gate can read what is around a literal: a `+` beside it, or
+* the array it is an element of being joined.
+*/
+function literalSpans(source, options = {}) {
+	const found = [];
+	walk(source, 0, found, false, options.jsx === true);
+	return found;
+}
+/** After one of these, a `/` opens a regex literal; after anything else it divides. */
+const VALUE_POSITION = /* @__PURE__ */ new Set([
+	"",
+	"(",
+	",",
+	"=",
+	":",
+	"[",
+	"!",
+	"&",
+	"|",
+	"?",
+	"{",
+	"}",
+	";",
+	"+",
+	"-",
+	"*",
+	"%",
+	"^",
+	"~",
+	"<",
+	">"
+]);
+/**
+* Walk code from `start`, pushing every literal it meets. Inside an interpolation (`nested`), an unmatched `}`
+* closes it: the walk returns the index just past that brace.
+*/
+function walk(source, start, found, nested, jsx) {
+	let depth = 0;
+	let previous = "";
+	let index = start;
+	while (index < source.length) {
+		const char = source[index];
+		if (char === "\"" || char === "'") {
+			index = quoted(source, index, char, found);
+			previous = char;
+			continue;
+		}
+		if (char === "`") {
+			index = template(source, index, found, jsx);
+			previous = char;
+			continue;
+		}
+		if (jsx && char === "<" && opensElement(source, index, previous)) {
+			const mark = found.length;
+			const end = element(source, index, found);
+			if (end !== null) {
+				index = end;
+				previous = ")";
+				continue;
+			}
+			found.length = mark;
+		}
+		if (char === "/" && VALUE_POSITION.has(previous)) {
+			index = endOfRegex(source, index);
+			previous = "/";
+			continue;
+		}
+		if (char === "{") depth += 1;
+		if (char === "}") {
+			if (depth === 0 && nested) return index + 1;
+			depth -= 1;
+		}
+		if (!/\s/.test(char)) previous = char;
+		index += 1;
+	}
+	return index;
+}
+/** One quoted string: its text pushed, the index past its closing quote returned. A newline ends it unclosed. */
+function quoted(source, start, quote, found) {
+	let text = "";
+	for (let index = start + 1; index < source.length; index += 1) {
+		const char = source[index];
+		if (char === "\\") {
+			text += source[index + 1] ?? "";
+			index += 1;
+			continue;
+		}
+		if (char === quote || char === "\n") {
+			const end = char === quote ? index + 1 : index;
+			found.push({
+				text,
+				start,
+				end
+			});
+			return end;
+		}
+		text += char;
+	}
+	found.push({
+		text,
+		start,
+		end: source.length
+	});
+	return source.length;
+}
+/**
+* One template: its text pushed with each `${…}` as `<x>`, and every literal inside an interpolation pushed in
+* its own right. Returns the index past the closing backtick.
+*/
+function template(source, start, found, jsx) {
+	let text = "";
+	const holes = [];
+	const slot = found.length;
+	found.push({
+		text: "",
+		start,
+		end: start
+	});
+	const close = (end) => ({
+		text,
+		start,
+		end,
+		...holes.length > 0 ? { holes } : {}
+	});
+	let index = start + 1;
+	while (index < source.length) {
+		const char = source[index];
+		if (char === "\\") {
+			text += source[index + 1] ?? "";
+			index += 2;
+			continue;
+		}
+		if (char === "`") {
+			found[slot] = close(index + 1);
+			return index + 1;
+		}
+		if (char === "$" && source[index + 1] === "{") {
+			text += "<x>";
+			const from = index + 2;
+			index = walk(source, from, found, true, jsx);
+			holes.push([from, source[index - 1] === "}" ? index - 1 : index]);
+			continue;
+		}
+		text += char;
+		index += 1;
+	}
+	found[slot] = close(source.length);
+	return source.length;
+}
+/** After one of these words, as after a {@link VALUE_POSITION} character, a value begins. */
+const VALUE_WORDS = /* @__PURE__ */ new Set([
+	"return",
+	"yield",
+	"await",
+	"default",
+	"case",
+	"else",
+	"do"
+]);
+/**
+* Whether the `<` at `index` opens a JSX element: where a value may begin — after an operator, a bracket, or a
+* word such as `return` — and followed by a tag name or, for a fragment, `>`. After an identifier or a closing
+* bracket it compares, or opens a type's arguments.
+*/
+function opensElement(source, index, previous) {
+	if (!/[A-Za-z_$>]/.test(source[index + 1] ?? "")) return false;
+	if (VALUE_POSITION.has(previous)) return true;
+	const before = /([A-Za-z_$][\w$]*)\s*$/.exec(source.slice(Math.max(0, index - 32), index));
+	return before !== null && VALUE_WORDS.has(before[1]);
+}
+/** A JSX text run as React renders it: whitespace collapsed, and nothing pushed for a run that is only space. */
+function pushText(text, start, end, found) {
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	if (collapsed.length > 0) found.push({
+		text: collapsed,
+		start,
+		end
+	});
+}
+/**
+* One JSX element from its `<`: each attribute string and each text run pushed, every `{…}` walked as code. Returns
+* the index past the element, or `null` when what follows the `<` is not an element — a generic arrow `<T,>(…)`,
+* or a `<` that never closes — for the caller to read as code.
+*/
+function element(source, start, found) {
+	let index = start + 1;
+	const name = /^[A-Za-z_$][\w$.:-]*/.exec(source.slice(index))?.[0] ?? "";
+	index += name.length;
+	for (;;) {
+		while (/\s/.test(source[index] ?? "")) index += 1;
+		const char = source[index];
+		if (char === void 0) return null;
+		if (char === "/" && source[index + 1] === ">") return index + 2;
+		if (char === ">") {
+			index += 1;
+			break;
+		}
+		if (char === "{") {
+			index = walk(source, index + 1, found, true, true);
+			continue;
+		}
+		const attribute = /^[A-Za-z_$][\w$:-]*/.exec(source.slice(index))?.[0];
+		if (attribute === void 0 || name === "") return null;
+		index += attribute.length;
+		while (/\s/.test(source[index] ?? "")) index += 1;
+		if (source[index] !== "=") continue;
+		index += 1;
+		while (/\s/.test(source[index] ?? "")) index += 1;
+		const value = source[index];
+		if (value === "{") {
+			index = walk(source, index + 1, found, true, true);
+			continue;
+		}
+		if (value !== "\"" && value !== "'") return null;
+		const close = source.indexOf(value, index + 1);
+		if (close === -1) return null;
+		found.push({
+			text: source.slice(index + 1, close),
+			start: index,
+			end: close + 1
+		});
+		index = close + 1;
+	}
+	let text = "";
+	let from = index;
+	while (index < source.length) {
+		const char = source[index];
+		if (char === "{") {
+			text += "<x>";
+			index = walk(source, index + 1, found, true, true);
+			continue;
+		}
+		if (char === "<") {
+			if (/^<\s*\//.exec(source.slice(index)) !== null) {
+				pushText(text, from, index, found);
+				const end = source.indexOf(">", index);
+				return end === -1 ? null : end + 1;
+			}
+			pushText(text, from, index, found);
+			const end = element(source, index, found);
+			if (end === null) return null;
+			index = end;
+			text = "";
+			from = index;
+			continue;
+		}
+		text += char;
+		index += 1;
+	}
+	return null;
+}
+/** Where a regex literal ends. A `/` inside a character class does not close it; a newline does. */
+function endOfRegex(source, start) {
+	let inClass = false;
+	for (let index = start + 1; index < source.length; index += 1) {
+		const char = source[index];
+		if (char === "\\") {
+			index += 1;
+			continue;
+		}
+		if (char === "\n") return index;
+		if (char === "[") inClass = true;
+		else if (char === "]") inClass = false;
+		else if (char === "/" && !inClass) return index + 1;
+	}
+	return source.length;
+}
+//#endregion
+export { literalSpans, literalTexts };

package/dist/version.generated.d.ts

@@ -3,5 +3,5 @@
 /** This package's npm name — the join key against a release feed. */
 export declare const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-export declare const PACKAGE_VERSION = "0.9.0";
+export declare const PACKAGE_VERSION = "0.10.0";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}
+{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,eAAe,WAAW,CAAC"}

package/dist/version.generated.js

@@ -4,6 +4,6 @@
 /** This package's npm name — the join key against a release feed. */
 const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-const PACKAGE_VERSION = "0.9.0";
+const PACKAGE_VERSION = "0.10.0";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

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

@@ -1 +1 @@
-{"version":3,"file":"dispatchRoute.d.ts","sourceRoot":"","sources":["../../src/workflow/dispatchRoute.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAW,IAAI,EAAQ,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAAsC,MAAM,gBAAgB,CAAC;AAGrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAQjE,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,EAAE,oBAA+B,CAAC;AAK7E,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACtC,wGAAwG;IACxG,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAqBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAkE7G"}
+{"version":3,"file":"dispatchRoute.d.ts","sourceRoot":"","sources":["../../src/workflow/dispatchRoute.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAW,IAAI,EAAQ,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EAAE,KAAK,UAAU,EAAsC,MAAM,gBAAgB,CAAC;AAIrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAQjE,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,EAAE,oBAA+B,CAAC;AAK7E,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACtC,wGAAwG;IACxG,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAqBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAwE7G"}

package/dist/workflow/dispatchRoute.js

@@ -1,11 +1,12 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { ForbiddenError, PithyError } from "../error/pithyError.js";
-import { validationHook } from "../http/validation.js";
-import { WORKFLOW_DISPATCH_ROUTE, WorkflowDispatchParams, WorkflowDispatchRequest } from "./schemas.js";
-import { workflowBindingFor } from "./dispatch.js";
+import { commandName } from "../cli/command.js";
 import { ambientEnv, compositionEnvironment } from "../env/ambient.js";
-import { zValidator } from "@hono/zod-validator";
+import { describeRoute } from "../http/routeSpec.js";
+import { validate } from "../http/validation.js";
+import { WORKFLOW_DISPATCH_ROUTE, WorkflowDispatchParams, WorkflowDispatchRequest, WorkflowDispatchResponse } from "./schemas.js";
+import { workflowBindingFor } from "./dispatch.js";
 //#region src/workflow/dispatchRoute.ts
 /**
 * The host's dispatch route — the loopback door `pithy dev` starts an instance through.
@@ -73,7 +74,7 @@ function specForBinding(registry, binding) {
 function refuseOutsideDev(capability, environment) {
 	return new ForbiddenError({
 		message: `Workflow dispatch over HTTP is served only in the ${DISPATCH_ENVIRONMENT} environment.`,
-		action: `Dispatch through the cross-script ${capability} Workflow binding, or run this host under pithy dev.`,
+		action: `Dispatch through the cross-script ${capability} Workflow binding, or run this host under ${commandName("dev")}.`,
 		detail: `The composition's ENVIRONMENT is ${environment ?? "unstamped"}.`
 	});
 }
@@ -91,7 +92,12 @@ function registerWorkflowDispatchRoute(app, options) {
 		if (environment !== DISPATCH_ENVIRONMENT) throw refuseOutsideDev(capability, environment);
 		await next();
 	};
-	app.post(WORKFLOW_DISPATCH_ROUTE, guard, zValidator("param", WorkflowDispatchParams, validationHook), zValidator("json", WorkflowDispatchRequest, validationHook), async (c) => {
+	app.post(WORKFLOW_DISPATCH_ROUTE, describeRoute({
+		summary: "Start a Workflow instance on this host, in dev only.",
+		description: "Refused outside a `dev` composition. Deployed Workers dispatch through a Workflow binding instead.",
+		verification: WORKFLOW_DISPATCH_VERIFICATION,
+		responses: { 202: WorkflowDispatchResponse }
+	}), guard, validate("param", WorkflowDispatchParams), validate("json", WorkflowDispatchRequest), async (c) => {
 		const { binding } = c.req.valid("param");
 		const { id, params } = c.req.valid("json");
 		const entry = specForBinding(registry, binding);

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

@@ -1 +1 @@
-{"version":3,"file":"faults.d.ts","sourceRoot":"","sources":["../../src/workflow/faults.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,UAAU,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,iHAAiH;IACjH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,WAAW,EAAE,wBAAwB,CAAC;IACtC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB;AAsDD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA0BhG;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD;;;OAGG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,wDAAwD;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,mBAAmB,EAC3B,aAAa,EAAE,wBAAwB,GACtC,eAAe,CAmDjB"}
+{"version":3,"file":"faults.d.ts","sourceRoot":"","sources":["../../src/workflow/faults.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,UAAU,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,iHAAiH;IACjH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,WAAW,EAAE,wBAAwB,CAAC;IACtC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB;AAsDD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA0BhG;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD;;;OAGG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,wDAAwD;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,mBAAmB,EAC3B,aAAa,EAAE,wBAAwB,GACtC,eAAe,CAqDjB"}

package/dist/workflow/faults.js

@@ -120,15 +120,14 @@ function classifiedSteps(step, policy, terminalError) {
 		* answer that cannot change.
 		*/
 		sleep(name, durationMs) {
-			const pause = step.sleep;
-			if (pause === void 0) return runner.do(`${name}/cannot-pause`, async () => {
+			if (step.sleep === void 0) return runner.do(`${name}/cannot-pause`, async () => {
 				throw new InternalError({
 					message: "This Workflow step runner cannot pause.",
 					action: "Give the step runner a `sleep`; the platform's own `WorkflowStep` always has one.",
 					detail: `step '${name}' asked to pause ${durationMs}ms through a runner that declares no sleep`
 				});
 			});
-			return pause.call(step, name, durationMs);
+			return step.sleep(name, durationMs);
 		}
 	};
 	return runner;

package/dist/workflow/hostEnv.d.ts

@@ -51,6 +51,7 @@ export declare const HostEnvProvider: z.ZodObject<{
     }>;
     name: z.ZodString;
     command: z.ZodOptional<z.ZodString>;
+    decision: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type HostEnvProvider = z.infer<typeof HostEnvProvider>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"hostEnv.d.ts","sourceRoot":"","sources":["../../src/workflow/hostEnv.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hostEnv.d.ts","sourceRoot":"","sources":["../../src/workflow/hostEnv.ts"],"names":[],"mappings":"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"}

package/dist/workflow/hostEnv.js

@@ -46,7 +46,8 @@ const HostEnvProviderKind = z.enum([
 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.")
+	command: z.string().min(1).optional().describe("The `pithy` command that fills it, where one does. Rendered as the report's action line."),
+	decision: z.string().min(1).optional().describe("What fills it when only a person may run the command that does — one that touches production — said as their decision. Rendered in place of `command`.")
 }).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
@@ -109,7 +110,8 @@ function checkHostEnv(declaration, env) {
 /** 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;
+	if (provider.command) return `${where} Run ${provider.command}.`;
+	return provider.decision ? `${where} ${provider.decision}` : where;
 }
 /**
 * The block a host logs before it refuses. One headline, then one line per field: the field, why it

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

@@ -1 +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"}
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../src/workflow/loopback.ts"],"names":[],"mappings":"AAMA,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

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { UpstreamError, UpstreamTimeoutError } from "../error/pithyError.js";
+import { commandName } from "../cli/command.js";
 import { workflowDispatchPath } from "./schemas.js";
 //#region src/workflow/loopback.ts
 /** 10 seconds. A loopback dispatch either lands immediately or is not going to. */
@@ -32,7 +33,7 @@ function loopbackWorkflowBinding(options) {
 	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}.`;
+	const running = `Check that the ${owner} host is running under ${commandName("dev")} at ${origin}.`;
 	return { async create(instance) {
 		const body = {
 			id: instance?.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
     "kysely-d1": "^0.4.0"
   },
   "devDependencies": {
-    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@cloudflare/vitest-plugin": "^1.4.2",
     "@pithy-sh/tsconfig": "workspace:*",
     "@vitest/coverage-v8": "^4.1.0",
     "hono": "^4.13.2",
@@ -47,7 +47,7 @@
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.0",
-    "wrangler": "^4.115.0",
+    "wrangler": "^4.151.0",
     "zod": "^4.4.0"
   },
   "peerDependencies": {

package/src/asyncapi/document.ts

@@ -0,0 +1,164 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+import type { Capability } from "../capability/capability";
+import { ErrorBody } from "../error/wire";
+import type { SocketChannel, SocketMessage } from "../http/socket";
+import type { VerificationStrategy } from "../http/verification";
+import {
+  type ContractInfo,
+  type JsonSchema,
+  jsonSchema,
+  openApiPath,
+  type UndescribedField,
+  undescribedFieldsIn,
+} from "../openapi/document";
+
+/**
+ * **The AsyncAPI contract: every socket a Worker serves, and every frame on it.**
+ *
+ * The OpenAPI document stops at the upgrade. This picks up after it, from the `sockets` each composed
+ * capability declares (`../http/socket.ts`): one channel per socket, one message per frame, and one operation
+ * per direction — `send` for what the Worker sends, `receive` for what it accepts, as AsyncAPI names them from
+ * the application's side. Every schema is the one the socket parses with, converted by `z.toJSONSchema` with
+ * its descriptions intact, so an engine with no generator still has typed messages to write against.
+ *
+ * AsyncAPI 3.0, whose schemas are JSON Schema — the dialect `z.toJSONSchema` writes.
+ */
+
+/** The AsyncAPI version this module writes. */
+export const ASYNCAPI_VERSION = "3.0.0";
+
+/** One capability's sockets. Becomes the channels tagged with its name. */
+export interface SocketGroup {
+  /** The capability's name. */
+  readonly tag: string;
+  /** The sockets it declared. */
+  readonly sockets: readonly SocketChannel[];
+}
+
+/** The sockets of every capability that declares one, grouped by capability, in composition order. */
+export function socketGroupsOf(capabilities: readonly Capability[]): SocketGroup[] {
+  return capabilities
+    .filter((capability) => (capability.sockets ?? []).length > 0)
+    .map((capability) => ({ tag: capability.name, sockets: capability.sockets ?? [] }));
+}
+
+/** The subset of an AsyncAPI 3.0 document this module writes. */
+export interface AsyncApiDocument {
+  asyncapi: string;
+  info: ContractInfo;
+  channels: Record<string, Record<string, unknown>>;
+  operations: Record<string, Record<string, unknown>>;
+  components: {
+    messages: Record<string, Record<string, unknown>>;
+    schemas: Record<string, JsonSchema>;
+  };
+}
+
+/** A frame's id in the document: its socket's name and its own, so two sockets' `error` frames stay apart. */
+function messageId(socket: SocketChannel, message: SocketMessage, direction: "send" | "receive"): string {
+  return `${socket.name}.${direction}.${message.name}`;
+}
+
+/** One `components.messages` entry: a JSON frame by its schema, a text frame by its exact text. */
+function messageOf(message: SocketMessage): Record<string, unknown> {
+  if (message.schema === undefined) {
+    return {
+      name: message.name,
+      summary: message.summary,
+      contentType: "text/plain",
+      payload: { type: "string", const: message.text ?? "", description: message.summary },
+    };
+  }
+  return {
+    name: message.name,
+    summary: message.summary,
+    contentType: "application/json",
+    payload: jsonSchema(message.schema, "input"),
+  };
+}
+
+/** The path parameters, from the same schema the upgrade route validates them with. */
+function parametersOf(params: z.ZodType | undefined): Record<string, Record<string, unknown>> {
+  if (params === undefined) return {};
+  const properties = (jsonSchema(params, "input").properties ?? {}) as Record<string, JsonSchema>;
+  return Object.fromEntries(
+    Object.entries(properties).map(([name, property]) => [
+      name,
+      typeof property.description === "string" ? { description: property.description } : {},
+    ]),
+  );
+}
+
+function strategiesOf(socket: SocketChannel): readonly VerificationStrategy[] {
+  return typeof socket.verification === "string" ? [socket.verification] : socket.verification;
+}
+
+/** The AsyncAPI document for these capabilities' sockets. */
+export function asyncApiDocument(info: ContractInfo, groups: readonly SocketGroup[]): AsyncApiDocument {
+  const document: AsyncApiDocument = {
+    asyncapi: ASYNCAPI_VERSION,
+    info,
+    channels: {},
+    operations: {},
+    components: { messages: {}, schemas: { Error: jsonSchema(ErrorBody, "input") } },
+  };
+
+  for (const group of groups) {
+    for (const socket of group.sockets) {
+      const channelMessages: Record<string, { $ref: string }> = {};
+      for (const direction of ["send", "receive"] as const) {
+        const refs: { $ref: string }[] = [];
+        for (const message of socket[direction]) {
+          const id = messageId(socket, message, direction);
+          document.components.messages[id] = messageOf(message);
+          channelMessages[id] = { $ref: `#/components/messages/${id}` };
+          refs.push({ $ref: `#/channels/${socket.name}/messages/${id}` });
+        }
+        if (refs.length > 0) {
+          document.operations[`${socket.name}.${direction}`] = {
+            action: direction,
+            channel: { $ref: `#/channels/${socket.name}` },
+            summary: direction === "send" ? "Frames the Worker sends." : "Frames the Worker accepts.",
+            messages: refs,
+          };
+        }
+      }
+      const parameters = parametersOf(socket.params);
+      document.channels[socket.name] = {
+        address: openApiPath(socket.path),
+        summary: socket.summary,
+        ...(socket.description === undefined ? {} : { description: socket.description }),
+        ...(Object.keys(parameters).length === 0 ? {} : { parameters }),
+        messages: channelMessages,
+        tags: [{ name: group.tag }],
+        bindings: { ws: { method: "GET" } },
+        "x-pithy-verification": strategiesOf(socket),
+        "x-pithy-subprotocols": socket.versions,
+      };
+      for (const [name, schema] of Object.entries(socket.schemas ?? {})) {
+        document.components.schemas[`${socket.name}.${name}`] = jsonSchema(schema, "input");
+      }
+    }
+  }
+  return document;
+}
+
+/**
+ * Every message property, schema property and channel parameter in the document without a description —
+ * the same rule as the OpenAPI document's, over the parts a client generates from.
+ */
+export function undescribedAsyncFields(document: AsyncApiDocument): UndescribedField[] {
+  const parameters = Object.entries(document.channels).flatMap(([channel, item]) =>
+    Object.entries((item.parameters ?? {}) as Record<string, Record<string, unknown>>)
+      .filter(([, parameter]) => typeof parameter.description !== "string")
+      .map(([name]) => ({ pointer: `/channels/${channel}/parameters/${name}` })),
+  );
+  return [
+    ...parameters,
+    ...undescribedFieldsIn(document.components.messages, "/components/messages"),
+    ...undescribedFieldsIn(document.components.schemas, "/components/schemas"),
+  ];
+}

package/src/capability/capability.ts

@@ -14,6 +14,7 @@ import type { DatabaseSpecMap } from "../data/databases";
 import type { EntitlementResolver } from "../entitlement/entitlement";
 import type { AuthContext } from "../http/authContext";
 import type { SameOriginGate } from "../http/sameOrigin";
+import type { SocketChannel } from "../http/socket";
 import type { LocaleCatalogs } from "../i18n/catalog";
 import type { LocaleContext } from "../i18n/locale";
 import type { Translator } from "../i18n/translator";
@@ -532,6 +533,12 @@ export interface Capability<
   boot?: (context: CapabilityComposeContext) => void;
   /** Mounts a Hono sub-router. */
   routes?: (app: Hono<PithyHonoEnv>) => void;
+  /**
+   * The WebSockets this capability serves, described for the AsyncAPI contract (`../http/socket.ts`). Built
+   * from the resolved config, like `adminRoutes`: the paths it mounted, and the schemas its frames are
+   * parsed with. A capability with no socket leaves it unset.
+   */
+  sockets?: readonly SocketChannel[];
   /** Composable middleware (e.g. turnstile(), requireAuth()). */
   middleware?: PithyMiddleware[];
   /**