@pithy-sh/core 0.1.0

package/src/workflow/schemas.ts

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

package/src/workflow/spec.ts

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+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>;

package/src/workflow/stepMessage.ts

@@ -0,0 +1,160 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * **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 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 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]+)*): /;
+
+/** 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 function splitWorkflowStepCode(text: string): { code?: string; rest: string } {
+  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.
+ */
+export function encodeWorkflowStepMessage(fields: WorkflowStepMessage): string {
+  const stated = `${fields.code}: ${fields.message}`;
+  const action = fields.action?.trim();
+  if (action === undefined || action === "" || LINE_BREAK.test(action)) return stated;
+  return `${stated}${WORKFLOW_STEP_SEPARATOR}${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.
+ */
+export function decodeWorkflowStepMessage(text: string): WorkflowStepMessage | null {
+  const { code, rest } = splitWorkflowStepCode(text.trim());
+  if (code === undefined) return null;
+
+  const cut = rest.indexOf(WORKFLOW_STEP_SEPARATOR);
+  const message = (cut === -1 ? rest : rest.slice(0, cut)).trim();
+  const action = cut === -1 ? undefined : rest.slice(cut + WORKFLOW_STEP_SEPARATOR.length).trim();
+
+  if (message === "" || message.length > MAX_WORKFLOW_STEP_TEXT || LINE_BREAK.test(message)) return null;
+  if (action === undefined) return { code, message };
+  if (action === "" || action.length > MAX_WORKFLOW_STEP_TEXT || LINE_BREAK.test(action)) return null;
+  return { code, message, action };
+}