@pithy-sh/core 0.1.2 → 0.1.3

package/dist/entitlement/entitlement.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+const EntitlementKey = z.string().min(1).max(64).regex(/^[a-z][a-z0-9_]*$/, "An entitlement key is lowercase letters, digits, and underscores, starting with a letter.").describe("A logical entitlement key (`pro`, `ads_removed`) — what gating code names. Never a store SKU: many products across many rails grant one key.");
+/**
+* One entitlement the caller holds, as the seam exposes it. This is the resolved read model, not a table:
+* `@pithy-sh/payments` materializes a row per `(holder, entitlement)` and decodes it into this shape.
+*
+* **Who the holder is stays out of this shape, deliberately.** A payments project bills either a person or
+* an organization, and its rows are keyed on that pair — but the seam resolves for *one* caller acting for
+* *one* holder, so the pair is constant across a single `list()` and every element of the result would
+* repeat it. Carrying it here would put a comparison within reach of {@link requireEntitlement} that the
+* gate has no correct way to make (see {@link EntitlementResolver}), and would hand every non-payments
+* provider two fields it cannot fill.
+*
+* `active` and `expiresAt` are both present, and both matter. The flag is an optimization written by
+* the projection; the timestamp is the truth. {@link entitlementGrantsAccess} applies both, so a
+* subscription that lapsed with no notification arriving stops granting access on the read path
+* without waiting for a write.
+*/
+const Entitlement = z.object({
+	key: EntitlementKey.describe("The entitlement key this grant is for."),
+	active: z.boolean().describe("Whether the granting purchase was in an access-granting state when the projection last wrote this row. An optimization, not the truth — `expiresAt` is rechecked on every read."),
+	expiresAt: z.date().nullable().describe("When the grant lapses, or null for a grant that never does (a non-consumable purchase). Evaluated at read time, so a silent lapse revokes access without a write."),
+	source: z.string().nullable().describe("Provenance — an opaque reference to whatever currently grants this entitlement (a purchase id, or a support grant). Opaque to core; the provider decides what it means.")
+}).describe("One entitlement the current caller holds, as the core seam exposes it — the resolved read model.");
+/**
+* The read-time rule, in one place: an entitlement grants access when the projection marked it active
+* **and** it has not expired. Applied by {@link requireEntitlement} rather than left to each provider,
+* so the recheck is a property of the seam instead of something a provider must remember.
+*
+* A read never writes. Repairing a stale row is the reconciliation Workflow's job, which keeps the hot
+* path a pure read.
+*/
+function entitlementGrantsAccess(entitlement, now) {
+	if (!entitlement.active) return false;
+	return entitlement.expiresAt === null || now.getTime() < entitlement.expiresAt.getTime();
+}
+/** Every key in `entitlements` that grants access at `now`, deduped. The set a gate is checked against. */
+function grantedEntitlementKeys(entitlements, now) {
+	const granted = /* @__PURE__ */ new Set();
+	for (const entitlement of entitlements) if (entitlementGrantsAccess(entitlement, now)) granted.add(entitlement.key);
+	return granted;
+}
+/**
+* The default resolver when no provider is composed: hold nothing. Every gate denies, which is the
+* fail-closed default the seam exists to guarantee. `createBackend` seeds it on every request, and a
+* provider's middleware replaces it.
+*/
+const noEntitlementProvider = {
+	provider: null,
+	list: async () => []
+};
+/**
+* The audit action a denied entitlement gate records, through the core `emit()` seam. Part of the
+* federated `domain/reason` taxonomy — core owns this one because core owns the gate. A blocked
+* attempt is a first-class audit record (`outcome: "denied"`), not only a 403.
+*/
+const ENTITLEMENT_DENIED_ACTION = "entitlement/denied";
+//#endregion
+export { ENTITLEMENT_DENIED_ACTION, Entitlement, EntitlementKey, entitlementGrantsAccess, grantedEntitlementKeys, noEntitlementProvider };

package/dist/entitlement/gateScan.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The source with its comments blanked, so a `// TODO: requireEntitlement("pro")` is not read as a gate.
+ *
+ * **String-aware, and it has to be.** Doing this with two regexes over raw source looks equivalent and is
+ * not: a `/*` inside a string literal opens a comment the scanner never sees closed, and everything up to
+ * the next `*/` in the file vanishes. A Worker with `app.get("/assets/*", …)` followed by any doc comment
+ * loses whatever sat between them — so a real gate goes unseen and the check reports clean. The same trap
+ * in reverse is `https://`, whose `//` is not a comment.
+ *
+ * So this walks the source once, tracking which of code / string / template / line comment / block comment
+ * it is in, and replaces comment characters with spaces rather than removing them — offsets stay put, which
+ * keeps anything reported against this text meaningful. A real parser would be the third option and is far
+ * more than a two-identifier search needs.
+ */
+export declare function withoutComments(source: string): string;
+/** Whether this source applies an entitlement gate, comments and string literals discounted. */
+export declare function callsGate(source: string): boolean;
+/**
+ * The files, of those given, that apply an entitlement gate — sorted, so a finding reads as a set.
+ *
+ * Takes the sources rather than a directory, which is what keeps this half free of `node:fs`. The CLI
+ * hands it a walked `src/`; a test in a Workers-typed program hands it `import.meta.glob(…, "?raw")`,
+ * which is the only way that program can read files at all.
+ */
+export declare function gateCallSites(sources: Readonly<Record<string, string>>): string[];
+//# sourceMappingURL=gateScan.d.ts.map

package/dist/entitlement/gateScan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateScan.d.ts","sourceRoot":"","sources":["../../src/entitlement/gateScan.ts"],"names":[],"mappings":"AAkCA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAuCtD;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,EAAE,CAKjF"}

package/dist/entitlement/gateScan.js

@@ -0,0 +1,96 @@
+//#region src/entitlement/gateScan.ts
+/**
+* Finding an entitlement gate in source text — the pure half of the composition check.
+*
+* `pithy doctor` scans a Worker's own source for calls to the gates in `./require`, because the runtime
+* cannot tell the two failing cases apart: a legitimately unentitled user and a Worker that forgot to
+* compose a provider both produce a 403. Walking a directory needs the filesystem. Deciding whether one
+* string of source gates does not, and the halves are split here so the second can be used on its own.
+*
+* On its own, because an adopter has the same question about their own source with the answer inverted:
+* not *where a gate must exist* but *where one may not*. No control-plane route in the Pithy dashboard may
+* gate on a subscription — a customer's data must not become unreachable over a billing problem of ours —
+* and a gate that is never reached at runtime is precisely the one a runtime test misses. That assertion
+* is a few lines over `import.meta.glob(…, "?raw")`, provided it can import these rules rather than restate
+* them. A restated copy drifts, and drifts quietly: both copies keep passing while they disagree.
+*
+* It lives beside the gates it names rather than in the CLI. A rename in `./require` is then one file's
+* work, core is the package every adopter already depends on, and core's no-`node:` rule is asserted over
+* every module here (`../worker-safety.test.ts`) — which is what makes this importable from a program
+* typed for the Workers runtime at all. The CLI composes it; see `entitlementGap.ts` there.
+*
+* The scan is textual, deliberately. Loading a Worker's routes to inspect them would execute the code
+* under audit, and the question is not subtle enough to need a parser: a call to one of two named helpers.
+*/
+/**
+* A call to either gate. `\b` before the name keeps `myRequireEntitlement(` out, and requiring the open
+* paren keeps a bare import or a re-export out — importing a gate is not applying one, and reporting an
+* unused import would make the check noise rather than signal.
+*/
+const GATE_CALL = /\brequire(?:Any)?Entitlement\s*\(/;
+/**
+* The source with its comments blanked, so a `// TODO: requireEntitlement("pro")` is not read as a gate.
+*
+* **String-aware, and it has to be.** Doing this with two regexes over raw source looks equivalent and is
+* not: a `/*` inside a string literal opens a comment the scanner never sees closed, and everything up to
+* the next `*/` in the file vanishes. A Worker with `app.get("/assets/*", …)` followed by any doc comment
+* loses whatever sat between them — so a real gate goes unseen and the check reports clean. The same trap
+* in reverse is `https://`, whose `//` is not a comment.
+*
+* So this walks the source once, tracking which of code / string / template / line comment / block comment
+* it is in, and replaces comment characters with spaces rather than removing them — offsets stay put, which
+* keeps anything reported against this text meaningful. A real parser would be the third option and is far
+* more than a two-identifier search needs.
+*/
+function withoutComments(source) {
+	const out = [];
+	let index = 0;
+	while (index < source.length) {
+		const char = source[index];
+		const next = source[index + 1];
+		if (char === "/" && next === "*") {
+			const close = source.indexOf("*/", index + 2);
+			const end = close === -1 ? source.length : close + 2;
+			out.push(source.slice(index, end).replace(/[^\n]/g, " "));
+			index = end;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			const newline = source.indexOf("\n", index);
+			const end = newline === -1 ? source.length : newline;
+			out.push(" ".repeat(end - index));
+			index = end;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			let scan = index + 1;
+			while (scan < source.length && source[scan] !== char) {
+				if (source[scan] === "\n" && char !== "`") break;
+				scan += source[scan] === "\\" ? 2 : 1;
+			}
+			const end = Math.min(scan + 1, source.length);
+			out.push(source.slice(index, end));
+			index = end;
+			continue;
+		}
+		out.push(char);
+		index += 1;
+	}
+	return out.join("");
+}
+/** Whether this source applies an entitlement gate, comments and string literals discounted. */
+function callsGate(source) {
+	return GATE_CALL.test(withoutComments(source));
+}
+/**
+* The files, of those given, that apply an entitlement gate — sorted, so a finding reads as a set.
+*
+* Takes the sources rather than a directory, which is what keeps this half free of `node:fs`. The CLI
+* hands it a walked `src/`; a test in a Workers-typed program hands it `import.meta.glob(…, "?raw")`,
+* which is the only way that program can read files at all.
+*/
+function gateCallSites(sources) {
+	return Object.entries(sources).filter(([, source]) => callsGate(source)).map(([file]) => file).sort((a, b) => a.localeCompare(b));
+}
+//#endregion
+export { callsGate, gateCallSites, withoutComments };

package/dist/entitlement/require.d.ts

@@ -0,0 +1,12 @@
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+/**
+ * Require any one of `keys`. Every key is parsed at construction, so a store SKU where an entitlement
+ * key belongs (`com.acme.pro.monthly`) fails on deploy rather than gating on something no projection
+ * ever writes. An empty list is refused for the same reason: it reads as "nothing required" but would
+ * deny every caller forever.
+ */
+export declare function requireAnyEntitlement(keys: readonly string[]): MiddlewareHandler<PithyHonoEnv>;
+/** Require one entitlement. The common case: one key gates one feature. */
+export declare function requireEntitlement(key: string): MiddlewareHandler<PithyHonoEnv>;
+//# sourceMappingURL=require.d.ts.map

package/dist/entitlement/require.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require.d.ts","sourceRoot":"","sources":["../../src/entitlement/require.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAoG7D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAmF9F;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAE/E"}

package/dist/entitlement/require.js

@@ -0,0 +1,123 @@
+import { InternalError, PithyError, UnauthorizedError, messageOf } from "../error/pithyError.js";
+import { ENTITLEMENT_DENIED_ACTION, EntitlementKey, grantedEntitlementKeys } from "./entitlement.js";
+//#region src/entitlement/require.ts
+/**
+* The entitlement gate — the middleware half of the seam. `requireEntitlement("pro")` is the
+* `verification`-strategy sibling every paid route carries: it says what the caller must *hold*, the
+* way `requireAuth()` says who the caller must *be*, and it belongs on the route line beside it.
+*
+*   app.get("/reports", requireAuth(), requireEntitlement("pro"), zValidator(…), handler)
+*
+* It lives in `@pithy-sh/core` rather than in `@pithy-sh/payments` for the same reason `requireAuth()`
+* is copied into each capability instead of imported from `@pithy-sh/auth`: a gate that arrives with a
+* package fails **open** when that package is absent. Depending on the core seam means an uncomposed
+* provider leaves `noEntitlementProvider` on the request, and every gate denies.
+*
+* Two names, not one variadic, because "any of these" and "all of these" are both plausible readings
+* of `requireEntitlement("pro", "team")` and the wrong reading is a security bug rather than a typo.
+*/
+/**
+* Why a gate denied — recorded in `detail` and in the audit event, never sent to the client.
+*
+* **Three readings, and keeping them apart is the whole job.** Nothing composed is one. A holder that has
+* bought nothing is the second. A caller acting for **no** holder at all is the third — the ordinary state
+* of somebody signed in with no organization selected, and before #412 it was spelled `payments resolved
+* []`, identically to the second. They want opposite fixes: one is a sale, the other is a subject resolver
+* returning nothing, and an operator reading one sentence had no way to tell which they were looking at.
+*
+* The holder is named only when the resolver reports one, and it is named as {@link EntitlementHolder}'s
+* `label` — display text, never a value this gate compares. A resolver that cannot say omits it, and the
+* sentence is exactly what it was.
+*/
+function denialDetail(keys, provider, held, reading) {
+	const required = keys.join(" | ");
+	if (provider === null) return `no entitlement provider is composed, so \`${required}\` cannot be held. Add a payments capability to this Worker's pithy.config.ts.`;
+	switch (reading.kind) {
+		case "nobody": return `${provider} resolved no holder for this caller, so nothing can be held; the route requires \`${required}\`. Under organization billing this is a caller acting for no organization, not an unentitled one.`;
+		case "failed": return `${provider} could not resolve a holder for this caller — the read raised, see the preceding log line; the route requires \`${required}\`.`;
+		case "known": return `${provider} resolved [${[...held].sort().join(", ")}] for ${reading.holder.label}; the route requires \`${required}\`.`;
+		default: return `${provider} resolved [${[...held].sort().join(", ")}]; the route requires \`${required}\`.`;
+	}
+}
+/** The gate's denial: one code, one status, whatever the reason. The reason rides in `detail`. */
+function denied(keys, provider, held, reading) {
+	return new PithyError({
+		code: "payments/entitlement_required",
+		status: 403,
+		message: "This feature requires an active subscription or purchase.",
+		action: "Purchase or restore the product that grants access, then retry.",
+		detail: denialDetail(keys, provider, held, reading)
+	});
+}
+/**
+* Require any one of `keys`. Every key is parsed at construction, so a store SKU where an entitlement
+* key belongs (`com.acme.pro.monthly`) fails on deploy rather than gating on something no projection
+* ever writes. An empty list is refused for the same reason: it reads as "nothing required" but would
+* deny every caller forever.
+*/
+function requireAnyEntitlement(keys) {
+	if (keys.length === 0) throw new InternalError({
+		message: "requireAnyEntitlement() needs at least one entitlement key.",
+		action: "Name the entitlements that grant access, or drop the gate if the route is not paid."
+	});
+	const required = keys.map((key) => EntitlementKey.parse(key));
+	return async (c, next) => {
+		const auth = c.var.auth;
+		if (!auth) throw new UnauthorizedError({
+			message: "Authentication required.",
+			action: "Sign in and retry with a valid session or bearer token."
+		});
+		const resolver = c.var.entitlements;
+		let held;
+		try {
+			held = grantedEntitlementKeys(await resolver.list(), /* @__PURE__ */ new Date());
+		} catch (error) {
+			c.var.log.error("entitlement resolution failed", {
+				provider: resolver.provider,
+				cause: messageOf(error)
+			});
+			held = /* @__PURE__ */ new Set();
+		}
+		if (required.some((key) => held.has(key))) {
+			await next();
+			return;
+		}
+		let reading = { kind: "unavailable" };
+		if (resolver.holder) try {
+			const answered = await resolver.holder();
+			reading = answered === void 0 ? { kind: "nobody" } : {
+				kind: "known",
+				holder: answered
+			};
+		} catch (error) {
+			reading = { kind: "failed" };
+			c.var.log.error("entitlement holder resolution failed", {
+				provider: resolver.provider,
+				cause: messageOf(error)
+			});
+		}
+		await c.var.emit({
+			action: ENTITLEMENT_DENIED_ACTION,
+			outcome: "denied",
+			severity: "info",
+			actorType: "user",
+			actorId: auth.userId,
+			sessionId: auth.sessionId,
+			resourceType: "entitlement",
+			resourceId: required.join("|"),
+			tenant: reading.kind === "known" ? reading.holder.tenant : null,
+			metadata: {
+				provider: resolver.provider,
+				required,
+				held: [...held].sort()
+			}
+		});
+		throw denied(required, resolver.provider, held, reading);
+	};
+}
+/** Require one entitlement. The common case: one key gates one feature. */
+function requireEntitlement(key) {
+	return requireAnyEntitlement([key]);
+}
+//#endregion
+export { requireAnyEntitlement, requireEntitlement };

package/dist/env/ambient.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What the *ambient* environment says about the composition being assembled — the two questions a
+ * capability may ask before it registers anything, and the one reader for both.
+ *
+ * ## Why a capability can ask this at all
+ *
+ * A Worker is handed its bindings per request, so `c.env` does not exist when `createBackend` calls a
+ * capability's `routes()`. `process.env` does: with `nodejs_compat` and a compatibility date past
+ * 2025-04-01 — every Worker `pithy init` scaffolds — workerd populates `process.env` from the script's
+ * own `vars` and secrets, and it is populated at module scope, before the first request. Verified
+ * against a real `wrangler dev`: at module scope `Object.keys(process.env)` is exactly the declared
+ * vars.
+ *
+ * That is the whole reach of this module, and the limit is the interesting half:
+ *
+ * - **`ENVIRONMENT` is here**, because `pithy init` stamps it into every environment stanza of every
+ *   Worker's `wrangler.jsonc` ({@link ENVIRONMENT_VAR}). A composition can therefore know it is `dev`
+ *   without being told.
+ * - **The host's environment is not here.** `CI=true` in the shell that ran `wrangler dev` does *not*
+ *   appear inside the Worker — workerd replaces `process.env` with the bindings rather than merging.
+ *   {@link ./ci.ts} carries that consequence and what is done about it.
+ *
+ * Read at call time, never captured at import: a module-scope snapshot is unstubbable in a test and
+ * would freeze the answer for the life of an isolate that outlives a `.dev.vars` edit.
+ */
+/** A process environment as this module reads one — the shape of `process.env`, and nothing assumed of it. */
+export type AmbientEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * The ambient environment, or an empty one where there is no `process` at all.
+ *
+ * Guarded rather than assumed: this module is bundled into Workers, and a runtime without
+ * `nodejs_compat` has no `process`. An empty environment answers "nothing was stamped", which is the
+ * refusing answer everywhere it is used — a missing `process` must never read as `dev`.
+ */
+export declare function ambientEnv(): AmbientEnv;
+/**
+ * Whether an environment variable counts as **set**: any non-blank value, blank is no override.
+ *
+ * One rule, stated once. It is `PITHY_OFFLINE`'s (#218), and the reason it is not "`=== "true"`" is
+ * that runners disagree — `true`, `1`, and an operator's own word all mean the same thing, and a
+ * variable someone deliberately blanked (`CI=`) is the one case that means "no".
+ */
+export declare function ambientFlag(env: AmbientEnv, name: string): boolean;
+/**
+ * The environment this composition was stamped for — `dev`, `staging`, `prod`, or an adopter's own —
+ * and `undefined` where nothing stamped one.
+ *
+ * **`undefined`, never a defaulted `dev`.** The callers are gates, and a gate that assumes `dev` when
+ * it was told nothing opens itself in exactly the deployment whose `wrangler.jsonc` lost the var.
+ */
+export declare function compositionEnvironment(env?: AmbientEnv): string | undefined;
+//# sourceMappingURL=ambient.d.ts.map

package/dist/env/ambient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient.d.ts","sourceRoot":"","sources":["../../src/env/ambient.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,8GAA8G;AAC9G,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAEvC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,UAAyB,GAAG,MAAM,GAAG,SAAS,CAGzF"}

package/dist/env/ambient.js

@@ -0,0 +1,35 @@
+import "../worker/identity.js";
+//#region src/env/ambient.ts
+/**
+* The ambient environment, or an empty one where there is no `process` at all.
+*
+* Guarded rather than assumed: this module is bundled into Workers, and a runtime without
+* `nodejs_compat` has no `process`. An empty environment answers "nothing was stamped", which is the
+* refusing answer everywhere it is used — a missing `process` must never read as `dev`.
+*/
+function ambientEnv() {
+	return globalThis.process?.env ?? {};
+}
+/**
+* Whether an environment variable counts as **set**: any non-blank value, blank is no override.
+*
+* One rule, stated once. It is `PITHY_OFFLINE`'s (#218), and the reason it is not "`=== "true"`" is
+* that runners disagree — `true`, `1`, and an operator's own word all mean the same thing, and a
+* variable someone deliberately blanked (`CI=`) is the one case that means "no".
+*/
+function ambientFlag(env, name) {
+	return (env[name] ?? "").trim().length > 0;
+}
+/**
+* The environment this composition was stamped for — `dev`, `staging`, `prod`, or an adopter's own —
+* and `undefined` where nothing stamped one.
+*
+* **`undefined`, never a defaulted `dev`.** The callers are gates, and a gate that assumes `dev` when
+* it was told nothing opens itself in exactly the deployment whose `wrangler.jsonc` lost the var.
+*/
+function compositionEnvironment(env = ambientEnv()) {
+	const value = (env["ENVIRONMENT"] ?? "").trim();
+	return value.length > 0 ? value : void 0;
+}
+//#endregion
+export { ambientEnv, ambientFlag, compositionEnvironment };

package/dist/env/ci.d.ts

@@ -0,0 +1,36 @@
+import { type AmbientEnv } from "./ambient";
+/**
+ * Is this continuous integration? One read, one rule, one place — the convention starts here.
+ *
+ * Nothing in this repository read `CI` before #243, so this is the declaration rather than a fourth
+ * copy of one. It exists because a gate that inlines `!!process.env.CI` at the point it guards is a
+ * gate whose meaning is re-decided by whoever writes the next one.
+ *
+ * ## What counts as set
+ *
+ * **Any non-blank value.** `CI=true`, `CI=1`, and `CI=woodpecker` are all CI; `CI=` (set but empty,
+ * which some runners do) and an absent `CI` are not. That is `PITHY_OFFLINE`'s rule (#218) applied
+ * unchanged, rather than a second rule for a second variable — see {@link ambientFlag}.
+ *
+ * ## Why anything reads it
+ *
+ * CI is where an unsupervised capability is most reachable and least watched. A `dev` composition is
+ * exactly what CI boots — integration suites, packaging checks, `pithy dev` itself — so "not `dev`"
+ * does not cover CI, and CI is not production, so neither signal implies the other. Anything gated on
+ * both asks twice, in two statements: an `||` folded into one expression is one edit from an `&&`, and
+ * the failure mode is a session-minting endpoint that answers.
+ *
+ * ## Where it can be read, and where it cannot
+ *
+ * In the CLI, and in anything else running under Node, this is the host's own `CI`. **Inside a Worker
+ * it is not**: workerd populates `process.env` from the script's bindings and nothing else, so the
+ * shell variable does not cross that boundary (see {@link ./ambient.ts}). A Worker-side gate is
+ * therefore only as truthful as what started the Worker — which is why `pithy dev` forwards `CI` into
+ * every Worker it launches as a var, and why a gate that depends on this must also carry a second,
+ * independent refusal that needs no forwarding.
+ */
+/** The variable every CI runner sets without configuration. The name is not ours to choose. */
+export declare const CI_ENV = "CI";
+/** Whether this process is running under continuous integration. Any non-blank `CI`; blank is not CI. */
+export declare function isContinuousIntegration(env?: AmbientEnv): boolean;
+//# sourceMappingURL=ci.d.ts.map

package/dist/env/ci.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci.d.ts","sourceRoot":"","sources":["../../src/env/ci.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,UAAU,EAA2B,MAAM,WAAW,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,+FAA+F;AAC/F,eAAO,MAAM,MAAM,OAAO,CAAC;AAE3B,yGAAyG;AACzG,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,UAAyB,GAAG,OAAO,CAE/E"}

package/dist/env/ci.js

@@ -0,0 +1,40 @@
+import { ambientEnv, ambientFlag } from "./ambient.js";
+//#region src/env/ci.ts
+/**
+* Is this continuous integration? One read, one rule, one place — the convention starts here.
+*
+* Nothing in this repository read `CI` before #243, so this is the declaration rather than a fourth
+* copy of one. It exists because a gate that inlines `!!process.env.CI` at the point it guards is a
+* gate whose meaning is re-decided by whoever writes the next one.
+*
+* ## What counts as set
+*
+* **Any non-blank value.** `CI=true`, `CI=1`, and `CI=woodpecker` are all CI; `CI=` (set but empty,
+* which some runners do) and an absent `CI` are not. That is `PITHY_OFFLINE`'s rule (#218) applied
+* unchanged, rather than a second rule for a second variable — see {@link ambientFlag}.
+*
+* ## Why anything reads it
+*
+* CI is where an unsupervised capability is most reachable and least watched. A `dev` composition is
+* exactly what CI boots — integration suites, packaging checks, `pithy dev` itself — so "not `dev`"
+* does not cover CI, and CI is not production, so neither signal implies the other. Anything gated on
+* both asks twice, in two statements: an `||` folded into one expression is one edit from an `&&`, and
+* the failure mode is a session-minting endpoint that answers.
+*
+* ## Where it can be read, and where it cannot
+*
+* In the CLI, and in anything else running under Node, this is the host's own `CI`. **Inside a Worker
+* it is not**: workerd populates `process.env` from the script's bindings and nothing else, so the
+* shell variable does not cross that boundary (see {@link ./ambient.ts}). A Worker-side gate is
+* therefore only as truthful as what started the Worker — which is why `pithy dev` forwards `CI` into
+* every Worker it launches as a var, and why a gate that depends on this must also carry a second,
+* independent refusal that needs no forwarding.
+*/
+/** The variable every CI runner sets without configuration. The name is not ours to choose. */
+const CI_ENV = "CI";
+/** Whether this process is running under continuous integration. Any non-blank `CI`; blank is not CI. */
+function isContinuousIntegration(env = ambientEnv()) {
+	return ambientFlag(env, "CI");
+}
+//#endregion
+export { CI_ENV, isContinuousIntegration };

package/dist/env/stem.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How a member of the dev set publishes its address, and how a sibling looks it up.
+ *
+ * `pithy dev` pins one port per worker at feature-create and exports `<STEM>_PORT` / `<STEM>_ORIGIN`
+ * for every one of them, so a worker reaches its peers at a known address rather than through
+ * wrangler's cross-`wrangler dev` service registry (CLAUDE.md §CLI). The stem is the join: the CLI
+ * writes the var, and code running *inside* the Worker reads it.
+ *
+ * **It lives in core because both ends are now real.** It was the CLI's private helper while only the
+ * CLI used it; the loopback Workflow dispatcher ({@link ../workflow/loopback.ts}) made the runtime the
+ * other end of the same wire, and two copies of a name-derivation rule are two answers the first day
+ * one of them learns about a character the other does not.
+ */
+/**
+ * The env-var stem for a worker or capability: uppercased, every non-alphanumeric run collapsed to a
+ * single `_`, leading and trailing separators dropped. `media-cli` → `MEDIA_CLI`.
+ *
+ * Deterministic, so the name a worker publishes is the name every sibling looks up.
+ */
+export declare function envStem(name: string): string;
+/** The var carrying one member's loopback address — `email` → `EMAIL_ORIGIN`. */
+export declare function originVarName(name: string): string;
+//# sourceMappingURL=stem.d.ts.map

package/dist/env/stem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stem.d.ts","sourceRoot":"","sources":["../../src/env/stem.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5C;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/env/stem.js

@@ -0,0 +1,29 @@
+//#region src/env/stem.ts
+/**
+* How a member of the dev set publishes its address, and how a sibling looks it up.
+*
+* `pithy dev` pins one port per worker at feature-create and exports `<STEM>_PORT` / `<STEM>_ORIGIN`
+* for every one of them, so a worker reaches its peers at a known address rather than through
+* wrangler's cross-`wrangler dev` service registry (CLAUDE.md §CLI). The stem is the join: the CLI
+* writes the var, and code running *inside* the Worker reads it.
+*
+* **It lives in core because both ends are now real.** It was the CLI's private helper while only the
+* CLI used it; the loopback Workflow dispatcher ({@link ../workflow/loopback.ts}) made the runtime the
+* other end of the same wire, and two copies of a name-derivation rule are two answers the first day
+* one of them learns about a character the other does not.
+*/
+/**
+* The env-var stem for a worker or capability: uppercased, every non-alphanumeric run collapsed to a
+* single `_`, leading and trailing separators dropped. `media-cli` → `MEDIA_CLI`.
+*
+* Deterministic, so the name a worker publishes is the name every sibling looks up.
+*/
+function envStem(name) {
+	return name.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+/** The var carrying one member's loopback address — `email` → `EMAIL_ORIGIN`. */
+function originVarName(name) {
+	return `${envStem(name)}_ORIGIN`;
+}
+//#endregion
+export { envStem, originVarName };