@pithy-sh/core 0.13.0 → 0.14.0

package/dist/controlPlane/data/oidcTrust.js

@@ -0,0 +1,173 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ControlPlaneKeyConflictError } from "../error/errors.js";
+import { JsonDate } from "../../data/codecs.js";
+import { z } from "zod";
+//#region src/controlPlane/data/oidcTrust.ts
+/**
+* An OIDC trust: the second credential kind a connection may hold, beside a registered key
+* (`docs/AGENT-ACCESS.md` §6.2, #722).
+*
+* A key is a bearer: one client holds the private half. A trust is a **policy**: a trusted issuer, the
+* audience its tokens must name, and a matcher over the claims that say which workload a token was minted
+* for. Nobody holds a secret. The workload asks its own identity provider for a short-lived token, and the
+* Worker checks it against the issuer's published keys with the verifier the webhooks already use,
+* `core/src/http/oidcWebhook.ts`.
+*
+* ## The claims become data here, and that is a deliberate departure
+*
+* In a webhook the claims check is a predicate the **route** holds, because whoever wrote the route knows
+* the legitimate sender. A connection's trust is per adopter, decided at registration by the same person who
+* grants the scopes, so the matcher is stored with the trust and validated on the way in. That is the whole
+* reason {@link OidcClaimMatch} exists rather than a function.
+*
+* ## The claims check is the boundary, not the signature
+*
+* An identity provider signs for everybody with the same keys. GitHub signs a token for every repository on
+* the planet. A trust whose matcher constrains nothing accepts all of them, so {@link OidcClaimMatch} refuses
+* one at registration — structurally, not as a warning — and refuses the claims that name the token rather
+* than the workload ({@link RESERVED_OIDC_CLAIMS}), since a matcher made of those constrains nothing either.
+*
+* ## Named claims, not the `sub` string
+*
+* A `sub` is a concatenation whose composition belongs to the provider and to the adopter's own template.
+* The claims beneath it — GitHub's `repository_id`, `environment`, `ref`; GitLab's `project_id` — are
+* published individually and are stable. So the matcher is a map of claim names to values, and `sub` is one
+* claim among the others rather than a special case.
+*
+* ## No rotation, and revocation changes shape
+*
+* There is no key to append, prove and expire. A token cannot be revoked; the trust is, and every token
+* already minted stays live until it expires — {@link TRUST_REVOCATION_LATENCY} is the sentence that says
+* so at the moment it matters.
+*
+* Nothing in this module reads a clock, a binding or D1. `now` is injected wherever time matters.
+*/
+/**
+* Claims that name the token rather than the workload: who minted it, for whom, and when. A matcher built
+* from these alone would accept every workload the issuer serves, so none of them may be registered.
+* `iss` and `aud` are checked anyway, by the trust's own issuer and audience.
+*/
+const RESERVED_OIDC_CLAIMS = [
+	"iss",
+	"aud",
+	"exp",
+	"nbf",
+	"iat",
+	"jti"
+];
+/** The most claims one trust may match on. Far above any real constraint; a bound on a stored row. */
+const MAX_TRUST_CLAIMS = 16;
+/** The most claims a refusal records, so a token carrying a hundred cannot fill the audit trail. */
+const MAX_OBSERVED_CLAIMS = 32;
+/** The longest claim value a matcher stores or a refusal records. */
+const MAX_CLAIM_VALUE = 256;
+/** A claim name: the plain alphabet providers use, plus `.`, `:` and `-` for a customized template. */
+const CLAIM_NAME = /^[A-Za-z0-9_.:-]{1,64}$/;
+/** Every C0 and C1 control, the line separators, and the bidi controls: a value is one line of plain text. */
+const UNRENDERABLE = /[\p{Cc}\p{Bidi_Control}\u2028\u2029]/u;
+const reserved = new Set(RESERVED_OIDC_CLAIMS);
+/**
+* One claim name in a matcher. A name, not a path: nested claims are not matched, because a matcher that
+* walks a structure is a matcher with more ways to be wrong on the check the whole trust rests on.
+*/
+const OidcClaimName = z.string().regex(CLAIM_NAME, "A claim name is letters, digits, `_`, `.`, `:` or `-`, at most 64.").refine((name) => !reserved.has(name), { message: `${RESERVED_OIDC_CLAIMS.join(", ")} name the token, not the workload, so they cannot constrain a trust.` }).describe("A claim the token must carry, by name — `repository_id`, `environment`, `project_id`, `sub`. Never one of the claims that name the token itself.");
+/** One claim value in a matcher: compared as a string against the token's claim of the same name. */
+const OidcClaimValue = z.string().min(1, "A claim value cannot be empty.").max(256, `A claim value is 256 characters at most.`).refine((value) => !UNRENDERABLE.test(value), "A claim value is one line of plain text.").describe("The exact value that claim must have. A numeric or boolean claim is compared by its string form, so `1262274726` matches a `repository_id` whichever way the provider typed it.");
+/**
+* Which workloads a trust accepts: every named claim must equal its value.
+*
+* **At least one, and that is the refusal the whole credential kind rests on.** An issuer with no claim
+* constraint accepts every workload it serves.
+*/
+const OidcClaimMatch = z.record(OidcClaimName, OidcClaimValue).refine((claims) => Object.keys(claims).length > 0, { message: "A trust needs at least one claim constraint. An issuer alone accepts every workload it serves." }).refine((claims) => Object.keys(claims).length <= 16, { message: `A trust matches on 16 claims at most.` }).describe("The subject constraint: every named claim must equal its value. At least one, because an issuer alone accepts every workload it serves.");
+/** An https URL. A trust's issuer and key endpoint are fetched from, so plain http is refused. */
+const HttpsUrl = z.url({ protocol: /^https$/ });
+/**
+* One registered OIDC trust, an element of the connection's `trusts` column.
+*
+* Stored beside `keys` rather than inside it: the two kinds share nothing but the connection they grant
+* through, and a union array would make every key reader learn about trusts.
+*/
+const OidcTrust = z.object({
+	trustId: z.string().min(1).max(64).describe("The trust's id, named by a call on the `pithy-control-plane-trust` header the way a token's `kid` names a key. Not a secret."),
+	issuer: HttpsUrl.describe("The exact `iss` this trust accepts — `https://token.actions.githubusercontent.com`, `https://gitlab.com`. A token from any other issuer is refused before its claims are read."),
+	jwksUrl: HttpsUrl.describe("Where the issuer publishes the keys that sign its tokens, read from its discovery document at registration. Public, so configuration and not a secret."),
+	audience: z.string().min(1).max(512).describe("The `aud` a token must name. Defaults to this environment's own Worker origin, which is what stops a staging token being replayed against production."),
+	claims: OidcClaimMatch,
+	authorizedBy: z.email().max(254).describe("Who sanctioned this trust: the signed-in session's email at registration. Never who may use it — a trust's users are whoever its claims admit."),
+	validFrom: JsonDate.describe("When the trust was registered and began to be honored."),
+	revokedAt: JsonDate.nullable().describe("When the trust was revoked, or null. Takes effect on the next call; a token already minted is refused from then on, but stays in its holder's hands until it expires."),
+	firstCallAt: JsonDate.nullable().describe("When a call first verified under this trust, or null while it is awaiting a first call. Nothing can prove a trust at registration — there is no private key here and no workload present — so this is the only proof there is.")
+}).describe("One OIDC trust: a trusted issuer, the audience its tokens must name, and the claims that say which workloads it admits.");
+/**
+* What a caller should expect after a trust is revoked, said at the moment it is revoked rather than
+* discovered afterwards.
+*/
+const TRUST_REVOCATION_LATENCY = "A token cannot be revoked, only the trust. Every call naming this trust is refused from now on, but a token already minted stays in its holder's hands until it expires — the issuer's own lifetime, typically minutes.";
+/** Every trust that may verify a call at `now`: not revoked, and started. */
+function activeTrusts(trusts, now) {
+	return trusts.filter((trust) => trust.revokedAt === null && trust.validFrom.getTime() <= now.getTime());
+}
+/** The trust a call names, if it is live at `now`, or null. The revocation check lives here so no caller forgets it. */
+function findVerifyingTrust(trusts, trustId, now) {
+	return activeTrusts(trusts, now).find((trust) => trust.trustId === trustId) ?? null;
+}
+/** Register a trust beside the others. A duplicate id is refused: the id is what a call addresses. */
+function appendTrust(trusts, trust) {
+	if (trusts.some((existing) => existing.trustId === trust.trustId)) throw new ControlPlaneKeyConflictError({
+		message: "That trust id is already registered on this connection.",
+		action: "Register the trust under a new id.",
+		detail: `duplicate trustId ${trust.trustId}`
+	});
+	return [...trusts, trust];
+}
+/**
+* Revoke one trust at `now`, or answer null when no trust answers to that id. A trust already revoked keeps
+* the instant it was first revoked: the window a call was refused under must not move.
+*/
+function revokeTrust(trusts, trustId, now) {
+	if (!trusts.some((trust) => trust.trustId === trustId)) return null;
+	return trusts.map((trust) => trust.trustId === trustId && trust.revokedAt === null ? {
+		...trust,
+		revokedAt: now
+	} : trust);
+}
+/** A claim's string form, or undefined for a value that is not a string, number or boolean. */
+function claimString(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (typeof value === "boolean") return String(value);
+}
+/**
+* Whether a token's claims satisfy a trust's matcher: every registered claim present and equal.
+*
+* An empty matcher matches nothing. Registration refuses one, and this refuses it again rather than letting
+* a hand-edited row vacuously admit every workload.
+*/
+function claimsMatch(match, claims) {
+	const entries = Object.entries(match);
+	if (entries.length === 0) return false;
+	return entries.every(([name, expected]) => claimString(claims[name]) === expected);
+}
+/**
+* The claims a refused token carried, as a refusal records them: the workload's claims, as strings, capped.
+*
+* This is what makes a custom issuer workable and a profiled one self-correcting — register, let the
+* workload run once, read what it actually sent. Only ever called once the signature, issuer and audience
+* have verified, so the caller demonstrably holds a genuine token for this audience and naming its claims
+* leaks nothing it does not already hold.
+*/
+function observedClaims(claims) {
+	const recorded = {};
+	for (const [name, value] of Object.entries(claims)) {
+		if (Object.keys(recorded).length >= 32) break;
+		if (reserved.has(name) || !CLAIM_NAME.test(name)) continue;
+		const text = claimString(value);
+		if (text === void 0) continue;
+		recorded[name] = text.slice(0, 256);
+	}
+	return recorded;
+}
+//#endregion
+export { MAX_CLAIM_VALUE, MAX_OBSERVED_CLAIMS, MAX_TRUST_CLAIMS, OidcClaimMatch, OidcClaimName, OidcClaimValue, OidcTrust, RESERVED_OIDC_CLAIMS, TRUST_REVOCATION_LATENCY, activeTrusts, appendTrust, claimsMatch, findVerifyingTrust, observedClaims, revokeTrust };

package/dist/controlPlane/data/tables.d.ts

@@ -5,6 +5,7 @@ import type { Kysely } from "kysely";
 import type { z } from "zod";
 import { type DatabaseSchema } from "../../data/db";
 import { ControlPlaneConnection } from "./connection";
+import { LegalHold } from "./hold";
 import { ControlPlaneReplay } from "./replay";
 /**
  * The connections table. `CamelCasePlugin` snake-cases it to `pithy_controlplane_connections` — the
@@ -19,6 +20,8 @@ export declare const CONTROL_PLANE_CONNECTIONS_TABLE = "pithyControlplaneConnect
  * makes the claim a primary-key insert and therefore strongly consistent. See `../replay/guard.ts`.
  */
 export declare const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
+/** Legal holds, kept after release as the record that one stood. */
+export declare const CONTROL_PLANE_HOLDS_TABLE = "pithyControlplaneHolds";
 /**
  * The control-plane tables map. Both are always present: a Worker that composes the seam and has never
  * been connected still needs somewhere for the answer "nobody is connected" to come from, and the
@@ -29,6 +32,7 @@ export declare function controlPlaneTables(): Record<string, z.ZodObject>;
 export type ControlPlaneTables = {
     [CONTROL_PLANE_CONNECTIONS_TABLE]: typeof ControlPlaneConnection;
     [CONTROL_PLANE_REPLAYS_TABLE]: typeof ControlPlaneReplay;
+    [CONTROL_PLANE_HOLDS_TABLE]: typeof LegalHold;
 };
 export type ControlPlaneDatabase = Kysely<DatabaseSchema<ControlPlaneTables>>;
 /** Build the control-plane database from the `DB` binding (CamelCasePlugin installed). */

package/dist/controlPlane/data/tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,iCAAiC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAKhE;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,+BAA+B,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACjE,CAAC,2BAA2B,CAAC,EAAE,OAAO,kBAAkB,CAAC;CAC1D,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAE9E,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,oBAAoB,CAKzE"}
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,iCAAiC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,2BAA2B,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAMhE;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,+BAA+B,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACjE,CAAC,2BAA2B,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACzD,CAAC,yBAAyB,CAAC,EAAE,OAAO,SAAS,CAAC;CAC/C,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAE9E,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,oBAAoB,CAMzE"}

package/dist/controlPlane/data/tables.js

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { ControlPlaneConnection } from "./connection.js";
+import { LegalHold } from "./hold.js";
 import { createDatabase } from "../../data/db.js";
+import { ControlPlaneConnection } from "./connection.js";
 import { ControlPlaneReplay } from "./replay.js";
 //#region src/controlPlane/data/tables.ts
 /**
@@ -17,6 +18,8 @@ const CONTROL_PLANE_CONNECTIONS_TABLE = "pithyControlplaneConnections";
 * makes the claim a primary-key insert and therefore strongly consistent. See `../replay/guard.ts`.
 */
 const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
+/** Legal holds, kept after release as the record that one stood. */
+const CONTROL_PLANE_HOLDS_TABLE = "pithyControlplaneHolds";
 /**
 * The control-plane tables map. Both are always present: a Worker that composes the seam and has never
 * been connected still needs somewhere for the answer "nobody is connected" to come from, and the
@@ -25,15 +28,17 @@ const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
 function controlPlaneTables() {
 	return {
 		[CONTROL_PLANE_CONNECTIONS_TABLE]: ControlPlaneConnection,
-		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay
+		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay,
+		[CONTROL_PLANE_HOLDS_TABLE]: LegalHold
 	};
 }
 /** Build the control-plane database from the `DB` binding (CamelCasePlugin installed). */
 function controlPlaneDatabase(d1) {
 	return createDatabase(d1, {
 		[CONTROL_PLANE_CONNECTIONS_TABLE]: ControlPlaneConnection,
-		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay
+		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay,
+		[CONTROL_PLANE_HOLDS_TABLE]: LegalHold
 	});
 }
 //#endregion
-export { CONTROL_PLANE_CONNECTIONS_TABLE, CONTROL_PLANE_REPLAYS_TABLE, controlPlaneDatabase, controlPlaneTables };
+export { CONTROL_PLANE_CONNECTIONS_TABLE, CONTROL_PLANE_HOLDS_TABLE, CONTROL_PLANE_REPLAYS_TABLE, controlPlaneDatabase, controlPlaneTables };

package/dist/controlPlane/data/trustFirstCall.d.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type ControlPlaneDatabase } from "./tables";
+/**
+ * Record the first call a trust answered (#722), so a listing stops saying *awaiting a first call*.
+ *
+ * **One statement that touches one field, never a read-modify-write of the column.** The verifier read the row
+ * moments ago, and an operator may have revoked the trust since. Writing back the whole `trusts` array as the
+ * verifier saw it would resurrect that trust — a revocation undone by the very call it was meant to stop. So the
+ * write is `json_set` on the matching element's `firstCallAt` alone, and only while that element is still
+ * unrevoked and still uncalled: a revoked trust is left exactly as revoked, and a second first call changes nothing.
+ *
+ * The instant is written as ISO-8601, the shape `JsonDate` stores inside the column.
+ */
+export declare function recordTrustFirstCall(db: ControlPlaneDatabase, connectionId: string, trustId: string, at: Date): Promise<void>;
+//# sourceMappingURL=trustFirstCall.d.ts.map

package/dist/controlPlane/data/trustFirstCall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trustFirstCall.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/trustFirstCall.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmC,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,oBAAoB,EACxB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,IAAI,GACP,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/controlPlane/data/trustFirstCall.js

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CONTROL_PLANE_CONNECTIONS_TABLE } from "./tables.js";
+import { sql } from "kysely";
+//#region src/controlPlane/data/trustFirstCall.ts
+/**
+* Record the first call a trust answered (#722), so a listing stops saying *awaiting a first call*.
+*
+* **One statement that touches one field, never a read-modify-write of the column.** The verifier read the row
+* moments ago, and an operator may have revoked the trust since. Writing back the whole `trusts` array as the
+* verifier saw it would resurrect that trust — a revocation undone by the very call it was meant to stop. So the
+* write is `json_set` on the matching element's `firstCallAt` alone, and only while that element is still
+* unrevoked and still uncalled: a revoked trust is left exactly as revoked, and a second first call changes nothing.
+*
+* The instant is written as ISO-8601, the shape `JsonDate` stores inside the column.
+*/
+async function recordTrustFirstCall(db, connectionId, trustId, at) {
+	const trusts = sql.ref("trusts");
+	const uncalled = (alias) => sql`json_extract(${sql.ref(`${alias}.value`)}, '$.trustId') = ${trustId}
+      and json_extract(${sql.ref(`${alias}.value`)}, '$.revokedAt') is null
+      and json_extract(${sql.ref(`${alias}.value`)}, '$.firstCallAt') is null`;
+	await db.updateTable(CONTROL_PLANE_CONNECTIONS_TABLE).set({ trusts: sql`json_set(${trusts}, '$[' || (select ${sql.ref("t.key")} from json_each(${trusts}) as t where ${uncalled("t")} limit 1) || '].firstCallAt', ${at.toISOString()})` }).where("id", "=", connectionId).where(sql`exists (select 1 from json_each(${trusts}) as u where ${uncalled("u")})`).execute();
+}
+//#endregion
+export { recordTrustFirstCall };

package/dist/controlPlane/discovery/adminRoute.d.ts

@@ -1,6 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { z } from "zod";
+import { ScopeKind } from "../scope/kind";
+import { ControlPlaneScope } from "../scope/scope";
 /**
  * What a capability tells a management client about its own admin surface.
  *
@@ -28,6 +30,24 @@ export declare const AdminRouteMethod: z.ZodEnum<{
     PUT: "PUT";
 }>;
 export type AdminRouteMethod = z.infer<typeof AdminRouteMethod>;
+/**
+ * An admin route's operation id (`docs/AGENT-ACCESS.md` §5): lowercase words joined by `.`, `_` or `-`.
+ *
+ * **Permanent once published.** An agent names a tool in prompts, saved workflows and its own record of what
+ * worked, so a renamed operation breaks callers silently — the same class of rule as a role name. Unique within
+ * its capability; `packages/cli/src/ci/adminOperations.test.ts` holds every kit capability's to a table.
+ */
+export declare const AdminOperation: z.ZodString;
+export type AdminOperation = z.infer<typeof AdminOperation>;
+/**
+ * An admin route's input as JSON Schema: an object whose `path`, `query` and `body` properties are each
+ * the JSON Schema of the validator the route runs on that part of the request.
+ *
+ * A record rather than a modeled schema, because it is JSON Schema — a vocabulary this manifest relays, never
+ * one it defines — and an MCP client publishes it verbatim as a tool's `inputSchema`.
+ */
+export declare const AdminRouteInput: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type AdminRouteInput = z.infer<typeof AdminRouteInput>;
 /** One admin route a capability contributes behind the `control-plane` strategy. */
 export declare const AdminRoute: z.ZodObject<{
     method: z.ZodEnum<{
@@ -40,8 +60,29 @@ export declare const AdminRoute: z.ZodObject<{
     path: z.ZodString;
     scope: z.ZodNullable<z.ZodString>;
     summary: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        charges: "charges";
+        credentials: "credentials";
+        deletes: "deletes";
+        reads: "reads";
+        sends: "sends";
+        writes: "writes";
+    }>>;
+    operation: z.ZodOptional<z.ZodString>;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export type AdminRoute = z.infer<typeof AdminRoute>;
+/**
+ * An admin route as a capability declares it: a scoped route states its kind, and a route with no scope has none.
+ * `Capability.adminRoutes` takes this, so a scoped route without a kind does not compile.
+ */
+export type AdminRouteDeclaration = Omit<AdminRoute, "scope" | "kind"> & ({
+    scope: ControlPlaneScope;
+    kind: ScopeKind;
+} | {
+    scope: null;
+    kind?: undefined;
+});
 /**
  * One composed capability's declaration — everything about it that is the same for every caller.
  *
@@ -64,6 +105,16 @@ export declare const CapabilityDeclaration: z.ZodObject<{
         path: z.ZodString;
         scope: z.ZodNullable<z.ZodString>;
         summary: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            charges: "charges";
+            credentials: "credentials";
+            deletes: "deletes";
+            reads: "reads";
+            sends: "sends";
+            writes: "writes";
+        }>>;
+        operation: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
@@ -89,6 +140,14 @@ export declare const CapabilityDeclaration: z.ZodObject<{
         summary: z.ZodString;
     }, z.core.$strip>>>;
     config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        scope: z.ZodString;
+        activities: z.ZodArray<z.ZodString>;
+        maxParticipants: z.ZodNumber;
+        sessionTicketPath: z.ZodNullable<z.ZodString>;
+        socketPath: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type CapabilityDeclaration = z.infer<typeof CapabilityDeclaration>;
 export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
@@ -106,6 +165,16 @@ export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
         path: z.ZodString;
         scope: z.ZodNullable<z.ZodString>;
         summary: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            charges: "charges";
+            credentials: "credentials";
+            deletes: "deletes";
+            reads: "reads";
+            sends: "sends";
+            writes: "writes";
+        }>>;
+        operation: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
@@ -131,6 +200,14 @@ export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
         summary: z.ZodString;
     }, z.core.$strip>>>;
     config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        scope: z.ZodString;
+        activities: z.ZodArray<z.ZodString>;
+        maxParticipants: z.ZodNumber;
+        sessionTicketPath: z.ZodNullable<z.ZodString>;
+        socketPath: z.ZodString;
+    }, z.core.$strip>>>;
     health: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>>;
     healthUnavailable: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
@@ -148,6 +225,16 @@ export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
         path: z.ZodString;
         scope: z.ZodNullable<z.ZodString>;
         summary: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            charges: "charges";
+            credentials: "credentials";
+            deletes: "deletes";
+            reads: "reads";
+            sends: "sends";
+            writes: "writes";
+        }>>;
+        operation: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
@@ -173,6 +260,14 @@ export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
         summary: z.ZodString;
     }, z.core.$strip>>>;
     config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        scope: z.ZodString;
+        activities: z.ZodArray<z.ZodString>;
+        maxParticipants: z.ZodNumber;
+        sessionTicketPath: z.ZodNullable<z.ZodString>;
+        socketPath: z.ZodString;
+    }, z.core.$strip>>>;
     health: z.ZodDiscriminatedUnion<[z.ZodObject<{
         state: z.ZodLiteral<"undeclared">;
     }, z.core.$strip>, z.ZodObject<{
@@ -193,7 +288,7 @@ export type CapabilityDescriptor = z.infer<typeof CapabilityDescriptor>;
  * now — so a capability that changed its paths or its scopes reports the change directly, and a schema
  * version would be a second source of truth to keep in sync with the first. That reasoning is unchanged.
  *
- * **And `capabilities[].version` travels with the package it belongs to** (#626). A version is only
+ * **And `capabilities[].version` travels with the package it belongs to**. A version is only
  * actionable joined against a release feed, a feed is keyed by package name, and a capability name is
  * not one — `controlplane` ships inside `@pithy-sh/core`. Reporting the version alone left every client
  * guessing the key, and the guess failed silently on the most frequently released package there is.
@@ -207,7 +302,7 @@ export type CapabilityDescriptor = z.infer<typeof CapabilityDescriptor>;
  * we just fixed", and "does this project predate the capability a pane needs". Reporting only one leaves
  * half the questions unanswerable, and they are the halves people actually ask.
  *
- * **And each entry carries a third thing: the configured facts that capability states** (#422). Knowing
+ * **And each entry carries a third thing: the configured facts that capability states**. Knowing
  * where a route is and which scope it needs is not always enough to call it — `POST
  * {base}/entitlements/grant` names a holder, and whether this project's holders are people or
  * organizations is a decision the adopter made in config. A client that cannot read the decision guesses
@@ -247,6 +342,38 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             liveVersions: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    retention: z.ZodOptional<z.ZodObject<{
+        purgeWindows: z.ZodArray<z.ZodObject<{
+            subject: z.ZodEnum<{
+                organization: "organization";
+                user: "user";
+            }>;
+            days: z.ZodNumber;
+            source: z.ZodEnum<{
+                capability: "capability";
+                floor: "floor";
+                policy: "policy";
+            }>;
+        }, z.core.$strip>>;
+        audit: z.ZodObject<{
+            defaultDays: z.ZodNullable<z.ZodNumber>;
+            floorDays: z.ZodNumber;
+            rules: z.ZodArray<z.ZodObject<{
+                prefix: z.ZodString;
+                days: z.ZodNumber;
+                source: z.ZodEnum<{
+                    capability: "capability";
+                    floor: "floor";
+                    policy: "policy";
+                }>;
+            }, z.core.$strip>>;
+            floored: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        classAges: z.ZodArray<z.ZodObject<{
+            class: z.ZodString;
+            days: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     capabilities: z.ZodArray<z.ZodCodec<z.ZodObject<{
         name: z.ZodString;
         version: z.ZodNullable<z.ZodString>;
@@ -262,6 +389,16 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             path: z.ZodString;
             scope: z.ZodNullable<z.ZodString>;
             summary: z.ZodString;
+            kind: z.ZodOptional<z.ZodEnum<{
+                charges: "charges";
+                credentials: "credentials";
+                deletes: "deletes";
+                reads: "reads";
+                sends: "sends";
+                writes: "writes";
+            }>>;
+            operation: z.ZodOptional<z.ZodString>;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
         healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
@@ -287,6 +424,14 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             summary: z.ZodString;
         }, z.core.$strip>>>;
         config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            scope: z.ZodString;
+            activities: z.ZodArray<z.ZodString>;
+            maxParticipants: z.ZodNumber;
+            sessionTicketPath: z.ZodNullable<z.ZodString>;
+            socketPath: z.ZodString;
+        }, z.core.$strip>>>;
         health: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>>;
         healthUnavailable: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
@@ -304,6 +449,16 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             path: z.ZodString;
             scope: z.ZodNullable<z.ZodString>;
             summary: z.ZodString;
+            kind: z.ZodOptional<z.ZodEnum<{
+                charges: "charges";
+                credentials: "credentials";
+                deletes: "deletes";
+                reads: "reads";
+                sends: "sends";
+                writes: "writes";
+            }>>;
+            operation: z.ZodOptional<z.ZodString>;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>>;
         healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
             key: z.ZodString;
@@ -329,6 +484,14 @@ export declare const ControlPlaneManifest: z.ZodObject<{
             summary: z.ZodString;
         }, z.core.$strip>>>;
         config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        presenceRooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            scope: z.ZodString;
+            activities: z.ZodArray<z.ZodString>;
+            maxParticipants: z.ZodNumber;
+            sessionTicketPath: z.ZodNullable<z.ZodString>;
+            socketPath: z.ZodString;
+        }, z.core.$strip>>>;
         health: z.ZodDiscriminatedUnion<[z.ZodObject<{
             state: z.ZodLiteral<"undeclared">;
         }, z.core.$strip>, z.ZodObject<{

package/dist/controlPlane/discovery/adminRoute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adminRoute.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/adminRoute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;;;;;;;;;;;;;GAiBG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB;;;;;;EAE8B,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,oFAAoF;AACpF,eAAO,MAAM,UAAU;;;;;;;;;;;iBAmBpB,CAAC;AACJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqD/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAiD1E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsC9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiCkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}
+{"version":3,"file":"adminRoute.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/adminRoute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAInD;;;;;;;;;;;;;;;;;GAiBG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB;;;;;;EAE8B,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,aAOgE,CAAC;AAC5F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,wCAE+D,CAAC;AAC5F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,oFAAoF;AACpF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;iBA+BpB,CAAC;AACJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,CAAC,GACpE,CAAC;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAEtF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6D/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAiD1E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsC9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}