@pithy-sh/core 0.10.0 → 0.12.0

package/dist/seed/writeD1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeD1.d.ts","sourceRoot":"","sources":["../../src/seed/writeD1.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,WAAW,CAE/B,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,EACf,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA4BvB"}
+{"version":3,"file":"writeD1.d.ts","sourceRoot":"","sources":["../../src/seed/writeD1.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,WAAW,CAE/B,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,EACf,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA+BvB"}

package/dist/seed/writeD1.js

@@ -63,12 +63,18 @@ async function seedD1Group(db, group, schema, options = {}) {
 	});
 	if (options.dryRun || encoded.length === 0) return {
 		table: group.table,
-		rows: encoded.length
+		rows: encoded.length,
+		written: 0
 	};
-	for (const chunk of chunkRowsByBoundParameters(encoded, columnsPerRow(encoded))) await db.insertInto(group.table).orIgnore().values(chunk).execute();
+	let written = 0n;
+	for (const chunk of chunkRowsByBoundParameters(encoded, columnsPerRow(encoded))) {
+		const results = await db.insertInto(group.table).orIgnore().values(chunk).execute();
+		for (const result of results) written += result.numInsertedOrUpdatedRows ?? 0n;
+	}
 	return {
 		table: group.table,
-		rows: encoded.length
+		rows: encoded.length,
+		written: Number(written)
 	};
 }
 //#endregion

package/dist/seed/writeKv.d.ts

@@ -15,6 +15,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;
 }
 /**
  * Seed one KV group, idempotently and non-destructively.

package/dist/seed/writeKv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeKv.d.ts","sourceRoot":"","sources":["../../src/seed/writeKv.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;CACjB;AA4CD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO,EAC/F,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACvB,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC3B,IAAI,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAiBvB"}
+{"version":3,"file":"writeKv.d.ts","sourceRoot":"","sources":["../../src/seed/writeKv.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,4HAA4H;IAC5H,OAAO,EAAE,MAAM,CAAC;CACjB;AA4CD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO,EAC/F,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACvB,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC3B,IAAI,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAmBvB"}

package/dist/seed/writeKv.js

@@ -50,15 +50,19 @@ async function seedKvGroup(store, group, spec, options = {}) {
 	});
 	if (options.dryRun) return {
 		store: group.store,
-		entries: group.entries.length
+		entries: group.entries.length,
+		written: 0
 	};
+	let written = 0;
 	for (const entry of group.entries) {
 		if (await keyExists(store, entry.key)) continue;
 		await store.put(entry.key, entry.value, entry.metadata !== void 0 ? { metadata: entry.metadata } : {});
+		written += 1;
 	}
 	return {
 		store: group.store,
-		entries: group.entries.length
+		entries: group.entries.length,
+		written
 	};
 }
 //#endregion

package/dist/version.generated.d.ts

@@ -3,5 +3,5 @@
 /** This package's npm name — the join key against a release feed. */
 export declare const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-export declare const PACKAGE_VERSION = "0.10.0";
+export declare const PACKAGE_VERSION = "0.12.0";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -4,6 +4,6 @@
 /** This package's npm name — the join key against a release feed. */
 const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-const PACKAGE_VERSION = "0.10.0";
+const PACKAGE_VERSION = "0.12.0";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/worker/serviceLoopback.d.ts

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * **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 declare const SERVICE_ORIGINS_VAR = "PITHY_SERVICE_ORIGINS";
+/** The transport. The runtime's `fetch`, or a test's. */
+export type ServiceLoopbackFetch = (request: Request) => Promise<Response>;
+/** 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 declare function withLocalServices(env: Record<string, unknown>, options?: LocalServicesOptions): Record<string, unknown>;
+//# sourceMappingURL=serviceLoopback.d.ts.map

package/dist/worker/serviceLoopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceLoopback.d.ts","sourceRoot":"","sources":["../../src/worker/serviceLoopback.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAa3D,yDAAyD;AACzD,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAgC3E,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBzB"}

package/dist/worker/serviceLoopback.js

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { UpstreamError } from "../error/pithyError.js";
+import { commandName } from "../cli/command.js";
+import "./identity.js";
+import { z } from "zod";
+//#region src/worker/serviceLoopback.ts
+/**
+* **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. */
+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`.");
+/** A stand-in for one service binding: every request sent to `origin`, its path, method, headers and body kept. */
+function localService(binding, origin, send) {
+	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 });
+		}
+	} };
+}
+/**
+* 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.
+*/
+function withLocalServices(env, options = {}) {
+	if (env["ENVIRONMENT"] !== LOCAL) return env;
+	const published = env[SERVICE_ORIGINS_VAR];
+	if (typeof published !== "string") return env;
+	let parsed;
+	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) => fetch(request));
+	const local = { ...env };
+	for (const [binding, origin] of Object.entries(origins.data)) local[binding] = localService(binding, origin, send);
+	return local;
+}
+//#endregion
+export { SERVICE_ORIGINS_VAR, withLocalServices };

package/dist/workflow/faults.d.ts

@@ -102,6 +102,17 @@ export interface DurableStepLike extends WorkflowStepLike {
     /** Pause the instance for `durationMs`, then resume. */
     sleep(name: string, durationMs: number): Promise<void>;
 }
+/** 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.
@@ -127,5 +138,5 @@ export interface TerminalErrorConstructor {
  * `runSendBatch`, `runAtRestKeyRotation`) takes this instead with no change: the classification is
  * declared once, at the entrypoint, and every step below it inherits the decision.
  */
-export declare function classifiedSteps(step: WorkflowStepLike, policy: WorkflowRetryPolicy, terminalError: TerminalErrorConstructor): DurableStepLike;
+export declare function classifiedSteps(step: WorkflowStepLike, policy: WorkflowRetryPolicy, terminalError: TerminalErrorConstructor): ClassifiedSteps;
 //# sourceMappingURL=faults.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"faults.d.ts","sourceRoot":"","sources":["../../src/workflow/faults.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,UAAU,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,iHAAiH;IACjH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,WAAW,EAAE,wBAAwB,CAAC;IACtC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB;AAsDD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA0BhG;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD;;;OAGG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,wDAAwD;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,mBAAmB,EAC3B,aAAa,EAAE,wBAAwB,GACtC,eAAe,CAqDjB"}
+{"version":3,"file":"faults.d.ts","sourceRoot":"","sources":["../../src/workflow/faults.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2FAA2F;AAC3F,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,UAAU,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,iHAAiH;IACjH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,WAAW,EAAE,wBAAwB,CAAC;IACtC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB;AAsDD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA0BhG;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD;;;OAGG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,wDAAwD;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAWD,oGAAoG;AACpG,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD;;;;;;OAMG;IACH,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,mBAAmB,EAC3B,aAAa,EAAE,wBAAwB,GACtC,eAAe,CA2DjB"}

package/dist/workflow/faults.js

@@ -91,23 +91,30 @@ function classifyWorkflowFault(error, policy) {
 * declared once, at the entrypoint, and every step below it inherits the decision.
 */
 function classifiedSteps(step, policy, terminalError) {
+	const classify = (fn) => async () => {
+		try {
+			return await fn();
+		} catch (error) {
+			const fault = classifyWorkflowFault(error, policy);
+			if (fault.disposition === "retry") throw error;
+			const terminal = new terminalError(encodeWorkflowStepMessage({
+				code: fault.code,
+				message: messageOf(error),
+				action: pithyActionOf(error)
+			}));
+			terminal.cause = error;
+			throw terminal;
+		}
+	};
 	const runner = {
 		do(name, fn) {
-			return step.do(name, async () => {
-				try {
-					return await fn();
-				} catch (error) {
-					const fault = classifyWorkflowFault(error, policy);
-					if (fault.disposition === "retry") throw error;
-					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(name, fn) {
+			return step.do(name, { retries: {
+				limit: 0,
+				delay: 0
+			} }, classify(fn));
 		},
 		/**
 		* Forwarded, and deliberately unclassified. A pause raises no fault of the capability's — the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "scripts": {
     "build": "tsdown && tsc -p tsconfig.build.json && bun ../../tooling/build/src/stampDeclarations.ts",
-    "typecheck": "tsc -p tsconfig.json",
+    "typecheck": "bun check -p tsconfig.json",
     "test": "vitest run",
     "test:node": "vitest run --project=node",
     "test:workers": "vitest run --project=workers",

package/src/access/access.ts

@@ -0,0 +1,298 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type RawBuilder, type SqlBool, sql } from "kysely";
+import type { PithyVars } from "../capability/capability";
+import type { ActingOrganization } from "./acting";
+import type { RecordVisibility } from "./visibility";
+
+/**
+ * Who may read a record, and who may change it — the rules media and storage both enforce, and the one
+ * hook an adopter answers to change them.
+ *
+ * ## The rules
+ *
+ * | Level          | Who reads it                                                       |
+ * |----------------|--------------------------------------------------------------------|
+ * | `private`      | The owner, acting for the organization the record was written under. |
+ * | `organization` | Any member of the record's organization, acting for it.            |
+ * | `public`       | Anyone holding the id or URL, signed in or not.                    |
+ *
+ * **Writing** — editing, deleting, changing visibility — is the owner's, acting for the record's
+ * organization, and that of a role holding the capability's manage power (`media:manage`,
+ * `storage:manage`) in the record's organization, so an organization can clean up after somebody who
+ * left. The manage power admits reading too: a record you may delete is a record you may see.
+ *
+ * **The organization is compared as recorded, null included.** A record written with no organization in
+ * force is its owner's while no organization is in force, and nobody's otherwise — not a manager's, since
+ * a power is only ever held *in* an organization. A record with no owner and no organization is the
+ * system's, and no rule reaches it; the hook is the only thing that can.
+ *
+ * ## The hook: allow, deny, or the default
+ *
+ * Asked on every read and every write. **Allow** admits — sharing a record with one person. **Deny**
+ * removes — a legal hold. **Default** is the rules above, and no hook at all is the rules unchanged.
+ * Sharing itself stays the adopter's: their grants, their requests for access, their tables. The hook is
+ * handed the Worker env so it can read them.
+ *
+ * **On a list, a deny filters and a grant does not list.** The rules run in SQL ({@link
+ * readablePredicate}); the hook is asked about each row on the page ({@link keepReadable}) and may only
+ * remove one. A record the hook grants is reached by id, and the adopter lists their own grants from
+ * their own tables.
+ *
+ * **The hook governs the record routes and nothing else.** Duplicate detection and control-plane rollups
+ * keep their non-disclosure rules whatever it answers: a hook that widened a per-subject total would
+ * reopen exactly the disclosure those rules close.
+ */
+
+/** Who is asking: the signed-in person, if any, and the organization they act for, if any. */
+export interface AccessCaller {
+  /** The signed-in user, from `c.var.auth.userId`; `null` for an anonymous caller. */
+  readonly userId: string | null;
+  /** The organization in force, from the acting-organization seam; `null` when none is. */
+  readonly acting: ActingOrganization | null;
+}
+
+/** The fields of a record the rules read. Every capability holding a person's record carries these. */
+export interface AccessRecord {
+  /** The record's id — handed to the hook so it can look up a grant. */
+  readonly id: string;
+  /** The user who owns it, or `null` for a system-owned record. */
+  readonly ownerId: string | null;
+  /** The organization in force when it was written, or `null` when none was. */
+  readonly organizationId: string | null;
+  /** Who may read it. */
+  readonly visibility: RecordVisibility;
+}
+
+/** What the hook is asked about. Reading, or changing — editing, deleting, changing visibility. */
+export type AccessAction = "read" | "write";
+
+/** The hook's answer. `default` defers to the rules. */
+export type PermissionDecision = "allow" | "deny" | "default";
+
+/** Everything the hook is told. */
+export interface PermissionRequest {
+  /** What the caller is trying to do. */
+  readonly action: AccessAction;
+  /** Which capability holds the record — `media` or `storage` — so one hook can serve both. */
+  readonly capability: string;
+  /** The record, as the rules see it. */
+  readonly record: AccessRecord;
+  /** Who is asking, as ids. */
+  readonly caller: { readonly userId: string | null; readonly organizationId: string | null };
+  /** The Worker env, so the hook can read the adopter's own grant tables through their own bindings. */
+  readonly env: Record<string, unknown>;
+}
+
+/** The one hook an adopter supplies. May be async — a grant lives in a table. */
+export type PermissionHook = (request: PermissionRequest) => PermissionDecision | Promise<PermissionDecision>;
+
+/** What a caller may do with one record. */
+export type AccessLevel = "none" | "read" | "write";
+
+/** The organization a caller acts for, as an id. */
+function organizationOf(caller: AccessCaller): string | null {
+  return caller.acting?.organizationId ?? null;
+}
+
+/** Whether the caller acts for the organization the record was written under — null matching null. */
+function actsForRecord(record: AccessRecord, caller: AccessCaller): boolean {
+  return record.organizationId === organizationOf(caller);
+}
+
+/** Whether the caller is the record's owner, acting for the record's organization. */
+function isActingOwner(record: AccessRecord, caller: AccessCaller): boolean {
+  return caller.userId !== null && record.ownerId === caller.userId && actsForRecord(record, caller);
+}
+
+/** Whether the caller holds the manage power in the record's organization. Never for a null organization. */
+function managesRecord(record: AccessRecord, caller: AccessCaller, managePower: string): boolean {
+  return (
+    caller.userId !== null &&
+    record.organizationId !== null &&
+    caller.acting !== null &&
+    caller.acting.organizationId === record.organizationId &&
+    caller.acting.roleAllows(managePower)
+  );
+}
+
+/** The rules alone, with no hook — what `default` means. */
+export function defaultAllows(
+  action: AccessAction,
+  record: AccessRecord,
+  caller: AccessCaller,
+  managePower: string,
+): boolean {
+  if (isActingOwner(record, caller) || managesRecord(record, caller, managePower)) return true;
+  if (action === "write") return false;
+  switch (record.visibility) {
+    case "public":
+      return true;
+    case "organization":
+      return caller.userId !== null && record.organizationId !== null && actsForRecord(record, caller);
+    case "private":
+      return false;
+  }
+}
+
+/** A record's owner and organization, as one reader may be told them. */
+export interface DisclosedTenancy {
+  readonly ownerId: string | null;
+  readonly organizationId: string | null;
+}
+
+/**
+ * Who holds a record, as this reader may learn it: the owner and organization when the reader is signed in
+ * and acts for the record's organization (none matching none), and neither otherwise.
+ *
+ * **Reading a record is not learning who holds it.** A public record is anyone's to read, but its owner's
+ * id beside its organization's id says that person belongs to that organization — and a list with
+ * `includePublic=true` reaches public records in every organization. An organization never learns that one
+ * of its people holds an account in another, so a record read from outside its organization, or by nobody
+ * in particular, names neither. Making a file public is a choice about the file, not about its owner.
+ *
+ * Every view a client sees of a media record or a stored file passes through this.
+ */
+export function disclosedTenancy(record: AccessRecord, caller: AccessCaller): DisclosedTenancy {
+  if (caller.userId === null || !actsForRecord(record, caller)) return { ownerId: null, organizationId: null };
+  return { ownerId: record.ownerId, organizationId: record.organizationId };
+}
+
+/** What {@link accessLevel} needs: the record, the caller, the capability's power, and the hook if any. */
+export interface AccessOptions {
+  /** The record being reached. */
+  readonly record: AccessRecord;
+  /** Who is reaching it. */
+  readonly caller: AccessCaller;
+  /** The capability's name, as the hook sees it. */
+  readonly capability: string;
+  /** The capability's manage power — `media:manage`, `storage:manage`. */
+  readonly managePower: string;
+  /** The adopter's hook, if they supplied one. */
+  readonly hook?: PermissionHook;
+  /** The Worker env, for the hook. */
+  readonly env: Record<string, unknown>;
+}
+
+/** Ask the hook, then the rules where it defers. */
+async function decide(action: AccessAction, options: AccessOptions): Promise<boolean> {
+  const fallback = () => defaultAllows(action, options.record, options.caller, options.managePower);
+  if (!options.hook) return fallback();
+  const decision = await options.hook({
+    action,
+    capability: options.capability,
+    record: options.record,
+    caller: { userId: options.caller.userId, organizationId: organizationOf(options.caller) },
+    env: options.env,
+  });
+  if (decision === "allow") return true;
+  if (decision === "deny") return false;
+  return fallback();
+}
+
+/**
+ * What the caller may do with one record: nothing, read it, or change it.
+ *
+ * Read is decided first, and write is never asked about a record the caller cannot read — so a record
+ * the caller cannot see answers `none`, which a route turns into **not found**, never forbidden. Only a
+ * caller who may already read a record can learn it is not theirs to change.
+ */
+export async function accessLevel(options: AccessOptions): Promise<AccessLevel> {
+  if (!(await decide("read", options))) return "none";
+  return (await decide("write", options)) ? "write" : "read";
+}
+
+/** What {@link keepReadable} needs. The rules already ran in SQL, so no power is consulted here. */
+export interface KeepReadableOptions {
+  readonly capability: string;
+  readonly caller: AccessCaller;
+  readonly hook?: PermissionHook;
+  readonly env: Record<string, unknown>;
+}
+
+/**
+ * Ask the hook about every row on a page and drop the ones it denies.
+ *
+ * Only a deny changes anything: the rows arrived through {@link readablePredicate}, so the rules already
+ * admitted them, and an allow cannot add a row that was never on the page. A page can come back short;
+ * the capability's cursor is computed before this runs, so a short page still says there is more.
+ */
+export async function keepReadable<Row extends AccessRecord>(
+  rows: readonly Row[],
+  options: KeepReadableOptions,
+): Promise<Row[]> {
+  const hook = options.hook;
+  if (!hook) return [...rows];
+  const kept: Row[] = [];
+  for (const row of rows) {
+    const decision = await hook({
+      action: "read",
+      capability: options.capability,
+      record: row,
+      caller: { userId: options.caller.userId, organizationId: organizationOf(options.caller) },
+      env: options.env,
+    });
+    if (decision !== "deny") kept.push(row);
+  }
+  return kept;
+}
+
+/** What a list asks for beyond the rules. */
+export interface ReadablePredicateOptions {
+  /** The capability's manage power — a holder lists every record in their organization. */
+  readonly managePower: string;
+  /** Add every public record. Off by default: nobody receives what they did not ask for. */
+  readonly includePublic?: boolean;
+}
+
+/**
+ * The rules, in SQL — the `where` a list runs, over a table carrying `owner_id`, `organization_id` and
+ * `visibility`.
+ *
+ * **A list returns the caller's own records and their organization's.** Their own is every record they
+ * own in the organization they act for (or in none, while none is in force). Their organization's is every
+ * record in it whose visibility admits members, and every record at all for a holder of the manage power.
+ * `includePublic` adds every public record, and nothing else does.
+ *
+ * `sql.ref` rather than a typed builder, so one predicate serves every capability's table; the
+ * `CamelCasePlugin` still snake-cases each reference. Values are bound parameters, never interpolated.
+ */
+export function readablePredicate(caller: AccessCaller, options: ReadablePredicateOptions): RawBuilder<SqlBool> {
+  const owner = sql.ref("ownerId");
+  const organization = sql.ref("organizationId");
+  const visibility = sql.ref("visibility");
+  const organizationId = organizationOf(caller);
+  const clauses: RawBuilder<SqlBool>[] = [];
+
+  if (caller.userId !== null) {
+    clauses.push(
+      organizationId === null
+        ? sql<SqlBool>`(${owner} = ${caller.userId} and ${organization} is null)`
+        : sql<SqlBool>`(${owner} = ${caller.userId} and ${organization} = ${organizationId})`,
+    );
+  }
+  if (caller.userId !== null && organizationId !== null) {
+    clauses.push(
+      caller.acting?.roleAllows(options.managePower)
+        ? sql<SqlBool>`(${organization} = ${organizationId})`
+        : sql<SqlBool>`(${organization} = ${organizationId} and ${visibility} in ('organization', 'public'))`,
+    );
+  }
+  if (options.includePublic) clauses.push(sql<SqlBool>`(${visibility} = 'public')`);
+
+  if (clauses.length === 0) return sql<SqlBool>`0 = 1`;
+  return sql<SqlBool>`(${sql.join(clauses, sql` or `)})`;
+}
+
+/**
+ * The caller, from a request: the signed-in user and the organization they act for.
+ *
+ * An anonymous caller never resolves an organization — there is no session to resolve one from, and not
+ * asking keeps a public read from paying for a tenancy query it cannot use.
+ */
+export async function accessCaller(vars: Pick<PithyVars, "auth" | "actingOrganization">): Promise<AccessCaller> {
+  const userId = vars.auth?.userId ?? null;
+  if (userId === null) return { userId: null, acting: null };
+  return { userId, acting: await vars.actingOrganization() };
+}

package/src/access/acting.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The acting-organization seam: which organization a request acts for, and what the caller's role there
+ * allows.
+ *
+ * **Core defines it and one capability fills it.** `@pithy-sh/organization` knows memberships, roles and
+ * the session's selection; `@pithy-sh/media` and `@pithy-sh/storage` need the answer and must never
+ * import the capability that computes it. The split is the `AuthContext` split, for the same reason: a
+ * capability that imported its tenancy from another package would fail open the day that package was
+ * absent, and through this seam it fails closed instead. With no organization capability composed the
+ * resolver answers `null`, every record a request writes carries a null organization, and every rule
+ * that admits by organization admits nobody.
+ *
+ * **A resolver, not a value.** Resolving costs a D1 read — the session's selection, rejoined against a
+ * live membership — and most requests never ask. So the organization capability publishes a function and
+ * the first reader pays for the answer; {@link memoizeActing} makes sure no second reader pays again.
+ * Reading `c.var.auth` at call time rather than at publish time is also what makes it independent of
+ * composition order: a Worker that lists `organization()` ahead of `auth()` still resolves against the
+ * session auth set.
+ *
+ * **Two facts and no more.** The organization id is what a write records and what a read is scoped to;
+ * `roleAllows` is the one authorization question a capability outside tenancy may ask, so it asks it
+ * without learning the role's name or the catalog's shape. A power is a string here because the catalog
+ * is the adopter's and is not known when core compiles; a power nobody declared simply allows nothing.
+ */
+
+/** The organization a request acts for, and the one question a capability may ask about the caller's role. */
+export interface ActingOrganization {
+  /** The organization this request acts for. What a write records and what a scoped read filters on. */
+  readonly organizationId: string;
+  /**
+   * Whether the caller's role in that organization holds a power — `media:manage`, `storage:manage`.
+   * Answered from the membership row read on this request, never from a session claim.
+   */
+  roleAllows(power: string): boolean;
+}
+
+/** How a request learns its acting organization. `null` is a real answer: nothing is in force. */
+export type ActingOrganizationResolver = () => Promise<ActingOrganization | null>;
+
+/** The seam's default: no organization capability is composed, so nothing is ever in force. */
+export const noActingOrganization: ActingOrganizationResolver = async () => null;
+
+/**
+ * Wrap a resolver so it runs at most once per request.
+ *
+ * The promise is kept, not the value, so concurrent readers share one read and a refusal stays a refusal:
+ * a resolver that threw for an unrecognized role must not be retried by the next reader into a different
+ * answer within the same request.
+ */
+export function memoizeActing(resolve: ActingOrganizationResolver): ActingOrganizationResolver {
+  let answer: Promise<ActingOrganization | null> | undefined;
+  return () => {
+    answer ??= resolve();
+    return answer;
+  };
+}