@pithy-sh/core 0.13.0 → 0.15.0

package/dist/processing/activity.js

@@ -0,0 +1,161 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError, fromZodError } from "../error/pithyError.js";
+import { PrivacyClassName } from "../privacy/classes.js";
+import { ConsentPurposeId } from "../consent/purpose.js";
+import { LegalBasis } from "./vocabulary.js";
+import { z } from "zod";
+//#region src/processing/activity.ts
+/**
+* Processing activities: what a Worker does with personal data, why, and on what legal basis — the declarations the
+* GDPR Article 30 record is derived from.
+*
+* ## Declared where the processing is
+*
+* A capability states the activities it performs, under its own `name` (`auth.account`), the rule consent purposes,
+* tables and error codes follow. The adopter adds their own in the `processing` block of a Worker's
+* `pithy.config.ts`, and may replace a capability's legal basis there.
+*
+* ## A missing basis is a gap, never a guess
+*
+* `legalBasis` is optional. An activity without one is reported as a gap in the record, and nothing fills it in.
+*/
+/** An activity id: `<domain>.<name>`, lowercase, the domain being the declaring capability's name. */
+const ProcessingActivityId = z.string().regex(/^[a-z][a-z0-9-]*\.[a-z][a-z0-9_.-]*$/, "A processing activity id is `<domain>.<name>`: lowercase, the domain being the declaring capability's name.").max(128).describe("A processing activity id, `<domain>.<name>` — `auth.account`. The domain is the declaring capability's name, or the adopter's own domain for an activity declared in `pithy.config.ts`.");
+/** Someone outside the Worker's own code who receives personal data for an activity. */
+const ProcessingRecipient = z.object({
+	name: z.string().min(1).max(120).describe("Who receives it, as an auditor would name them — `Stripe`, `Cloudflare Email Service`."),
+	receives: z.string().min(1).max(500).describe("What they receive, in one sentence — `The buyer's email address and what they bought.`"),
+	classes: z.array(PrivacyClassName).default([]).describe("The data classes in what they receive — `pii`, `phi`, or an adopter's own.")
+}).describe("One recipient of personal data: who it is, what it receives, and the classes in it.");
+/** A consent purpose belongs with a consent basis and nowhere else. */
+function consentPurposeNeedsConsent(value, ctx) {
+	if (value.consentPurpose !== void 0 && value.legalBasis !== "consent") ctx.addIssue({
+		code: "custom",
+		path: ["consentPurpose"],
+		message: "`consentPurpose` names the purpose a `consent` basis rests on. Set `legalBasis` to `consent`, or drop it."
+	});
+}
+/** One processing activity, as a capability or the adopter declares it. */
+const ProcessingActivity = z.object({
+	id: ProcessingActivityId,
+	purpose: z.string().min(1).max(500).describe("Why the data is processed, in one sentence an auditor reads — `Keep an account and sign its holder in.`"),
+	classes: z.array(PrivacyClassName).default([]).describe("The data classes the activity uses — `pii`, `phi`, or an adopter's own. Cross-checked against the classes the Worker's schemas store."),
+	legalBasis: LegalBasis.optional().describe("The lawful basis it rests on. Absent is reported as a gap in the processing record, never filled in."),
+	consentPurpose: ConsentPurposeId.optional().describe("For a `consent` basis, the consent purpose the activity rests on — `email.marketing`. The record cites its grant counts."),
+	recipients: z.array(ProcessingRecipient).default([]).describe("Who receives the data beyond Cloudflare, which the record always lists — a payment rail, a mail provider. Built from the resolved config, so a rail that is off is not named.")
+}).superRefine(consentPurposeNeedsConsent).describe("One processing activity: its purpose, the data classes it uses, its legal basis and its recipients.");
+/** The adopter's replacement for a capability's legal basis. */
+const ProcessingOverride = z.object({
+	legalBasis: LegalBasis.describe("The basis that replaces the capability's own."),
+	consentPurpose: ConsentPurposeId.optional().describe("For a `consent` basis, the consent purpose it rests on. Left out, a capability's own purpose is kept.")
+}).strict().superRefine(consentPurposeNeedsConsent).describe("A legal basis the adopter states for a capability's activity, replacing the one it declares.");
+/** The `processing` block, as a Worker's `pithy.config.ts` writes it. */
+const ProcessingPolicy = z.object({
+	activities: z.array(ProcessingActivity).optional().describe("Your own processing activities, beside the ones composed capabilities declare. Each under your own domain."),
+	overrides: z.record(ProcessingActivityId, ProcessingOverride).optional().describe("A legal basis per capability activity, replacing the one it declares: `{ \"auth.account\": { legalBasis: \"legitimate-interests\" } }`.")
+}).strict().describe("What this Worker does with personal data beyond what its capabilities declare, and the bases you state.");
+/** The domain half of an activity id: `auth` for `auth.account`. */
+function activityDomain(id) {
+	const dot = id.indexOf(".");
+	return dot === -1 ? id : id.slice(0, dot);
+}
+/**
+* Parse one declarer's activities and refuse what the record could not attribute: an invalid activity, one under a
+* domain that is not the declarer's, or two with one id. `domain` is the declaring capability's name, or `null` for
+* the adopter's own, which may use any domain but a reserved one.
+*/
+function parseProcessingActivities(declarer, activities, domain, reserved = /* @__PURE__ */ new Set()) {
+	const seen = /* @__PURE__ */ new Set();
+	return activities.map((input) => {
+		const parsed = ProcessingActivity.safeParse(input);
+		if (!parsed.success) throw new ValidationError({
+			message: `${declarer} declares a processing activity that is not valid: ${parsed.error.issues[0]?.message ?? "invalid"}.`,
+			action: "Give it an id of the form `<domain>.<name>` and a purpose; name a consent purpose only under a consent basis."
+		});
+		const activity = parsed.data;
+		const own = activityDomain(activity.id);
+		if (domain !== null && own !== domain) throw new ValidationError({
+			message: `The ${declarer} capability declares the processing activity "${activity.id}" outside its own domain.`,
+			action: `Name it under ${domain}. — a capability declares activities only under its own name.`
+		});
+		if (domain === null && reserved.has(own)) throw new ValidationError({
+			message: `The processing activity "${activity.id}" is under ${own}., which a composed capability owns.`,
+			action: "Name your own activities under your own domain, such as your app's name."
+		});
+		if (seen.has(activity.id)) throw new ValidationError({
+			message: `${declarer} declares the processing activity "${activity.id}" twice.`,
+			action: "Declare each activity once."
+		});
+		seen.add(activity.id);
+		return activity;
+	});
+}
+/** Parse a `processing` block, or refuse it naming what is wrong. `undefined` is the empty policy. */
+function parseProcessingPolicy(input) {
+	if (input === void 0) return {};
+	const parsed = ProcessingPolicy.safeParse(input);
+	if (!parsed.success) throw fromZodError(parsed.error, {
+		message: "The processing block in pithy.config.ts does not parse.",
+		action: "Fix the field named, then deploy again."
+	});
+	return parsed.data;
+}
+/** One declared activity, before any override. */
+function resolved(activity, declaredBy, source) {
+	return {
+		id: activity.id,
+		purpose: activity.purpose,
+		classes: [...activity.classes],
+		legalBasis: activity.legalBasis ?? null,
+		basisSource: activity.legalBasis === void 0 ? null : source,
+		consentPurpose: activity.consentPurpose ?? null,
+		recipients: activity.recipients.map((recipient) => ({
+			...recipient,
+			classes: [...recipient.classes]
+		})),
+		declaredBy
+	};
+}
+/**
+* Every activity as it takes effect over a composition: each capability's, in composition order, then the adopter's,
+* with the block's overrides applied. Refuses an adopter activity under a composed capability's domain, an id declared
+* twice, and an override naming an activity no composed capability declares. Called when a Worker assembles.
+*/
+function resolveProcessing(policy, capabilities) {
+	const reserved = new Set(capabilities.map((capability) => capability.name));
+	const own = parseProcessingActivities("pithy.config.ts", policy.activities ?? [], null, reserved);
+	const declared = capabilities.flatMap((capability) => (capability.processing ?? []).map((activity) => resolved(activity, capability.name, "capability")));
+	const ids = /* @__PURE__ */ new Set();
+	for (const activity of declared) {
+		if (ids.has(activity.id)) throw new ValidationError({
+			message: `The processing activity "${activity.id}" is declared twice.`,
+			action: "Declare each activity once."
+		});
+		ids.add(activity.id);
+	}
+	const overrides = policy.overrides ?? {};
+	for (const id of Object.keys(overrides)) {
+		if (own.some((activity) => activity.id === id)) throw new ValidationError({
+			message: `The processing block overrides "${id}", which is declared in the same block.`,
+			action: `State its legal basis on the activity itself.`
+		});
+		if (!ids.has(id)) throw new ValidationError({
+			message: `The processing block overrides "${id}", which no composed capability declares.`,
+			action: "Name an activity a composed capability declares. `GET /control-plane/processing` lists them."
+		});
+	}
+	return [...declared.map((activity) => {
+		const override = overrides[activity.id];
+		if (override === void 0) return activity;
+		const consentPurpose = override.legalBasis === "consent" ? override.consentPurpose ?? activity.consentPurpose : null;
+		return {
+			...activity,
+			legalBasis: override.legalBasis,
+			basisSource: "config",
+			consentPurpose
+		};
+	}), ...own.map((activity) => resolved(activity, "config", "config"))];
+}
+//#endregion
+export { ProcessingActivity, ProcessingActivityId, ProcessingOverride, ProcessingPolicy, ProcessingRecipient, activityDomain, parseProcessingActivities, parseProcessingPolicy, resolveProcessing };

package/dist/processing/composed.d.ts

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../capability/capability";
+import { type ResolvedActivity } from "./activity";
+/**
+ * The processing activities as this Worker resolved them at assembly, reachable from module scope, so the control
+ * plane reads the same record `createBackend` refused or accepted. One Worker assembles one backend; a second assembly
+ * in one isolate replaces the first wholesale, as `../retention/composed.ts` does for the retention policy.
+ */
+/** Parse and resolve a Worker's `processing` block over what it composes, or refuse it. */
+export declare function effectiveProcessing(block: unknown, capabilities: readonly Capability[]): ResolvedActivity[];
+/** Record the resolved activities. Called once by `createBackend`. */
+export declare function recordProcessing(activities: readonly ResolvedActivity[]): void;
+/** Forget them. For a test that needs the un-assembled state back. */
+export declare function forgetProcessing(): void;
+/** The resolved activities, or `null` before any backend has been assembled in this isolate. */
+export declare function composedProcessing(): readonly ResolvedActivity[] | null;
+//# sourceMappingURL=composed.d.ts.map

package/dist/processing/composed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composed.d.ts","sourceRoot":"","sources":["../../src/processing/composed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAyB,KAAK,gBAAgB,EAAqB,MAAM,YAAY,CAAC;AAE7F;;;;GAIG;AAEH,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,gBAAgB,EAAE,CAE3G;AAID,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAE9E;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,gGAAgG;AAChG,wBAAgB,kBAAkB,IAAI,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAEvE"}

package/dist/processing/composed.js

@@ -0,0 +1,28 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { parseProcessingPolicy, resolveProcessing } from "./activity.js";
+//#region src/processing/composed.ts
+/**
+* The processing activities as this Worker resolved them at assembly, reachable from module scope, so the control
+* plane reads the same record `createBackend` refused or accepted. One Worker assembles one backend; a second assembly
+* in one isolate replaces the first wholesale, as `../retention/composed.ts` does for the retention policy.
+*/
+/** Parse and resolve a Worker's `processing` block over what it composes, or refuse it. */
+function effectiveProcessing(block, capabilities) {
+	return resolveProcessing(parseProcessingPolicy(block), capabilities);
+}
+let recorded = null;
+/** Record the resolved activities. Called once by `createBackend`. */
+function recordProcessing(activities) {
+	recorded = activities;
+}
+/** Forget them. For a test that needs the un-assembled state back. */
+function forgetProcessing() {
+	recorded = null;
+}
+/** The resolved activities, or `null` before any backend has been assembled in this isolate. */
+function composedProcessing() {
+	return recorded;
+}
+//#endregion
+export { composedProcessing, effectiveProcessing, forgetProcessing, recordProcessing };

package/dist/processing/vocabulary.d.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/** The processing record's closed vocabularies, apart from the walk that fills them, so a browser may import them. */
+/** What kind of gap the record names. */
+export declare const PROCESSING_GAP_KINDS: readonly ["no-legal-basis", "no-consent-purpose", "class-not-stored", "class-unclaimed", "phi-not-covered", "no-standing-grant"];
+export type ProcessingGapKindId = (typeof PROCESSING_GAP_KINDS)[number];
+/** Where a recipient came from. */
+export declare const RECIPIENT_SOURCES: readonly ["platform", "binding", "declared"];
+export type RecipientSource = (typeof RECIPIENT_SOURCES)[number];
+/** Where a legal basis came from: the declaring capability, or the `processing` block. */
+export declare const BASIS_SOURCES: readonly ["capability", "config"];
+export type BasisSource = (typeof BASIS_SOURCES)[number];
+/** The six lawful bases of GDPR Article 6(1), (a) to (f), in that order. */
+export declare const LEGAL_BASES: readonly ["consent", "contract", "legal-obligation", "vital-interests", "public-task", "legitimate-interests"];
+/** One lawful basis for processing. */
+export declare const LegalBasis: z.ZodEnum<{
+    consent: "consent";
+    contract: "contract";
+    "legal-obligation": "legal-obligation";
+    "legitimate-interests": "legitimate-interests";
+    "public-task": "public-task";
+    "vital-interests": "vital-interests";
+}>;
+export type LegalBasis = z.infer<typeof LegalBasis>;
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/processing/vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.d.ts","sourceRoot":"","sources":["../../src/processing/vocabulary.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,sHAAsH;AAEtH,yCAAyC;AACzC,eAAO,MAAM,oBAAoB,YAC/B,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,CACX,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,mCAAmC;AACnC,eAAO,MAAM,iBAAiB,YAAI,UAAU,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAC9E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,0FAA0F;AAC1F,eAAO,MAAM,aAAa,YAAI,YAAY,EAAE,QAAQ,CAAU,CAAC;AAC/D,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,4EAA4E;AAC5E,eAAO,MAAM,WAAW,YACtB,SAAS,EACT,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,sBAAsB,CACd,CAAC;AAEX,uCAAuC;AACvC,eAAO,MAAM,UAAU;;;;;;;EAIpB,CAAC;AACJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/processing/vocabulary.js

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/processing/vocabulary.ts
+/** The processing record's closed vocabularies, apart from the walk that fills them, so a browser may import them. */
+/** What kind of gap the record names. */
+const PROCESSING_GAP_KINDS = [
+	"no-legal-basis",
+	"no-consent-purpose",
+	"class-not-stored",
+	"class-unclaimed",
+	"phi-not-covered",
+	"no-standing-grant"
+];
+/** Where a recipient came from. */
+const RECIPIENT_SOURCES = [
+	"platform",
+	"binding",
+	"declared"
+];
+/** Where a legal basis came from: the declaring capability, or the `processing` block. */
+const BASIS_SOURCES = ["capability", "config"];
+/** The six lawful bases of GDPR Article 6(1), (a) to (f), in that order. */
+const LEGAL_BASES = [
+	"consent",
+	"contract",
+	"legal-obligation",
+	"vital-interests",
+	"public-task",
+	"legitimate-interests"
+];
+/** One lawful basis for processing. */
+const LegalBasis = z.enum(LEGAL_BASES).describe("The lawful basis of GDPR Article 6(1): `consent` (a), `contract` (b), `legal-obligation` (c), `vital-interests` (d), `public-task` (e) or `legitimate-interests` (f). A `consent` basis names the consent purpose it rests on.");
+//#endregion
+export { BASIS_SOURCES, LEGAL_BASES, LegalBasis, PROCESSING_GAP_KINDS, RECIPIENT_SOURCES };

package/dist/queue/consumer.d.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { ExecutionContext } from "@cloudflare/workers-types";
+import type { Logger } from "../logger/logger";
+/**
+ * **A capability's queue consumer, and how one Worker's `queue` export finds it (#824).**
+ *
+ * A Worker has one `queue` handler for every queue it consumes, the way it has one `email` and one `scheduled`.
+ * Which capability a message belongs to cannot be read off the batch: `batch.queue` is the provisioned name,
+ * `<project>-<env>-<thing>`, which no capability knows at runtime and which a long name truncates. So the message
+ * says it: every body a capability sends carries its own name under {@link QUEUE_CAPABILITY_FIELD}, built with
+ * {@link queueBody}, and the dispatcher hands each capability exactly the messages that name it.
+ *
+ * **A message no composed capability claims is acknowledged and logged**, never retried. Retrying cannot make a
+ * capability appear, so a retry would only walk the message to its dead-letter queue and count it as a delivery
+ * failure it never was.
+ *
+ * **A handler that throws costs its own messages, and nothing else.** Every other capability's messages are still
+ * handed over; the first failure is rethrown after the pass, so the invocation is recorded as failed and the runtime
+ * retries what was neither acknowledged nor retried.
+ */
+/**
+ * One delivered message, as much of the runtime's as a consumer touches. Stated here rather than imported, so the
+ * Workers types' `Message` — a word half the kit uses for other things — never becomes a name the kit reaches for.
+ */
+export interface QueueMessage {
+    /** The runtime's id for this delivery. */
+    readonly id: string;
+    /** The body as sent. */
+    readonly body: unknown;
+    /** How many times this message has been delivered, this one included. Starts at 1. */
+    readonly attempts: number;
+    /** Settle it: delivered, never to be seen again. */
+    ack(): void;
+    /** Settle it: deliver it again after the delay, or to the dead-letter queue once retries are spent. */
+    retry(options?: {
+        delaySeconds?: number;
+    }): void;
+}
+/** One batch the runtime hands a Worker's `queue` export. */
+export interface QueueBatch {
+    /** The provisioned queue's name. */
+    readonly queue: string;
+    /** Its messages. */
+    readonly messages: readonly QueueMessage[];
+}
+/** The body field that names the capability a queue message belongs to. */
+export declare const QUEUE_CAPABILITY_FIELD = "capability";
+/** A capability's queue handler: the messages that name it, from one batch. */
+export type CapabilityQueueHandler = (messages: readonly QueueMessage[], env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
+/** A message body, stamped with the capability it belongs to so the Worker's one `queue` export can route it. */
+export declare function queueBody<const Capability extends string, const Body extends Record<string, unknown>>(capability: Capability, body: Body): Body & {
+    capability: Capability;
+};
+/** The capability a message body names, or null when it names none. */
+export declare function queueMessageCapability(body: unknown): string | null;
+/** Hand each composed capability the messages of one batch that name it. */
+export declare function dispatchQueueBatch(batch: QueueBatch, handlers: ReadonlyMap<string, CapabilityQueueHandler>, env: Record<string, unknown>, ctx: ExecutionContext, log?: Pick<Logger, "warn">): Promise<void>;
+//# sourceMappingURL=consumer.d.ts.map

package/dist/queue/consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../../src/queue/consumer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,GAAG,IAAI,IAAI,CAAC;IACZ,uGAAuG;IACvG,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAClD;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD,+EAA+E;AAC/E,MAAM,MAAM,sBAAsB,GAAG,CACnC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,gBAAgB,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,iHAAiH;AACjH,wBAAgB,SAAS,CAAC,KAAK,CAAC,UAAU,SAAS,MAAM,EAAE,KAAK,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnG,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,IAAI,GACT,IAAI,GAAG;IAAE,UAAU,EAAE,UAAU,CAAA;CAAE,CAEnC;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAInE;AAED,4EAA4E;AAC5E,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,EACrD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,gBAAgB,EACrB,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,GACzB,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/queue/consumer.js

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/queue/consumer.ts
+/** The body field that names the capability a queue message belongs to. */
+const QUEUE_CAPABILITY_FIELD = "capability";
+/** A message body, stamped with the capability it belongs to so the Worker's one `queue` export can route it. */
+function queueBody(capability, body) {
+	return {
+		...body,
+		capability
+	};
+}
+/** The capability a message body names, or null when it names none. */
+function queueMessageCapability(body) {
+	if (typeof body !== "object" || body === null) return null;
+	const value = body[QUEUE_CAPABILITY_FIELD];
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+/** Hand each composed capability the messages of one batch that name it. */
+async function dispatchQueueBatch(batch, handlers, env, ctx, log) {
+	const claimed = /* @__PURE__ */ new Map();
+	for (const message of batch.messages) {
+		const capability = queueMessageCapability(message.body);
+		if (capability === null || !handlers.has(capability)) {
+			log?.warn("queue message unclaimed", {
+				queue: batch.queue,
+				messageId: message.id,
+				capability
+			});
+			message.ack();
+			continue;
+		}
+		const list = claimed.get(capability) ?? [];
+		list.push(message);
+		claimed.set(capability, list);
+	}
+	const failures = [];
+	for (const [capability, messages] of claimed) try {
+		await handlers.get(capability)?.(messages, env, ctx);
+	} catch (error) {
+		failures.push(error);
+	}
+	if (failures[0] !== void 0) throw failures[0];
+}
+//#endregion
+export { QUEUE_CAPABILITY_FIELD, dispatchQueueBatch, queueBody, queueMessageCapability };

package/dist/retention/composed.d.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../capability/capability";
+import type { PurgeSubject } from "../capability/purge";
+import { type EffectiveRetention, type RetentionComposition } from "./policy";
+/**
+ * **The retention policy as this Worker resolved it, reachable from module scope** — so a purge, a prune and
+ * an inactivity pass, each running in a Workflow the runtime constructs with `env` alone, read the same policy the
+ * routes do. The reasoning, and the cost, are `../capability/composition.ts`'s: `createBackend` runs at module load,
+ * one Worker assembles one backend, and a second assembly in one isolate replaces the first wholesale.
+ */
+/**
+ * What resolving reads off a composition: each capability's window, and every lifecycle action it audits — the
+ * transitions it declares, then the ones its erasure records.
+ */
+export declare function retentionComposition(capabilities: readonly Capability[]): RetentionComposition;
+/**
+ * Parse and resolve a Worker's `retention` block over what it composes, or refuse it. What `createBackend` calls at
+ * assembly and `pithy doctor` calls on the same config, so both report — or refuse — one policy.
+ */
+export declare function effectiveRetention(block: unknown, capabilities: readonly Capability[]): EffectiveRetention;
+/** Record the resolved policy. Called once by `createBackend`, beside `recordComposition`. */
+export declare function recordRetention(retention: EffectiveRetention): void;
+/** Forget it. For a test that needs the un-assembled state back. */
+export declare function forgetRetention(): void;
+/**
+ * The resolved policy — or, before any assembly, `null`. A caller with a capability's own default in hand falls back
+ * to it, which is exactly what an empty block means.
+ */
+export declare function composedRetention(): EffectiveRetention | null;
+/**
+ * The privacy classes a subject's rows hold: every class marked on a schema of a capability that erases that
+ * subject in its purge — the capabilities that hold rows keyed to the subject. What the class ages are read against:
+ * an account holds `pii` when a capability holding its rows marks a field `pii`.
+ */
+export declare function subjectClasses(capabilities: readonly Capability[], subject: PurgeSubject): string[];
+//# sourceMappingURL=composed.d.ts.map

package/dist/retention/composed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composed.d.ts","sourceRoot":"","sources":["../../src/retention/composed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,KAAK,kBAAkB,EAAwB,KAAK,oBAAoB,EAAoB,MAAM,UAAU,CAAC;AAEtH;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,oBAAoB,CAS9F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,kBAAkB,CAE1G;AAKD,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAEnE;AAED,oEAAoE;AACpE,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,GAAG,IAAI,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAUnG"}

package/dist/retention/composed.js

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { privacyInventory } from "../privacy/inventory.js";
+import { parseRetentionPolicy, resolveRetention } from "./policy.js";
+//#region src/retention/composed.ts
+/**
+* **The retention policy as this Worker resolved it, reachable from module scope** — so a purge, a prune and
+* an inactivity pass, each running in a Workflow the runtime constructs with `env` alone, read the same policy the
+* routes do. The reasoning, and the cost, are `../capability/composition.ts`'s: `createBackend` runs at module load,
+* one Worker assembles one backend, and a second assembly in one isolate replaces the first wholesale.
+*/
+/**
+* What resolving reads off a composition: each capability's window, and every lifecycle action it audits — the
+* transitions it declares, then the ones its erasure records.
+*/
+function retentionComposition(capabilities) {
+	return {
+		purgeWindows: capabilities.flatMap((capability) => capability.purgeWindow ? [capability.purgeWindow] : []),
+		lifecycleActions: capabilities.flatMap((capability) => {
+			const actions = capability.erasureRecords?.auditActions;
+			const erasure = actions ? [
+				...actions.deleted,
+				actions.step,
+				actions.failed,
+				actions.purged
+			] : [];
+			return [...capability.lifecycleAuditActions ?? [], ...erasure];
+		})
+	};
+}
+/**
+* Parse and resolve a Worker's `retention` block over what it composes, or refuse it. What `createBackend` calls at
+* assembly and `pithy doctor` calls on the same config, so both report — or refuse — one policy.
+*/
+function effectiveRetention(block, capabilities) {
+	return resolveRetention(parseRetentionPolicy(block), retentionComposition(capabilities));
+}
+/** The resolved policy, or null before any backend has been assembled in this isolate. */
+let recorded = null;
+/** Record the resolved policy. Called once by `createBackend`, beside `recordComposition`. */
+function recordRetention(retention) {
+	recorded = retention;
+}
+/** Forget it. For a test that needs the un-assembled state back. */
+function forgetRetention() {
+	recorded = null;
+}
+/**
+* The resolved policy — or, before any assembly, `null`. A caller with a capability's own default in hand falls back
+* to it, which is exactly what an empty block means.
+*/
+function composedRetention() {
+	return recorded;
+}
+/**
+* The privacy classes a subject's rows hold: every class marked on a schema of a capability that erases that
+* subject in its purge — the capabilities that hold rows keyed to the subject. What the class ages are read against:
+* an account holds `pii` when a capability holding its rows marks a field `pii`.
+*/
+function subjectClasses(capabilities, subject) {
+	const holders = new Set(capabilities.filter((capability) => capability.purge?.some((contribution) => contribution.subject === subject)).map((capability) => capability.name));
+	const classes = privacyInventory(capabilities).schemas.filter((schema) => holders.has(schema.capability)).flatMap((schema) => schema.fields.map((field) => field.class));
+	return [...new Set(classes)].sort();
+}
+//#endregion
+export { composedRetention, effectiveRetention, forgetRetention, recordRetention, retentionComposition, subjectClasses };

package/dist/retention/holds.d.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type HoldSubjectType, LegalHold } from "../controlPlane/data/hold";
+import { type ControlPlaneDatabase } from "../controlPlane/data/tables";
+/**
+ * **Legal holds: placing, releasing and reading them, and the one question every purge asks.**
+ *
+ * The holds live in the control plane's table in the app database, `DB`. A capability that erases — auth's purge,
+ * organization's purge, audit's prune, auth's inactivity pass — cannot import the control plane, so it asks through
+ * {@link legalHolds}, over the env its Workflow was handed, before every step that would touch a subject.
+ *
+ * **A hold that cannot be read is not an absent hold.** Only one answer reads as "nothing is held" without a row: a
+ * database that has no hold table, because no control plane ever migrated it, so nothing could have placed one. Any
+ * other failure throws, and the step that asked fails and retries rather than erasing past a hold it could not see.
+ */
+/** Who places or releases a hold: the management client's own user id. */
+export interface HoldActor {
+    readonly subject: string;
+}
+/** Place a hold. Holds stack: a second hold on one subject is its own row, released on its own. */
+export declare function placeHold(db: ControlPlaneDatabase, input: {
+    subjectType: HoldSubjectType;
+    subjectId: string | null;
+    reason: string;
+    actor: HoldActor;
+    at: Date;
+}): Promise<LegalHold>;
+/**
+ * Release a hold, with a reason. A hold already released is a conflict, never a second release: the row keeps the
+ * first one's who and why. An unknown id is a 404.
+ */
+export declare function releaseHold(db: ControlPlaneDatabase, input: {
+    id: string;
+    reason: string;
+    actor: HoldActor;
+    at: Date;
+}): Promise<LegalHold>;
+/** One hold by id, or null. */
+export declare function readHold(db: ControlPlaneDatabase, id: string): Promise<LegalHold | null>;
+/** Every hold, active first, newest first within each, at most `limit`. */
+export declare function listHolds(db: ControlPlaneDatabase, options: {
+    state?: "active" | "released";
+    limit: number;
+}): Promise<LegalHold[]>;
+/** How many holds stand. What the manifest carries. */
+export declare function countActiveHolds(db: ControlPlaneDatabase): Promise<number>;
+/** The question every purge, prune and inactivity pass asks before it touches a subject. */
+export interface LegalHolds {
+    /** Whether an active hold stands on this subject. A `null` id is the untenanted audit trail. */
+    held(subjectType: HoldSubjectType, subjectId: string | null): Promise<boolean>;
+}
+/** The app database the control plane keeps its holds in. Fixed, as the seam's own binding is. */
+export declare const HOLDS_BINDING = "DB";
+/** The holds over one env, read from {@link HOLDS_BINDING}. See the file header for what an unreadable read does. */
+export declare function legalHolds(env: Record<string, unknown>): LegalHolds;
+/**
+ * How many holds stand in this env's app database — zero where no control plane ever migrated it, since nothing
+ * could have placed one there. Any other failure throws, and the manifest reports the summary unavailable.
+ */
+export declare function standingHolds(env: Record<string, unknown>): Promise<number>;
+//# sourceMappingURL=holds.d.ts.map

package/dist/retention/holds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"holds.d.ts","sourceRoot":"","sources":["../../src/retention/holds.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,6BAA6B,CAAC;AAIrC;;;;;;;;;;GAUG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,mGAAmG;AACnG,wBAAsB,SAAS,CAC7B,EAAE,EAAE,oBAAoB,EACxB,KAAK,EAAE;IAAE,WAAW,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAC5G,OAAO,CAAC,SAAS,CAAC,CAepB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,oBAAoB,EACxB,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAChE,OAAO,CAAC,SAAS,CAAC,CA6BpB;AAED,+BAA+B;AAC/B,wBAAsB,QAAQ,CAAC,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAG9F;AAED,2EAA2E;AAC3E,wBAAsB,SAAS,CAC7B,EAAE,EAAE,oBAAoB,EACxB,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxD,OAAO,CAAC,SAAS,EAAE,CAAC,CAUtB;AAED,uDAAuD;AACvD,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAOhF;AAED,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,gGAAgG;IAChG,IAAI,CAAC,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChF;AAED,kGAAkG;AAClG,eAAO,MAAM,aAAa,OAAO,CAAC;AAQlC,qHAAqH;AACrH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAsBnE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CASjF"}