@pithy-sh/core 0.10.0 → 0.11.0

package/src/naming/feature.ts

@@ -34,11 +34,26 @@ import { assertValidProjectName, kebab } from "./resource";
  * implementation rather than two that drift.
  */
 
-/** A Cloudflare resource kind a feature can provision. All two characters — `MAX_FEATURE_KIND` in `./limits`. */
-export type FeatureResourceKind = "d1" | "kv" | "r2";
+/** A Cloudflare resource kind Pithy names and creates — in a feature, and in every declared environment. */
+export type FeatureResourceKind = "d1" | "kv" | "r2" | "queue";
 
 /** Every feature resource kind, for tests and for callers that enumerate. */
-export const FEATURE_RESOURCE_KINDS: readonly FeatureResourceKind[] = ["d1", "kv", "r2"];
+export const FEATURE_RESOURCE_KINDS: readonly FeatureResourceKind[] = ["d1", "kv", "r2", "queue"];
+
+/**
+ * **The segment each kind ends a feature resource's name with — never more than `MAX_FEATURE_KIND` (#662).**
+ *
+ * `d1`, `kv` and `r2` spell themselves. A queue is `q`, and that is load-bearing: `MAX_FEATURE_KIND` is a term in
+ * `FEATURE_DERIVED_PROJECT_NAME`, so spelling it `queue` would take the project budget from 26 to 23 — and a
+ * project name is stable forever once anything is provisioned, so a smaller budget orphans every resource of a
+ * project already named against the old one. `feature.test.ts` fails on a segment longer than the budget.
+ */
+export const FEATURE_KIND_SEGMENT: Readonly<Record<FeatureResourceKind, string>> = {
+  d1: "d1",
+  kv: "kv",
+  r2: "r2",
+  queue: "q",
+};
 
 /** The identity of a feature — everything a feature name is derived from. */
 export interface FeatureIdentity {
@@ -292,10 +307,11 @@ export function assertFeatureSlugFits(identity: FeatureIdentity, shapes: readonl
 }
 
 /**
- * The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>--<binding>-<kind>`.
+ * The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>--<binding>-<kind>`, the
+ * kind spelled by {@link FEATURE_KIND_SEGMENT}.
  *
- * Held to **R2's 63**, the strictest of the three kinds a feature provisions, so one shape is legal for
- * all of them: lowercase, hyphenated, alphanumeric at both ends. A D1 or KV name could be longer, but a
+ * Held to **R2's 63**, the strictest of the kinds a feature provisions and a queue's number too, so one shape is
+ * legal for all of them: lowercase, hyphenated, alphanumeric at both ends. A D1 or KV name could be longer, but a
  * feature that provisions a bucket and a database wants them recognizably the same name.
  */
 export function featureResourceName(identity: FeatureIdentity, binding: string, kind: FeatureResourceKind): string {
@@ -303,7 +319,7 @@ export function featureResourceName(identity: FeatureIdentity, binding: string,
     identity,
     kebab(identity.slug),
     kebab(binding),
-    `-${kind}`,
+    `-${FEATURE_KIND_SEGMENT[kind]}`,
     NAMESPACE_LIMITS.r2.maxLength,
     NAMESPACE_LIMITS.r2.label,
   );
@@ -364,6 +380,29 @@ export function featureWorkerName(identity: FeatureIdentity, app: string): strin
   );
 }
 
+/** The `<thing>` a feature's Artifacts namespace ends with, after {@link FEATURE_TAIL_SEPARATOR} (#673). */
+export const FEATURE_ARTIFACTS_THING = "artifacts";
+
+/**
+ * A feature's **Artifacts namespace** — `<project>-f<issue>-<slug>--artifacts` (#673).
+ *
+ * A declared environment's namespace is `<project>-<env>` and has no `<thing>`. A feature's needs one, because the
+ * separator and what follows it are what make a name a feature name: {@link isFeatureOwnedName} reads this one back
+ * as this feature's, so `pithy feature destroy` reaps the repos of exactly this branch and of no sibling. Held to the
+ * namespace's 63, the same number the rest of a feature's names are derived against, and `artifacts` is shorter than
+ * the shortest binding tail, so it moves no slug budget.
+ */
+export function featureArtifactsNamespace(identity: FeatureIdentity): string {
+  return composeFeatureName(
+    identity,
+    kebab(identity.slug),
+    FEATURE_ARTIFACTS_THING,
+    "",
+    NAMESPACE_LIMITS.artifactsNamespace.maxLength,
+    NAMESPACE_LIMITS.artifactsNamespace.label,
+  );
+}
+
 /**
  * The deployed name of one of a feature's **Workflows** — `<project>-f<issue>-<slug>--<capability>-<job>` (#643).
  *

package/src/naming/limits.ts

@@ -107,6 +107,35 @@ export const NAMESPACE_LIMITS = {
    * no longer hashes one at 63.
    */
   kv: { label: "a KV namespace title", maxLength: 512, minLength: 1, policy: "truncate", source: "cloudflare" },
+  /**
+   * A Queue name: **1 to 63 characters**, lowercase letters, digits and dashes, starting and ending with a letter
+   * or number ([Queues · Get started](https://developers.cloudflare.com/queues/get-started/), verified
+   * 2026-10-18). Truncated rather than refused: Pithy recomputes a queue's name from its binding on every run,
+   * as it does a bucket's, so a deterministic hash is safe (#662). The same 63 as R2, so a feature's queue fits
+   * the shape {@link FEATURE_DERIVED_PROJECT_NAME} is derived against and moves no budget.
+   */
+  queue: { label: "a Queue name", maxLength: 63, minLength: 1, policy: "truncate", source: "cloudflare" },
+  /**
+   * An Artifacts namespace: **2 to 63 characters**, starting with a letter or digit, the rest letters, digits, `.`,
+   * `_` and `-` ([Artifacts · Limits](https://developers.cloudflare.com/artifacts/platform/limits/), verified
+   * 2026-10-18). Truncated rather than refused: the kit derives it from the project and the environment on every
+   * run, like an R2 bucket name, and the longest project and environment compose 34 characters, so it never is (#673).
+   */
+  artifactsNamespace: {
+    label: "an Artifacts namespace name",
+    maxLength: 63,
+    minLength: 2,
+    policy: "truncate",
+    source: "cloudflare",
+  },
+  /**
+   * An Artifacts repo name. **The charset is Cloudflare's** — a letter or digit, then letters, digits, `.`, `_` and
+   * `-` ([Artifacts · Limits](https://developers.cloudflare.com/artifacts/platform/limits/), verified 2026-10-18) —
+   * and **the length is ours**: that page states one for a namespace and none for a repo, so 2 to 63 mirrors the
+   * namespace rather than inventing a second number. Refused, never truncated: a repo name is either a UUID or a
+   * name somebody chose, and a name somebody chose is never silently shortened (#673).
+   */
+  artifactsRepo: { label: "an Artifacts repo name", maxLength: 63, minLength: 2, policy: "refuse", source: "pithy" },
   /**
    * A D1 database name: `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` in the OpenAPI schema, and **no documented
    * length cap** — the limits page has no row for it. So the ceiling here is {@link MAX_PITHY_NAME}.
@@ -196,7 +225,10 @@ export const FEATURE_TAIL_SEPARATOR = "--";
  */
 export const MIN_VERBATIM_BINDING = 12;
 
-/** The longest feature resource kind — `d1`, `kv`, `r2` are all two characters. `feature.test.ts` pins it. */
+/**
+ * The longest feature resource kind segment — `d1`, `kv`, `r2`, and a queue's `q` (#662). `feature.test.ts` pins
+ * every kind's `FEATURE_KIND_SEGMENT` to it, so a longer segment fails rather than shrinking every project's budget.
+ */
 export const MAX_FEATURE_KIND = 2;
 
 /**
@@ -217,7 +249,7 @@ export const WORKFLOW_DERIVED_PROJECT_NAME =
 
 /**
  * What the longest feature resource name leaves a project — `<project>-f<issue>-<slug>--<binding>-<kind>`,
- * against R2's 63 (the strictest of the three kinds a feature provisions, and the same number a
+ * against R2's 63 (the strictest of the kinds a feature provisions, a queue's number too, and the same number a
  * feature Worker script gets).
  *
  * ```
@@ -226,7 +258,7 @@ export const WORKFLOW_DERIVED_PROJECT_NAME =
  *   -  6   the issue number, six digits — `f999999` (MAX_ISSUE_DIGITS)
  *   - 12   `-` + a legible slug (MIN_LEGIBLE_SLUG)
  *   - 14   `--` + a binding kept whole (FEATURE_TAIL_SEPARATOR, MIN_VERBATIM_BINDING)
- *   -  3   `-` + the kind, `d1` | `kv` | `r2`
+ *   -  3   `-` + the kind, `d1` | `kv` | `r2` | `q`
  *   ----
  *     26
  * ```

package/src/naming/provisionScope.ts

@@ -8,6 +8,7 @@ import { assertValidEnvironment, FEATURE_ENVIRONMENT, GLOBAL_SCOPE, isFeatureMar
 import {
   type FeatureIdentity,
   type FeatureResourceKind,
+  featureArtifactsNamespace,
   featureResourceName,
   featureSecretEntryName,
   featureWorkerName,
@@ -189,10 +190,21 @@ export interface ProvisionScope {
    * `<project>-feature-email-send` would be one Workflow every open branch deployed over every other's.
    */
   readonly workflowHost: Omit<WorkflowHostNameParts, "capability">;
+  /**
+   * The Artifacts namespace an `artifacts` binding names in this scope (#673): `<project>-<env>` in a declared
+   * environment, `<project>-f<issue>-<slug>--artifacts` in a feature. On the scope for the reason every other name
+   * is: the stanza a run writes and the namespace it writes into it are one decision.
+   */
+  readonly artifactsNamespace: string;
 }
 
 /** The wrangler binding array a resource kind's name is composed for. */
-const KIND_NAMER: Record<FeatureResourceKind, "d1" | "kv" | "r2"> = { d1: "d1", kv: "kv", r2: "r2" };
+const KIND_NAMER: Record<FeatureResourceKind, "d1" | "kv" | "r2" | "queue"> = {
+  d1: "d1",
+  kv: "kv",
+  r2: "r2",
+  queue: "queue",
+};
 
 /**
  * The one branch every scope shares: a `global` secret resolves to the project's single
@@ -345,6 +357,7 @@ export function environmentScope(project: string, environment: string): Provisio
     secretEntry: (secret, secretScope) =>
       secretEntryName(project, secret, secretScope, () => names.secretEntry(secret)),
     workflowHost: { project, env: environment },
+    artifactsNamespace: names.artifactsNamespace(),
   };
 }
 
@@ -392,6 +405,11 @@ export function featureScope(identity: FeatureIdentity): ProvisionScope {
     secretEntry: (secret) => featureSecretEntryName(identity, secret),
     // `env` is the stanza — what the host's `ENVIRONMENT` var says — and `feature` is what its names take.
     workflowHost: { project: identity.project, env: FEATURE_ENVIRONMENT, feature: identity },
+    // The feature's own, read back as its own by `isFeatureOwnedName`, so teardown reaps no sibling's repos. A
+    // getter, so a slug too long for it refuses where the namespace is asked for, never where the scope is made.
+    get artifactsNamespace() {
+      return featureArtifactsNamespace(identity);
+    },
   };
 }
 

package/src/naming/resourceNames.ts

@@ -4,7 +4,13 @@
 import { InternalError, ValidationError } from "../error/pithyError";
 import { workflowHostName, workflowScriptName } from "../workflow/naming";
 import { assertValidEnvironment, GLOBAL_SCOPE } from "./environment";
-import { type FeatureIdentity, type FeatureResourceKind, featureResourceName, featureWorkerName } from "./feature";
+import {
+  type FeatureIdentity,
+  type FeatureResourceKind,
+  featureArtifactsNamespace,
+  featureResourceName,
+  featureWorkerName,
+} from "./feature";
 import { NAMESPACE_LIMITS, type NamespaceLimit } from "./limits";
 import { assertValidProjectName, kebab, resourceName } from "./resource";
 
@@ -57,6 +63,8 @@ export interface ScopedNames {
   kv(binding: string): string;
   /** An R2 bucket. Cloudflare's 63 — the one namespace where that number was always right. */
   r2(binding: string): string;
+  /** A Queue. Cloudflare's 63, truncated with a stable hash like a bucket (#662). */
+  queue(binding: string): string;
   /** A Vectorize index. 64 bytes, refused rather than truncated: a renamed index has no vectors. */
   vectorizeIndex(index: string): string;
   /** A Secrets Store entry. No Cloudflare cap; Pithy's ceiling. */
@@ -65,15 +73,33 @@ export interface ScopedNames {
   apiToken(profile: string): string;
 }
 
+/**
+ * The names in one declared environment: everything a scope has, and the one name that exists per environment
+ * and never at `global`.
+ */
+export interface EnvironmentNames extends ScopedNames {
+  /**
+   * The Artifacts namespace — `<project>-<env>`, with no `<thing>` (#673). One per environment, so a feature's
+   * repos never sit beside production's and the per-namespace rate limit splits per environment. There is no
+   * global one, because a namespace shared across environments is exactly that mix.
+   */
+  artifactsNamespace(): string;
+}
+
 /** The names a feature environment provisions under, with the project already bound. */
 export interface FeatureNames {
-  /** A feature's D1, KV, or R2 resource — `<project>-f<issue>-<slug>-<binding>-<kind>`. */
+  /** A feature's D1, KV, R2 or Queue resource — `<project>-f<issue>-<slug>--<binding>-<kind>`. */
   resource(binding: string, kind: FeatureResourceKind): string;
   /**
    * A feature's Worker script — `<project>-f<issue>-<slug>-<app>`, from the `apps/<app>` directory and
    * never the deploy name, which already leads with the project (#587).
    */
   worker(app: string): string;
+  /**
+   * A feature's Artifacts namespace — `<project>-f<issue>-<slug>--artifacts` (#673). The tail is what makes it a
+   * feature name `isFeatureOwnedName` reads back, so teardown reaps this feature's repos and no sibling's.
+   */
+  artifactsNamespace(): string;
 }
 
 /** Everything a project can be asked to name. Created once, from the project, by {@link resourceNames}. */
@@ -81,7 +107,7 @@ export interface ProjectNames {
   /** The kebabbed project name every name below leads with. */
   readonly project: string;
   /** The names in one environment. Throws if the environment is not one this scheme accepts. */
-  env(environment: string): ScopedNames;
+  env(environment: string): EnvironmentNames;
   /** The names shared by every environment — the `global` scope, without typing the word. */
   readonly global: ScopedNames;
   /** The names a feature environment provisions under. */
@@ -134,6 +160,22 @@ function scopedName(project: string, scope: string, thing: string, limit: Namesp
   return name;
 }
 
+/**
+ * `<project>-<env>`, under the Artifacts namespace rule. The project and environment are both validated by now, and
+ * the longest of each compose 34 characters, so the cap is a check rather than a truncation that ever happens.
+ */
+function artifactsNamespaceName(project: string, environment: string): string {
+  const limit = NAMESPACE_LIMITS.artifactsNamespace;
+  const name = `${project}-${environment}`;
+  if (name.length > limit.maxLength || name.length < limit.minLength) {
+    throw new InternalError({
+      message: `"${name}" does not fit ${limit.label}, which takes ${limit.minLength} to ${limit.maxLength} characters.`,
+      action: "Shorten the project or environment name.",
+    });
+  }
+  return name;
+}
+
 /** The getters for one scope. `global` and every environment share this, so nothing special-cases either. */
 function scopedNames(project: string, scope: string): ScopedNames {
   return {
@@ -142,6 +184,7 @@ function scopedNames(project: string, scope: string): ScopedNames {
     d1: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.d1),
     kv: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.kv),
     r2: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.r2),
+    queue: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.queue),
     vectorizeIndex: (index) => scopedName(project, scope, index, NAMESPACE_LIMITS.vectorizeIndex),
     secretEntry: (secret) => scopedName(project, scope, secret, NAMESPACE_LIMITS.secretEntry),
     apiToken: (profile) => scopedName(project, scope, profile, NAMESPACE_LIMITS.apiToken),
@@ -161,9 +204,12 @@ export function resourceNames(project: string): ProjectNames {
 
   return {
     project: normalized,
-    env(environment: string): ScopedNames {
+    env(environment: string): EnvironmentNames {
       assertValidEnvironment(environment);
-      return scopedNames(normalized, environment);
+      return {
+        ...scopedNames(normalized, environment),
+        artifactsNamespace: () => artifactsNamespaceName(normalized, environment),
+      };
     },
     global: scopedNames(normalized, GLOBAL_SCOPE),
     feature(identity): FeatureNames {
@@ -171,6 +217,7 @@ export function resourceNames(project: string): ProjectNames {
       return {
         resource: (binding, kind) => featureResourceName(full, binding, kind),
         worker: (app) => featureWorkerName(full, app),
+        artifactsNamespace: () => featureArtifactsNamespace(full),
       };
     },
   };

package/src/seed/writeD1.ts

@@ -17,8 +17,14 @@ export interface SeedD1Options {
 export interface SeedD1Result {
   /** The table seeded. */
   table: string;
-  /** The number of rows validated (and, unless `dryRun`, written). */
+  /** The number of rows the fixture holds, every one validated. */
   rows: number;
+  /**
+   * The number of rows this call inserted. Under `INSERT OR IGNORE` a row whose key is already there is
+   * not, so a re-run writes none, and says so here rather than repeating `rows` (#764). Always `0` under
+   * `dryRun`.
+   */
+  written: number;
 }
 
 /**
@@ -89,15 +95,18 @@ export async function seedD1Group(
   });
 
   if (options.dryRun || encoded.length === 0) {
-    return { table: group.table, rows: encoded.length };
+    return { table: group.table, rows: encoded.length, written: 0 };
   }
 
+  let written = 0n;
   for (const chunk of chunkRowsByBoundParameters(encoded, columnsPerRow(encoded))) {
-    await db
+    const results = await db
       .insertInto(group.table)
       .orIgnore()
       .values(chunk as never)
       .execute();
+    // D1's `meta.changes`: the rows the statement inserted, which an ignored conflict is not.
+    for (const result of results) written += result.numInsertedOrUpdatedRows ?? 0n;
   }
-  return { table: group.table, rows: encoded.length };
+  return { table: group.table, rows: encoded.length, written: Number(written) };
 }

package/src/seed/writeKv.ts

@@ -19,6 +19,8 @@ export interface SeedKvResult {
   store: string;
   /** The number of entries validated (and, unless `dryRun`, considered for writing). */
   entries: number;
+  /** The number of entries this call put. An existing key is left alone and not counted (#764). Always `0` under `dryRun`. */
+  written: number;
 }
 
 /**
@@ -87,13 +89,15 @@ export async function seedKvGroup<V extends z.ZodType, K extends z.ZodObject, M
   });
 
   if (options.dryRun) {
-    return { store: group.store, entries: group.entries.length };
+    return { store: group.store, entries: group.entries.length, written: 0 };
   }
 
+  let written = 0;
   for (const entry of group.entries) {
     // Never overwrite an existing key — the KV counterpart of D1's INSERT OR IGNORE.
     if (await keyExists(store, entry.key)) continue;
     await store.put(entry.key, entry.value, entry.metadata !== undefined ? { metadata: entry.metadata } : {});
+    written += 1;
   }
-  return { store: group.store, entries: group.entries.length };
+  return { store: group.store, entries: group.entries.length, written };
 }

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.10.0";
+export const PACKAGE_VERSION = "0.11.0";

package/src/worker/serviceLoopback.ts

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { commandName } from "../cli/command";
+import { UpstreamError } from "../error/pithyError";
+import { ENVIRONMENT_VAR } from "./identity";
+
+/**
+ * **A service binding under `pithy dev`: the call reaches the local target on its pinned port (#617).**
+ *
+ * Deployed, `env.APP_B.fetch(request)` is a service binding: Cloudflare runs the call inside the runtime, into
+ * the script the binding names. Locally there is no such script. `wrangler dev` would look for one in its own
+ * cross-process registry — the one `pithy dev` never relies on — and a Worker started on its own with
+ * `pithy dev --app app-a` would find nothing there at all. What does exist is the target itself, on the port its
+ * feature pinned for it, and `pithy dev` knows that address before anything starts.
+ *
+ * So `pithy dev` publishes one var, {@link SERVICE_ORIGINS_VAR}: a JSON map from each service binding this
+ * Worker declares to its target's local origin. Under `dev`, and only there, each of those bindings is replaced
+ * with a stand-in whose `fetch` sends the same request to that origin. The call site is byte-identical either
+ * way. A target that is not running refuses the connection, so the call fails at once as
+ * `core/upstream_failed`, naming the binding and the address, rather than hanging on a registry lookup.
+ *
+ * **Only `dev`, and only what was published.** The var is written by `pithy dev` and by nothing else, and the
+ * gate reads `ENVIRONMENT` off the request env as the Workflow loopback does (`workflow/dispatch.ts`): a
+ * deployment that lost its `ENVIRONMENT` var never opens it.
+ */
+
+/** The var `pithy dev` publishes: each service binding's local target, as JSON. */
+export const SERVICE_ORIGINS_VAR = "PITHY_SERVICE_ORIGINS";
+
+/** The one environment the stand-in is made in. */
+const LOCAL = "dev";
+
+/** What the var carries: binding name to an `http(s)` origin. */
+const ServiceOrigins = z
+  .record(
+    z.string().describe("A service binding's name in the Worker env."),
+    z.url({ protocol: /^https?$/ }).describe("The local origin of the Worker it calls, as `pithy dev` pinned it."),
+  )
+  .describe("Each service binding's local target, published by `pithy dev`.");
+
+/** The transport. The runtime's `fetch`, or a test's. */
+export type ServiceLoopbackFetch = (request: Request) => Promise<Response>;
+
+/** A Fetcher's one method that a plain `fetch` target uses. */
+interface LocalService {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+
+/** A stand-in for one service binding: every request sent to `origin`, its path, method, headers and body kept. */
+function localService(binding: string, origin: string, send: ServiceLoopbackFetch): LocalService {
+  const target = new URL(origin);
+  return {
+    async fetch(input, init) {
+      const request = new Request(input, init);
+      const url = new URL(request.url);
+      url.protocol = target.protocol;
+      url.host = target.host;
+      try {
+        return await send(new Request(url, request));
+      } catch (cause) {
+        throw new UpstreamError(
+          {
+            message: `The Worker ${binding} calls is not answering.`,
+            action: `Check that it is running under ${commandName("dev")} at ${target.origin}.`,
+            detail: `${request.method} ${url.href} failed: ${String(cause)}`,
+          },
+          { cause },
+        );
+      }
+    },
+  };
+}
+
+/** Options for {@link withLocalServices}. */
+export interface LocalServicesOptions {
+  /** The transport. Defaults to the runtime's `fetch`. */
+  fetch?: ServiceLoopbackFetch;
+}
+
+/**
+ * The env a request runs with: under `pithy dev`, each published service binding replaced with its local
+ * stand-in; anywhere else, the env unchanged — the same object, so nothing outside `dev` pays for this.
+ */
+export function withLocalServices(
+  env: Record<string, unknown>,
+  options: LocalServicesOptions = {},
+): Record<string, unknown> {
+  if (env[ENVIRONMENT_VAR] !== LOCAL) return env;
+  const published = env[SERVICE_ORIGINS_VAR];
+  if (typeof published !== "string") return env;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(published);
+  } catch {
+    return env;
+  }
+  const origins = ServiceOrigins.safeParse(parsed);
+  if (!origins.success || Object.keys(origins.data).length === 0) return env;
+  const send = options.fetch ?? ((request: Request) => fetch(request));
+  const local: Record<string, unknown> = { ...env };
+  for (const [binding, origin] of Object.entries(origins.data)) local[binding] = localService(binding, origin, send);
+  return local;
+}

package/src/workflow/faults.ts

@@ -192,6 +192,27 @@ export interface DurableStepLike extends WorkflowStepLike {
   sleep(name: string, durationMs: number): Promise<void>;
 }
 
+/**
+ * The platform step's configured `do`: a retry policy ahead of the body. Every `WorkflowStep` has it; a
+ * test double that only takes two arguments does not, which is why {@link ClassifiedSteps.once} is the one
+ * place it is reached for.
+ */
+interface ConfiguredStepLike {
+  do<T>(name: string, config: { retries: { limit: number; delay: number } }, fn: () => Promise<T>): Promise<T>;
+}
+
+/** What {@link classifiedSteps} hands back: a pausing runner, and a step that runs exactly once. */
+export interface ClassifiedSteps extends DurableStepLike {
+  /**
+   * Run a named step with **no retries**, still classified (pithy-sh/pithy#602).
+   *
+   * For a body that mutates somebody else's system — a provider roll — where a platform re-running the
+   * step after an eviction would do it twice. The classification still decides what the instance's
+   * failure says; it can no longer decide on a retry, because there is none to give.
+   */
+  once<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+
 /**
  * The platform's terminal-error class — `NonRetryableError` from `cloudflare:workflows`, taken as a
  * parameter.
@@ -222,31 +243,37 @@ export function classifiedSteps(
   step: WorkflowStepLike,
   policy: WorkflowRetryPolicy,
   terminalError: TerminalErrorConstructor,
-): DurableStepLike {
-  const runner: DurableStepLike = {
+): ClassifiedSteps {
+  const classify =
+    <T>(fn: () => Promise<T>) =>
+    async (): Promise<T> => {
+      try {
+        return await fn();
+      } catch (error) {
+        const fault = classifyWorkflowFault(error, policy);
+        if (fault.disposition === "retry") throw error;
+        // The one sanctioned non-`PithyError` throw in the kit: a platform contract, at the durable
+        // boundary, carrying the `PithyError` it replaced as its `cause` so nothing is lost in this
+        // process. Across the boundary the text is the whole channel — the engine records it and
+        // discards the throw — so what an operator is owed is encoded into it, at one stated site,
+        // and read back at one (./stepMessage). The `cause` does not travel; `detail` never did.
+        const terminal = new terminalError(
+          encodeWorkflowStepMessage({
+            code: fault.code,
+            message: messageOf(error),
+            action: pithyActionOf(error),
+          }),
+        );
+        terminal.cause = error;
+        throw terminal;
+      }
+    };
+  const runner: ClassifiedSteps = {
     do<T>(name: string, fn: () => Promise<T>): Promise<T> {
-      return step.do(name, async () => {
-        try {
-          return await fn();
-        } catch (error) {
-          const fault = classifyWorkflowFault(error, policy);
-          if (fault.disposition === "retry") throw error;
-          // The one sanctioned non-`PithyError` throw in the kit: a platform contract, at the durable
-          // boundary, carrying the `PithyError` it replaced as its `cause` so nothing is lost in this
-          // process. Across the boundary the text is the whole channel — the engine records it and
-          // discards the throw — so what an operator is owed is encoded into it, at one stated site,
-          // and read back at one (./stepMessage). The `cause` does not travel; `detail` never did.
-          const terminal = new terminalError(
-            encodeWorkflowStepMessage({
-              code: fault.code,
-              message: messageOf(error),
-              action: pithyActionOf(error),
-            }),
-          );
-          terminal.cause = error;
-          throw terminal;
-        }
-      });
+      return step.do(name, classify(fn));
+    },
+    once<T>(name: string, fn: () => Promise<T>): Promise<T> {
+      return (step as unknown as ConfiguredStepLike).do(name, { retries: { limit: 0, delay: 0 } }, classify(fn));
     },
     /**
      * Forwarded, and deliberately unclassified. A pause raises no fault of the capability's — the