@pithy-sh/core 0.10.0 → 0.12.0

package/dist/crypto/fieldKeys.d.ts

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { EncryptionConfig } from "./envelope";
+/**
+ * **The field key: what an app Worker seals its encrypted fields with** (#390).
+ *
+ * `PITHY_FIELD_KEYS` is an {@link EncryptionConfig}, the same versioned shape as secrets' master key, and it is a
+ * **different key on purpose**. Field encryption seals and opens inside the adopter's own Workers, so every Worker that
+ * holds an encrypted field must hold the key it uses. Were that the master key `SECRETS_ENCRYPTION_KEYS`, every such
+ * Worker would hold the key to the whole secrets vault, and one compromised would open it. A key of its own limits
+ * that to the fields: a Worker that holds an encrypted field and composes no `secrets` is bound this key and never
+ * the master key.
+ *
+ * It is not a second mechanism: `pithy secrets provision` mints it beside the master key, in the same format, binds
+ * it to every Worker that holds an encrypted field, and the manager's at-rest cron rotates it every
+ * {@link FIELD_KEY_ROTATION_DAYS} days.
+ */
+/** The binding an app Worker reads its field key through. Fixed across environments; only the store entry is scoped. */
+export declare const FIELD_KEYS_BINDING = "PITHY_FIELD_KEYS";
+/** How often the manager rotates the field key, in days. */
+export declare const FIELD_KEY_ROTATION_DAYS = 30;
+/** A Secrets Store binding: `.get()` resolves the plaintext inside the Worker. */
+export interface FieldKeyBinding {
+    get(): Promise<string>;
+}
+/**
+ * Where a field key comes from: the Worker's `env.PITHY_FIELD_KEYS` binding (a Secrets Store binding deployed, a JSON
+ * string from `.dev.vars` locally), or a config a caller already resolved.
+ */
+export type FieldKeys = FieldKeyBinding | string | EncryptionConfig;
+/**
+ * Resolve a field key to its config. A missing binding, text that is not JSON, and JSON that is not a key set are each
+ * refused, and **nothing read is ever echoed**: what failed to parse is the key set.
+ */
+export declare function resolveFieldKeys(keys: FieldKeys | undefined): Promise<EncryptionConfig>;
+/**
+ * Every live version in a key set, newest first, as numbers. A version key that is not an integer is refused rather
+ * than sorted as text, where `"10"` sorts before `"9"`.
+ */
+export declare function liveVersions(config: EncryptionConfig): number[];
+//# sourceMappingURL=fieldKeys.d.ts.map

package/dist/crypto/fieldKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldKeys.d.ts","sourceRoot":"","sources":["../../src/crypto/fieldKeys.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AAEH,wHAAwH;AACxH,eAAO,MAAM,kBAAkB,qBAAqB,CAAC;AAErD,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,MAAM,GAAG,gBAAgB,CAAC;AAEpE;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoB7F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAM/D"}

package/dist/crypto/fieldKeys.js

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "../error/pithyError.js";
+import { remedy } from "../cli/command.js";
+import { EncryptionConfig } from "./envelope.js";
+//#region src/crypto/fieldKeys.ts
+/**
+* **The field key: what an app Worker seals its encrypted fields with** (#390).
+*
+* `PITHY_FIELD_KEYS` is an {@link EncryptionConfig}, the same versioned shape as secrets' master key, and it is a
+* **different key on purpose**. Field encryption seals and opens inside the adopter's own Workers, so every Worker that
+* holds an encrypted field must hold the key it uses. Were that the master key `SECRETS_ENCRYPTION_KEYS`, every such
+* Worker would hold the key to the whole secrets vault, and one compromised would open it. A key of its own limits
+* that to the fields: a Worker that holds an encrypted field and composes no `secrets` is bound this key and never
+* the master key.
+*
+* It is not a second mechanism: `pithy secrets provision` mints it beside the master key, in the same format, binds
+* it to every Worker that holds an encrypted field, and the manager's at-rest cron rotates it every
+* {@link FIELD_KEY_ROTATION_DAYS} days.
+*/
+/** The binding an app Worker reads its field key through. Fixed across environments; only the store entry is scoped. */
+const FIELD_KEYS_BINDING = "PITHY_FIELD_KEYS";
+/** How often the manager rotates the field key, in days. */
+const FIELD_KEY_ROTATION_DAYS = 30;
+/**
+* Resolve a field key to its config. A missing binding, text that is not JSON, and JSON that is not a key set are each
+* refused, and **nothing read is ever echoed**: what failed to parse is the key set.
+*/
+async function resolveFieldKeys(keys) {
+	let raw = keys;
+	if (keys === void 0 || keys === null) throw new InternalError({
+		message: "This Worker holds an encrypted field and no field key.",
+		action: `Bind ${FIELD_KEYS_BINDING}. ${remedy("secrets provision").say((command) => `${command} binds it to every Worker with an encrypted field.`)}`,
+		detail: `${FIELD_KEYS_BINDING} binding is not configured`
+	});
+	if (typeof keys === "object" && "get" in keys && typeof keys.get === "function") raw = await keys.get();
+	if (typeof raw === "string") try {
+		raw = JSON.parse(raw);
+	} catch {
+		throw new InternalError({ detail: `${FIELD_KEYS_BINDING} is not valid JSON` });
+	}
+	const parsed = EncryptionConfig.safeParse(raw);
+	if (!parsed.success) throw new InternalError({ detail: `${FIELD_KEYS_BINDING} is not a valid EncryptionConfig` });
+	return parsed.data;
+}
+/**
+* Every live version in a key set, newest first, as numbers. A version key that is not an integer is refused rather
+* than sorted as text, where `"10"` sorts before `"9"`.
+*/
+function liveVersions(config) {
+	const versions = Object.keys(config.versions).map(Number);
+	if (!versions.every((version) => Number.isInteger(version))) throw new InternalError({ detail: `${FIELD_KEYS_BINDING}: a version key is not a stringified integer` });
+	return versions.sort((left, right) => right - left);
+}
+//#endregion
+export { FIELD_KEYS_BINDING, FIELD_KEY_ROTATION_DAYS, liveVersions, resolveFieldKeys };

package/dist/data/codecs.d.ts

@@ -8,17 +8,29 @@ export declare const SQLiteDate: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.
 /** JsonDate: Date ↔ ISO string, for dates nested inside `sqliteJson` payloads. */
 export declare const JsonDate: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
 /**
- * sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode
- * accepts a JSON string or an already-parsed value; the result is validated
- * against `schema` before it reaches the app.
- *
- * **Both `JSON` functions throw**, and both were reachable. `JSON.parse` throws a
- * `SyntaxError` on any string that is not a JSON document — which a column holding
- * text an older writer put there, or a payload a customer's Worker returned, can be.
- * `JSON.stringify` throws a `TypeError` on a `BigInt` and on a cycle, either of
- * which a `schema` can legitimately admit. Both become an issue (#358).
+ * sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode accepts a JSON string or an
+ * already-parsed value; the result is validated against `schema` before it reaches the app.
  */
-export declare function sqliteJson<T extends z.ZodType>(schema: T): z.ZodCodec<z.ZodUnion<readonly [z.ZodString, T]>, T>;
+export declare function sqliteJson<T extends z.ZodType>(schema: T): SqliteJson<T>;
+/**
+ * Names the type `sqliteJson` returns, and nothing else. A type only: no value carries it. `Redacted<T>` reads a JSON
+ * column's fields through it, as `redact` reads them through {@link isSqliteJson}, so an adopter's codec of the same
+ * shape is opaque to both.
+ */
+declare const kitJsonColumn: unique symbol;
+/** What `sqliteJson(schema)` returns: the kit's JSON column over `schema`. Clones keep it, as they return `this`. */
+export type SqliteJson<T extends z.ZodType> = z.ZodCodec<z.ZodUnion<[z.ZodString, T]>, T> & {
+    readonly [kitJsonColumn]: T;
+};
+/** The schema a kit JSON column decodes to, or `never` for any other node. */
+export type SqliteJsonSchema<S> = S extends {
+    readonly [kitJsonColumn]: infer T;
+} ? T : never;
+/**
+ * Whether a schema is a JSON column `sqliteJson` built, or a clone of one (`.describe()`, `.meta()`), read by its
+ * decode. `redact` walks such a column's fields one by one, and treats every other codec as opaque.
+ */
+export declare function isSqliteJson(schema: z.ZodType): boolean;
 export declare const MAX_TIMEZONE_LENGTH = 64;
 /**
  * Trim, validate, and canonicalize an IANA timezone; anything invalid becomes
@@ -33,4 +45,5 @@ export declare function isValidIanaTimezone(value: string): boolean;
  * to `undefined` on both decode and encode rather than throwing.
  */
 export declare const IanaTimezone: z.ZodCodec<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodOptional<z.ZodString>>;
+export {};
 //# sourceMappingURL=codecs.d.ts.map

package/dist/data/codecs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../../src/data/codecs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+CxB,+EAA+E;AAC/E,eAAO,MAAM,aAAa,8GAGxB,CAAC;AAoBH,6EAA6E;AAC7E,eAAO,MAAM,UAAU,mFAGrB,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,QAAQ,mFAGnB,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,wDA8BxD;AAED,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASxE;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,mFAGvB,CAAC"}
+{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../../src/data/codecs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+CxB,+EAA+E;AAC/E,eAAO,MAAM,aAAa,8GAGxB,CAAC;AAoBH,6EAA6E;AAC7E,eAAO,MAAM,UAAU,mFAGrB,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,QAAQ,mFAGnB,CAAC;AA0CH;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAKxE;AAED;;;;GAIG;AACH,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAE3C,qHAAqH;AACrH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAC1F,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE9F;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAGvD;AAED,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASxE;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,mFAGvB,CAAC"}

package/dist/data/codecs.js

@@ -64,47 +64,61 @@ const JsonDate = z.codec(z.union([
 	encode: (value) => value.toISOString()
 });
 /**
-* sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode
-* accepts a JSON string or an already-parsed value; the result is validated
-* against `schema` before it reaches the app.
+* sqliteJson's decode: a JSON string is parsed, an already-parsed value passes through. One function for every
+* column, so `isSqliteJson` can tell the kit's codec from any other by its decode.
 *
-* **Both `JSON` functions throw**, and both were reachable. `JSON.parse` throws a
-* `SyntaxError` on any string that is not a JSON document — which a column holding
-* text an older writer put there, or a payload a customer's Worker returned, can be.
-* `JSON.stringify` throws a `TypeError` on a `BigInt` and on a cycle, either of
-* which a `schema` can legitimately admit. Both become an issue (#358).
+* **`JSON.parse` throws**, and it was reachable: a column holding text an older writer put there, or a payload a
+* customer's Worker returned, need not be a JSON document. That becomes an issue (#358).
+*/
+function decodeJson(value, payload) {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		payload.issues.push({
+			code: "invalid_format",
+			format: "json",
+			input: value,
+			message: "Not valid JSON."
+		});
+		return z.NEVER;
+	}
+}
+/**
+* sqliteJson's encode. **`JSON.stringify` throws** on a `BigInt` and on a cycle, either of which a schema can
+* legitimately admit, so that becomes an issue too (#358).
+*/
+function encodeJson(value, payload) {
+	try {
+		const json = JSON.stringify(value);
+		if (typeof json === "string") return json;
+	} catch {}
+	payload.issues.push({
+		code: "invalid_format",
+		format: "json",
+		input: void 0,
+		message: "Not serializable as JSON."
+	});
+	return z.NEVER;
+}
+/**
+* sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode accepts a JSON string or an
+* already-parsed value; the result is validated against `schema` before it reaches the app.
 */
 function sqliteJson(schema) {
 	return z.codec(z.union([z.string(), schema]), schema, {
-		decode: (value, payload) => {
-			if (typeof value !== "string") return value;
-			try {
-				return JSON.parse(value);
-			} catch {
-				payload.issues.push({
-					code: "invalid_format",
-					format: "json",
-					input: value,
-					message: "Not valid JSON."
-				});
-				return z.NEVER;
-			}
-		},
-		encode: (value, payload) => {
-			try {
-				const json = JSON.stringify(value);
-				if (typeof json === "string") return json;
-			} catch {}
-			payload.issues.push({
-				code: "invalid_format",
-				format: "json",
-				input: void 0,
-				message: "Not serializable as JSON."
-			});
-			return z.NEVER;
-		}
+		decode: decodeJson,
+		encode: encodeJson
 	});
 }
+/**
+* Whether a schema is a JSON column `sqliteJson` built, or a clone of one (`.describe()`, `.meta()`), read by its
+* decode. `redact` walks such a column's fields one by one, and treats every other codec as opaque.
+*/
+function isSqliteJson(schema) {
+	const def = schema._zod.def;
+	return def.type === "pipe" && def.transform === decodeJson;
+}
 const MAX_TIMEZONE_LENGTH = 64;
 /**
 * Trim, validate, and canonicalize an IANA timezone; anything invalid becomes
@@ -134,4 +148,4 @@ const IanaTimezone = z.codec(z.string().nullish(), z.string().optional(), {
 	encode: (value) => normalizeIanaTimezone(value)
 });
 //#endregion
-export { IanaTimezone, JsonDate, MAX_TIMEZONE_LENGTH, SQLiteBoolean, SQLiteDate, isValidIanaTimezone, normalizeIanaTimezone, sqliteJson };
+export { IanaTimezone, JsonDate, MAX_TIMEZONE_LENGTH, SQLiteBoolean, SQLiteDate, isSqliteJson, isValidIanaTimezone, normalizeIanaTimezone, sqliteJson };

package/dist/entitlement/allowance.d.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import type { MeterLimit } from "./entitlement";
+/** How many of `name` the caller's holder may have: a whole number, or `null` for unlimited. */
+export declare function quota(c: Context<PithyHonoEnv>, name: string): Promise<number | null>;
+/** Whether `name` is on for the caller's holder. Always a boolean. */
+export declare function feature(c: Context<PithyHonoEnv>, name: string): Promise<boolean>;
+/**
+ * The ceiling a capability enforces on a meter it counts itself, for the current caller.
+ *
+ * **No provider, or one that binds nothing to this meter, is `{ enforced: false }`** — and the capability
+ * keeps its own configured ceiling. Enforcement is opt-in per meter because a cap that arrives by surprise
+ * breaks an adopter who was already over it.
+ *
+ * **A provider that throws refuses, and logs.** Storage already says which way round to err: over-counting
+ * briefly and reclaiming is the right way round, and under-counting has no recovery. Treating a failed read
+ * as unenforced would hand a customer an unbounded allowance for as long as the read kept failing. The cost
+ * is real and is stated rather than discovered: our bug becomes a refused write for a paying customer.
+ * Enforcement being opt-in is what bounds it — an adopter who would rather over-serve leaves the meter
+ * advisory.
+ */
+export declare function meterLimit(c: Context<PithyHonoEnv>, meter: string): Promise<MeterLimit>;
+//# sourceMappingURL=allowance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"allowance.d.ts","sourceRoot":"","sources":["../../src/entitlement/allowance.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAqChD,gGAAgG;AAChG,wBAAsB,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAI1F;AAED,sEAAsE;AACtE,wBAAsB,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAItF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAa7F"}

package/dist/entitlement/allowance.js

@@ -0,0 +1,80 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError, messageOf } from "../error/pithyError.js";
+//#region src/entitlement/allowance.ts
+/**
+* The allowance readers — how much the current caller may have, and whether a switch is on.
+*
+*   const seats = await quota(c, "seats");                  // number, or null for unlimited
+*   if (seats !== null && (await countMembers(orgId)) >= seats) throw new SeatLimitReached(…);
+*   if (await feature(c, "auditExport")) { … }               // boolean, never null
+*
+* **Neither takes an entitlement key, and that is the point.** A route does not know which tier the
+* caller's holder is on, and during an upgrade overlap it holds two. The provider resolves across every
+* key the holder has and answers the higher, so an adopter compares numbers and never ranks tiers.
+*
+* **Read, never enforced.** A quota denies nothing on its own and a feature set to `false` denies
+* nothing either — `requireEntitlement` still gates on the key alone. What a number means for a request
+* is the adopter's code to decide, because only the adopter can count what it owns.
+*
+* **They live in core for the reason `requireEntitlement` does.** A reader that arrived with
+* `@pithy-sh/payments` would be absent when payments is, and a route reading an allowance must then fail
+* rather than read something. So with no provider composed — or one that declares no allowances — both
+* throw `core/internal` naming the gap. Never `0`, which is a paywall shut for a reason nobody can see;
+* never unlimited, which is a paywall that does not exist.
+*/
+/** The refusal when nothing on the request can answer an allowance. The adopter's wiring, so `core/internal`. */
+function noProvider(c, kind, name) {
+	const provider = c.var.entitlements?.provider ?? null;
+	return new InternalError({
+		message: `No ${kind} "${name}" can be resolved here.`,
+		action: "Compose a payments capability that declares its entitlements in this Worker's pithy.config.ts.",
+		detail: provider === null ? `no entitlement provider is composed, so ${kind}("${name}") has nothing to read.` : `${provider} resolves entitlements and declares no allowances, so ${kind}("${name}") has nothing to read.`
+	});
+}
+/** How many of `name` the caller's holder may have: a whole number, or `null` for unlimited. */
+async function quota(c, name) {
+	const resolver = c.var.entitlements;
+	if (!resolver?.quota) throw noProvider(c, "quota", name);
+	return resolver.quota(name);
+}
+/** Whether `name` is on for the caller's holder. Always a boolean. */
+async function feature(c, name) {
+	const resolver = c.var.entitlements;
+	if (!resolver?.feature) throw noProvider(c, "feature", name);
+	return resolver.feature(name);
+}
+/**
+* The ceiling a capability enforces on a meter it counts itself, for the current caller.
+*
+* **No provider, or one that binds nothing to this meter, is `{ enforced: false }`** — and the capability
+* keeps its own configured ceiling. Enforcement is opt-in per meter because a cap that arrives by surprise
+* breaks an adopter who was already over it.
+*
+* **A provider that throws refuses, and logs.** Storage already says which way round to err: over-counting
+* briefly and reclaiming is the right way round, and under-counting has no recovery. Treating a failed read
+* as unenforced would hand a customer an unbounded allowance for as long as the read kept failing. The cost
+* is real and is stated rather than discovered: our bug becomes a refused write for a paying customer.
+* Enforcement being opt-in is what bounds it — an adopter who would rather over-serve leaves the meter
+* advisory.
+*/
+async function meterLimit(c, meter) {
+	const resolver = c.var.entitlements;
+	if (!resolver?.meterLimit) return { enforced: false };
+	try {
+		return await resolver.meterLimit(meter);
+	} catch (error) {
+		c.var.log?.error("meter limit resolution failed", {
+			provider: resolver.provider,
+			meter,
+			cause: messageOf(error)
+		});
+		throw new InternalError({
+			message: "Usage could not be checked, so nothing was written.",
+			action: "Read the preceding log line for why the allowance read failed.",
+			detail: `${resolver.provider} threw resolving the ${meter} meter's ceiling; refusing rather than serving unbounded.`
+		});
+	}
+}
+//#endregion
+export { feature, meterLimit, quota };

package/dist/entitlement/entitlement.d.ts

@@ -66,7 +66,48 @@ export interface EntitlementResolver {
      * See {@link EntitlementHolder} for why this is a label and a tenant rather than the holder itself.
      */
     holder?(): Promise<EntitlementHolder | undefined>;
+    /**
+     * How many of `name` the current caller's holder may have — a whole number, or `null` for unlimited.
+     * Optional: a provider with no allowances omits it, and {@link import("./allowance").quota} refuses
+     * rather than inventing a number. A provider throws for a name it does not declare, never answers 0.
+     */
+    quota?(name: string): Promise<number | null>;
+    /** Whether `name` is on for the current caller's holder. Never null. Optional, as {@link quota} is. */
+    feature?(name: string): Promise<boolean>;
+    /**
+     * The ceiling a capability that counts its own rows enforces for `meter` — storage's bytes, media's
+     * items — or `{ enforced: false }` where the provider binds no ceiling to it. Optional, and absent is
+     * `{ enforced: false }`: a capability composed with no provider keeps its own configured behavior.
+     */
+    meterLimit?(meter: string): Promise<MeterLimit>;
 }
+/**
+ * What a provider says about one meter for the current caller: whether it binds a ceiling at all, and if
+ * it does, what the ceiling is and whose rows it covers. `limit: null` is unlimited — an enforced meter on
+ * a subject whose plan or override says so.
+ *
+ * Two states rather than a nullable number, because "this meter is advisory here" and "this subject is
+ * unlimited" are different facts and a capability must fall back to its own configured ceiling on the
+ * first and never on the second.
+ *
+ * **An enforced ceiling says which rows it is the whole of**, because a ceiling counted against the wrong
+ * rows is a different allowance. Under organization billing the plan's 10 GB is the company's: counted
+ * against one member's files it becomes 10 GB per member, and a paid quota is bypassed by an invitation.
+ * So `tenant` is the organization the ceiling was resolved for, exactly as {@link EntitlementHolder.tenant}
+ * is, and a capability sums every row it holds for that tenant, whoever wrote it. `null` means the holder
+ * is not a tenant: the ceiling is the caller's own, and the caller's rows are what count.
+ *
+ * It is a counting key, never a gate. A capability that would write a row for a different tenant than the
+ * one the ceiling covers refuses the write — that row would sit outside the sum, and under-counting has no
+ * recovery.
+ */
+export type MeterLimit = {
+    readonly enforced: false;
+} | {
+    readonly enforced: true;
+    readonly limit: number | null;
+    readonly tenant: string | null;
+};
 /**
  * How a resolver's holder appears in a denial's `detail` and on the denial's audit row — and **nothing a
  * gate may compare**.

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

@@ -1 +1 @@
-{"version":3,"file":"entitlement.d.ts","sourceRoot":"","sources":["../../src/entitlement/entitlement.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,eAAO,MAAM,cAAc,aAUxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;;;;;iBAqBuF,CAAC;AAChH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGpF;AAED,2GAA2G;AAC3G,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAMnG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wGAAwG;IACxG,IAAI,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACxC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sGAAsG;IACtG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAGnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,uBAAuB,CAAC"}
+{"version":3,"file":"entitlement.d.ts","sourceRoot":"","sources":["../../src/entitlement/entitlement.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,eAAO,MAAM,cAAc,aAUxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;;;;;iBAqBuF,CAAC;AAChH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGpF;AAED,2GAA2G;AAC3G,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAMnG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wGAAwG;IACxG,IAAI,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACxC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;IAClD;;;;OAIG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,uGAAuG;IACvG,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC;;;;OAIG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sGAAsG;IACtG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAGnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,uBAAuB,CAAC"}

package/dist/entitlement/meter.d.ts

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../capability/capability";
+import type { Logger } from "../logger/logger";
+/**
+ * The usage-meter seam — how a capability that writes the rows a meter counts asks whether one more is
+ * allowed, when there is no request to ask through.
+ *
+ * `@pithy-sh/email` enqueues from a route, from a Workflow step and from a cron, and only the first has a
+ * `c.var.entitlements`. So the meter it charges is found the way the ledger is found — among the composed
+ * capabilities, by a structural predicate — and it is handed the holder explicitly. Nothing here imports the
+ * provider: an email capability composed with no payments finds no meter and enqueues as it always did.
+ *
+ * **A meter refuses; it never bills.** `charge` either records the use or throws the provider's own refusal
+ * (`payments/quota_exceeded`, 402). What it counted is never reported to a store — the kit does not sell
+ * overage — so this seam has no way to read a count back out.
+ */
+/** Who a charge is against: the holder pair, exactly as the provider keys it. */
+export interface MeterSubject {
+    /** The kind of holder — `user` or `organization` under `@pithy-sh/payments`. */
+    readonly subjectType: string;
+    /** The holder's id. */
+    readonly subjectId: string;
+}
+/** One charge against one meter. */
+export interface MeterCharge {
+    /** Who uses it. */
+    readonly subject: MeterSubject;
+    /** Which meter — `emails`. */
+    readonly meter: string;
+    /** How many. A whole number from 1. */
+    readonly amount: number;
+    /** The clock. Defaults to now. */
+    readonly now?: Date;
+    /** Where a refused or failed charge is logged. Optional; the provider logs through its own when absent. */
+    readonly log?: Logger;
+}
+/** The meter a provider exposes. */
+export interface UsageMeter {
+    /** The capability answering — `payments`. */
+    readonly provider: string;
+    /**
+     * Record `amount` of `meter` against `subject`, or refuse. An advisory meter records nothing and refuses
+     * nothing. **A charge that cannot be checked refuses**, because under-counting has no recovery.
+     */
+    charge(env: Record<string, unknown>, charge: MeterCharge): Promise<void>;
+}
+/** A composed capability that provides a meter. */
+export interface UsageMeterProvider extends Capability {
+    /** The meter. */
+    readonly usageMeter: UsageMeter;
+}
+/** Whether a composed capability provides a usage meter. Structural, so no provider package is imported. */
+export declare function isUsageMeterProvider(capability: Capability): capability is UsageMeterProvider;
+/** The composed usage meter, or undefined when nothing composed provides one. */
+export declare function composedUsageMeter(capabilities: readonly Capability[]): UsageMeter | undefined;
+//# sourceMappingURL=meter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../src/entitlement/meter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;;;;;;;;;GAYG;AAEH,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IACpB,2GAA2G;IAC3G,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,iBAAiB;IACjB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED,4GAA4G;AAC5G,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,kBAAkB,CAG7F;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,GAAG,SAAS,CAE9F"}

package/dist/entitlement/meter.js

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/entitlement/meter.ts
+/** Whether a composed capability provides a usage meter. Structural, so no provider package is imported. */
+function isUsageMeterProvider(capability) {
+	return typeof capability.usageMeter?.charge === "function";
+}
+/** The composed usage meter, or undefined when nothing composed provides one. */
+function composedUsageMeter(capabilities) {
+	return capabilities.find(isUsageMeterProvider)?.usageMeter;
+}
+//#endregion
+export { composedUsageMeter, isUsageMeterProvider };

package/dist/error/extend.d.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import type { MessageParams } from "../i18n/catalog";
+import type { UnmarkedString } from "../privacy/types";
 import type { ErrorPayload, KitErrorDomain } from "./payload";
 import { ExtendedErrorPayload } from "./payload";
 /**
@@ -84,11 +85,11 @@ export declare function defineErrorPayload<const Code extends `${string}/${strin
     /** The HTTP status this code maps to. A 4xx or a 5xx — an error is not a success. */
     status: number;
     /** Public, safe-to-expose summary. Sent to clients and shown in the terminal. */
-    message: string;
-    /** Operator remediation hint. Becomes the CLI action line. Never sent to a client. */
-    action?: string;
-    /** Internal context for logs + audit. NEVER serialized to clients — the HTTP codec strips it. */
-    detail?: string;
+    message: UnmarkedString;
+    /** Operator remediation hint. Becomes the CLI action line. Never sent to a client. Never a marked value (#132). */
+    action?: UnmarkedString;
+    /** Internal context for logs + audit. NEVER serialized to clients — the HTTP codec strips it. Never a marked value (#132). */
+    detail?: UnmarkedString;
     /**
      * Values a translating client interpolates into its own wording for this code. Client-facing:
      * these cross the boundary with `message`, unlike `action` and `detail`.

package/dist/error/extend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extend.d.ts","sourceRoot":"","sources":["../../src/error/extend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAMjD;;;;GAIG;AACH,KAAK,cAAc,CAAC,IAAI,SAAS,MAAM,IAAI,IAAI,SAAS,GAAG,cAAc,IAAI,MAAM,EAAE,GACjF;IAAE,IAAI,EAAE,2EAA2E,CAAA;CAAE,GACrF,OAAO,CAAC;AAEZ;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACrG,oBAAoB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACrC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,EAClE,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,IAAI,GACT,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,CAEjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,EACzE,OAAO,EAAE;IACP,uGAAuG;IACvG,IAAI,EAAE,IAAI,CAAC;IACX,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,GAAG,cAAc,CAAC,IAAI,CAAC,GACvB,cAAc,CAAC,IAAI,CAAC,CAiBtB"}
+{"version":3,"file":"extend.d.ts","sourceRoot":"","sources":["../../src/error/extend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAMjD;;;;GAIG;AACH,KAAK,cAAc,CAAC,IAAI,SAAS,MAAM,IAAI,IAAI,SAAS,GAAG,cAAc,IAAI,MAAM,EAAE,GACjF;IAAE,IAAI,EAAE,2EAA2E,CAAA;CAAE,GACrF,OAAO,CAAC;AAEZ;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACrG,oBAAoB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACrC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,EAClE,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,IAAI,GACT,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,CAEjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,EACzE,OAAO,EAAE;IACP,uGAAuG;IACvG,IAAI,EAAE,IAAI,CAAC;IACX,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,OAAO,EAAE,cAAc,CAAC;IACxB,mHAAmH;IACnH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,8HAA8H;IAC9H,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,GAAG,cAAc,CAAC,IAAI,CAAC,GACvB,cAAc,CAAC,IAAI,CAAC,CAiBtB"}