@pithy-sh/core 0.1.1 → 0.1.3

package/dist/workflow/schemas.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+//#region src/workflow/schemas.ts
+/**
+* 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`. */
+const WORKFLOW_DISPATCH_BASE = "/__pithy/workflows";
+/** The registered path pattern. `:binding` is the host's own Workflow binding name. */
+const WORKFLOW_DISPATCH_ROUTE = `${WORKFLOW_DISPATCH_BASE}/:binding`;
+/** The concrete path for one binding — what the loopback dispatcher POSTs to. */
+function workflowDispatchPath(binding) {
+	return `${WORKFLOW_DISPATCH_BASE}/${encodeURIComponent(binding)}`;
+}
+/** The path segment naming which of the host's own Workflow bindings to start an instance on. */
+const WorkflowDispatchParams = z.object({ binding: z.string().min(1).max(64).regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "A binding name is an identifier: letters, digits and underscores, not starting with a digit.").describe("The Workflow binding on this host's own env — `EMAIL_SENDER`, not a `<capability>/<job>` key. The loopback dispatcher stands in for exactly one binding, and a binding is what it knows itself by.") }).describe("The path parameters of the host dispatch route.");
+/** The body: the instance id and the payload, exactly as `create({ id, params })` takes them. */
+const WorkflowDispatchRequest = z.object({
+	id: z.string().min(1).max(128).optional().describe("The instance id to start under. Optional because the platform's own `create` allows omitting it — and relayed rather than minted here, because an id a dispatcher did not choose is an instance the caller's row cannot name (pithy-sh/pithy#342). Every Pithy dispatcher passes one."),
+	params: z.unknown().describe("The instance payload. Unconstrained on the wire and validated on arrival against the declaring spec's own schema, so a malformed payload fails with the field named rather than inside a running instance.")
+}).describe("A request to start one instance of a Workflow this host hosts.");
+/**
+* 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.
+*/
+const WorkflowDispatchResponse = z.object({
+	binding: z.string().describe("The binding an instance was started on — the one the request named."),
+	id: z.string().optional().describe("The instance id, when the request named one."),
+	started: z.literal(true).describe("Always true. The route answers 202 once Cloudflare has accepted the instance, never on completion.")
+}).describe("What the host answers when it has accepted a dispatch.");
+//#endregion
+export { WORKFLOW_DISPATCH_BASE, WORKFLOW_DISPATCH_ROUTE, WorkflowDispatchParams, WorkflowDispatchRequest, WorkflowDispatchResponse, workflowDispatchPath };

package/dist/workflow/spec.d.ts

@@ -0,0 +1,81 @@
+import type { z } from "zod";
+/**
+ * The durable-job seam. A capability declares the Cloudflare Workflows it owns as a map of
+ * job name → {@link WorkflowSpec}; `createBackend` collects every capability's map into one
+ * registry, derives each spec's binding so a missing one fails at boot, and serves a typed
+ * dispatcher on `c.var.workflows`.
+ *
+ * The spec is the single description of a job. The CLI reads it to write the host worker's
+ * `workflows` array and its cron triggers; the dispatcher reads it to validate params and find
+ * the binding; `naming.ts` reads it to resolve the per-environment script name. One declaration,
+ * no drift between the wrangler config, the provisioner, and the call site.
+ */
+/**
+ * The minimal structural shape of a Cloudflare Workflow binding: enough to start an instance,
+ * and nothing more. Typed structurally rather than against `Workflow<P>` from
+ * `@cloudflare/workers-types` so core gains no runtime dependency and a test injects a plain
+ * object literal — the same posture `@pithy-sh/media` already takes for its AI binding.
+ */
+export interface WorkflowBinding {
+    /** Start a new instance. `params` is the validated payload the Workflow receives as `event.payload`. */
+    create(options?: {
+        id?: string;
+        params?: unknown;
+    }): Promise<unknown>;
+}
+/**
+ * One durable job a capability registers. Keyed in {@link WorkflowSpecMap} by its job name, which
+ * is also the second segment of the `<capability>/<job>` dispatch key.
+ */
+export interface WorkflowSpec<Params extends z.ZodType = z.ZodType> {
+    /**
+     * The binding name the Workflow is bound to in the Worker env (e.g. `MEDIA_IMAGE_TO_TEXT`).
+     * `createBackend` derives a `workflow` {@link BindingSpec} from it, so a job whose binding is
+     * absent surfaces as a startup failure rather than a silent no-op at dispatch time.
+     */
+    binding: string;
+    /**
+     * The instance parameters, validated **at dispatch** — before the binding is touched. A malformed
+     * trigger therefore fails at the call site with `core/invalid_workflow_params`, rather than inside
+     * a running instance where the only signal is a failed step and a retry budget burning down.
+     */
+    params: Params;
+    /**
+     * A cron expression. Present means the CLI writes a `triggers.crons` entry into the host worker's
+     * resolved `wrangler.jsonc` and `createEntrypoint` routes the `scheduled` event here. Absent means
+     * dispatch-only. A scheduled job stays manually triggerable either way — a backfill nobody can run
+     * on demand is untestable.
+     */
+    schedule?: string;
+    /**
+     * The exported `WorkflowEntrypoint` subclass in the host worker that runs this job — the
+     * `class_name` the CLI writes into the host's `workflows` array. Omit only for a job whose host
+     * config is hand-maintained.
+     */
+    className?: string;
+    /**
+     * Treat the derived binding as optional, so a project that has not provisioned the host worker
+     * still boots. Defaults to false. `@pithy-sh/media` sets it: its enrichment Workflows appear only
+     * once `pithy media provision` has run, and the app must serve every other route until then.
+     */
+    optional?: boolean;
+}
+/** A capability's durable jobs: job name → {@link WorkflowSpec}. The peer of `databases` and `kvNamespaces`. */
+export type WorkflowSpecMap = Record<string, WorkflowSpec>;
+/**
+ * A spec resolved against the capability that declared it — what the registry holds and the
+ * dispatcher looks up. `key` is the `<capability>/<job>` dispatch key.
+ */
+export interface RegisteredWorkflow {
+    /** The dispatch key, `<capability>/<job>`. */
+    key: string;
+    /** The capability that declared the job — the first key segment and the script-name segment. */
+    capability: string;
+    /** The job name — the second key segment. */
+    job: string;
+    /** The spec as declared. */
+    spec: WorkflowSpec;
+}
+/** The project-wide registry: dispatch key → {@link RegisteredWorkflow}. */
+export type WorkflowRegistry = Record<string, RegisteredWorkflow>;
+//# sourceMappingURL=spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/workflow/spec.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,wGAAwG;IACxG,MAAM,CAAC,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvE;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAChE;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,gHAAgH;AAChH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,gGAAgG;IAChG,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC"}

package/dist/workflow/stepMessage.d.ts

@@ -0,0 +1,122 @@
+/**
+ * **The one statement of what a terminal Workflow step writes into its error text, and the one reader of it.**
+ *
+ * A step's error text is the whole channel. The engine records the throw's message and nothing else —
+ * no fields, no cause, no payload — so every operator-facing thing a `PithyError` carries across a
+ * durable boundary has to ride inside that one string. `classifiedSteps` used to write
+ * `${code}: ${message}`, which meant `action` — the remedy line every other `PithyError` reaching the
+ * CLI prints under the problem line — died at the step (pithy-sh/pithy#353).
+ *
+ * Both ends of that channel live here. {@link encodeWorkflowStepMessage} is called by
+ * `classifiedSteps`; {@link decodeWorkflowStepMessage} is called by `@pithy-sh/cloudflare`'s
+ * `kitSentence`. **Neither end restates the format.** Two packages that agree about a string by each
+ * writing it down is not agreement, it is a coincidence with a maintenance schedule — so the format is
+ * the thing being called, not a rule at two call sites, and `stepFailure.test.ts` pins the wire it
+ * produces to a hand-written literal so a change to either end has to be a change to both.
+ *
+ * ## The encoding, and why it is a separator rather than JSON
+ *
+ * `${code}: ${message}` — unchanged, byte for byte, from what #349 captured — then, when there is one,
+ * a separator and the action.
+ *
+ * A JSON payload was the other candidate, and it is the more obvious answer: unambiguous, extensible,
+ * no grammar to get wrong. It loses on the surface nobody controls. **A step's raw text is read by a
+ * human, in the Cloudflare dashboard, at three in the morning**, and that reader is the whole reason
+ * the message was ever put in the throw. `{"code":"secrets/already_exists","message":"Secret
+ * 'api-token' already exists.","action":"Use \`update\` to change an existing secret."}` is strictly
+ * worse to read than the two lines it would replace, and it would make every instance already recorded
+ * unreadable to the new reader and every instance recorded by the new writer unreadable to the old one.
+ * A separator costs a grammar and keeps the sentence.
+ *
+ * ## Why the separator is a newline
+ *
+ * A printable delimiter — ` | `, ` :: ` — is ambiguous, and nothing at the reader can resolve it: a
+ * message that happens to contain the delimiter splits in the wrong place and the operator reads half
+ * a sentence with the other half presented as the remedy. A newline is not ambiguous, because a
+ * promoted message may not contain one. That rule is older than this encoding — #349 declined a
+ * newline-carrying sentence precisely because it *would forge the CLI's action line* — and it is what
+ * makes the split total rather than best-effort. The second line stops being a forgery and becomes the
+ * field it always looked like.
+ *
+ * It also renders. The CLI prints a problem line then an action line, and the dashboard now shows the
+ * same two lines the operator's terminal does.
+ *
+ * **The forgery concern does not disappear; it is bounded, and it was always this size.** A step's text
+ * arrives from a Worker whose code we did not write, and the reader promotes it only when it carries a
+ * kit throw name and this code grammar. Anyone who can forge that can already forge the problem line.
+ * The action line is exactly as trustworthy as the sentence above it — no more, and no less.
+ *
+ * ## Captured, not assumed
+ *
+ * The engine embeds the throw's text in its step record raw — it does not JSON-quote it, and it does
+ * not escape a newline. Read off a real local Workflows engine (wrangler 4.115.0, 2026-08-14) by
+ * driving a Workflow that threw exactly this shape and fetching the instance from the dev session's
+ * own Local Explorer instance endpoint:
+ *
+ * ```text
+ * Step threw a NonRetryableError with message "NonRetryableError: secrets/already_exists: Secret
+ * 'api-token' already exists.
+ * Use `update` to change an existing secret."
+ * ```
+ *
+ * The same run with no action produced #349's captured text byte for byte, which is the compatibility
+ * claim stated as a measurement rather than a hope.
+ *
+ * **`detail` is not here and never will be.** It is the security boundary: client-safe text in
+ * `message`, throw-site context in `detail`, and a durable boundary is not a reason to move the line.
+ * `action` crosses because `action` is already operator-facing — the CLI prints it and `operatorError`
+ * includes it. This stops losing a field that was always meant for this reader.
+ */
+/**
+ * The separator between the step's sentence and its action. One newline, stated once.
+ *
+ * Exported so a test can assert the wire rather than ask the code what it produces — and so the plant
+ * that proves the gate can fail is a one-character edit here.
+ */
+export declare const WORKFLOW_STEP_SEPARATOR = "\n";
+/**
+ * The most either half may run to before it stops being treated as one.
+ *
+ * The text comes from a Worker over an API, and what it says decides how many bytes land in a terminal,
+ * a log line, and an audit row. Over the bound a half is not truncated — it is declined, because half a
+ * sentence read as the reason is worse than a general one with the reason underneath it.
+ */
+export declare const MAX_WORKFLOW_STEP_TEXT = 512;
+/** What a terminal step's text carries across the boundary: the code, the sentence, and the remedy. */
+export interface WorkflowStepMessage {
+    /** The `PithyError` code the step raised — `secrets/already_exists`. */
+    code: string;
+    /** The public sentence. `PithyError.payload.message`, written to be safe for a client. */
+    message: string;
+    /** The remedy, when the raising error stated one. The CLI's action line. */
+    action?: string;
+}
+/**
+ * Split a leading `<domain>/<reason>: ` off a text.
+ *
+ * Exported because the code grammar has exactly one statement and two readers: this encoding, and
+ * `@pithy-sh/cloudflare`'s handling of a bare `PithyError` throw, whose text is `payload.message` and
+ * carries no encoding at all. A second regex over there is how the two would drift.
+ */
+export declare function splitWorkflowStepCode(text: string): {
+    code?: string;
+    rest: string;
+};
+/**
+ * The text a terminal step throws. The inverse of {@link decodeWorkflowStepMessage}, and tested as one.
+ *
+ * An action is appended only when there is one to append and it is a single line. An action carrying a
+ * break would encode a shape the reader declines, taking the sentence down with it — so the sentence
+ * is kept and the action dropped. Losing the remedy is a worse day; losing both is a worse one still.
+ */
+export declare function encodeWorkflowStepMessage(fields: WorkflowStepMessage): string;
+/**
+ * Read a terminal step's text back, or `null` when it is not this encoding.
+ *
+ * Strict on purpose. No code prefix, an empty sentence, a half over the bound, a stray `\r`, or a
+ * second separator means the text is not something {@link encodeWorkflowStepMessage} wrote, and text
+ * the kit did not write does not become an operator's sentence — it stays in `detail`, where the raw
+ * platform text belongs.
+ */
+export declare function decodeWorkflowStepMessage(text: string): WorkflowStepMessage | null;
+//# sourceMappingURL=stepMessage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stepMessage.d.ts","sourceRoot":"","sources":["../../src/workflow/stepMessage.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAc1C,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAInF;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAK7E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAYlF"}

package/dist/workflow/stepMessage.js

@@ -0,0 +1,152 @@
+//#region src/workflow/stepMessage.ts
+/**
+* **The one statement of what a terminal Workflow step writes into its error text, and the one reader of it.**
+*
+* A step's error text is the whole channel. The engine records the throw's message and nothing else —
+* no fields, no cause, no payload — so every operator-facing thing a `PithyError` carries across a
+* durable boundary has to ride inside that one string. `classifiedSteps` used to write
+* `${code}: ${message}`, which meant `action` — the remedy line every other `PithyError` reaching the
+* CLI prints under the problem line — died at the step (pithy-sh/pithy#353).
+*
+* Both ends of that channel live here. {@link encodeWorkflowStepMessage} is called by
+* `classifiedSteps`; {@link decodeWorkflowStepMessage} is called by `@pithy-sh/cloudflare`'s
+* `kitSentence`. **Neither end restates the format.** Two packages that agree about a string by each
+* writing it down is not agreement, it is a coincidence with a maintenance schedule — so the format is
+* the thing being called, not a rule at two call sites, and `stepFailure.test.ts` pins the wire it
+* produces to a hand-written literal so a change to either end has to be a change to both.
+*
+* ## The encoding, and why it is a separator rather than JSON
+*
+* `${code}: ${message}` — unchanged, byte for byte, from what #349 captured — then, when there is one,
+* a separator and the action.
+*
+* A JSON payload was the other candidate, and it is the more obvious answer: unambiguous, extensible,
+* no grammar to get wrong. It loses on the surface nobody controls. **A step's raw text is read by a
+* human, in the Cloudflare dashboard, at three in the morning**, and that reader is the whole reason
+* the message was ever put in the throw. `{"code":"secrets/already_exists","message":"Secret
+* 'api-token' already exists.","action":"Use \`update\` to change an existing secret."}` is strictly
+* worse to read than the two lines it would replace, and it would make every instance already recorded
+* unreadable to the new reader and every instance recorded by the new writer unreadable to the old one.
+* A separator costs a grammar and keeps the sentence.
+*
+* ## Why the separator is a newline
+*
+* A printable delimiter — ` | `, ` :: ` — is ambiguous, and nothing at the reader can resolve it: a
+* message that happens to contain the delimiter splits in the wrong place and the operator reads half
+* a sentence with the other half presented as the remedy. A newline is not ambiguous, because a
+* promoted message may not contain one. That rule is older than this encoding — #349 declined a
+* newline-carrying sentence precisely because it *would forge the CLI's action line* — and it is what
+* makes the split total rather than best-effort. The second line stops being a forgery and becomes the
+* field it always looked like.
+*
+* It also renders. The CLI prints a problem line then an action line, and the dashboard now shows the
+* same two lines the operator's terminal does.
+*
+* **The forgery concern does not disappear; it is bounded, and it was always this size.** A step's text
+* arrives from a Worker whose code we did not write, and the reader promotes it only when it carries a
+* kit throw name and this code grammar. Anyone who can forge that can already forge the problem line.
+* The action line is exactly as trustworthy as the sentence above it — no more, and no less.
+*
+* ## Captured, not assumed
+*
+* The engine embeds the throw's text in its step record raw — it does not JSON-quote it, and it does
+* not escape a newline. Read off a real local Workflows engine (wrangler 4.115.0, 2026-08-14) by
+* driving a Workflow that threw exactly this shape and fetching the instance from the dev session's
+* own Local Explorer instance endpoint:
+*
+* ```text
+* Step threw a NonRetryableError with message "NonRetryableError: secrets/already_exists: Secret
+* 'api-token' already exists.
+* Use `update` to change an existing secret."
+* ```
+*
+* The same run with no action produced #349's captured text byte for byte, which is the compatibility
+* claim stated as a measurement rather than a hope.
+*
+* **`detail` is not here and never will be.** It is the security boundary: client-safe text in
+* `message`, throw-site context in `detail`, and a durable boundary is not a reason to move the line.
+* `action` crosses because `action` is already operator-facing — the CLI prints it and `operatorError`
+* includes it. This stops losing a field that was always meant for this reader.
+*/
+/**
+* The separator between the step's sentence and its action. One newline, stated once.
+*
+* Exported so a test can assert the wire rather than ask the code what it produces — and so the plant
+* that proves the gate can fail is a one-character edit here.
+*/
+const WORKFLOW_STEP_SEPARATOR = "\n";
+/**
+* The most either half may run to before it stops being treated as one.
+*
+* The text comes from a Worker over an API, and what it says decides how many bytes land in a terminal,
+* a log line, and an audit row. Over the bound a half is not truncated — it is declined, because half a
+* sentence read as the reason is worse than a general one with the reason underneath it.
+*/
+const MAX_WORKFLOW_STEP_TEXT = 512;
+/**
+* Any line break. The separator is one specific break, so every other one — a bare `\r`, a second
+* newline — is a shape this encoding never produces, and an unrecognized shape is declined.
+*/
+const LINE_BREAK = /[\n\r]/;
+/**
+* The `domain/reason` grammar of every kit and adopter error code, mirroring `codeSegment` in
+* ../error/payload. Anchored at the start, so it is the prefix or it is nothing.
+*/
+const CODE_PREFIX = /^([a-z][a-z0-9]*(?:_[a-z0-9]+)*\/[a-z][a-z0-9]*(?:_[a-z0-9]+)*): /;
+/**
+* Split a leading `<domain>/<reason>: ` off a text.
+*
+* Exported because the code grammar has exactly one statement and two readers: this encoding, and
+* `@pithy-sh/cloudflare`'s handling of a bare `PithyError` throw, whose text is `payload.message` and
+* carries no encoding at all. A second regex over there is how the two would drift.
+*/
+function splitWorkflowStepCode(text) {
+	const matched = CODE_PREFIX.exec(text);
+	if (matched === null) return { rest: text };
+	return {
+		code: matched[1],
+		rest: text.slice(matched[0].length)
+	};
+}
+/**
+* The text a terminal step throws. The inverse of {@link decodeWorkflowStepMessage}, and tested as one.
+*
+* An action is appended only when there is one to append and it is a single line. An action carrying a
+* break would encode a shape the reader declines, taking the sentence down with it — so the sentence
+* is kept and the action dropped. Losing the remedy is a worse day; losing both is a worse one still.
+*/
+function encodeWorkflowStepMessage(fields) {
+	const stated = `${fields.code}: ${fields.message}`;
+	const action = fields.action?.trim();
+	if (action === void 0 || action === "" || LINE_BREAK.test(action)) return stated;
+	return `${stated}
+${action}`;
+}
+/**
+* Read a terminal step's text back, or `null` when it is not this encoding.
+*
+* Strict on purpose. No code prefix, an empty sentence, a half over the bound, a stray `\r`, or a
+* second separator means the text is not something {@link encodeWorkflowStepMessage} wrote, and text
+* the kit did not write does not become an operator's sentence — it stays in `detail`, where the raw
+* platform text belongs.
+*/
+function decodeWorkflowStepMessage(text) {
+	const { code, rest } = splitWorkflowStepCode(text.trim());
+	if (code === void 0) return null;
+	const cut = rest.indexOf("\n");
+	const message = (cut === -1 ? rest : rest.slice(0, cut)).trim();
+	const action = cut === -1 ? void 0 : rest.slice(cut + 1).trim();
+	if (message === "" || message.length > 512 || LINE_BREAK.test(message)) return null;
+	if (action === void 0) return {
+		code,
+		message
+	};
+	if (action === "" || action.length > 512 || LINE_BREAK.test(action)) return null;
+	return {
+		code,
+		message,
+		action
+	};
+}
+//#endregion
+export { MAX_WORKFLOW_STEP_TEXT, WORKFLOW_STEP_SEPARATOR, decodeWorkflowStepMessage, encodeWorkflowStepMessage, splitWorkflowStepCode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -8,19 +8,24 @@
     "directory": "packages/core"
   },
   "files": [
+    "dist",
     "src",
     "pithy.manifest.json",
-    "!src/**/*.test.*"
+    "!src/**/*.test.*",
+    "!dist/**/*.test.*"
   ],
   "type": "module",
   "engines": {
     "node": ">=22"
   },
   "exports": {
-    "./src/*": "./src/*.ts"
+    "./src/*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "build": "tsdown && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run",
     "test:node": "vitest run --project=node",
@@ -31,17 +36,23 @@
   "dependencies": {
     "@cloudflare/workers-types": "^5.20260729.1",
     "@hono/zod-validator": "^0.9.0",
-    "hono": "^4.13.2",
-    "kysely": "^0.29.0",
-    "kysely-d1": "^0.4.0",
-    "zod": "^4.0.0"
+    "kysely-d1": "^0.4.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-plugin": "^1.0.0",
     "@pithy-sh/tsconfig": "workspace:*",
     "@vitest/coverage-v8": "^4.1.0",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.0",
-    "wrangler": "^4.115.0"
+    "wrangler": "^4.115.0",
+    "zod": "^4.4.0"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.4.0"
   }
 }

package/src/capability/manifest.ts

@@ -458,6 +458,15 @@ export const ConfigOption = z
       .describe(
         "The values this option accepts, when they are a closed set. Three things follow from stating them, and none of them can be had without: the prompt is a select rather than free text, `--set` refuses a value outside them instead of writing it into the config, and a refusal can name what is legal — which is the whole of what a caller needs in order to answer a required option. Held to the same printable-string rule as a default, because a choice becomes the value written into the adopter's TypeScript.",
       ),
+    // The key is a choice, so it is held to what a rendered value may be. **The value is not**: it is an
+    // error's action line and reaches no generated source, so the printable rule that governs every
+    // other string here would be the wrong constraint — it forbids a double quote, and the sentence has
+    // to be able to say `billingSubject: "user"`.
+    choicesNeedingCode: manifestRecord(z.record(PrintableString, z.string().min(1)))
+      .optional()
+      .describe(
+        "Choices `pithy add` must refuse, each mapped to the sentence telling the adopter what to do instead — a value whose composition needs a seam only they can write. `pithy add` renders JSON into `pithy.config.ts`; it cannot render a function, so a choice whose validity depends on one is a choice it can write and the kit will then refuse to load. `payments`' `billingSubject: \"organization\"` is the one: it requires a `resolveSubject` saying which organization a caller acts for, deliberately has no default because a capability that guessed would key a company's plan to whoever signed in first, and so a config carrying the choice without the seam is refused at assembly — bricking every later command in the project, since they all begin by loading the config (#483). Refusing the choice up front costs the adopter one hand-edit; writing it costs them the project.",
+      ),
     constant: ConfigConstant.optional().describe(
       "A constant the scaffolded pithy.config.ts defines, rendered *unquoted* in place of `default` when the target config declares it. The one that exists is `publicOrigin` — `PUBLIC_ORIGIN`, this Worker's address for the environment it composes in. An option whose value is an origin must name it rather than state a URL, because a URL written down is production's URL written into staging: it is what mailed staging's testers magic links into production and unsubscribed them there (#256). `default` is still required *for such an option* and is what a config with no such constant gets, so an older project is never handed an identifier it does not define — the one place the absent-default rule does not reach, and it is checked rather than trusted.",
     ),
@@ -485,6 +494,18 @@ export const ConfigOption = z
         message: `A config option's default must be one of its choices, and ${JSON.stringify(option.default)} is not — ${option.key} offers ${JSON.stringify(option.choices)}.`,
       });
     }
+    // A choice that cannot be chosen has to be a choice. Without this, a typo names a value nothing
+    // offers, the refusal never fires, and the config it was meant to prevent is written as before.
+    for (const choice of Object.keys(option.choicesNeedingCode ?? {})) {
+      if (!option.choices?.includes(choice)) {
+        ctx.issues.push({
+          code: "custom",
+          input: choice,
+          path: ["choicesNeedingCode", choice],
+          message: `A choice needing code must be one this option offers, and ${JSON.stringify(choice)} is not — ${option.key} offers ${JSON.stringify(option.choices ?? [])}.`,
+        });
+      }
+    }
     if (option.constant !== undefined && option.default === undefined) {
       ctx.issues.push({
         code: "custom",

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/core";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.1.1";
+export const PACKAGE_VERSION = "0.1.3";