@pithy-sh/core 0.7.3 → 0.8.0

package/src/worker/identity.ts

@@ -28,6 +28,16 @@ export const PROJECT_VAR = "PROJECT";
 /** The var naming the environment this deployment serves — `dev`, `staging`, or `prod`. */
 export const ENVIRONMENT_VAR = "ENVIRONMENT";
 
+/**
+ * The var naming where a deployed Worker answers — `https://<host>`, no path, no trailing slash.
+ *
+ * Generated, never hand-set: `pithy worker sync` writes it from a declared domain, and `pithy provision
+ * --feature` writes a feature's from its `workers.dev` address (#643). It is the one statement of a feature's
+ * origin a running Worker can read, because the account's `workers.dev` subdomain is something only the
+ * Cloudflare API knows, and a Worker has no business calling it at module scope.
+ */
+export const BASE_URL_VAR = "BASE_URL";
+
 /**
  * The var carrying a Worker's **own** dev origin, from `pithy dev` to whatever launches that Worker.
  *

package/src/workflow/faults.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { d1TransientFault } from "../data/withD1Retry";
-import { PithyError } from "../error/pithyError";
+import { InternalError, PithyError } from "../error/pithyError";
 import { encodeWorkflowStepMessage } from "./stepMessage";
 
 /**
@@ -153,10 +153,43 @@ export function classifyWorkflowFault(error: unknown, policy: WorkflowRetryPolic
   };
 }
 
-/** The half of a Workflow step this kit uses: run a named body, or serve its journalled result. */
+/**
+ * The half of a Workflow step this kit uses: run a named body, or serve its journalled result.
+ *
+ * **`sleep` is optional here and required on what {@link classifiedSteps} hands back, and the asymmetry
+ * is the truth rather than a convenience.** The platform's own `WorkflowStep` always offers one. What
+ * does not are this kit's hand-written test doubles, which exist to exercise the classification and
+ * nothing else — and demanding a primitive the classifier never classifies would cost every one of them
+ * a line of noise. Handing an optional one back instead would push a null check into the one caller that
+ * genuinely pauses.
+ */
 export interface WorkflowStepLike {
   /** Run a named step, or return its journalled result if this instance already completed it. */
   do<T>(name: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Pause the instance for `durationMs` and resume it afterwards — possibly in a fresh isolate, which
+   * is the whole reason a caller reaches for it rather than for a timer. Absent only on a test double.
+   */
+  sleep?(name: string, durationMs: number): Promise<void>;
+}
+
+/**
+ * A step runner that can pause — what {@link classifiedSteps} hands back, always.
+ *
+ * The durable pause is why this type exists rather than being a convenience over the one above. A `sleep`
+ * is journalled, so a wait survives the instance being evicted during it; a `setTimeout` inside one step
+ * burns that step's wall clock and dies with the instance holding it.
+ *
+ * **It was introduced on a stronger claim, and the claim did not survive contact (pithy-sh/pithy#647).** The
+ * argument was that a Secrets Store binding answers the same for its isolate's whole life, so only a resume
+ * into a fresh isolate could ever see a write land. Measured against a real store on 2026-09-25, that is
+ * false: a binding refreshes inside a live isolate roughly 1.3-1.5s after the REST write, proved by holding
+ * two isolates warm through a write and watching each serve the old value before it and the new one after,
+ * over 328 samples. The durability argument above is the true one and is sufficient on its own.
+ */
+export interface DurableStepLike extends WorkflowStepLike {
+  /** Pause the instance for `durationMs`, then resume. */
+  sleep(name: string, durationMs: number): Promise<void>;
 }
 
 /**
@@ -189,8 +222,8 @@ export function classifiedSteps(
   step: WorkflowStepLike,
   policy: WorkflowRetryPolicy,
   terminalError: TerminalErrorConstructor,
-): WorkflowStepLike {
-  return {
+): DurableStepLike {
+  const runner: DurableStepLike = {
     do<T>(name: string, fn: () => Promise<T>): Promise<T> {
       return step.do(name, async () => {
         try {
@@ -215,5 +248,29 @@ export function classifiedSteps(
         }
       });
     },
+    /**
+     * Forwarded, and deliberately unclassified. A pause raises no fault of the capability's — the
+     * instance either resumes or it is gone — so there is nothing here for a policy to decide.
+     *
+     * A runner that cannot pause is refused, and the refusal is raised **through `do`** rather than
+     * thrown from here. A throw from here is a throw the engine never classifies, so it is free to
+     * re-drive the instance — and re-driving is the unbounded loop the caller is spending its sleeps to
+     * avoid. Going through `do` makes the refusal terminal on its first attempt, like every other
+     * answer that cannot change.
+     */
+    sleep(name: string, durationMs: number): Promise<void> {
+      const pause = step.sleep;
+      if (pause === undefined) {
+        return runner.do<void>(`${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 runner;
 }

package/src/workflow/host.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { InternalError } from "../error/pithyError";
+import type { FeatureIdentity } from "../naming/feature";
 import { ENVIRONMENT_VAR, PROJECT_VAR } from "../worker/identity";
 import { type WorkflowHostNameParts, workflowHostName, workflowScriptName } from "./naming";
 import type { WorkflowRegistry } from "./spec";
@@ -118,6 +119,12 @@ export interface WorkflowHostParams {
   capability: string;
   /** The target environment (`dev` | `staging` | `production`). */
   env: string;
+  /**
+   * The feature this host serves, when it serves one (#643). Its name then takes the feature's head —
+   * `<project>-f<issue>-<slug>-<capability>` — as the Workflows derived with the same parts do; `env` still
+   * says `feature`, and that is what the host's `ENVIRONMENT` var is stamped with.
+   */
+  feature?: FeatureIdentity;
   /** D1 binding name → database id. An unlisted binding keeps the template's id. */
   databaseIds?: Record<string, string>;
   /**
@@ -195,7 +202,12 @@ export function resolveWorkflowHost(template: WorkflowHostTemplate, params: Work
   const resolved = structuredClone(template);
   const remote = new Set(params.remoteBindings ?? []);
 
-  resolved.name = workflowHostName({ project: params.project, capability: params.capability, env: params.env });
+  resolved.name = workflowHostName({
+    project: params.project,
+    capability: params.capability,
+    env: params.env,
+    ...(params.feature ? { feature: params.feature } : {}),
+  });
 
   if (resolved.d1_databases) {
     resolved.d1_databases = resolved.d1_databases.map((entry) => ({
@@ -293,7 +305,7 @@ export function hostWorkflowsFor(
   registry: WorkflowRegistry,
   parts: WorkflowHostNameParts,
 ): { workflows: HostWorkflowBinding[]; crons: string[] } {
-  const { project, capability, env } = parts;
+  const { project, capability, env, feature } = parts;
   const owned = Object.values(registry).filter((entry) => entry.capability === capability);
   const workflows: HostWorkflowBinding[] = [];
   const crons: string[] = [];
@@ -307,7 +319,7 @@ export function hostWorkflowsFor(
     }
     workflows.push({
       binding: entry.spec.binding,
-      name: workflowScriptName({ project, capability, job: entry.job, env }),
+      name: workflowScriptName({ project, capability, job: entry.job, env, ...(feature ? { feature } : {}) }),
       class_name: entry.spec.className,
     });
     if (entry.spec.schedule) crons.push(entry.spec.schedule);

package/src/workflow/naming.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { InternalError } from "../error/pithyError";
+import { type FeatureIdentity, featureWorkerName, featureWorkflowName } from "../naming/feature";
 import { MAX_CAPABILITY_JOB, NAMESPACE_LIMITS } from "../naming/limits";
 import { assertValidProjectName, kebab } from "../naming/resource";
 import { NAME_SEGMENT } from "../naming/segment";
@@ -109,6 +110,21 @@ function head(project: string, env: string): string {
   return `${kebab(project)}-${env}`;
 }
 
+/**
+ * The feature a name is composed for, held to the project the parts name — two projects in one set of parts is
+ * a name composed for somebody else's feature.
+ */
+function featureOf(parts: WorkflowHostNameParts): FeatureIdentity {
+  const feature = parts.feature as FeatureIdentity;
+  if (feature.project !== parts.project) {
+    throw new InternalError({
+      message: "A feature's Workflow name was asked for with two different projects.",
+      detail: `parts name project "${parts.project}" and a feature of project "${feature.project}".`,
+    });
+  }
+  return feature;
+}
+
 /** The identity of a capability's deployment in one environment. */
 export interface WorkflowHostNameParts {
   /** The project name — the root `pithy.config.ts` `name`, resolved by `requireProjectName` and never guessed. */
@@ -117,6 +133,13 @@ export interface WorkflowHostNameParts {
   capability: string;
   /** The deployment environment (e.g. `staging`). */
   env: string;
+  /**
+   * **The feature this deployment is, when it is one (#643).** A feature's host Worker and Workflows take the
+   * feature's head — `<project>-f<issue>-<slug>-…` — not `<project>-feature-…`, which every open branch would
+   * share: Worker and Workflow names are account-wide, so a second branch's deploy would replace the first's.
+   * `env` stays `feature`, which is what the host's `ENVIRONMENT` var says; only the names change.
+   */
+  feature?: FeatureIdentity;
 }
 
 /** The identity of one durable job's Workflow in one environment. */
@@ -139,6 +162,7 @@ export function workflowScriptName(parts: WorkflowScriptNameParts): string {
   assertSegment(parts.capability, "capability");
   assertSegment(parts.job, "job");
   assertCapabilityJob(parts.capability, parts.job);
+  if (parts.feature) return featureWorkflowName(featureOf(parts), parts.capability, parts.job);
   return assertLength(`${head(parts.project, parts.env)}-${parts.capability}-${parts.job}`, MAX_WORKFLOW_NAME_BYTES);
 }
 
@@ -151,6 +175,7 @@ export function workflowScriptName(parts: WorkflowScriptNameParts): string {
  */
 export function workflowHostName(parts: WorkflowHostNameParts): string {
   assertSegment(parts.capability, "capability");
+  if (parts.feature) return featureWorkerName(featureOf(parts), parts.capability);
   return assertLength(`${head(parts.project, parts.env)}-${parts.capability}`, MAX_WORKER_NAME_BYTES);
 }