@pithy-sh/core 0.13.0 → 0.15.0

package/src/retention/holds.ts

@@ -0,0 +1,175 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { type HoldSubjectType, LegalHold } from "../controlPlane/data/hold";
+import {
+  CONTROL_PLANE_HOLDS_TABLE,
+  type ControlPlaneDatabase,
+  controlPlaneDatabase,
+} from "../controlPlane/data/tables";
+import { SQLiteDate } from "../data/codecs";
+import { ConflictError, NotFoundError } from "../error/pithyError";
+
+/**
+ * **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 async function placeHold(
+  db: ControlPlaneDatabase,
+  input: { subjectType: HoldSubjectType; subjectId: string | null; reason: string; actor: HoldActor; at: Date },
+): Promise<LegalHold> {
+  const hold: LegalHold = {
+    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.
+ */
+export async function releaseHold(
+  db: ControlPlaneDatabase,
+  input: { id: string; reason: string; actor: HoldActor; at: Date },
+): Promise<LegalHold> {
+  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. */
+export async function readHold(db: ControlPlaneDatabase, id: string): Promise<LegalHold | null> {
+  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`. */
+export async function listHolds(
+  db: ControlPlaneDatabase,
+  options: { state?: "active" | "released"; limit: number },
+): Promise<LegalHold[]> {
+  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. */
+export async function countActiveHolds(db: ControlPlaneDatabase): Promise<number> {
+  const row = await db
+    .selectFrom(CONTROL_PLANE_HOLDS_TABLE)
+    .select((eb) => eb.fn.countAll<number>().as("n"))
+    .where("state", "=", "active")
+    .executeTakeFirst();
+  return Number(row?.n ?? 0);
+}
+
+/** 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 const HOLDS_BINDING = "DB";
+
+/** Whether a D1 failure is the hold table not existing — a database no control plane ever migrated. */
+function noHoldTable(error: unknown): boolean {
+  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. */
+export function legalHolds(env: Record<string, unknown>): LegalHolds {
+  const binding = env[HOLDS_BINDING];
+  // No app database at all is a Worker no control plane could ever have placed a hold through.
+  if (typeof binding !== "object" || binding === null) return { held: async () => false };
+  const db = controlPlaneDatabase(binding as D1Database);
+  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.
+ */
+export async function standingHolds(env: Record<string, unknown>): Promise<number> {
+  const binding = env[HOLDS_BINDING];
+  if (typeof binding !== "object" || binding === null) return 0;
+  try {
+    return await countActiveHolds(controlPlaneDatabase(binding as D1Database));
+  } catch (error) {
+    if (noHoldTable(error)) return 0;
+    throw error;
+  }
+}

package/src/retention/holdsPurge.ts

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { personRowsExport } from "../capability/personRows";
+import type { RetainingPurgeContribution } from "../capability/purge";
+import { LegalHold } from "../controlPlane/data/hold";
+import { CONTROL_PLANE_HOLDS_TABLE } from "../controlPlane/data/tables";
+
+/**
+ * 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 const HOLDS_PURGE_SUMMARY = "Keeps every legal hold placed on the user.";
+
+/** Why, in the sentence the person is told. */
+export 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 function holdsUserPurge(database = "DB"): RetainingPurgeContribution {
+  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",
+        },
+      ],
+    }),
+  };
+}

package/src/retention/policy.ts

@@ -0,0 +1,305 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { fromZodError, ValidationError } from "../error/pithyError";
+import { PrivacyClassName } from "../privacy/classes";
+
+/**
+ * **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 const MS_PER_DAY = 86_400_000;
+
+/** The least the kit keeps a floored audit action: a year. */
+export 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 const FLOORED_AUDIT_PREFIXES = ["controlplane/"] as const;
+
+/** 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 } as const;
+
+/** The longest any duration may be: a century. Past that, say `forever`. */
+const MAX_DAYS = 36_500;
+
+/**
+ * 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 const RetentionDuration = z
+  .union([
+    z.number().int().min(1).max(MAX_DAYS),
+    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.",
+  );
+export type RetentionDuration = z.infer<typeof RetentionDuration>;
+
+/** A duration in whole days. */
+export function durationDays(value: RetentionDuration): number {
+  if (typeof value === "number") return value;
+  const unit = value.slice(-1) as keyof typeof UNIT_DAYS;
+  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. */
+export 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.");
+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 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.",
+  );
+export type RetentionSource = z.infer<typeof RetentionSource>;
+
+/** The policy as it takes effect: every value resolved to days, and where each came from. */
+export 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.");
+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[];
+}
+
+/** Whether a rule's prefix would decide the window of a floored prefix or action. */
+function covers(prefix: string, floored: string): boolean {
+  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.
+ */
+export function parseRetentionPolicy(input: unknown): RetentionPolicy {
+  if (input === undefined) 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.
+ */
+export function resolveRetention(policy: RetentionPolicy, composition: RetentionComposition): EffectiveRetention {
+  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" as RetentionSource,
+  }));
+  for (const rule of rules) {
+    if (rule.days >= AUDIT_RETENTION_FLOOR_DAYS) continue;
+    const hit = floored.find((each) => covers(rule.prefix, each));
+    if (hit !== undefined) {
+      throw new ValidationError({
+        message: `The retention block keeps ${rule.prefix} for ${rule.days} days, under the kit's floor of ${AUDIT_RETENTION_FLOOR_DAYS} for ${hit}.`,
+        action: `Keep it at least ${AUDIT_RETENTION_FLOOR_DAYS} 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 === undefined || fallback === "forever" ? null : durationDays(fallback);
+  // Under a default shorter than the floor, every floored action no rule already decides is held at the floor.
+  if (defaultDays !== null && defaultDays < AUDIT_RETENTION_FLOOR_DAYS) {
+    for (const each of floored) {
+      const decided = rules.some((rule) => each.startsWith(rule.prefix));
+      if (!decided) rules.push({ prefix: each, days: AUDIT_RETENTION_FLOOR_DAYS, 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 === undefined
+      ? { subject, days, source: "capability" as RetentionSource }
+      : { subject, days: durationDays(stated), source: "policy" as RetentionSource };
+  });
+
+  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: AUDIT_RETENTION_FLOOR_DAYS, 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.
+ */
+export function auditWindowDays(retention: EffectiveRetention, action: string): number | null {
+  const rule = retention.audit.rules.find((each) => action.startsWith(each.prefix));
+  const days = rule?.days ?? retention.audit.defaultDays;
+  if (days === null) return null;
+  const floored = retention.audit.floored.some((each) => action.startsWith(each));
+  return floored ? Math.max(days, retention.audit.floorDays) : days;
+}
+
+/** Whether the policy prunes any audit event at all. */
+export function prunesAudit(retention: EffectiveRetention): boolean {
+  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. */
+export function purgeWindowDays(retention: EffectiveRetention, subject: "user" | "organization"): number | undefined {
+  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.
+ */
+export function inactivityDays(retention: EffectiveRetention, held: readonly string[]): number | null {
+  const ages = retention.classAges.filter((age) => held.includes(age.class)).map((age) => age.days);
+  return ages.length === 0 ? null : Math.min(...ages);
+}

package/src/session/rotated.ts

@@ -0,0 +1,53 @@
+// 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 async function announceSessionRotated(
+  capabilities: readonly Capability[],
+  rotation: SessionRotation,
+): Promise<SessionRotatedFailure[]> {
+  const failures: SessionRotatedFailure[] = [];
+  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;
+}

package/src/test-utils/connectionFixtures.ts

@@ -0,0 +1,58 @@
+// 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 const FIXTURE_NOW = new Date("2026-10-27T12:00:00.000Z");
+const REGISTERED = new Date("2026-10-01T00:00:00.000Z");
+
+/** A registered key, live at {@link FIXTURE_NOW} unless overridden. */
+export function fixtureKey(keyId: string, overrides: Partial<RegisteredKey> = {}): RegisteredKey {
+  return {
+    keyId,
+    publicKey: { kty: "OKP", crv: "Ed25519", x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" },
+    validFrom: REGISTERED,
+    validUntil: null,
+    revokedAt: null,
+    ...overrides,
+  };
+}
+
+/** An OIDC trust, live at {@link FIXTURE_NOW} unless overridden. */
+export function fixtureTrust(trustId: string, overrides: Partial<OidcTrust> = {}): OidcTrust {
+  return {
+    trustId,
+    issuer: "https://token.actions.githubusercontent.com",
+    jwksUrl: "https://token.actions.githubusercontent.com/.well-known/jwks",
+    audience: "https://api.example.com",
+    claims: { repository_id: "1262274726" },
+    authorizedBy: "ada@example.com",
+    validFrom: REGISTERED,
+    revokedAt: null,
+    firstCallAt: null,
+    ...overrides,
+  };
+}
+
+/** A connection authorized by ada@example.com, holding one live key, unless overridden. */
+export function fixtureConnection(overrides: Partial<ControlPlaneConnection> = {}): ControlPlaneConnection {
+  return {
+    id: "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+    environment: "prod",
+    issuer: "https://app.pithy.sh",
+    workerUrl: "https://api.example.com",
+    basePath: "/control-plane",
+    managementOrigin: null,
+    authorizedBy: "ada@example.com",
+    actorKind: "agent",
+    purpose: "Nightly audit summarizer.",
+    scopes: ["manifest:read"],
+    keys: [fixtureKey("k1")],
+    trusts: [],
+    createdAt: REGISTERED,
+    updatedAt: REGISTERED,
+    ...overrides,
+  };
+}

package/src/test-utils/interleave.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely, KyselyPlugin, QueryId } from "kysely";
+
+/**
+ * The same database, with `between` run after each of its first `times` reads and before the caller sees the rows: a
+ * write that lands between a read and the write made from it.
+ *
+ * `between` receives the count of reads it has followed so far, from 0. It must write through another handle, since a
+ * read it made through this one would be followed in turn.
+ */
+export function writeAfterRead<DB>(
+  db: Kysely<DB>,
+  between: (count: number) => Promise<void>,
+  times = Number.POSITIVE_INFINITY,
+): Kysely<DB> {
+  const reads = new WeakSet<QueryId>();
+  let count = 0;
+  const plugin: KyselyPlugin = {
+    transformQuery({ queryId, node }) {
+      if (node.kind === "SelectQueryNode") reads.add(queryId);
+      return node;
+    },
+    async transformResult({ queryId, result }) {
+      if (reads.has(queryId) && count < times) await between(count++);
+      return result;
+    },
+  };
+  return db.withPlugin(plugin);
+}