@pithy-sh/core 0.12.0 → 0.14.0

package/dist/controlPlane/migrations/0005_holds.d.ts

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Migration } from "kysely/migration";
+/**
+ * Legal holds. Appended: the seam has shipped and adopters' databases hold its rows.
+ *
+ * One row per hold, kept after it is released, so the table is the record of every hold that ever stood. Indexed on
+ * `(state, subject_type, subject_id)`, because the question every purge and prune asks is "is an active hold on this
+ * subject", and it is asked once per step.
+ */
+export declare const controlplane_0005_holds: Migration;
+//# sourceMappingURL=0005_holds.d.ts.map

package/dist/controlPlane/migrations/0005_holds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0005_holds.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/migrations/0005_holds.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,SA0BrC,CAAC"}

package/dist/controlPlane/migrations/0005_holds.js

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/controlPlane/migrations/0005_holds.ts
+/**
+* Legal holds. Appended: the seam has shipped and adopters' databases hold its rows.
+*
+* One row per hold, kept after it is released, so the table is the record of every hold that ever stood. Indexed on
+* `(state, subject_type, subject_id)`, because the question every purge and prune asks is "is an active hold on this
+* subject", and it is asked once per step.
+*/
+const controlplane_0005_holds = {
+	up: async (db) => {
+		await db.schema.createTable("pithyControlplaneHolds").addColumn("id", "text", (c) => c.primaryKey()).addColumn("subjectType", "text", (c) => c.notNull()).addColumn("subjectId", "text").addColumn("reason", "text", (c) => c.notNull()).addColumn("placedBy", "text", (c) => c.notNull()).addColumn("placedAt", "integer", (c) => c.notNull()).addColumn("state", "text", (c) => c.notNull()).addColumn("releasedAt", "integer").addColumn("releasedBy", "text").addColumn("releaseReason", "text").execute();
+		await db.schema.createIndex("pithyControlplaneHoldsSubjectIdx").on("pithyControlplaneHolds").columns([
+			"state",
+			"subjectType",
+			"subjectId"
+		]).execute();
+	},
+	down: async (db) => {
+		await db.schema.dropIndex("pithyControlplaneHoldsSubjectIdx").execute();
+		await db.schema.dropTable("pithyControlplaneHolds").execute();
+	}
+};
+//#endregion
+export { controlplane_0005_holds };

package/dist/controlPlane/processing/derive.d.ts

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { ConsentPurpose } from "../../consent/purpose";
+import type { ConsentPurposeStanding } from "../../consent/reader";
+import type { PrivacyInventory } from "../../privacy/report";
+import type { ResolvedActivity } from "../../processing/activity";
+import type { EffectiveRetention } from "../../retention/policy";
+import { type EvidenceControlId, type EvidenceState } from "../evidence/mapping";
+import type { ControlPlaneProcessingResponse } from "../http/responses";
+/**
+ * The record of processing activities, derived. Pure: `./read.ts` gathers what the Worker declares and records, and
+ * this turns it into the GDPR Article 30 record.
+ *
+ * **It describes the processing and changes none of it.** Every gap is named and none is filled in: an activity with
+ * no legal basis reads as having none, and the record never guesses one.
+ */
+/** The evidence pack's controls that protect stored personal data, which every activity cites. */
+export declare const PROCESSING_MEASURES: readonly ["data-protection", "audit-logging", "management-access", "key-rotation", "route-verification", "csrf"];
+/** The platform every Worker runs on, which receives everything it serves and stores. */
+export declare const CLOUDFLARE = "Cloudflare";
+/** What the record knows of consent. */
+export type ConsentInput = 
+/** The composed reader answered: every purpose in its catalog, with counts. */
+{
+    readonly state: "read";
+    readonly standings: readonly ConsentPurposeStanding[];
+}
+/** No consent capability is composed: purposes may be declared, and no grant can be recorded. */
+ | {
+    readonly state: "not-composed";
+    readonly declared: readonly ConsentPurpose[];
+}
+/**
+ * A reader is composed and its record could not be read: its whole catalog, read from memory, or null where the
+ * reader cannot list one.
+ */
+ | {
+    readonly state: "unreadable";
+    readonly catalog: readonly ConsentPurpose[] | null;
+};
+/** A recipient a binding implies, on the capability that declares the binding. */
+export interface BindingRecipient {
+    readonly name: string;
+    readonly receives: string;
+    readonly classes: readonly string[];
+    readonly capability: string;
+}
+/** Everything the derivation reads. */
+export interface ProcessingInputs {
+    readonly activities: readonly ResolvedActivity[];
+    /** The privacy inventory, or null where it could not be walked. */
+    readonly inventory: PrivacyInventory | null;
+    /** The resolved retention, or null where the Worker recorded none. */
+    readonly retention: EffectiveRetention | null;
+    readonly consent: ConsentInput;
+    readonly bindingRecipients: readonly BindingRecipient[];
+    /** Each control's state from the evidence pack, or null where the connection may not read it. */
+    readonly measures: Readonly<Partial<Record<EvidenceControlId, EvidenceState>>> | null;
+    /** Whether a gap may name a stored table and field, which only a connection holding `privacy:read` may read. */
+    readonly fieldNames: boolean;
+}
+/** The record, without the envelope the route adds. */
+export type DerivedProcessingRecord = Omit<ControlPlaneProcessingResponse, "environment" | "generatedAt" | "version">;
+/** A capability shaped enough to say which bindings it needs. */
+interface BindingDeclarer {
+    readonly name: string;
+    readonly requiredBindings: readonly {
+        readonly type: string;
+        readonly name: string;
+    }[];
+}
+/** Workers AI, once for each capability whose `ai` binding this Worker has. */
+export declare function workersAiRecipients(capabilities: readonly BindingDeclarer[], env: Record<string, unknown>): BindingRecipient[];
+/** Derive the record from what the Worker declares and records. */
+export declare function deriveProcessingRecord(inputs: ProcessingInputs): DerivedProcessingRecord;
+export {};
+//# sourceMappingURL=derive.d.ts.map

package/dist/controlPlane/processing/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/processing/derive.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAqB,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,KAAK,EACV,8BAA8B,EAM/B,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AAEH,kGAAkG;AAClG,eAAO,MAAM,mBAAmB,kHAOiB,CAAC;AAElD,yFAAyF;AACzF,eAAO,MAAM,UAAU,eAAe,CAAC;AAKvC,wCAAwC;AACxC,MAAM,MAAM,YAAY;AACtB,+EAA+E;AAC7E;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;CAAE;AACnF,iGAAiG;GAC/F;IAAE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;CAAE;AAClF;;;GAGG;GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI,CAAA;CAAE,CAAC;AAEzF,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACtF,gHAAgH;IAChH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,uDAAuD;AACvD,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,8BAA8B,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS,CAAC,CAAC;AAEtH,iEAAiE;AACjE,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxF;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,SAAS,eAAe,EAAE,EACxC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,gBAAgB,EAAE,CAWpB;AAoLD,mEAAmE;AACnE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,uBAAuB,CA2ExF"}

package/dist/controlPlane/processing/derive.js

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { EVIDENCE_CONTROLS } from "../evidence/mapping.js";
+//#region src/controlPlane/processing/derive.ts
+/**
+* The record of processing activities, derived. Pure: `./read.ts` gathers what the Worker declares and records, and
+* this turns it into the GDPR Article 30 record.
+*
+* **It describes the processing and changes none of it.** Every gap is named and none is filled in: an activity with
+* no legal basis reads as having none, and the record never guesses one.
+*/
+/** The evidence pack's controls that protect stored personal data, which every activity cites. */
+const PROCESSING_MEASURES = [
+	"data-protection",
+	"audit-logging",
+	"management-access",
+	"key-rotation",
+	"route-verification",
+	"csrf"
+];
+/** The platform every Worker runs on, which receives everything it serves and stores. */
+const CLOUDFLARE = "Cloudflare";
+const CLOUDFLARE_RECEIVES = "Every request this Worker serves, and everything it stores in D1, KV, R2 and Durable Objects.";
+/** Workers AI, once for each capability whose `ai` binding this Worker has. */
+function workersAiRecipients(capabilities, env) {
+	return capabilities.flatMap((capability) => capability.requiredBindings.filter((binding) => binding.type === "ai" && env[binding.name] != null).map((binding) => ({
+		name: "Cloudflare Workers AI",
+		receives: `What ${capability.name} sends for inference through the ${binding.name} binding.`,
+		classes: [],
+		capability: capability.name
+	})));
+}
+/** The catalog's purposes, however the record learned of them, or null where it could learn none. */
+function catalogOf(consent) {
+	const purposes = consent.state === "read" ? consent.standings.map((entry) => entry.purpose) : consent.state === "unreadable" ? consent.catalog : consent.declared;
+	return purposes === null ? null : new Map(purposes.map((purpose) => [purpose.id, purpose]));
+}
+/** A consent-based activity's purpose and its counts, where they are known. */
+function consentView(id, consent) {
+	const purpose = catalogOf(consent)?.get(id);
+	const counted = consent.state === "read" ? consent.standings.find((entry) => entry.purpose.id === id) : void 0;
+	const zero = consent.state === "not-composed" && purpose !== void 0 ? 0 : null;
+	return {
+		purpose: id,
+		noticeVersion: purpose?.noticeVersion ?? null,
+		explicit: purpose?.explicit ?? null,
+		grants: counted?.grants ?? zero,
+		withdrawals: counted?.withdrawals ?? zero,
+		standing: counted?.standing ?? zero
+	};
+}
+/** The retention behind an activity's classes. */
+function retentionView(classes, retention) {
+	if (retention === null) return null;
+	return {
+		classAges: retention.classAges.filter((age) => classes.includes(age.class)).map((age) => ({ ...age })),
+		purgeWindows: retention.purgeWindows.map((window) => ({ ...window }))
+	};
+}
+/** A recipient as the record shows it. */
+function recipient(name, receives, classes, source) {
+	return {
+		name,
+		receives,
+		classes: [...classes],
+		source
+	};
+}
+/** The gaps one activity has. */
+function activityGaps(activity, stored, catalog) {
+	const gaps = [];
+	if (activity.legalBasis === null) gaps.push({
+		kind: "no-legal-basis",
+		subject: activity.id,
+		detail: "No legal basis is declared. State one on the activity, or in the processing block's overrides."
+	});
+	if (activity.legalBasis === "consent") {
+		if (activity.consentPurpose === null) gaps.push({
+			kind: "no-consent-purpose",
+			subject: activity.id,
+			detail: "The basis is consent and no consent purpose is named."
+		});
+		else if (catalog !== null && !catalog.has(activity.consentPurpose)) gaps.push({
+			kind: "no-consent-purpose",
+			subject: activity.id,
+			detail: `The basis is consent, and no composed catalog declares the purpose ${activity.consentPurpose}.`
+		});
+	}
+	if (stored !== null) {
+		const unstored = activity.classes.filter((each) => !stored.has(each));
+		if (unstored.length > 0) gaps.push({
+			kind: "class-not-stored",
+			subject: activity.id,
+			detail: `It claims ${unstored.join(", ")}, which no composed schema stores.`
+		});
+	}
+	return gaps;
+}
+/** Stored classes no activity of their capability, and none of the adopter's, claims. Tables only with field names. */
+function unclaimedGaps(activities, inventory, fieldNames) {
+	const adopter = new Set(activities.filter((each) => each.declaredBy === "config").flatMap((each) => each.classes));
+	const byCapability = /* @__PURE__ */ new Map();
+	for (const schema of inventory.schemas) {
+		const claimed = new Set(activities.filter((each) => each.declaredBy === schema.capability).flatMap((each) => each.classes));
+		for (const field of schema.fields) {
+			if (claimed.has(field.class) || adopter.has(field.class)) continue;
+			const classes = byCapability.get(schema.capability) ?? /* @__PURE__ */ new Map();
+			const tables = classes.get(field.class) ?? /* @__PURE__ */ new Set();
+			tables.add(schema.name);
+			classes.set(field.class, tables);
+			byCapability.set(schema.capability, classes);
+		}
+	}
+	return [...byCapability].flatMap(([capability, classes]) => [...classes].map(([cls, tables]) => ({
+		kind: "class-unclaimed",
+		subject: capability,
+		detail: fieldNames ? `It stores ${cls} in ${[...tables].join(", ")}, and no processing activity claims it.` : `It stores ${cls}, and no processing activity claims it.`
+	})));
+}
+/**
+* Every stored `phi` field no consent purpose in the catalog covers: field by field with field names, and otherwise
+* once for each capability that stores one. Silent where the catalog is unknown.
+*/
+function uncoveredPhi(inventory, catalog, fieldNames) {
+	if (catalog === null) return [];
+	if ([...catalog.values()].some((purpose) => purpose.classes.includes("phi"))) return [];
+	if (!fieldNames) return [...new Set(inventory.schemas.filter((schema) => schema.fields.some((field) => field.class === "phi")).map((schema) => schema.capability))].map((capability) => ({
+		kind: "phi-not-covered",
+		subject: capability,
+		detail: "It stores phi, and no consent purpose covers phi."
+	}));
+	return inventory.schemas.flatMap((schema) => schema.fields.filter((field) => field.class === "phi").map((field) => ({
+		kind: "phi-not-covered",
+		subject: `${schema.capability}/${schema.name}.${field.path}`,
+		detail: "A phi field is stored, and no consent purpose covers phi."
+	})));
+}
+/** Every purpose covering a class that holds no standing grant. Silent where the record could not be read. */
+function grantlessPurposes(consent) {
+	if (consent.state === "unreadable") return [];
+	if (consent.state === "not-composed") return consent.declared.filter((purpose) => purpose.classes.length > 0).map((purpose) => ({
+		kind: "no-standing-grant",
+		subject: purpose.id,
+		detail: `It covers ${purpose.classes.join(", ")}, and no consent capability is composed to record a grant.`
+	}));
+	return consent.standings.filter((entry) => entry.purpose.classes.length > 0 && entry.standing === 0).map((entry) => ({
+		kind: "no-standing-grant",
+		subject: entry.purpose.id,
+		detail: `It covers ${entry.purpose.classes.join(", ")}, and no subject holds a current, unexpired grant.`
+	}));
+}
+/** Derive the record from what the Worker declares and records. */
+function deriveProcessingRecord(inputs) {
+	const { activities, inventory, retention, consent } = inputs;
+	const stored = inventory === null ? null : new Set(inventory.observed);
+	const catalog = catalogOf(consent);
+	const entries = activities.map((activity) => ({
+		id: activity.id,
+		purpose: activity.purpose,
+		declaredBy: activity.declaredBy,
+		classes: [...activity.classes],
+		legalBasis: activity.legalBasis,
+		basisSource: activity.basisSource,
+		consent: activity.legalBasis === "consent" && activity.consentPurpose !== null ? consentView(activity.consentPurpose, consent) : null,
+		recipients: [
+			recipient(CLOUDFLARE, CLOUDFLARE_RECEIVES, activity.classes, "platform"),
+			...inputs.bindingRecipients.filter((each) => each.capability === activity.declaredBy).map((each) => recipient(each.name, each.receives, each.classes, "binding")),
+			...activity.recipients.map((each) => recipient(each.name, each.receives, each.classes, "declared"))
+		],
+		retention: retentionView(activity.classes, retention),
+		measures: [...PROCESSING_MEASURES],
+		gaps: activityGaps(activity, stored, catalog)
+	}));
+	const recipients = [recipient(CLOUDFLARE, CLOUDFLARE_RECEIVES, inventory?.observed ?? [], "platform")];
+	const seen = /* @__PURE__ */ new Set();
+	const others = [...inputs.bindingRecipients.map((each) => recipient(each.name, each.receives, each.classes, "binding")), ...activities.flatMap((activity) => activity.recipients.map((each) => recipient(each.name, each.receives, each.classes, "declared")))];
+	for (const each of others) {
+		const key = `${each.name}\u0000${each.receives}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		recipients.push(each);
+	}
+	const notDerivable = [];
+	if (inventory === null) notDerivable.push("The privacy inventory could not be walked, so data classes are not cross-checked.");
+	if (consent.state === "unreadable") notDerivable.push("The consent record could not be read, so grant counts are unknown.");
+	if (catalog === null) notDerivable.push("The consent catalog could not be listed, so consent purposes and phi coverage are not cross-checked.");
+	return {
+		activities: entries,
+		recipients,
+		measures: PROCESSING_MEASURES.map((control) => ({
+			control,
+			title: EVIDENCE_CONTROLS[control].title,
+			soc2: [...EVIDENCE_CONTROLS[control].soc2],
+			iso27001: [...EVIDENCE_CONTROLS[control].iso27001],
+			state: inputs.measures?.[control] ?? null
+		})),
+		gaps: [
+			...inventory === null ? [] : unclaimedGaps(activities, inventory, inputs.fieldNames),
+			...inventory === null ? [] : uncoveredPhi(inventory, catalog, inputs.fieldNames),
+			...grantlessPurposes(consent)
+		],
+		notDerivable
+	};
+}
+//#endregion
+export { CLOUDFLARE, PROCESSING_MEASURES, deriveProcessingRecord, workersAiRecipients };

package/dist/controlPlane/processing/read.d.ts

@@ -0,0 +1,10 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import type { ControlPlaneContext } from "../context";
+import type { ControlPlaneHandlerDeps } from "../http/handlers";
+import type { ControlPlaneProcessingResponse } from "../http/responses";
+/** Read everything the record derives from, and derive it. */
+export declare function readProcessingRecord(c: Context<PithyHonoEnv>, deps: ControlPlaneHandlerDeps, context: ControlPlaneContext): Promise<ControlPlaneProcessingResponse>;
+//# sourceMappingURL=read.d.ts.map

package/dist/controlPlane/processing/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/processing/read.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAOhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AA8DxE,8DAA8D;AAC9D,wBAAsB,oBAAoB,CACxC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EACxB,IAAI,EAAE,uBAAuB,EAC7B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,8BAA8B,CAAC,CAmBzC"}

package/dist/controlPlane/processing/read.js

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PRIVACY_READ_SCOPE } from "../scope/scope.js";
+import { workerVersionMetadata } from "../../worker/identity.js";
+import { causeMessage } from "../../error/cause.js";
+import { readEvidencePack } from "../evidence/pack.js";
+import { composedConsent, composedConsentPurposes } from "../../consent/reader.js";
+import { composedProcessing, effectiveProcessing } from "../../processing/composed.js";
+import { deriveProcessingRecord, workersAiRecipients } from "./derive.js";
+//#region src/controlPlane/processing/read.ts
+/**
+* The reads behind the processing record: what the Worker composes, declares and records, gathered once per call.
+* Each read that fails costs the record what it would have said, named in `notDerivable`, and the record still
+* answers. A cause goes to the Worker's log and never into the record.
+*
+* **It never widens a scope.** The measures carry the evidence pack's states only when the connection also holds
+* `evidence:read`; without it they are cited by control and their state is null. A gap names a stored table or field
+* only when the connection also holds `privacy:read`; without it, the capability and the class.
+*/
+/** The privacy inventory, or null where the walk threw. */
+function inventoryOf(c, deps) {
+	try {
+		return deps.privacyInventory();
+	} catch (cause) {
+		c.var.log.warn("processing: privacy inventory unreadable", { reason: causeMessage(cause) ?? String(cause) });
+		return null;
+	}
+}
+/** What the composed consent capability says, or that none is composed. */
+async function consentOf(c, deps) {
+	const composition = deps.composition();
+	const declared = composedConsentPurposes(composition);
+	const reader = composedConsent(composition, c.env);
+	if (reader === null) return {
+		state: "not-composed",
+		declared
+	};
+	if (reader.standings !== void 0) try {
+		return {
+			state: "read",
+			standings: await reader.standings()
+		};
+	} catch (cause) {
+		c.var.log.warn("processing: consent record unreadable", { reason: causeMessage(cause) ?? String(cause) });
+	}
+	return {
+		state: "unreadable",
+		catalog: catalogOf(c, reader)
+	};
+}
+/** The reader's whole catalog from memory, or null where it cannot list one. */
+function catalogOf(c, reader) {
+	if (reader.purposes === void 0) return null;
+	try {
+		return reader.purposes();
+	} catch (cause) {
+		c.var.log.warn("processing: consent catalog unreadable", { reason: causeMessage(cause) ?? String(cause) });
+		return null;
+	}
+}
+/** Each control's state, read through the evidence pack, or null without `evidence:read`. */
+async function measuresOf(c, deps, context) {
+	if (!context.grantedScopes.includes("evidence:read")) return null;
+	const pack = await readEvidencePack(c, deps, context);
+	return Object.fromEntries(pack.controls.map((entry) => [entry.control, entry.state]));
+}
+/** Read everything the record derives from, and derive it. */
+async function readProcessingRecord(c, deps, context) {
+	const env = c.env;
+	const composition = deps.composition();
+	const [consent, measures] = await Promise.all([consentOf(c, deps), measuresOf(c, deps, context)]);
+	const record = deriveProcessingRecord({
+		activities: composedProcessing() ?? effectiveProcessing(void 0, composition),
+		inventory: inventoryOf(c, deps),
+		retention: deps.retention?.() ?? null,
+		consent,
+		bindingRecipients: workersAiRecipients(composition, env),
+		measures,
+		fieldNames: context.grantedScopes.includes(PRIVACY_READ_SCOPE)
+	});
+	return {
+		environment: context.environment,
+		generatedAt: deps.now().toISOString(),
+		version: workerVersionMetadata(c.env).id,
+		...record
+	};
+}
+//#endregion
+export { readProcessingRecord };

package/dist/controlPlane/scope/kind.d.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * What kind of operation a control-plane scope grants, declared by the capability that owns the scope.
+ *
+ * Scopes are federated and open, so a management client cannot tell from the string whether `auth:users:suspend`
+ * reads, writes or does something worse. The kind is the closed vocabulary it maps its own roles onto instead: the
+ * app tools' effects, with `reads` beneath them and `credentials` (mints, rotates or revokes a credential) above.
+ * Ordered from least to most restrictive. Written out rather than spread from `TOOL_EFFECTS`, so a scope declaration
+ * stays importable from a browser program without the route machinery; `kind.test.ts` holds the two together.
+ */
+export declare const SCOPE_KINDS: readonly ["reads", "writes", "sends", "charges", "deletes", "credentials"];
+export declare const ScopeKind: z.ZodEnum<{
+    charges: "charges";
+    credentials: "credentials";
+    deletes: "deletes";
+    reads: "reads";
+    sends: "sends";
+    writes: "writes";
+}>;
+export type ScopeKind = z.infer<typeof ScopeKind>;
+/** The kind a client assumes for a scoped route that states none: a Worker too old to say. */
+export declare const MOST_RESTRICTIVE_SCOPE_KIND: ScopeKind;
+/** The part of an admin route a kind is read from. */
+export interface ScopedRoute {
+    readonly scope: string | null;
+    readonly kind?: ScopeKind | undefined;
+}
+/**
+ * The kind of a route as a client reads it: its declared kind, {@link MOST_RESTRICTIVE_SCOPE_KIND} for a scoped
+ * route that declares none, and null for a route with no scope, which grants nothing to classify.
+ */
+export declare function scopeKindOf(route: ScopedRoute): ScopeKind | null;
+/** One scope whose routes declare more than one kind. */
+export interface ScopeKindConflict {
+    readonly scope: string;
+    /** Every kind declared for it, in the order first seen. */
+    readonly kinds: readonly ScopeKind[];
+}
+/**
+ * Every scope whose routes disagree about its kind. Holding a scope confers every route that requires it, so a
+ * scope has exactly one kind, and two routes declaring different ones is a declaration to fix.
+ */
+export declare function scopeKindConflicts(routes: Iterable<ScopedRoute>): ScopeKindConflict[];
+//# sourceMappingURL=kind.d.ts.map

package/dist/controlPlane/scope/kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/scope/kind.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,YAAI,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,CAAU,CAAC;AAEtG,eAAO,MAAM,SAAS;;;;;;;EAInB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,8FAA8F;AAC9F,eAAO,MAAM,2BAA2B,EAAE,SAAyB,CAAC;AAEpE,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAGhE;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,iBAAiB,EAAE,CAUrF"}

package/dist/controlPlane/scope/kind.js

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/controlPlane/scope/kind.ts
+/**
+* What kind of operation a control-plane scope grants, declared by the capability that owns the scope.
+*
+* Scopes are federated and open, so a management client cannot tell from the string whether `auth:users:suspend`
+* reads, writes or does something worse. The kind is the closed vocabulary it maps its own roles onto instead: the
+* app tools' effects, with `reads` beneath them and `credentials` (mints, rotates or revokes a credential) above.
+* Ordered from least to most restrictive. Written out rather than spread from `TOOL_EFFECTS`, so a scope declaration
+* stays importable from a browser program without the route machinery; `kind.test.ts` holds the two together.
+*/
+const SCOPE_KINDS = [
+	"reads",
+	"writes",
+	"sends",
+	"charges",
+	"deletes",
+	"credentials"
+];
+const ScopeKind = z.enum(SCOPE_KINDS).describe("What kind of operation a scope grants: `reads`, `writes`, `sends` (mail or a message leaves the system), `charges` (money or an entitlement moves), `deletes`, or `credentials` (a credential is minted, rotated or revoked).");
+/** The kind a client assumes for a scoped route that states none: a Worker too old to say. */
+const MOST_RESTRICTIVE_SCOPE_KIND = "credentials";
+/**
+* The kind of a route as a client reads it: its declared kind, {@link MOST_RESTRICTIVE_SCOPE_KIND} for a scoped
+* route that declares none, and null for a route with no scope, which grants nothing to classify.
+*/
+function scopeKindOf(route) {
+	if (route.scope === null) return null;
+	return route.kind ?? "credentials";
+}
+/**
+* Every scope whose routes disagree about its kind. Holding a scope confers every route that requires it, so a
+* scope has exactly one kind, and two routes declaring different ones is a declaration to fix.
+*/
+function scopeKindConflicts(routes) {
+	const kinds = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const kind = scopeKindOf(route);
+		if (route.scope === null || kind === null) continue;
+		const seen = kinds.get(route.scope) ?? [];
+		if (!seen.includes(kind)) seen.push(kind);
+		kinds.set(route.scope, seen);
+	}
+	return [...kinds].filter(([, seen]) => seen.length > 1).map(([scope, seen]) => ({
+		scope,
+		kinds: seen
+	}));
+}
+//#endregion
+export { MOST_RESTRICTIVE_SCOPE_KIND, SCOPE_KINDS, ScopeKind, scopeKindConflicts, scopeKindOf };

package/dist/controlPlane/scope/scope.d.ts

@@ -51,25 +51,80 @@ export declare const MANIFEST_READ_SCOPE: ControlPlaneScope;
 export declare const KEYS_ROTATE_SCOPE: ControlPlaneScope;
 /**
  * Read where each database this Worker binds stands: what is applied, what is pending, what is undeclared,
- * and which run put it there (#729). Read-only by construction — every route behind it is a `GET`, and
+ * and which run put it there. Read-only by construction — every route behind it is a `GET`, and
  * nothing over the seam runs, reverses or resets a migration. The two migration health keys on the seam's
  * manifest entry sit behind it too, so a connection without it gets no number rather than a zero.
  */
 export declare const MIGRATIONS_READ_SCOPE: ControlPlaneScope;
 /**
  * Read this Worker's full privacy inventory: every storage schema holding a marked field, each marked field's
- * path, its class, and where it is stored (#132). Read-only — the one route behind it is a `GET`.
+ * path, its class, and where it is stored. Read-only — the one route behind it is a `GET`.
  *
  * **Its own scope rather than `manifest:read`**, because field names are the kind of thing an adopter may
  * reasonably withhold from a client that has no business seeing them. The manifest's privacy block carries
  * classes and counts only, so a connection without this one still sees the posture headline.
  */
 export declare const PRIVACY_READ_SCOPE: ControlPlaneScope;
+/**
+ * Read this Worker's evidence pack: the SOC 2 and ISO 27001 evidence it derives from its own declarations.
+ * Read-only — the one route behind it is a `GET`, and it performs nothing it reports on.
+ *
+ * **Its own scope**, because the pack reads across the seam: every connection's principal, kind, purpose and
+ * grant, and every route's verification. It never widens another scope. A fact a capability keeps behind its own
+ * read — migration counts behind {@link MIGRATIONS_READ_SCOPE}, a capability's health behind that capability's
+ * scope — stays behind it, and a connection without that scope gets `not-derivable` naming it.
+ */
+export declare const EVIDENCE_READ_SCOPE: ControlPlaneScope;
+/**
+ * Read the erasure attestation: one subject's purge, or every purge in a period, with the audit events that
+ * record each step. Read-only — both routes behind it are `GET`s — and kind `reads`.
+ *
+ * **Its own scope**, because it answers across subjects: which accounts and organizations were deleted, by which
+ * kind of actor and why. It carries nothing about a person beyond the id the lifecycle trail already keeps, and it
+ * never widens `audit:events:read`: it cites an event by id and chain position, never its contents.
+ */
+export declare const ERASURE_READ_SCOPE: ControlPlaneScope;
+/**
+ * Read the record of processing activities, GDPR Article 30: each activity's purpose, data classes, legal basis,
+ * recipients, retention and measures, and every gap. Read-only — the one route behind it is a `GET` — and kind
+ * `reads`.
+ *
+ * **Its own scope**, because it reads across the Worker: every activity, the consent counts behind each consent
+ * basis, and where each stored class sits. It never widens another: the measures carry the evidence pack's states
+ * only for a connection that also holds {@link EVIDENCE_READ_SCOPE}, and a gap names a stored table or field only for
+ * one that also holds {@link PRIVACY_READ_SCOPE}. Without it, a gap names the capability and the class.
+ */
+export declare const PROCESSING_READ_SCOPE: ControlPlaneScope;
+/**
+ * Place and release a legal hold on a user, an organization or a tenant's audit trail. A write — both routes
+ * behind it are `POST`s — and kind `writes`, so `pithy dashboard connect` offers it and never grants it by default.
+ *
+ * **It can only preserve.** A hold suspends purges, prunes and inactivity deletions; releasing one returns the subject
+ * to the policy the Worker deploys with. No route behind it, or anywhere, shortens a retention.
+ */
+export declare const RETENTION_HOLD_SCOPE: ControlPlaneScope;
+/**
+ * Read the legal holds: every hold, standing or released, with who placed it and why. Read-only — the one
+ * route behind it is a `GET` — and kind `reads`. The manifest's count of standing holds sits behind it too:
+ * `activeHolds`, in the health of the `controlplane` entry.
+ */
+export declare const RETENTION_READ_SCOPE: ControlPlaneScope;
+/**
+ * List every connection bound to this Worker's environment: who authorized it, what kind of client it is for, its purpose, its
+ * credential kinds, its grant and when it was registered or revoked. Kind `reads`. Never key material.
+ */
+export declare const CONNECTIONS_READ_SCOPE: ControlPlaneScope;
+/**
+ * Revoke every key and trust another connection in this Worker's environment holds, with a reason. Kind
+ * `credentials`. Refused on the caller's own connection, which ends through `disconnect`.
+ */
+export declare const CONNECTIONS_REVOKE_SCOPE: ControlPlaneScope;
 /**
  * The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
  * because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
  *
- * **{@link MIGRATIONS_READ_SCOPE} and {@link PRIVACY_READ_SCOPE} are absent on purpose.** Each is a read —
+ * **The seam's reads are absent on purpose** — {@link MIGRATIONS_READ_SCOPE}, {@link PRIVACY_READ_SCOPE},
+ * {@link EVIDENCE_READ_SCOPE}, {@link ERASURE_READ_SCOPE}, {@link PROCESSING_READ_SCOPE}. Each is a read —
  * every route requiring it is a `GET` — so `connect` derives it from the seam's `adminRoutes` the way it
  * derives every capability's reads. The base exists for `keys:rotate`, which is not a read and would
  * otherwise drop out.

package/dist/controlPlane/scope/scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/scope/scope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA2D,CAAC;AAErG;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,mBAAmB,CAAC;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAmC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAAiC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,iBAAkC,CAAC;AAEpE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,iBAAiB,EAA6C,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIrH"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/scope/scope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA2D,CAAC;AAErG;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,mBAAmB,CAAC;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAmC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAAiC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,iBAAkC,CAAC;AAEpE;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAmC,CAAC;AAEtE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,iBAAkC,CAAC;AAEpE;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,iBAAoC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,iBAAoC,CAAC;AAExE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAAsC,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAwC,CAAC;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,iBAAiB,EAA6C,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIrH"}