@pithy-sh/core 0.13.0 → 0.15.0

package/dist/retention/holds.js

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ConflictError, NotFoundError } from "../error/pithyError.js";
+import { SQLiteDate } from "../data/codecs.js";
+import { LegalHold } from "../controlPlane/data/hold.js";
+import { CONTROL_PLANE_HOLDS_TABLE, controlPlaneDatabase } from "../controlPlane/data/tables.js";
+//#region src/retention/holds.ts
+/** Place a hold. Holds stack: a second hold on one subject is its own row, released on its own. */
+async function placeHold(db, input) {
+	const hold = {
+		id: crypto.randomUUID(),
+		subjectType: input.subjectType,
+		subjectId: input.subjectId,
+		reason: input.reason,
+		placedBy: input.actor.subject,
+		placedAt: input.at,
+		state: "active",
+		releasedAt: null,
+		releasedBy: null,
+		releaseReason: null
+	};
+	await db.insertInto(CONTROL_PLANE_HOLDS_TABLE).values(LegalHold.encode(hold)).execute();
+	return hold;
+}
+/**
+* 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.
+*/
+async function releaseHold(db, input) {
+	const existing = await readHold(db, input.id);
+	if (!existing) throw new NotFoundError({
+		message: "No hold has that id.",
+		detail: `hold ${input.id} not found`
+	});
+	const result = await db.updateTable(CONTROL_PLANE_HOLDS_TABLE).set({
+		state: "released",
+		releasedAt: SQLiteDate.encode(input.at),
+		releasedBy: input.actor.subject,
+		releaseReason: input.reason
+	}).where("id", "=", input.id).where("state", "=", "active").executeTakeFirst();
+	if (Number(result.numUpdatedRows) === 0) throw new ConflictError({
+		message: "That hold is already released.",
+		detail: `hold ${input.id} was released before this call`
+	});
+	return {
+		...existing,
+		state: "released",
+		releasedAt: input.at,
+		releasedBy: input.actor.subject,
+		releaseReason: input.reason
+	};
+}
+/** One hold by id, or null. */
+async function readHold(db, id) {
+	const row = await db.selectFrom(CONTROL_PLANE_HOLDS_TABLE).selectAll().where("id", "=", id).executeTakeFirst();
+	return row ? LegalHold.parse(row) : null;
+}
+/** Every hold, active first, newest first within each, at most `limit`. */
+async function listHolds(db, options) {
+	let query = db.selectFrom(CONTROL_PLANE_HOLDS_TABLE).selectAll().orderBy("state", "asc").orderBy("placedAt", "desc").orderBy("id", "asc").limit(options.limit);
+	if (options.state) query = query.where("state", "=", options.state);
+	return (await query.execute()).map((row) => LegalHold.parse(row));
+}
+/** How many holds stand. What the manifest carries. */
+async function countActiveHolds(db) {
+	const row = await db.selectFrom(CONTROL_PLANE_HOLDS_TABLE).select((eb) => eb.fn.countAll().as("n")).where("state", "=", "active").executeTakeFirst();
+	return Number(row?.n ?? 0);
+}
+/** The app database the control plane keeps its holds in. Fixed, as the seam's own binding is. */
+const HOLDS_BINDING = "DB";
+/** Whether a D1 failure is the hold table not existing — a database no control plane ever migrated. */
+function noHoldTable(error) {
+	const text = error instanceof Error ? `${error.message} ${String(error.cause ?? "")}` : String(error);
+	return /no such table/i.test(text) && /pithy_controlplane_holds/i.test(text);
+}
+/** The holds over one env, read from {@link HOLDS_BINDING}. See the file header for what an unreadable read does. */
+function legalHolds(env) {
+	const binding = env["DB"];
+	if (typeof binding !== "object" || binding === null) return { held: async () => false };
+	const db = controlPlaneDatabase(binding);
+	return { held: async (subjectType, subjectId) => {
+		try {
+			let query = db.selectFrom(CONTROL_PLANE_HOLDS_TABLE).select("id").where("state", "=", "active").where("subjectType", "=", subjectType).limit(1);
+			query = subjectId === null ? query.where("subjectId", "is", null) : query.where("subjectId", "=", subjectId);
+			return (await query.execute()).length > 0;
+		} catch (error) {
+			if (noHoldTable(error)) return false;
+			throw error;
+		}
+	} };
+}
+/**
+* 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.
+*/
+async function standingHolds(env) {
+	const binding = env["DB"];
+	if (typeof binding !== "object" || binding === null) return 0;
+	try {
+		return await countActiveHolds(controlPlaneDatabase(binding));
+	} catch (error) {
+		if (noHoldTable(error)) return 0;
+		throw error;
+	}
+}
+//#endregion
+export { HOLDS_BINDING, countActiveHolds, legalHolds, listHolds, placeHold, readHold, releaseHold, standingHolds };

package/dist/retention/holdsPurge.d.ts

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { RetainingPurgeContribution } from "../capability/purge";
+/**
+ * What a person's purge means for the legal holds: **nothing is erased, and the export says so and why.**
+ *
+ * A hold names the user it preserves. The row is the record that a hold stood, from when to when and why it ended,
+ * and it is kept after release for exactly that reason; a purge the hold allowed to run does not take the record of
+ * the hold with it. The export answers for every hold placed on the person.
+ *
+ * **Only `user` holds are theirs.** One `subjectId` column names users, organizations and audit tenants, and a
+ * tenant may be named by a user's id. **And the export says that a hold stood, never who placed it or why**: the
+ * operator who placed or lifted it is another person, and the reasons are counsel's words about a matter the person
+ * may be a party to.
+ */
+/** The one sentence the purge records with this step. */
+export declare const HOLDS_PURGE_SUMMARY = "Keeps every legal hold placed on the user.";
+/** Why, in the sentence the person is told. */
+export declare const HOLDS_RETENTION_BASIS = "Kept as the record that a legal hold stood, when it was placed and why it ended.";
+/** The user contribution the control plane declares, over the app database its holds live in. */
+export declare function holdsUserPurge(database?: string): RetainingPurgeContribution;
+//# sourceMappingURL=holdsPurge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"holdsPurge.d.ts","sourceRoot":"","sources":["../../src/retention/holdsPurge.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAItE;;;;;;;;;;;GAWG;AAEH,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,+CAA+C,CAAC;AAEhF,+CAA+C;AAC/C,eAAO,MAAM,qBAAqB,qFAAqF,CAAC;AAExH,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,QAAQ,SAAO,GAAG,0BAA0B,CAqB1E"}

package/dist/retention/holdsPurge.js

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { LegalHold } from "../controlPlane/data/hold.js";
+import { CONTROL_PLANE_HOLDS_TABLE } from "../controlPlane/data/tables.js";
+import { personRowsExport } from "../capability/personRows.js";
+//#region src/retention/holdsPurge.ts
+/**
+* What a person's purge means for the legal holds: **nothing is erased, and the export says so and why.**
+*
+* A hold names the user it preserves. The row is the record that a hold stood, from when to when and why it ended,
+* and it is kept after release for exactly that reason; a purge the hold allowed to run does not take the record of
+* the hold with it. The export answers for every hold placed on the person.
+*
+* **Only `user` holds are theirs.** One `subjectId` column names users, organizations and audit tenants, and a
+* tenant may be named by a user's id. **And the export says that a hold stood, never who placed it or why**: the
+* operator who placed or lifted it is another person, and the reasons are counsel's words about a matter the person
+* may be a party to.
+*/
+/** The one sentence the purge records with this step. */
+const HOLDS_PURGE_SUMMARY = "Keeps every legal hold placed on the user.";
+/** Why, in the sentence the person is told. */
+const HOLDS_RETENTION_BASIS = "Kept as the record that a legal hold stood, when it was placed and why it ended.";
+/** The user contribution the control plane declares, over the app database its holds live in. */
+function holdsUserPurge(database = "DB") {
+	return {
+		subject: "user",
+		summary: HOLDS_PURGE_SUMMARY,
+		retain: { basis: HOLDS_RETENTION_BASIS },
+		export: personRowsExport({
+			capability: "controlplane",
+			database,
+			tables: [{
+				table: CONTROL_PLANE_HOLDS_TABLE,
+				schema: LegalHold,
+				columns: ["subjectId"],
+				match: { subjectType: "user" },
+				as: "holds",
+				omit: [
+					"placedBy",
+					"releasedBy",
+					"reason",
+					"releaseReason"
+				],
+				orderBy: "placedAt"
+			}]
+		})
+	};
+}
+//#endregion
+export { HOLDS_PURGE_SUMMARY, HOLDS_RETENTION_BASIS, holdsUserPurge };

package/dist/retention/policy.d.ts

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * **How long everything is kept, declared in one place.**
+ *
+ * A Worker's `pithy.config.ts` carries one `retention` block beside its `capabilities`, so the policy is bundled
+ * with the code that enforces it and deployed like it. Three things are governed:
+ *
+ * - **Purge windows.** How long a deleted user or organization stays restorable before its purge. Each capability
+ *   that owns a deletion keeps its own `retention.purgeAfterDays` as the default; a window stated here replaces it.
+ * - **Audit retention.** How long audit events are kept, by action prefix, with a default. Absent means forever.
+ *   The prune Workflow in `@pithy-sh/audit` removes events past their window and leaves a checkpointed tombstone.
+ * - **Class ages.** The longest an account may sit inactive while it holds a privacy class. An account untouched
+ *   for longer than the strictest class it holds is soft-deleted through the lifecycle that already exists.
+ *
+ * **The kit holds a floor under the audit trail.** No rule may keep `controlplane/*` or a lifecycle action for
+ * less than {@link AUDIT_RETENTION_FLOOR_DAYS} days, and a rule that would is refused when the config loads. The
+ * default is not a rule: a short default leaves the floored actions at the floor, and the manifest says so.
+ *
+ * Nothing here shortens anything at runtime. The policy is code, and no route changes it.
+ */
+/** A day, in ms. */
+export declare const MS_PER_DAY = 86400000;
+/** The least the kit keeps a floored audit action: a year. */
+export declare const AUDIT_RETENTION_FLOOR_DAYS = 365;
+/**
+ * The action prefixes the floor always covers, whatever is composed. The control plane's own trail — every call,
+ * every key, every hold — is the record of who managed the Worker, and it outlives any short default.
+ */
+export declare const FLOORED_AUDIT_PREFIXES: readonly ["controlplane/"];
+/**
+ * A length of time: whole days as a number, or a count and a unit — `90d`, `12w`, `18m`, `3y`. A month is thirty
+ * days and a year is 365.
+ */
+export declare const RetentionDuration: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+export type RetentionDuration = z.infer<typeof RetentionDuration>;
+/** A duration in whole days. */
+export declare function durationDays(value: RetentionDuration): number;
+/** The `retention` block, as a Worker's `pithy.config.ts` writes it. */
+export declare const RetentionPolicy: z.ZodObject<{
+    purgeWindows: z.ZodOptional<z.ZodObject<{
+        user: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        organization: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    }, z.core.$strict>>;
+    audit: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodLiteral<"forever">]>>;
+        prefixes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
+    }, z.core.$strict>>;
+    classAges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
+}, z.core.$strict>;
+export type RetentionPolicy = z.infer<typeof RetentionPolicy>;
+export type RetentionPolicyInput = z.input<typeof RetentionPolicy>;
+/** Where an effective value came from: this block, a capability's own config, or the kit's floor. */
+export declare const RetentionSource: z.ZodEnum<{
+    capability: "capability";
+    floor: "floor";
+    policy: "policy";
+}>;
+export type RetentionSource = z.infer<typeof RetentionSource>;
+/** The policy as it takes effect: every value resolved to days, and where each came from. */
+export declare const EffectiveRetention: z.ZodObject<{
+    purgeWindows: z.ZodArray<z.ZodObject<{
+        subject: z.ZodEnum<{
+            organization: "organization";
+            user: "user";
+        }>;
+        days: z.ZodNumber;
+        source: z.ZodEnum<{
+            capability: "capability";
+            floor: "floor";
+            policy: "policy";
+        }>;
+    }, z.core.$strip>>;
+    audit: z.ZodObject<{
+        defaultDays: z.ZodNullable<z.ZodNumber>;
+        floorDays: z.ZodNumber;
+        rules: z.ZodArray<z.ZodObject<{
+            prefix: z.ZodString;
+            days: z.ZodNumber;
+            source: z.ZodEnum<{
+                capability: "capability";
+                floor: "floor";
+                policy: "policy";
+            }>;
+        }, z.core.$strip>>;
+        floored: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    classAges: z.ZodArray<z.ZodObject<{
+        class: z.ZodString;
+        days: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EffectiveRetention = z.infer<typeof EffectiveRetention>;
+/** A capability's own soft-delete window, the default a policy may replace. */
+export interface PurgeWindowDefault {
+    readonly subject: "user" | "organization";
+    readonly days: number;
+}
+/** What resolving needs from the composition: each capability's window, and the lifecycle actions it audits. */
+export interface RetentionComposition {
+    /** Each composed capability's own soft-delete window, in composition order. */
+    readonly purgeWindows: readonly PurgeWindowDefault[];
+    /** Every lifecycle audit action the composed capabilities record — the floor covers each. */
+    readonly lifecycleActions: readonly string[];
+}
+/**
+ * Parse a `retention` block, or refuse it naming what is wrong. `undefined` is the empty policy: every capability's
+ * own window, an audit trail kept forever, no class ages.
+ */
+export declare function parseRetentionPolicy(input: unknown): RetentionPolicy;
+/**
+ * The policy as it takes effect over a composition — or refused, when a rule would keep a floored action for less
+ * than the floor. Called when a Worker assembles, so a policy that would prune the control plane's trail early never
+ * deploys.
+ */
+export declare function resolveRetention(policy: RetentionPolicy, composition: RetentionComposition): EffectiveRetention;
+/**
+ * How many days an audit event with this action is kept, or `null` for forever. The longest matching rule decides;
+ * with none, the default. A floored action is never kept under the floor, whichever decided.
+ */
+export declare function auditWindowDays(retention: EffectiveRetention, action: string): number | null;
+/** Whether the policy prunes any audit event at all. */
+export declare function prunesAudit(retention: EffectiveRetention): boolean;
+/** The soft-delete window for a subject, in days, or `undefined` when no composed capability runs one. */
+export declare function purgeWindowDays(retention: EffectiveRetention, subject: "user" | "organization"): number | undefined;
+/**
+ * The longest an account may sit inactive given the classes it holds, in days — the strictest class age among
+ * them — or `null` when no class it holds has an age.
+ */
+export declare function inactivityDays(retention: EffectiveRetention, held: readonly string[]): number | null;
+//# sourceMappingURL=policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/retention/policy.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,oBAAoB;AACpB,eAAO,MAAM,UAAU,WAAa,CAAC;AAErC,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,YAAI,eAAe,CAAU,CAAC;AAQjE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,iDAO3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,gCAAgC;AAChC,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAI7D;AAaD,wEAAwE;AACxE,eAAO,MAAM,eAAe;;;;;;;;;;kBA0CgF,CAAC;AAC7G,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC9D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAEnE,qGAAqG;AACrG,eAAO,MAAM,eAAe;;;;EAIzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuD4E,CAAC;AAC5G,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gHAAgH;AAChH,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrD,6FAA6F;IAC7F,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAOD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAUpE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB,GAAG,kBAAkB,CA0C/G;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM5F;AAED,wDAAwD;AACxD,wBAAgB,WAAW,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAElE;AAED,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,SAAS,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,MAAM,GAAG,SAAS,CAEnH;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAGpG"}

package/dist/retention/policy.js

@@ -0,0 +1,197 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError, fromZodError } from "../error/pithyError.js";
+import { PrivacyClassName } from "../privacy/classes.js";
+import { z } from "zod";
+//#region src/retention/policy.ts
+/**
+* **How long everything is kept, declared in one place.**
+*
+* A Worker's `pithy.config.ts` carries one `retention` block beside its `capabilities`, so the policy is bundled
+* with the code that enforces it and deployed like it. Three things are governed:
+*
+* - **Purge windows.** How long a deleted user or organization stays restorable before its purge. Each capability
+*   that owns a deletion keeps its own `retention.purgeAfterDays` as the default; a window stated here replaces it.
+* - **Audit retention.** How long audit events are kept, by action prefix, with a default. Absent means forever.
+*   The prune Workflow in `@pithy-sh/audit` removes events past their window and leaves a checkpointed tombstone.
+* - **Class ages.** The longest an account may sit inactive while it holds a privacy class. An account untouched
+*   for longer than the strictest class it holds is soft-deleted through the lifecycle that already exists.
+*
+* **The kit holds a floor under the audit trail.** No rule may keep `controlplane/*` or a lifecycle action for
+* less than {@link AUDIT_RETENTION_FLOOR_DAYS} days, and a rule that would is refused when the config loads. The
+* default is not a rule: a short default leaves the floored actions at the floor, and the manifest says so.
+*
+* Nothing here shortens anything at runtime. The policy is code, and no route changes it.
+*/
+/** A day, in ms. */
+const MS_PER_DAY = 864e5;
+/** The least the kit keeps a floored audit action: a year. */
+const AUDIT_RETENTION_FLOOR_DAYS = 365;
+/**
+* The action prefixes the floor always covers, whatever is composed. The control plane's own trail — every call,
+* every key, every hold — is the record of who managed the Worker, and it outlives any short default.
+*/
+const FLOORED_AUDIT_PREFIXES = ["controlplane/"];
+/** Days per unit of a duration string. A month is thirty days and a year is 365: a policy, not a calendar. */
+const UNIT_DAYS = {
+	d: 1,
+	w: 7,
+	m: 30,
+	y: 365
+};
+/**
+* A length of time: whole days as a number, or a count and a unit — `90d`, `12w`, `18m`, `3y`. A month is thirty
+* days and a year is 365.
+*/
+const RetentionDuration = z.union([z.number().int().min(1).max(36500), z.string().regex(/^[1-9]\d{0,4}[dwmy]$/, "A duration is a whole number and a unit: `90d`, `12w`, `18m` or `3y`.")]).describe("A length of time: whole days as a number, or a count and a unit — `90d`, `12w`, `18m`, `3y`. A month is thirty days and a year is 365.");
+/** A duration in whole days. */
+function durationDays(value) {
+	if (typeof value === "number") return value;
+	const unit = value.slice(-1);
+	return Number(value.slice(0, -1)) * UNIT_DAYS[unit];
+}
+/** An audit action prefix: a domain, a slash, and as much of the reason as the rule means. */
+const AuditActionPrefix = z.string().regex(/^[a-z][a-z0-9_]*\/[a-z0-9_.]*$/, "An audit prefix is a domain and a slash, optionally followed by the start of a reason: `auth/`, `support/thread_`.").describe("An audit action prefix: a domain and a slash, optionally the start of a reason — `auth/`, `support/thread_`. The longest prefix matching an action decides its window.");
+/** The `retention` block, as a Worker's `pithy.config.ts` writes it. */
+const RetentionPolicy = z.object({
+	purgeWindows: z.object({
+		user: RetentionDuration.optional().describe("How long a deleted account stays restorable before its purge. Replaces `auth({ retention: { purgeAfterDays } })`."),
+		organization: RetentionDuration.optional().describe("How long a deleted organization stays restorable before its purge. Replaces `organization({ retention: { purgeAfterDays } })`.")
+	}).strict().optional().describe("Every soft-delete window, in one place. A subject left out keeps the window its own capability configures."),
+	audit: z.object({
+		default: z.union([RetentionDuration, z.literal("forever")]).optional().describe("How long an audit event no prefix names is kept. Absent, or `forever`, keeps it forever. Never applied under the floor to a floored action."),
+		prefixes: z.record(AuditActionPrefix, RetentionDuration).optional().describe("How long events are kept by action prefix. The longest matching prefix wins. A rule under 365 days that covers `controlplane/*` or a lifecycle action is refused.")
+	}).strict().optional().describe("How long the audit trail is kept. Absent keeps everything forever."),
+	classAges: z.record(PrivacyClassName, RetentionDuration).optional().describe("The longest an account may sit inactive — no sign-in, no session — while it holds a privacy class: `{ pii: \"3y\" }`. Past the strictest class it holds, it is soft-deleted through the lifecycle, with its notice mail and its purge window.")
+}).strict().describe("How long this Worker keeps deleted accounts, the audit trail and each class of personal data.");
+/** Where an effective value came from: this block, a capability's own config, or the kit's floor. */
+const RetentionSource = z.enum([
+	"policy",
+	"capability",
+	"floor"
+]).describe("Where the value came from: `policy`, the `retention` block; `capability`, the capability's own config, because the block names none; `floor`, the kit's minimum for the audit trail.");
+/** The policy as it takes effect: every value resolved to days, and where each came from. */
+const EffectiveRetention = z.object({
+	purgeWindows: z.array(z.object({
+		subject: z.enum(["user", "organization"]).describe("Whose deletion the window governs."),
+		days: z.number().int().min(0).describe("How many days a deletion stays restorable before its purge."),
+		source: RetentionSource
+	}).describe("One soft-delete window as it takes effect.")).describe("Every soft-delete window a composed capability runs, in composition order."),
+	audit: z.object({
+		defaultDays: z.number().int().min(1).nullable().describe("How long an event no rule names is kept, in days. Null keeps it forever."),
+		floorDays: z.number().int().min(1).describe("The least the kit keeps `controlplane/*` and every lifecycle action, in days."),
+		rules: z.array(z.object({
+			prefix: z.string().describe("The action prefix, or a floored action in full."),
+			days: z.number().int().min(1).describe("How long matching events are kept, in days."),
+			source: RetentionSource
+		}).describe("One audit rule as it takes effect.")).describe("Every rule, longest prefix first. A `floor` rule is the kit holding a floored action at the floor under a shorter default."),
+		floored: z.array(z.string()).describe("Every prefix and action the floor covers: `controlplane/` and each composed lifecycle action.")
+	}).describe("How long the audit trail is kept."),
+	classAges: z.array(z.object({
+		class: PrivacyClassName.describe("The privacy class."),
+		days: z.number().int().min(1).describe("The longest an account holding it may sit inactive, in days.")
+	}).describe("One class age.")).describe("Every class age the block declares, strictest first.")
+}).describe("This Worker's retention, as it takes effect: every window in days, and where each came from.");
+/** Whether a rule's prefix would decide the window of a floored prefix or action. */
+function covers(prefix, floored) {
+	return floored.startsWith(prefix) || prefix.startsWith(floored);
+}
+/**
+* Parse a `retention` block, or refuse it naming what is wrong. `undefined` is the empty policy: every capability's
+* own window, an audit trail kept forever, no class ages.
+*/
+function parseRetentionPolicy(input) {
+	if (input === void 0) return {};
+	const parsed = RetentionPolicy.safeParse(input);
+	if (!parsed.success) throw fromZodError(parsed.error, {
+		message: "The retention block in pithy.config.ts does not parse.",
+		action: "Fix the field named, then deploy again."
+	});
+	return parsed.data;
+}
+/**
+* The policy as it takes effect over a composition — or refused, when a rule would keep a floored action for less
+* than the floor. Called when a Worker assembles, so a policy that would prune the control plane's trail early never
+* deploys.
+*/
+function resolveRetention(policy, composition) {
+	const floored = [...FLOORED_AUDIT_PREFIXES, ...new Set(composition.lifecycleActions)];
+	const rules = Object.entries(policy.audit?.prefixes ?? {}).map(([prefix, duration]) => ({
+		prefix,
+		days: durationDays(duration),
+		source: "policy"
+	}));
+	for (const rule of rules) {
+		if (rule.days >= 365) continue;
+		const hit = floored.find((each) => covers(rule.prefix, each));
+		if (hit !== void 0) throw new ValidationError({
+			message: `The retention block keeps ${rule.prefix} for ${rule.days} days, under the kit's floor of 365 for ${hit}.`,
+			action: `Keep it at least 365 days, or name a narrower prefix that leaves ${hit} out.`,
+			detail: `audit retention rule ${rule.prefix}=${rule.days}d covers floored ${hit}`
+		});
+	}
+	const fallback = policy.audit?.default;
+	const defaultDays = fallback === void 0 || fallback === "forever" ? null : durationDays(fallback);
+	if (defaultDays !== null && defaultDays < 365) {
+		for (const each of floored) if (!rules.some((rule) => each.startsWith(rule.prefix))) rules.push({
+			prefix: each,
+			days: 365,
+			source: "floor"
+		});
+	}
+	rules.sort((a, b) => b.prefix.length - a.prefix.length || a.prefix.localeCompare(b.prefix));
+	const windows = policy.purgeWindows ?? {};
+	const purgeWindows = composition.purgeWindows.map(({ subject, days }) => {
+		const stated = windows[subject];
+		return stated === void 0 ? {
+			subject,
+			days,
+			source: "capability"
+		} : {
+			subject,
+			days: durationDays(stated),
+			source: "policy"
+		};
+	});
+	const classAges = Object.entries(policy.classAges ?? {}).map(([name, duration]) => ({
+		class: name,
+		days: durationDays(duration)
+	})).sort((a, b) => a.days - b.days || a.class.localeCompare(b.class));
+	return {
+		purgeWindows,
+		audit: {
+			defaultDays,
+			floorDays: 365,
+			rules,
+			floored
+		},
+		classAges
+	};
+}
+/**
+* How many days an audit event with this action is kept, or `null` for forever. The longest matching rule decides;
+* with none, the default. A floored action is never kept under the floor, whichever decided.
+*/
+function auditWindowDays(retention, action) {
+	const days = retention.audit.rules.find((each) => action.startsWith(each.prefix))?.days ?? retention.audit.defaultDays;
+	if (days === null) return null;
+	return retention.audit.floored.some((each) => action.startsWith(each)) ? Math.max(days, retention.audit.floorDays) : days;
+}
+/** Whether the policy prunes any audit event at all. */
+function prunesAudit(retention) {
+	return retention.audit.defaultDays !== null || retention.audit.rules.some((rule) => rule.source === "policy");
+}
+/** The soft-delete window for a subject, in days, or `undefined` when no composed capability runs one. */
+function purgeWindowDays(retention, subject) {
+	return retention.purgeWindows.find((each) => each.subject === subject)?.days;
+}
+/**
+* The longest an account may sit inactive given the classes it holds, in days — the strictest class age among
+* them — or `null` when no class it holds has an age.
+*/
+function inactivityDays(retention, held) {
+	const ages = retention.classAges.filter((age) => held.includes(age.class)).map((age) => age.days);
+	return ages.length === 0 ? null : Math.min(...ages);
+}
+//#endregion
+export { AUDIT_RETENTION_FLOOR_DAYS, EffectiveRetention, FLOORED_AUDIT_PREFIXES, MS_PER_DAY, RetentionDuration, RetentionPolicy, RetentionSource, auditWindowDays, durationDays, inactivityDays, parseRetentionPolicy, prunesAudit, purgeWindowDays, resolveRetention };

package/dist/session/rotated.d.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../capability/capability";
+/**
+ * One session replaced by its successor: a refresh-credential rotation. The capability that owns sessions
+ * announces it once the presented session is spent and the successor stands, so a capability that keyed
+ * state on the old id can carry it to the new one.
+ */
+export interface SessionRotation {
+    /** The session that was presented and is now gone. */
+    readonly previousSessionId: string;
+    /** The session that replaces it. */
+    readonly sessionId: string;
+    /** Whose sessions both are. A listener matches on it as well as the id. */
+    readonly userId: string;
+    /** The Worker's bindings for this request. */
+    readonly env: Record<string, unknown>;
+}
+/**
+ * Hear of a rotation. Called after the successor exists and the presented session is gone; a throw is the
+ * listener's own failure, and the rotation it reports has already happened.
+ */
+export type SessionRotatedListener = (rotation: SessionRotation) => Promise<void>;
+/** A listener that threw, named by its capability. */
+export interface SessionRotatedFailure {
+    readonly capability: string;
+    readonly error: unknown;
+}
+/**
+ * Tell every composed capability that declares {@link Capability.sessionRotated}, in composition order. Each
+ * listener runs whatever the one before it did; the failures come back for the caller to log.
+ */
+export declare function announceSessionRotated(capabilities: readonly Capability[], rotation: SessionRotation): Promise<SessionRotatedFailure[]>;
+//# sourceMappingURL=rotated.d.ts.map

package/dist/session/rotated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotated.d.ts","sourceRoot":"","sources":["../../src/session/rotated.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAElF,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,SAAS,UAAU,EAAE,EACnC,QAAQ,EAAE,eAAe,GACxB,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAYlC"}

package/dist/session/rotated.js

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/session/rotated.ts
+/**
+* Tell every composed capability that declares {@link Capability.sessionRotated}, in composition order. Each
+* listener runs whatever the one before it did; the failures come back for the caller to log.
+*/
+async function announceSessionRotated(capabilities, rotation) {
+	const failures = [];
+	for (const capability of capabilities) {
+		const listener = capability.sessionRotated;
+		if (!listener) continue;
+		try {
+			await listener(rotation);
+		} catch (error) {
+			failures.push({
+				capability: capability.name,
+				error
+			});
+		}
+	}
+	return failures;
+}
+//#endregion
+export { announceSessionRotated };

package/dist/test-utils/connectionFixtures.d.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { ControlPlaneConnection, RegisteredKey } from "../controlPlane/data/connection";
+import type { OidcTrust } from "../controlPlane/data/oidcTrust";
+/** The instant the connection fixtures are read at. */
+export declare const FIXTURE_NOW: Date;
+/** A registered key, live at {@link FIXTURE_NOW} unless overridden. */
+export declare function fixtureKey(keyId: string, overrides?: Partial<RegisteredKey>): RegisteredKey;
+/** An OIDC trust, live at {@link FIXTURE_NOW} unless overridden. */
+export declare function fixtureTrust(trustId: string, overrides?: Partial<OidcTrust>): OidcTrust;
+/** A connection authorized by ada@example.com, holding one live key, unless overridden. */
+export declare function fixtureConnection(overrides?: Partial<ControlPlaneConnection>): ControlPlaneConnection;
+//# sourceMappingURL=connectionFixtures.d.ts.map

package/dist/test-utils/connectionFixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionFixtures.d.ts","sourceRoot":"","sources":["../../src/test-utils/connectionFixtures.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAC7F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE,uDAAuD;AACvD,eAAO,MAAM,WAAW,MAAuC,CAAC;AAGhE,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,aAAa,CAS/F;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAa3F;AAED,2FAA2F;AAC3F,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAAG,sBAAsB,CAkBzG"}