@pithy-sh/core 0.13.0 → 0.15.0

package/dist/consent/purpose.d.ts

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * Consent purposes: what a person is asked to agree to, declared where the processing is.
+ *
+ * ## Declared, never discovered
+ *
+ * A capability that processes under consent says so, the way it states its migrations: `@pithy-sh/email` declares
+ * `email.marketing` and `email.tracking`. The adopter adds their own to `consent({ purposes })`. The consent
+ * capability composes every declaration into one catalog, and `hasConsent` answers only for a purpose in it.
+ *
+ * ## A purpose says what it covers and what it demands
+ *
+ * Beside its notice version, a purpose names the data classes it covers, whether it is **explicit** (GDPR
+ * Article 9), the **minimum method** a grant needs, and whether a withdrawal must be made at least at the grade
+ * of the grant it withdraws, the way a HIPAA revocation must be in writing.
+ *
+ * ## The id is the capability's own
+ *
+ * `<domain>.<name>`, and a capability may declare purposes only under its own `name`, the rule `pithy_<name>_*`
+ * tables and `<name>/…` error codes follow, for the same reason: the domain is what keeps two declarations from
+ * colliding. `defineCapability` refuses anything else, naming the capability.
+ */
+/**
+ * How a grant was given, weakest first. The order is the grade: a purpose's `minimumMethod` refuses a grant below
+ * it, and a purpose with `writtenWithdrawal` refuses a withdrawal below the grant it withdraws.
+ */
+export declare const CONSENT_METHODS: readonly ["click", "typed", "drawn", "provider"];
+/** How a consent was given or withdrawn. */
+export declare const ConsentMethod: z.ZodEnum<{
+    click: "click";
+    drawn: "drawn";
+    provider: "provider";
+    typed: "typed";
+}>;
+export type ConsentMethod = z.output<typeof ConsentMethod>;
+/** A method's grade: its place in {@link CONSENT_METHODS}, so `click` is 0 and `provider` is 3. */
+export declare function methodRank(method: ConsentMethod): number;
+/** Whether `method` meets `minimum`: at its grade or above. */
+export declare function meetsMethod(method: ConsentMethod, minimum: ConsentMethod): boolean;
+/** A purpose id: `<domain>.<name>`, lowercase, the domain being the declaring capability's name. */
+export declare const ConsentPurposeId: z.ZodString;
+export type ConsentPurposeId = z.output<typeof ConsentPurposeId>;
+/** One purpose a capability or the adopter processes under consent. */
+export declare const ConsentPurpose: z.ZodObject<{
+    id: z.ZodString;
+    summary: z.ZodString;
+    noticeVersion: z.ZodNumber;
+    classes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    explicit: z.ZodDefault<z.ZodBoolean>;
+    minimumMethod: z.ZodDefault<z.ZodEnum<{
+        click: "click";
+        drawn: "drawn";
+        provider: "provider";
+        typed: "typed";
+    }>>;
+    writtenWithdrawal: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ConsentPurpose = z.output<typeof ConsentPurpose>;
+export type ConsentPurposeInput = z.input<typeof ConsentPurpose>;
+/** The domain half of a purpose id: `email` for `email.marketing`. */
+export declare function purposeDomain(id: string): string;
+/**
+ * Parse one declarer's purposes and refuse what no consent capability could answer for: an id that is not a
+ * purpose id, one under a domain that is not the declarer's, or two with one id. `domain` is the declaring
+ * capability's name, or `null` for the adopter's own, which may use any domain but a reserved one.
+ */
+export declare function parseConsentPurposes(declarer: string, purposes: readonly ConsentPurposeInput[], domain: string | null, reserved?: ReadonlySet<string>): ConsentPurpose[];
+//# sourceMappingURL=purpose.d.ts.map

package/dist/consent/purpose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purpose.d.ts","sourceRoot":"","sources":["../../src/consent/purpose.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,YAAI,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAU,CAAC;AAEhF,4CAA4C;AAC5C,eAAO,MAAM,aAAa;;;;;EAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAExD;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAElF;AAED,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,aAS1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,uEAAuE;AACvE,eAAO,MAAM,cAAc;;;;;;;;;;;;;iBAuCsF,CAAC;AAClH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAC7D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEjE,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,mBAAmB,EAAE,EACxC,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,cAAc,EAAE,CAiClB"}

package/dist/consent/purpose.js

@@ -0,0 +1,97 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError } from "../error/pithyError.js";
+import { PrivacyClassName } from "../privacy/classes.js";
+import { z } from "zod";
+//#region src/consent/purpose.ts
+/**
+* Consent purposes: what a person is asked to agree to, declared where the processing is.
+*
+* ## Declared, never discovered
+*
+* A capability that processes under consent says so, the way it states its migrations: `@pithy-sh/email` declares
+* `email.marketing` and `email.tracking`. The adopter adds their own to `consent({ purposes })`. The consent
+* capability composes every declaration into one catalog, and `hasConsent` answers only for a purpose in it.
+*
+* ## A purpose says what it covers and what it demands
+*
+* Beside its notice version, a purpose names the data classes it covers, whether it is **explicit** (GDPR
+* Article 9), the **minimum method** a grant needs, and whether a withdrawal must be made at least at the grade
+* of the grant it withdraws, the way a HIPAA revocation must be in writing.
+*
+* ## The id is the capability's own
+*
+* `<domain>.<name>`, and a capability may declare purposes only under its own `name`, the rule `pithy_<name>_*`
+* tables and `<name>/…` error codes follow, for the same reason: the domain is what keeps two declarations from
+* colliding. `defineCapability` refuses anything else, naming the capability.
+*/
+/**
+* How a grant was given, weakest first. The order is the grade: a purpose's `minimumMethod` refuses a grant below
+* it, and a purpose with `writtenWithdrawal` refuses a withdrawal below the grant it withdraws.
+*/
+const CONSENT_METHODS = [
+	"click",
+	"typed",
+	"drawn",
+	"provider"
+];
+/** How a consent was given or withdrawn. */
+const ConsentMethod = z.enum(CONSENT_METHODS).describe("How a consent was given or withdrawn, weakest first: `click` (a checkbox or a button), `typed` (the person typed their name), `drawn` (a drawn signature), or `provider` (an e-signature provider's completed envelope). The order is the grade a purpose's minimum is held against.");
+/** A method's grade: its place in {@link CONSENT_METHODS}, so `click` is 0 and `provider` is 3. */
+function methodRank(method) {
+	return CONSENT_METHODS.indexOf(method);
+}
+/** Whether `method` meets `minimum`: at its grade or above. */
+function meetsMethod(method, minimum) {
+	return methodRank(method) >= methodRank(minimum);
+}
+/** A purpose id: `<domain>.<name>`, lowercase, the domain being the declaring capability's name. */
+const ConsentPurposeId = z.string().regex(/^[a-z][a-z0-9-]*\.[a-z][a-z0-9_.-]*$/, "A consent purpose id is `<domain>.<name>`: lowercase, the domain being the declaring capability's name.").max(128).describe("A consent purpose id, `<domain>.<name>` — `email.marketing`. The domain is the declaring capability's name, or the adopter's own domain for a purpose declared in `consent({ purposes })`.");
+/** One purpose a capability or the adopter processes under consent. */
+const ConsentPurpose = z.object({
+	id: ConsentPurposeId,
+	summary: z.string().min(1).max(500).describe("One sentence, written for the person, on what agreeing allows — `Send me news and offers by email.` Shown on the consent settings screen."),
+	noticeVersion: z.number().int().positive().describe("The version of the notice a person agrees to. Bump it when the notice changes: every grant under an older version then needs renewing, and `hasConsent` answers no for it until it is."),
+	classes: z.array(PrivacyClassName).default([]).describe("The data classes this purpose covers — `pii`, `phi`, or an adopter's own. The processing record reads it to name a classed field with no consent behind it."),
+	explicit: z.boolean().default(false).describe("Whether this purpose needs explicit consent (GDPR Article 9), as processing health data does. Recorded so an auditor can see which purposes claim it."),
+	minimumMethod: ConsentMethod.default("click").describe("The weakest method a grant may be given by. A grant below it is refused, and `hasConsent` answers no for one recorded below it before the minimum was raised."),
+	writtenWithdrawal: z.boolean().default(false).describe("Whether a withdrawal must be made at least at the grade of the grant it withdraws, as a HIPAA revocation must be in writing. Off, a click withdraws any grant: withdrawing is then never harder than granting.")
+}).describe("One purpose processed under consent: what it allows, its notice version, and what a grant demands.");
+/** The domain half of a purpose id: `email` for `email.marketing`. */
+function purposeDomain(id) {
+	const dot = id.indexOf(".");
+	return dot === -1 ? id : id.slice(0, dot);
+}
+/**
+* Parse one declarer's purposes and refuse what no consent capability could answer for: an id that is not a
+* purpose id, one under a domain that is not the declarer's, or two with one id. `domain` is the declaring
+* capability's name, or `null` for the adopter's own, which may use any domain but a reserved one.
+*/
+function parseConsentPurposes(declarer, purposes, domain, reserved = /* @__PURE__ */ new Set()) {
+	const seen = /* @__PURE__ */ new Set();
+	return purposes.map((input) => {
+		const parsed = ConsentPurpose.safeParse(input);
+		if (!parsed.success) throw new ValidationError({
+			message: `${declarer} declares a consent purpose that is not valid: ${parsed.error.issues[0]?.message ?? "invalid"}.`,
+			action: "Give it an id of the form `<domain>.<name>`, a summary, and a positive notice version."
+		});
+		const purpose = parsed.data;
+		const own = purposeDomain(purpose.id);
+		if (domain !== null && own !== domain) throw new ValidationError({
+			message: `The ${declarer} capability declares the consent purpose "${purpose.id}" outside its own domain.`,
+			action: `Name it under ${domain}. — a capability declares purposes only under its own name.`
+		});
+		if (domain === null && reserved.has(own)) throw new ValidationError({
+			message: `The consent purpose "${purpose.id}" is under ${own}., which a composed capability owns.`,
+			action: "Name your own purposes under your own domain, such as your app's name."
+		});
+		if (seen.has(purpose.id)) throw new ValidationError({
+			message: `${declarer} declares the consent purpose "${purpose.id}" twice.`,
+			action: "Declare each purpose once."
+		});
+		seen.add(purpose.id);
+		return purpose;
+	});
+}
+//#endregion
+export { CONSENT_METHODS, ConsentMethod, ConsentPurpose, ConsentPurposeId, meetsMethod, methodRank, parseConsentPurposes, purposeDomain };

package/dist/consent/reader.d.ts

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../capability/capability";
+import type { ConsentPurpose } from "./purpose";
+/**
+ * The consent seam: the one question a capability asks before consent-based processing.
+ *
+ * `@pithy-sh/consent` answers it, and nothing imports that package to ask: a capability finds the composed reader
+ * through {@link composedConsent}, the shape `composedAuditEmit` gives the audit recorder, so `@pithy-sh/email`
+ * gates its tracking without depending on a sibling (principle 4).
+ *
+ * **Absent is not "no".** With no consent capability composed there is no record to consult, so
+ * {@link composedConsent} answers `null`, and a capability gates nothing on it. `pithy doctor`
+ * names that state, because processing that a law may require consent for is running with no record behind it.
+ */
+/** The subject a consent is recorded against: an account's user id, or a visitor's anonymous device id. */
+export interface ConsentSubject {
+    /** `account` — a user id from `@pithy-sh/auth`; `visitor` — an anonymous device id held in a first-party cookie. */
+    readonly kind: "account" | "visitor";
+    /** The id in that kind. */
+    readonly id: string;
+}
+/** What the consent capability answers. */
+export interface ConsentReader {
+    /**
+     * Whether `subject` holds consent to `purpose` now: a grant under the purpose's current notice version, at or
+     * above its minimum method, not withdrawn since, and not expired. An account's answer includes what the visitors
+     * merged into it granted. A purpose the catalog does not know answers no.
+     */
+    hasConsent(subject: ConsentSubject, purpose: string): Promise<boolean>;
+    /**
+     * Every purpose in the composed catalog, the adopter's included, with how many subjects stand where on it now. What
+     * the processing record cites for a consent-based activity. Optional on the seam: a reader without it leaves the
+     * counts unknown, never zero.
+     */
+    standings?(): Promise<readonly ConsentPurposeStanding[]>;
+    /**
+     * Every purpose in the composed catalog, the adopter's included, read from memory and never from the record. What
+     * the processing record checks a consent basis against when `standings` cannot answer. Optional on the seam: a
+     * reader without it leaves the catalog unknown, and the record then reports no gap that rests on the catalog.
+     */
+    purposes?(): readonly ConsentPurpose[];
+}
+/** One purpose in the catalog, and where its subjects stand on it now. */
+export interface ConsentPurposeStanding {
+    /** The purpose as the catalog composed it. */
+    readonly purpose: ConsentPurpose;
+    /** Subjects whose latest choice is a grant, under any notice version, expired or not. */
+    readonly grants: number;
+    /** Subjects whose latest choice is a withdrawal. */
+    readonly withdrawals: number;
+    /**
+     * Subjects `hasConsent` answers yes for now: a grant under the current notice version, at or above the purpose's
+     * minimum method, unexpired, and for a visitor not merged into an account, inside the visitor window.
+     */
+    readonly standing: number;
+}
+/** One withdrawal, as a capability that keeps its own state in step with consent is told of it. */
+export interface ConsentWithdrawal {
+    /** Who withdrew. */
+    readonly subject: ConsentSubject;
+    /** What they withdrew from. */
+    readonly purpose: string;
+    /** The Worker's bindings for this request. */
+    readonly env: Record<string, unknown>;
+    /**
+     * The subject's email address, read on demand from the capability that owns accounts, or `null` for a visitor
+     * or an account with none. A function, so a listener that needs no address reads none.
+     */
+    readonly address: () => Promise<string | null>;
+}
+/**
+ * Hear of a withdrawal from one of this capability's own purposes. `@pithy-sh/email` suppresses the address for
+ * marketing when `email.marketing` is withdrawn, so the suppression list and the consent record never disagree.
+ * Called after the withdrawal is recorded; a throw is the listener's own failure and never undoes the record.
+ */
+export type ConsentWithdrawnListener = (withdrawal: ConsentWithdrawal) => Promise<void>;
+/** One grant that now stands, as a capability that keeps its own state in step with consent is told of it. */
+export type ConsentGrant = ConsentWithdrawal;
+/**
+ * Hear of a grant to one of this capability's own purposes, once it stands. The other half of
+ * {@link ConsentWithdrawnListener}: `@pithy-sh/email` lifts the marketing suppression a withdrawal wrote when
+ * `email.marketing` is granted again, and nothing else, so a person who changes their mind back is heard. Called
+ * after the grant is recorded and only when the subject's standing is `granted`; a throw never undoes the record.
+ */
+export type ConsentGrantedListener = (grant: ConsentGrant) => Promise<void>;
+/** Every purpose the composed capabilities declare, in composition order. */
+export declare function composedConsentPurposes(capabilities: readonly Capability[]): ConsentPurpose[];
+/** The composed consent reader for this env, or `null` when no capability provides one. */
+export declare function composedConsent(capabilities: readonly Capability[], env: Record<string, unknown>): ConsentReader | null;
+/** Whether any composed capability provides the consent seam. */
+export declare function providesConsent(capabilities: readonly Capability[]): boolean;
+/**
+ * The account's address, read through the capability that owns accounts (`@pithy-sh/auth`'s `addressOf`), or
+ * `null` where nothing composed can say. Never throws: a listener that cannot learn the address does less, and the
+ * withdrawal it heard of stands.
+ */
+export declare function composedAddress(capabilities: readonly Capability[], env: Record<string, unknown>, subject: ConsentSubject): Promise<string | null>;
+//# sourceMappingURL=reader.d.ts.map

package/dist/consent/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/consent/reader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;;GAUG;AAEH,2GAA2G;AAC3G,MAAM,WAAW,cAAc;IAC7B,oHAAoH;IACpH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE;;;;OAIG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAAC;IACzD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,SAAS,cAAc,EAAE,CAAC;CACxC;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,mGAAmG;AACnG,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,UAAU,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExF,8GAA8G;AAC9G,MAAM,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,cAAc,EAAE,CAE7F;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAC7B,YAAY,EAAE,SAAS,UAAU,EAAE,EACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,aAAa,GAAG,IAAI,CAGtB;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAE5E;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,SAAS,UAAU,EAAE,EACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxB"}

package/dist/consent/reader.js

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/consent/reader.ts
+/** Every purpose the composed capabilities declare, in composition order. */
+function composedConsentPurposes(capabilities) {
+	return capabilities.flatMap((capability) => [...capability.consentPurposes ?? []]);
+}
+/** The composed consent reader for this env, or `null` when no capability provides one. */
+function composedConsent(capabilities, env) {
+	const provider = capabilities.find((capability) => capability.consentReader !== void 0);
+	return provider?.consentReader ? provider.consentReader(env) : null;
+}
+/** Whether any composed capability provides the consent seam. */
+function providesConsent(capabilities) {
+	return capabilities.some((capability) => capability.consentReader !== void 0);
+}
+/**
+* The account's address, read through the capability that owns accounts (`@pithy-sh/auth`'s `addressOf`), or
+* `null` where nothing composed can say. Never throws: a listener that cannot learn the address does less, and the
+* withdrawal it heard of stands.
+*/
+async function composedAddress(capabilities, env, subject) {
+	if (subject.kind !== "account") return null;
+	const provider = capabilities.find((capability) => capability.addressOf !== void 0);
+	if (!provider?.addressOf) return null;
+	try {
+		return await provider.addressOf(env, subject.id);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { composedAddress, composedConsent, composedConsentPurposes, providesConsent };

package/dist/controlPlane/audit/actions.d.ts

@@ -22,8 +22,8 @@ import type { Logger } from "../../logger/logger";
  * Emission goes through core's `emit` seam (`c.var.emit`), a no-op when the audit capability is
  * absent, so the seam never imports audit at runtime either (principle 4).
  *
- * **Four of these are emitted by a route; three are emitted by the CLI** (#294). The connection
- * lifecycle — registered, updated, removed — is written by `pithy dashboard` opening the adopter's D1
+ * **Most of these are emitted by a route; four are emitted by the CLI, one of them by a route as well.** The
+ * connection lifecycle — registered, updated, removed — is written by `pithy dashboard` opening the adopter's D1
  * directly, because those operations never reach their Worker: a first connect has no key to sign with
  * and the Worker may not be deployed, an update re-points an address the Worker never reads, and a
  * disconnect withdraws trust, which must not depend on a working connection (docs/CONTROL-PLANE.md §15).
@@ -32,8 +32,12 @@ import type { Logger } from "../../logger/logger";
  * `control-plane`, meaning the management client called in and proved it, while a CLI-side event carries
  * the adopter's own operator and no session at all.
  *
- * A declared code that nothing emits is a surface the trail promises and never delivers, which is what
- * these three were until #294. `packages/cli/src/ci/auditActions.test.ts` fails the build on one.
+ * `connectionRevoked` is the one written from both sides: by `POST {basePath}/connections/:connectionId/revoke`,
+ * with `actorType` `control-plane` and the caller's connection, and by `pithy dashboard connections --revoke`, with
+ * the operator as actor and no session.
+ *
+ * A declared code that nothing emits is a surface the trail promises and never delivers.
+ * `packages/cli/src/ci/auditActions.test.ts` fails the build on one.
  */
 export declare const ControlPlaneAuditActions: {
     /** A verified, in-scope management call was admitted. The trail of what the dashboard actually did. */
@@ -50,6 +54,13 @@ export declare const ControlPlaneAuditActions: {
     readonly connectionUpdated: "controlplane/connection_updated";
     /** A connection was removed. The seam returns to its shipped state: connected to nothing, denying everything. */
     readonly connectionRemoved: "controlplane/connection_removed";
+    /**
+     * Another connection's keys and trusts were revoked, with a reason: by a management client over the seam, or by the
+     * operator at the CLI.
+     */
+    readonly connectionRevoked: "controlplane/connection_revoked";
+    readonly holdPlaced: "controlplane/hold_placed";
+    readonly holdReleased: "controlplane/hold_released";
 };
 /** One of the control-plane audit action codes. */
 export type ControlPlaneAuditAction = (typeof ControlPlaneAuditActions)[keyof typeof ControlPlaneAuditActions];

package/dist/controlPlane/audit/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/audit/actions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,wBAAwB;IACnC,uGAAuG;aACvG,WAAW,EAAE,2BAA2B;IACxC,8GAA8G;aAC9G,UAAU,EAAE,0BAA0B;IACtC,mFAAmF;aACnF,aAAa,EAAE,6BAA6B;IAC5C,gFAAgF;aAChF,UAAU,EAAE,0BAA0B;IACtC,qGAAqG;aACrG,oBAAoB,EAAE,oCAAoC;IAC1D,+GAA+G;aAC/G,iBAAiB,EAAE,iCAAiC;IACpD,iHAAiH;aACjH,iBAAiB,EAAE,iCAAiC;CAC5C,CAAC;AAEX,mDAAmD;AACnD,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAE/G;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnG"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/audit/actions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,wBAAwB;IACnC,uGAAuG;aACvG,WAAW,EAAE,2BAA2B;IACxC,8GAA8G;aAC9G,UAAU,EAAE,0BAA0B;IACtC,mFAAmF;aACnF,aAAa,EAAE,6BAA6B;IAC5C,gFAAgF;aAChF,UAAU,EAAE,0BAA0B;IACtC,qGAAqG;aACrG,oBAAoB,EAAE,oCAAoC;IAC1D,+GAA+G;aAC/G,iBAAiB,EAAE,iCAAiC;IACpD,iHAAiH;aACjH,iBAAiB,EAAE,iCAAiC;IACpD;;;OAGG;aACH,iBAAiB,EAAE,iCAAiC;aACpD,UAAU,EAAE,0BAA0B;aACtC,YAAY,EAAE,4BAA4B;CAClC,CAAC;AAEX,mDAAmD;AACnD,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAE/G;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnG"}

package/dist/controlPlane/audit/actions.js

@@ -20,8 +20,8 @@
 * Emission goes through core's `emit` seam (`c.var.emit`), a no-op when the audit capability is
 * absent, so the seam never imports audit at runtime either (principle 4).
 *
-* **Four of these are emitted by a route; three are emitted by the CLI** (#294). The connection
-* lifecycle — registered, updated, removed — is written by `pithy dashboard` opening the adopter's D1
+* **Most of these are emitted by a route; four are emitted by the CLI, one of them by a route as well.** The
+* connection lifecycle — registered, updated, removed — is written by `pithy dashboard` opening the adopter's D1
 * directly, because those operations never reach their Worker: a first connect has no key to sign with
 * and the Worker may not be deployed, an update re-points an address the Worker never reads, and a
 * disconnect withdraws trust, which must not depend on a working connection (docs/CONTROL-PLANE.md §15).
@@ -30,8 +30,12 @@
 * `control-plane`, meaning the management client called in and proved it, while a CLI-side event carries
 * the adopter's own operator and no session at all.
 *
-* A declared code that nothing emits is a surface the trail promises and never delivers, which is what
-* these three were until #294. `packages/cli/src/ci/auditActions.test.ts` fails the build on one.
+* `connectionRevoked` is the one written from both sides: by `POST {basePath}/connections/:connectionId/revoke`,
+* with `actorType` `control-plane` and the caller's connection, and by `pithy dashboard connections --revoke`, with
+* the operator as actor and no session.
+*
+* A declared code that nothing emits is a surface the trail promises and never delivers.
+* `packages/cli/src/ci/auditActions.test.ts` fails the build on one.
 */
 const ControlPlaneAuditActions = {
 	/** A verified, in-scope management call was admitted. The trail of what the dashboard actually did. */
@@ -47,7 +51,14 @@ const ControlPlaneAuditActions = {
 	/** An existing connection changed — its granted scopes, the Worker URL it points at, or the keys it trusts. */
 	connectionUpdated: "controlplane/connection_updated",
 	/** A connection was removed. The seam returns to its shipped state: connected to nothing, denying everything. */
-	connectionRemoved: "controlplane/connection_removed"
+	connectionRemoved: "controlplane/connection_removed",
+	/**
+	* Another connection's keys and trusts were revoked, with a reason: by a management client over the seam, or by the
+	* operator at the CLI.
+	*/
+	connectionRevoked: "controlplane/connection_revoked",
+	holdPlaced: "controlplane/hold_placed",
+	holdReleased: "controlplane/hold_released"
 };
 /**
 * Emit an audit event and swallow any failure.

package/dist/controlPlane/capability.d.ts

@@ -17,6 +17,16 @@ import { CONTROL_PLANE_KV_BINDING } from "./replay/kvGuard";
  */
 export declare const CONTROLPLANE_MIGRATION_ORDER = 1100;
 export type ControlPlaneOptions = ControlPlaneConfigInput;
+/** The standing legal holds, on the seam's own manifest entry. Behind the scope the holds listing requires. */
+export declare const ACTIVE_HOLDS_HEALTH_KEY: {
+    readonly key: "activeHolds";
+    readonly kind: "count";
+    readonly states: null;
+    readonly scope: string;
+    readonly cost: "indexed";
+    readonly summary: "Legal holds standing. While one stands, no purge, prune or inactivity deletion touches its subject.";
+    readonly nominal: null;
+};
 /** The control-plane capability, with its resolved config attached. */
 export interface ControlPlaneCapability extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "controlplane"> {
     /** The resolved seam config. */

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

@@ -1 +1 @@
-{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/controlPlane/capability.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,UAAU,EAAuC,MAAM,0BAA0B,CAAC;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAc,MAAM,kBAAkB,CAAC;AAKvE,OAAO,EAAE,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAkBnF,OAAO,EACL,wBAAwB,EAIzB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE1D,uEAAuE;AACvE,MAAM,WAAW,sBAAuB,SAAQ,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,cAAc,CAAC;IAC7G,gCAAgC;IAChC,kBAAkB,EAAE,kBAAkB,CAAC;CACxC;AAED,qGAAqG;AACrG,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,sBAAsB,CAErG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,sBAAsB,CA6LtF;AAED,4GAA4G;AAC5G,OAAO,EAAE,wBAAwB,EAAE,CAAC"}
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/controlPlane/capability.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,UAAU,EAAuC,MAAM,0BAA0B,CAAC;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAc,MAAM,kBAAkB,CAAC;AAWvE,OAAO,EAAE,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAqBnF,OAAO,EACL,wBAAwB,EAIzB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE1D,+GAA+G;AAC/G,eAAO,MAAM,uBAAuB;aAClC,GAAG,EAAE,aAAa;aAClB,IAAI,EAAE,OAAO;aACb,MAAM;aACN,KAAK;aACL,IAAI,EAAE,SAAS;aACf,OAAO,EAAE,qGAAqG;aAC9G,OAAO;CACC,CAAC;AAEX,uEAAuE;AACvE,MAAM,WAAW,sBAAuB,SAAQ,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,cAAc,CAAC;IAC7G,gCAAgC;IAChC,kBAAkB,EAAE,kBAAkB,CAAC;CACxC;AAED,qGAAqG;AACrG,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,sBAAsB,CAErG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,sBAAsB,CAsPtF;AAED,4GAA4G;AAC5G,OAAO,EAAE,wBAAwB,EAAE,CAAC"}

package/dist/controlPlane/capability.js

@@ -1,13 +1,21 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import { RETENTION_READ_SCOPE } from "./scope/scope.js";
 import { defineCapability } from "../capability/capability.js";
+import { memoryJwksCache } from "../http/oidcWebhook.js";
+import { routeGroupsOf } from "../openapi/routeGroups.js";
+import { describePresenceRooms } from "../presence/http/routes.js";
 import { readRetirement } from "../privacy/fieldRotation.js";
 import { lazyPrivacyInventory } from "../privacy/inventory.js";
+import { composedRetention } from "../retention/composed.js";
+import { ControlPlaneConnection } from "./data/connection.js";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, controlPlaneTables } from "./data/tables.js";
+import { standingHolds } from "../retention/holds.js";
+import { holdsUserPurge } from "../retention/holdsPurge.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.generated.js";
 import "../worker/identity.js";
 import { ControlPlaneConfig } from "./config/config.js";
-import { ControlPlaneConnection } from "./data/connection.js";
-import { CONTROL_PLANE_CONNECTIONS_TABLE, controlPlaneTables } from "./data/tables.js";
+import { recordTrustFirstCall } from "./data/trustFirstCall.js";
 import { capabilityHealthSources, defineCapabilityHealth } from "./discovery/health.js";
 import { createControlPlaneVerifier } from "./http/guard.js";
 import { MIGRATION_HEALTH_KEYS, composeMigrationDatabases, readMigrationHealth } from "./migrationState/migrationState.js";
@@ -15,6 +23,8 @@ import { controlPlaneRouteDescriptors, registerControlPlaneRoutes } from "./http
 import { controlplane_0001_init } from "./migrations/0001_init.js";
 import { controlplane_0002_management_origin } from "./migrations/0002_management_origin.js";
 import { controlplane_0003_connection_principal } from "./migrations/0003_connection_principal.js";
+import { controlplane_0004_connection_trusts } from "./migrations/0004_connection_trusts.js";
+import { controlplane_0005_holds } from "./migrations/0005_holds.js";
 import { d1ReplayGuard } from "./replay/d1Guard.js";
 import { CONTROL_PLANE_KV_BINDING, controlPlaneKvNamespaces, kvReplayGuard } from "./replay/kvGuard.js";
 //#region src/controlPlane/capability.ts
@@ -29,6 +39,16 @@ import { CONTROL_PLANE_KV_BINDING, controlPlaneKvNamespaces, kvReplayGuard } fro
 * composed key and make Kysely re-run an applied migration.
 */
 const CONTROLPLANE_MIGRATION_ORDER = 1100;
+/** The standing legal holds, on the seam's own manifest entry. Behind the scope the holds listing requires. */
+const ACTIVE_HOLDS_HEALTH_KEY = {
+	key: "activeHolds",
+	kind: "count",
+	states: null,
+	scope: RETENTION_READ_SCOPE,
+	cost: "indexed",
+	summary: "Legal holds standing. While one stands, no purge, prune or inactivity deletion touches its subject.",
+	nominal: null
+};
 /** Narrow a composed capability to this one — the CLI and tests use it to find the seam's config. */
 function isControlPlaneCapability(capability) {
 	return capability.name === "controlplane";
@@ -57,7 +77,9 @@ function controlplane(options = {}) {
 	const migrations = {
 		"0001_init": controlplane_0001_init,
 		"0002_management_origin": controlplane_0002_management_origin,
-		"0003_connection_principal": controlplane_0003_connection_principal
+		"0003_connection_principal": controlplane_0003_connection_principal,
+		"0004_connection_trusts": controlplane_0004_connection_trusts,
+		"0005_holds": controlplane_0005_holds
 	};
 	const requiredBindings = [{
 		type: "d1",
@@ -75,6 +97,7 @@ function controlplane(options = {}) {
 	*/
 	const database = (c) => c.var.db.app;
 	const now = () => /* @__PURE__ */ new Date();
+	const jwksCache = memoryJwksCache({ now });
 	/**
 	* The replay guard for this request, chosen once by config.
 	*
@@ -90,6 +113,7 @@ function controlplane(options = {}) {
 	let health = /* @__PURE__ */ new Map();
 	let migrationDatabases = [];
 	let composedCapabilities = [];
+	let presence = /* @__PURE__ */ new Map();
 	const privacy = lazyPrivacyInventory(() => composedCapabilities);
 	return {
 		...defineCapability({
@@ -106,9 +130,17 @@ function controlplane(options = {}) {
 			} },
 			kvNamespaces: usesKvReplay ? controlPlaneKvNamespaces(config.jtiTtlSeconds) : {},
 			adminRoutes: controlPlaneRouteDescriptors(config.basePath),
+			purge: [holdsUserPurge()],
 			health: defineCapabilityHealth({
-				keys: MIGRATION_HEALTH_KEYS,
-				read: (c) => readMigrationHealth(c.env, migrationDatabases)
+				keys: [...MIGRATION_HEALTH_KEYS, ACTIVE_HOLDS_HEALTH_KEY],
+				read: async (c) => {
+					const env = c.env;
+					const [migrations, activeHolds] = await Promise.all([readMigrationHealth(env, migrationDatabases), standingHolds(env)]);
+					return {
+						...migrations,
+						activeHolds
+					};
+				}
 			}),
 			compose: ({ capabilities }) => {
 				composed = capabilities.map((cap) => ({
@@ -118,8 +150,10 @@ function controlplane(options = {}) {
 					adminRoutes: [...cap.adminRoutes ?? []],
 					healthKeys: [...cap.health?.keys ?? []],
 					configKeys: [...cap.manifestConfig?.keys ?? []],
-					config: { ...cap.manifestConfig?.values ?? {} }
+					config: { ...cap.manifestConfig?.values ?? {} },
+					presenceRooms: cap.presence ? describePresenceRooms(cap.presence) : []
 				}));
+				presence = new Map(capabilities.flatMap((cap) => cap.presence ? cap.presence.rooms.map((room) => [room.kind, cap.presence]) : []));
 				health = capabilityHealthSources(capabilities);
 				migrationDatabases = composeMigrationDatabases(capabilities);
 				composedCapabilities = [...capabilities];
@@ -127,6 +161,7 @@ function controlplane(options = {}) {
 			middleware: [(app) => {
 				app.use("*", async (c, next) => {
 					const db = database(c);
+					const environment = String(c.env["ENVIRONMENT"] ?? "");
 					c.set("controlPlaneVerifier", createControlPlaneVerifier({
 						loadConnection: async (connectionId) => {
 							const row = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("id", "=", connectionId).executeTakeFirst();
@@ -136,9 +171,18 @@ function controlplane(options = {}) {
 							return (await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).select("id").limit(1).execute()).length;
 						},
 						replay: replay(c),
-						environment: String(c.env["ENVIRONMENT"] ?? ""),
+						environment,
 						config,
 						now
+					}, {
+						loadEnvironmentConnection: async () => {
+							const row = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("environment", "=", environment).executeTakeFirst();
+							return row ? ControlPlaneConnection.parse(row) : null;
+						},
+						environment,
+						now,
+						jwksCache,
+						recordFirstCall: (connectionId, trustId, at) => recordTrustFirstCall(db, connectionId, trustId, at)
 					}));
 					await next();
 				});
@@ -152,6 +196,10 @@ function controlplane(options = {}) {
 					composedMigrations: () => migrationDatabases,
 					privacyInventory: privacy,
 					retirement: (env) => readRetirement(env, composedCapabilities),
+					composedPresence: () => presence,
+					composition: () => composedCapabilities,
+					routeGroups: () => routeGroupsOf(app),
+					retention: composedRetention,
 					now
 				});
 			}
@@ -160,4 +208,4 @@ function controlplane(options = {}) {
 	};
 }
 //#endregion
-export { CONTROLPLANE_MIGRATION_ORDER, CONTROL_PLANE_KV_BINDING, controlplane, isControlPlaneCapability };
+export { ACTIVE_HOLDS_HEALTH_KEY, CONTROLPLANE_MIGRATION_ORDER, CONTROL_PLANE_KV_BINDING, controlplane, isControlPlaneCapability };

package/dist/controlPlane/context.d.ts

@@ -24,6 +24,10 @@ export declare const ControlPlaneContext: z.ZodObject<{
     grantedScopes: z.ZodArray<z.ZodString>;
     keyId: z.ZodString;
     tokenId: z.ZodString;
+    credentialKind: z.ZodOptional<z.ZodEnum<{
+        key: "key";
+        trust: "trust";
+    }>>;
     actorKind: z.ZodNullable<z.ZodEnum<{
         agent: "agent";
         dashboard: "dashboard";

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

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/controlPlane/context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBA4C7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/controlPlane/context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAoD7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/controlPlane/context.js

@@ -25,8 +25,9 @@ const ControlPlaneContext = z.object({
 	subject: z.string().describe("The management client's own user id from the token's `sub` — who, on their side, is acting. Recorded as the audit `actorId` so the trail answers 'which person at the dashboard did this', not just 'the dashboard'."),
 	scope: ControlPlaneScope.describe("The single scope this token was minted for. One call, one operation — a token carrying the whole grant would make every call as dangerous as the most dangerous one."),
 	grantedScopes: z.array(ControlPlaneScope).describe("Every scope the adopter granted this connection, read from their own row. The authority: a scope absent here is denied however the token is written."),
-	keyId: z.string().describe("Which registered key verified this call. Recorded so a rotation can be traced through the trail, and so a key still in use is visible before it is expired."),
-	tokenId: z.string().describe("The token's `jti`, already claimed in the replay set. Recorded to tie one audit event to one call."),
+	keyId: z.string().describe("Which registered key verified this call — or, for a call under an OIDC trust, which trust. Recorded so a rotation can be traced through the trail, and so a credential still in use is visible before it is retired."),
+	tokenId: z.string().describe("The token's `jti`, already claimed in the replay set. Recorded to tie one audit event to one call. For a call under an OIDC trust, the provider token's own `jti` when it carries one, else empty: such a token is verified per call and never spent."),
+	credentialKind: z.enum(["key", "trust"]).optional().describe("Which kind of credential verified this call: a registered `key`, or an OIDC `trust` (#722), in which case `keyId` names the trust. Absent reads as a key, which is every call made before trusts existed."),
 	actorKind: ControlPlaneActorKind.nullable().describe("What kind of client the connection is for — `agent`, `dashboard` or `script` — read from the adopter's own row, never from the token. The gate stamps it onto every control-plane audit row this call writes. Null for a connection registered before the kind was recorded (#721).")
 }).describe("The verified control-plane caller for one request. Never an AuthContext: a management client is not a user of the adopter's app.");
 //#endregion