@pithy-sh/core 0.10.0 → 0.12.0

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.12.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