@pithy-sh/core 0.1.2 → 0.1.3

package/dist/controlPlane/discovery/adminRoute.js

@@ -0,0 +1,136 @@
+import { ControlPlaneScope } from "../scope/scope.js";
+import { CapabilityHealthReport, HealthSummary, HealthSummaryKey, healthReport, healthWire } from "./healthSummary.js";
+import { ManifestConfigKey, ManifestConfigValues } from "./configuration.js";
+import { z } from "zod";
+//#region src/controlPlane/discovery/adminRoute.ts
+/**
+* What a capability tells a management client about its own admin surface.
+*
+* **This exists because knowing a capability is installed is not enough to call it.** A management
+* client that learns only names still has to hold a route table for every capability, guess that
+* payments is mounted at `/payments`, and know out-of-band which scope each operation needs. Every one
+* of those is a thing that can be wrong, and `basePath` is configurable — an adopter who mounts
+* payments at `/billing` would silently 404 a client that hardcoded the default.
+*
+* So the capability declares the routes it actually registered, with the paths it actually used, and
+* `GET /control-plane/manifest` reports them. That is what makes discovery-over-configuration real
+* rather than aspirational: a client composes its navigation *and* its calls from what the Worker says
+* about itself, and an adopter who moves a mount point or upgrades a capability changes what the client
+* does without either side coordinating.
+*
+* **The declaration is checked against the router**, not trusted — see `missingAdminRoutes`. A manifest
+* that drifts from the routes is worse than no manifest, because a client would believe it.
+*/
+/** The HTTP methods an admin route may use. */
+const AdminRouteMethod = z.enum([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]).describe("The HTTP method this admin route answers on.");
+/** One admin route a capability contributes behind the `control-plane` strategy. */
+const AdminRoute = z.object({
+	method: AdminRouteMethod.describe("The method to call this route with."),
+	path: z.string().min(1).describe("The **fully mounted** path, with the capability's configured `basePath` already applied — `/billing/entitlements/grant`, not `/entitlements/grant`. Built by the capability at assembly, so an adopter who moved the mount point is reflected here rather than silently breaking a client that assumed the default."),
+	scope: ControlPlaneScope.nullable().describe("The scope this route requires, or null when it needs only a verified caller (the seam's `ping`). A client compares it against the connection's granted scopes to know which operations it may actually offer, instead of discovering a 403 by trying."),
+	summary: z.string().min(1).describe("One line describing what the route does, for a management client to render beside it.")
+}).describe("One admin route, described well enough for a management client to call it without holding any capability-specific knowledge.");
+/**
+* One composed capability's declaration — everything about it that is the same for every caller.
+*
+* Split from {@link CapabilityDescriptor} because the health *values* are the one part of a manifest
+* entry that depends on who is asking, and the seam holds this half from assembly (`compose`) while the
+* other half is resolved per request.
+*/
+const CapabilityDeclaration = z.object({
+	name: z.string().min(1).describe("The capability's name — the same token used as its migration namespace and error domain."),
+	version: z.string().nullable().describe("The npm version of the package supplying this capability, or null where there is none — the adopter's own `app` capability has a name and no package. Reported per capability and never aggregated: the package name is the join key against a release feed, and a project composes some capabilities and not others, so only the intersection of what it composes and what changed is worth reporting."),
+	adminRoutes: z.array(AdminRoute).describe("Every admin route this capability contributes, or empty when it contributes none. Most capabilities are empty: having no management surface is the normal case, and saying so explicitly is what lets a client render a capability it cannot act on."),
+	healthKeys: z.array(HealthSummaryKey).default([]).describe("The closed vocabulary of scalars this capability may report about its own state, or empty when it reports none — including when the Worker predates this field and says nothing at all. Declared alongside the routes so a client can render a key it has never heard of from what the Worker says about it — and so a *withheld* number is visible as a key with no value, rather than as silence."),
+	configKeys: z.array(ManifestConfigKey).default([]).describe("The configured facts this capability states, or empty when it states none — including when the Worker predates this field. Declared alongside the routes, because a fact is what a client needs to *call* one: `POST /billing/entitlements/grant` names a holder and never assumes it, so a client that cannot learn what this project bills can only guess — and a guess writes a row nothing reads."),
+	config: ManifestConfigValues.default({}).describe("What each declared fact resolved to for this deployment. The same answer for every caller, read off the capability's parsed config at assembly: there is no producer here, so no failure state, no per-request cost, and no staleness beyond the manifest itself.")
+}).describe("One capability this Worker composes, the version it is at, the admin surface it exposes, the summary it may report, and the configured facts a client must respect to call any of it.");
+/**
+* One composed capability's manifest entry **as it goes over the wire**.
+*
+* Two flat fields, and neither is what a consumer reads: {@link CapabilityDescriptor} decodes them into
+* one value that says which of the four states it is in. They are flat here because the wire has an
+* older half to keep working. A Worker deployed before #350 sends no `healthUnavailable` and a Worker
+* deployed before #317 sends neither field, and both must still parse; and a client pinned to a build
+* older than the Worker it is reading strips the field it has never heard of and lands on `health:
+* null`, which renders as silence rather than as a zero. Putting the fourth state *inside* `health`
+* would have cost that client the whole manifest for one capability's bad afternoon, which is the
+* failure #352 is about.
+*/
+const CapabilityDescriptorWire = CapabilityDeclaration.extend({
+	health: HealthSummary.nullable().default(null).describe("Every declared value this caller may see, or null when there is none to give — either nothing is declared, or this connection lacks the scope the value is behind, or producing it failed, or the Worker predates this field. **Null is never zero.**"),
+	healthUnavailable: z.boolean().default(false).describe("Whether producing this capability's summary failed on this read — the fourth state (#350), and the reason `health` being null is not enough on its own. Carries no message, no code and no error: what the producer threw may name a row or a key, so nothing derived from it travels. False when the Worker predates this field.")
+});
+/**
+* One composed capability, as `GET /control-plane/manifest` reports it to **this** caller.
+*
+* `health` is the only per-caller part of a manifest entry, and it is a four-state value rather than a
+* nullable record: a capability that declares nothing, one that declares a number this connection was
+* not granted, one that reports a number — zero included — and one whose producer failed. A management
+* client that collapsed any two of those tells an adopter something untrue. The first two collapsed
+* says everything is fine when it has simply not been allowed to look; the last two collapsed says
+* nothing is pending when the store is down.
+*
+* The state travels **on** the value, so the scalars are unreachable without narrowing and a consumer
+* that forgets the sick case gets a type error rather than a zero.
+*/
+const CapabilityDescriptorRead = CapabilityDeclaration.extend({ health: CapabilityHealthReport.describe("What this caller is told about the capability's own state: nothing declared, a number withheld, the numbers themselves, or a producer that failed. Four states on one value, so none of them is reachable by forgetting to check another.") });
+const CapabilityDescriptor = z.codec(CapabilityDescriptorWire, CapabilityDescriptorRead, {
+	decode: ({ health, healthUnavailable, ...declaration }) => ({
+		...declaration,
+		health: healthReport({
+			healthKeys: declaration.healthKeys,
+			health,
+			healthUnavailable
+		})
+	}),
+	encode: ({ health, healthKeys, configKeys, config, ...declaration }) => ({
+		...declaration,
+		healthKeys: (healthKeys ?? []).map((key) => ({
+			...key,
+			nominal: key.nominal ?? null
+		})),
+		configKeys: configKeys ?? [],
+		config: config ?? {},
+		...healthWire(health)
+	})
+}).describe("One capability this Worker composes, as reported to one caller: its version, its admin surface, and the summary that caller is entitled to — or the named reason there is none.");
+/**
+* The manifest a management client reads to build itself.
+*
+* **There is deliberately no manifest schema version, and that is a different thing from the two build
+* identities below.** A client dispatches on the routes described here — what this Worker declares right
+* 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.
+*
+* What the manifest does carry is **identity**, not schema, and it carries two of them because they
+* answer questions neither can answer alone. `version` is Cloudflare's opaque per-deploy id: it says
+* *exactly which build* is running, which is what forensics needs, what reproduces a report, and what
+* pins the code an audited action ran against. It carries no version semantics, so it says nothing about
+* features. `capabilities[].version` is the npm version of each composed package: it says *which
+* features*, which is what answers "should this customer upgrade", "which customers are exposed to what
+* 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
+* 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
+* it, and a guess writes a row nothing reads. See `discovery/configuration.ts` for why a fact is not a
+* health number, despite the two fields sitting side by side.
+*/
+const ControlPlaneManifest = z.object({
+	environment: z.string().describe("The environment this connection is bound to, echoed so a client can label what it is looking at."),
+	connectionId: z.string().describe("The connection this call authenticated as."),
+	version: z.string().nullable().describe("The Cloudflare version id of the build answering this call, from the `CF_VERSION_METADATA` binding, or null where the binding is absent. Opaque and per-deploy: it identifies which build is running, never which features it has. Null is honest — a Worker scaffolded before the binding was declared genuinely cannot say."),
+	capabilities: z.array(CapabilityDescriptor).describe("Every capability composed into this Worker, in composition order with the adopter's own app last. A capability absent here has no data to show, which is a fact the client discovers rather than a setting anybody maintains."),
+	grantedScopes: z.array(ControlPlaneScope).describe("Every scope this connection holds. Together with each route's own `scope`, this is what tells a client which operations to offer and which to hide.")
+}).describe("What this Worker is, what it composes, and how to call the admin surface it exposes.");
+//#endregion
+export { AdminRoute, AdminRouteMethod, CapabilityDeclaration, CapabilityDescriptor, ControlPlaneManifest };

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

@@ -0,0 +1,108 @@
+import { z } from "zod";
+/**
+ * One configured fact's value. A string, a number, or a boolean — never anything else.
+ *
+ * The rule is in the type rather than in a comment: a config object, a product list, or a credentials
+ * bag does not compile, so the seam cannot become the route by which an adopter's catalog reaches a
+ * discovery read.
+ */
+export declare const ManifestConfigValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+export type ManifestConfigValue = z.output<typeof ManifestConfigValue>;
+/** Anything that is not a scalar. Named as a type so the tripwire below is a list to delete from. */
+type NonScalar = object | ((...args: never[]) => unknown);
+/**
+ * `true` while `T` is scalars only, `never` the moment it admits anything else — so the assignment
+ * below stops compiling if {@link ManifestConfigValue} is ever widened.
+ *
+ * Declared here rather than imported from `health.ts`: that module reaches `capability.ts` and, through
+ * it, hono and kysely, and this one is zod-only so a browser client can read the manifest without them
+ * (#430). The tuple wrapper is not decoration — a bare `Extract<...> extends never` distributes over a
+ * union and would answer `true` for every member, which is the one way this check could quietly pass.
+ */
+type ScalarOnly<T> = [Extract<T, NonScalar>] extends [never] ? true : never;
+/** The compile-time half of "scalars only". Widen the value type and this line names the file. */
+export declare const MANIFEST_CONFIG_VALUE_IS_SCALAR_ONLY: ScalarOnly<ManifestConfigValue>;
+/**
+ * One configured fact a capability may state, declared alongside its routes.
+ *
+ * `choices` is nullable rather than optional, and a null means "no closed list" rather than "not
+ * decided yet": a client renders a fact it has never heard of from the summary, and offers a picker
+ * only where the values are enumerable. A base path has no list; what a project bills has exactly two.
+ */
+export declare const ManifestConfigKey: z.ZodObject<{
+    key: z.ZodString;
+    choices: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    summary: z.ZodString;
+}, z.core.$strip>;
+export type ManifestConfigKey = z.output<typeof ManifestConfigKey>;
+/**
+ * A capability's configured facts as the manifest carries them: declared key → scalar.
+ *
+ * A record rather than a closed object, because the vocabulary is federated the way scopes and audit
+ * actions are — the capability name already namespaces it. **Parsing tolerates a key it has never heard
+ * of on purpose**: a client reading a newer Worker must drop the unknown one rather than fail the whole
+ * manifest, which is what {@link namedConfigValues} does with it.
+ */
+export declare const ManifestConfigValues: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+export type ManifestConfigValues = z.output<typeof ManifestConfigValues>;
+/**
+ * The brand only {@link defineManifestConfig} can produce.
+ *
+ * Module-local and never exported, so nothing outside this file can write it: the factory becomes the
+ * **only** way to build the seam, and a fact therefore cannot reach a manifest without having been
+ * checked against a declaration. An inline object literal on `Capability.manifestConfig` is a compile
+ * error, which is what stops the next capability from stating a fact nothing validated.
+ */
+declare const manifestConfigSeam: unique symbol;
+/** What a capability declares and what it resolved to. Built only by {@link defineManifestConfig}. */
+export interface CapabilityManifestConfig {
+    /** The brand. Present only on a declaration that went through the factory, and never serialized. */
+    readonly [manifestConfigSeam]: true;
+    /** The closed vocabulary: every fact this capability states, parsed. */
+    readonly keys: readonly ManifestConfigKey[];
+    /** What each declared fact resolved to for this composition. One answer, for every caller. */
+    readonly values: ManifestConfigValues;
+}
+/** The authoring shape — facts as written, before parsing. */
+export interface CapabilityManifestConfigInput {
+    /** Every fact this capability states. At least one; an empty vocabulary states nothing. */
+    keys: readonly z.input<typeof ManifestConfigKey>[];
+    /** The resolved value of each declared fact. Built from the capability's parsed config, never its defaults. */
+    values: ManifestConfigValues;
+}
+/**
+ * Declare a capability's configured facts. The one constructor, so every declaration in the tree is
+ * checked — the key against the name pattern, the values against the keys, and each value against its
+ * own closed list.
+ *
+ * **Nothing downstream re-checks this.** `missingAdminRoutes` keeps a route declaration honest against
+ * the router that mounted it, and there is no equivalent here: the declaration and the value come from
+ * the same object, so the only defense against a fact that disagrees with the capability is building it
+ * from the *resolved* config at the one call site, exactly as `adminRoutes` is built from the resolved
+ * `basePath`.
+ *
+ * Every refusal is an {@link InternalError} rather than a bare `ZodError`, key named, because every one
+ * of them is an author's mistake read off a deploy that would not start — and an author reading it
+ * wants the problem line and the action line the rest of this kit gives them.
+ */
+export declare function defineManifestConfig(input: CapabilityManifestConfigInput): CapabilityManifestConfig;
+/** One fact with the declaration that says how to read it. */
+export interface NamedConfigValue {
+    /** The declaration — its closed list, if it has one, and what it decides. */
+    key: ManifestConfigKey;
+    /** The value this composition resolved it to. */
+    value: ManifestConfigValue;
+}
+/**
+ * Pair a capability's configured facts with their declarations, dropping any value nothing declares.
+ *
+ * This is how "an unknown fact reads as nothing rather than as an error" is real rather than
+ * aspirational: a client reads what this returns, so a key from a Worker newer than its build simply is
+ * not in the list — and a fact it cannot name is a fact it would otherwise have to guess the meaning of.
+ */
+export declare function namedConfigValues(descriptor: {
+    configKeys: readonly ManifestConfigKey[];
+    config: ManifestConfigValues;
+}): NamedConfigValue[];
+export {};
+//# sourceMappingURL=configuration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/configuration.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuDxB;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,+DAI7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,qGAAqG;AACrG,KAAK,SAAS,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,CAAC;AAE1D;;;;;;;;GAQG;AACH,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAE5E,kGAAkG;AAClG,eAAO,MAAM,oCAAoC,EAAE,UAAU,CAAC,mBAAmB,CAAQ,CAAC;AAE1F;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;;;iBAoB3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,yFAI9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE;;;;;;;GAOG;AACH,QAAA,MAAM,kBAAkB,EAAE,OAAO,MAAoD,CAAC;AAEtF,sGAAsG;AACtG,MAAM,WAAW,wBAAwB;IACvC,oGAAoG;IACpG,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC5C,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC;AAED,8DAA8D;AAC9D,MAAM,WAAW,6BAA6B;IAC5C,2FAA2F;IAC3F,IAAI,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,EAAE,CAAC;IACnD,+GAA+G;IAC/G,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,6BAA6B,GAAG,wBAAwB,CAuEnG;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,GAAG,EAAE,iBAAiB,CAAC;IACvB,iDAAiD;IACjD,KAAK,EAAE,mBAAmB,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE;IAC5C,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACzC,MAAM,EAAE,oBAAoB,CAAC;CAC9B,GAAG,gBAAgB,EAAE,CAWrB"}

package/dist/controlPlane/discovery/configuration.js

@@ -0,0 +1,187 @@
+import { InternalError } from "../../error/pithyError.js";
+import { z } from "zod";
+//#region src/controlPlane/discovery/configuration.ts
+/**
+* The configured facts a capability states into its own manifest entry (#422).
+*
+* **A management client cannot call an operation it has to guess an argument for.**
+* `POST {base}/entitlements/grant` names the holder and never assumes it, which is right — but
+* `PaymentsConfig.billingSubject` decides whether this project's holders are people or organizations,
+* it is required with no default, and nothing on the wire said so. A client guessing `user` against an
+* organization-billed project writes a row nothing reads: the call succeeds, the audit line is real,
+* the screen says `Done.`, and the person still cannot use what somebody just gave them. That is worse
+* than a refusal, because it looks like it worked.
+*
+* So a capability declares the configured facts a client must respect, and the manifest carries them
+* beside the routes they govern. `billingSubject` is the first and will not be the last, which is why
+* this is a vocabulary rather than one field bolted onto the manifest.
+*
+* ## This is not health, and the difference is the whole design
+*
+* The shapes rhyme — `configKeys`/`config` beside `healthKeys`/`health` — and a reader who folds them
+* together gets both wrong. They differ on every axis that matters:
+*
+* - A health value is **per caller**; a configured fact is the same for everybody.
+* - A health value is **produced**, so it may fail, and `unavailable` is one of its four states. A fact
+*   is read off resolved config at assembly, so there is no producer, no query, and no failure state to
+*   collapse into a zero.
+* - A health value is **as old as the manifest a client cached** and must never be shown as live. A
+*   fact changes only when the adopter redeploys, which is when the manifest changes anyway.
+* - A health value is a number to **render**. A fact is a decision to **respect** — it goes into the
+*   next request a client makes, not onto a rail.
+*
+* ## No per-key scope, deliberately
+*
+* A health key's `scope` is required, on the stated ground that a count is still a fact
+* about somebody's security posture. A configured fact is not that. `billingSubject` names no account,
+* no transaction and no amount, and reads identically against an empty database — it is a fact about
+* the adopter's own configuration, and the whole manifest already sits behind `manifest:read`, the same
+* gate that discloses every route, every scope and every composed version.
+*
+* Withholding stays addable with no wire change if a later fact wants it — a from-address, a region. A
+* value absent from `config` while its key is present in `configKeys` already means "declared and not
+* shown", which is the same pairing that tells `undeclared` from `withheld` for health, and
+* {@link namedConfigValues} already survives it.
+*
+* ## What keeps it from becoming a config dump
+*
+* A capability's resolved config holds provider secrets, price ids and an adopter's whole catalog. The
+* factory is the only door, and it is narrow on purpose: scalars only, a closed declared vocabulary,
+* and a value refused unless something declared it. Nobody can write `manifestConfig: resolved`.
+*/
+/** A fact's name: one camelCase token, so it reads as a field and never as a path or an id. */
+const MANIFEST_CONFIG_KEY_PATTERN = /^[a-z][A-Za-z0-9]*$/;
+/**
+* One configured fact's value. A string, a number, or a boolean — never anything else.
+*
+* The rule is in the type rather than in a comment: a config object, a product list, or a credentials
+* bag does not compile, so the seam cannot become the route by which an adopter's catalog reaches a
+* discovery read.
+*/
+const ManifestConfigValue = z.union([
+	z.string(),
+	z.number(),
+	z.boolean()
+]).describe("One scalar: a word, a number, or a flag. Nothing else is representable — no nested objects, no lists, no credentials.");
+/** The compile-time half of "scalars only". Widen the value type and this line names the file. */
+const MANIFEST_CONFIG_VALUE_IS_SCALAR_ONLY = true;
+/**
+* One configured fact a capability may state, declared alongside its routes.
+*
+* `choices` is nullable rather than optional, and a null means "no closed list" rather than "not
+* decided yet": a client renders a fact it has never heard of from the summary, and offers a picker
+* only where the values are enumerable. A base path has no list; what a project bills has exactly two.
+*/
+const ManifestConfigKey = z.object({
+	key: z.string().regex(MANIFEST_CONFIG_KEY_PATTERN, "A config key is one camelCase token — `billingSubject`.").describe("The key this fact appears under in the capability's config. One camelCase token."),
+	choices: z.array(z.string().min(1)).min(1, "A closed list needs a value in it. Write null where the values are not enumerable.").nullable().describe("Every value this fact may take, so a client can offer the same choice the adopter made, or null where the values are not enumerable. At least one where it is a list: an empty one is not `null` spelled differently, it is a list nothing satisfies, so the capability could never boot and the refusal would name no permitted value at all. Read off the capability's own enum rather than retyped, so a new member cannot land without the manifest learning it."),
+	summary: z.string().min(1).describe("One line saying what the fact governs, for a client to render beside it without knowing the key.")
+}).describe("One configured fact a capability states: what it is called, what it may be, and what it decides — enough for a client to respect a decision it did not make.");
+/**
+* A capability's configured facts as the manifest carries them: declared key → scalar.
+*
+* A record rather than a closed object, because the vocabulary is federated the way scopes and audit
+* actions are — the capability name already namespaces it. **Parsing tolerates a key it has never heard
+* of on purpose**: a client reading a newer Worker must drop the unknown one rather than fail the whole
+* manifest, which is what {@link namedConfigValues} does with it.
+*/
+const ManifestConfigValues = z.record(z.string(), ManifestConfigValue).describe("One capability's configured facts: each declared key to its scalar. Unknown keys parse rather than throw, so a client of an older build reads what it knows and nothing for the rest.");
+/**
+* The brand only {@link defineManifestConfig} can produce.
+*
+* Module-local and never exported, so nothing outside this file can write it: the factory becomes the
+* **only** way to build the seam, and a fact therefore cannot reach a manifest without having been
+* checked against a declaration. An inline object literal on `Capability.manifestConfig` is a compile
+* error, which is what stops the next capability from stating a fact nothing validated.
+*/
+const manifestConfigSeam = Symbol("pithy.controlPlane.manifestConfig");
+/**
+* Declare a capability's configured facts. The one constructor, so every declaration in the tree is
+* checked — the key against the name pattern, the values against the keys, and each value against its
+* own closed list.
+*
+* **Nothing downstream re-checks this.** `missingAdminRoutes` keeps a route declaration honest against
+* the router that mounted it, and there is no equivalent here: the declaration and the value come from
+* the same object, so the only defense against a fact that disagrees with the capability is building it
+* from the *resolved* config at the one call site, exactly as `adminRoutes` is built from the resolved
+* `basePath`.
+*
+* Every refusal is an {@link InternalError} rather than a bare `ZodError`, key named, because every one
+* of them is an author's mistake read off a deploy that would not start — and an author reading it
+* wants the problem line and the action line the rest of this kit gives them.
+*/
+function defineManifestConfig(input) {
+	if (input.keys.length === 0) throw new InternalError({
+		message: "A capability declared configured facts with no keys.",
+		action: "Declare at least one key, or omit the manifest config entirely.",
+		detail: "defineManifestConfig received an empty key list; an empty vocabulary states no fact."
+	});
+	const keys = [];
+	const declared = /* @__PURE__ */ new Map();
+	for (const written of input.keys) {
+		const parsed = ManifestConfigKey.safeParse(written);
+		if (!parsed.success) throw new InternalError({
+			message: "A capability declared a configured fact its own schema refuses.",
+			action: "Name the fact with one camelCase token, list its values or null, and say what it decides.",
+			detail: `manifest config key ${JSON.stringify(written)} is invalid: ${parsed.error.message}`
+		});
+		if (declared.has(parsed.data.key)) throw new InternalError({
+			message: "A capability declared the same configured fact twice.",
+			action: "Give each fact one declaration — the second silently decides what the first meant.",
+			detail: `manifest config key ${parsed.data.key} is declared more than once`
+		});
+		declared.set(parsed.data.key, parsed.data);
+		keys.push(parsed.data);
+	}
+	const parsed = ManifestConfigValues.safeParse(input.values);
+	if (!parsed.success) throw new InternalError({
+		message: "A capability stated a configured fact that is not a scalar.",
+		action: "State a word, a number or a flag. A capability's own config never crosses whole.",
+		detail: `manifest config values are invalid: ${parsed.error.message}`
+	});
+	const values = parsed.data;
+	for (const key of Object.keys(values)) if (!declared.has(key)) throw new InternalError({
+		message: "A capability stated a configured fact it never declared.",
+		action: "Declare the fact alongside the capability's routes, or stop stating it.",
+		detail: `manifest config value ${key} has no declaration, so a client could only guess at what it means`
+	});
+	for (const key of keys) {
+		const value = Object.hasOwn(values, key.key) ? values[key.key] : void 0;
+		if (value === void 0) throw new InternalError({
+			message: "A capability declared a configured fact and stated no value for it.",
+			action: "State every declared fact, or remove the declaration.",
+			detail: `manifest config key ${key.key} is declared and has no value`
+		});
+		if (key.choices !== null && !(typeof value === "string" && key.choices.includes(value))) throw new InternalError({
+			message: "A capability stated a configured fact its own declaration does not permit.",
+			action: "State one of the declared choices, or widen the declaration to the enum it came from.",
+			detail: `manifest config key ${key.key} was given ${JSON.stringify(value)}, which is not one of ${key.choices.join(", ")}`
+		});
+	}
+	return {
+		[manifestConfigSeam]: true,
+		keys,
+		values
+	};
+}
+/**
+* Pair a capability's configured facts with their declarations, dropping any value nothing declares.
+*
+* This is how "an unknown fact reads as nothing rather than as an error" is real rather than
+* aspirational: a client reads what this returns, so a key from a Worker newer than its build simply is
+* not in the list — and a fact it cannot name is a fact it would otherwise have to guess the meaning of.
+*/
+function namedConfigValues(descriptor) {
+	const named = [];
+	for (const key of descriptor.configKeys) {
+		if (!Object.hasOwn(descriptor.config, key.key)) continue;
+		const value = descriptor.config[key.key];
+		if (value !== void 0) named.push({
+			key,
+			value
+		});
+	}
+	return named;
+}
+//#endregion
+export { MANIFEST_CONFIG_VALUE_IS_SCALAR_ONLY, ManifestConfigKey, ManifestConfigValue, ManifestConfigValues, defineManifestConfig, namedConfigValues };

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

@@ -0,0 +1,64 @@
+import type { Hono } from "hono";
+import type { Capability } from "../../capability/capability";
+import type { AdminRoute } from "./adminRoute";
+/**
+ * The gate that keeps `GET /control-plane/manifest` honest.
+ *
+ * A capability declares its admin routes by hand, and a hand-maintained list beside generated
+ * behavior is a list that rots: someone renames a path, changes a `basePath` default, moves an
+ * operation behind a different scope, and the declaration keeps confidently describing the old shape.
+ *
+ * **That failure is worse than having no manifest at all.** With no manifest a client knows it is
+ * guessing. With a stale one it believes a route exists, calls it, and gets a 404 it has no way to
+ * interpret — and the adopter sees a management client that is broken for reasons entirely inside
+ * somebody else's package.
+ *
+ * So the declaration is checked against the router that actually mounted, the same way
+ * `uncoveredParamRoutes` checks that every `:segment` carries a validator. Each capability asserts this
+ * in its own `routeContract.test.ts`, so a drifting declaration fails that package's CI rather than
+ * some integration run much later.
+ */
+/** One declared route that no composed route answers, and which capability claimed it. */
+export interface AdminRouteDrift {
+    /** The capability whose declaration is wrong. */
+    capability: string;
+    /** The route it claims to expose. */
+    route: AdminRoute;
+}
+/** One mounted control-plane route that no capability declares. */
+export interface UndeclaredAdminRoute {
+    /** The method it answers on. */
+    method: string;
+    /** The path it is mounted at. */
+    path: string;
+}
+/**
+ * Every admin route a capability declares that the composed app does not actually serve.
+ *
+ * Empty is the passing state. A non-empty result names the capability and the route, because the fix
+ * is always in one of two places — the declaration or the registration — and knowing which capability
+ * owns both is most of the diagnosis.
+ *
+ * The comparison is on method and path only. Whether the route carries the right *scope* is not
+ * knowable from the router (a middleware is an opaque function to Hono), so that half stays the
+ * capability's responsibility and is covered by its own route tests.
+ */
+export declare function missingAdminRoutes(app: Hono<never>, capabilities: readonly Capability[]): AdminRouteDrift[];
+/**
+ * Every control-plane route the app actually serves that no capability declares — the other direction.
+ *
+ * {@link missingAdminRoutes} walks declared → mounted and catches a declaration that lies. This walks
+ * mounted → declared and catches the opposite: a route that is guarded, reachable, and invisible.
+ *
+ * **That gap stopped being cosmetic when CORS started deriving from this table** (#468). An undeclared
+ * admin route was previously discoverable-by-trying — the manifest omitted it, a client that knew the
+ * path could still call it. Now it also gets no `app.use`, so its preflight 404s and no browser can
+ * reach it at all, while every test in the capability that owns it keeps passing. The failure is
+ * invisible from the capability's own suite and shows up as a pane that will not load.
+ *
+ * A route is control-plane if its handler chain carries a {@link isControlPlaneGuard} gate, which is
+ * the only thing that distinguishes one — a middleware is otherwise an opaque function to Hono, and
+ * inferring it from the path would be guessing about the one table this is meant to check.
+ */
+export declare function undeclaredAdminRoutes(app: Hono<never>, capabilities: readonly Capability[]): UndeclaredAdminRoute[];
+//# sourceMappingURL=drift.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"drift.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/drift.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AAEH,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,eAAe,EAAE,CAS3G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,oBAAoB,EAAE,CAcnH"}

package/dist/controlPlane/discovery/drift.js

@@ -0,0 +1,58 @@
+import { isControlPlaneGuard } from "../http/guard.js";
+//#region src/controlPlane/discovery/drift.ts
+/** `app.routes` entries, reduced to the pairs worth comparing. */
+function mounted(app) {
+	return new Set(app.routes.map((route) => `${route.method.toUpperCase()} ${route.path}`));
+}
+/**
+* Every admin route a capability declares that the composed app does not actually serve.
+*
+* Empty is the passing state. A non-empty result names the capability and the route, because the fix
+* is always in one of two places — the declaration or the registration — and knowing which capability
+* owns both is most of the diagnosis.
+*
+* The comparison is on method and path only. Whether the route carries the right *scope* is not
+* knowable from the router (a middleware is an opaque function to Hono), so that half stays the
+* capability's responsibility and is covered by its own route tests.
+*/
+function missingAdminRoutes(app, capabilities) {
+	const served = mounted(app);
+	const drift = [];
+	for (const capability of capabilities) for (const route of capability.adminRoutes ?? []) if (!served.has(`${route.method} ${route.path}`)) drift.push({
+		capability: capability.name,
+		route
+	});
+	return drift;
+}
+/**
+* Every control-plane route the app actually serves that no capability declares — the other direction.
+*
+* {@link missingAdminRoutes} walks declared → mounted and catches a declaration that lies. This walks
+* mounted → declared and catches the opposite: a route that is guarded, reachable, and invisible.
+*
+* **That gap stopped being cosmetic when CORS started deriving from this table** (#468). An undeclared
+* admin route was previously discoverable-by-trying — the manifest omitted it, a client that knew the
+* path could still call it. Now it also gets no `app.use`, so its preflight 404s and no browser can
+* reach it at all, while every test in the capability that owns it keeps passing. The failure is
+* invisible from the capability's own suite and shows up as a pane that will not load.
+*
+* A route is control-plane if its handler chain carries a {@link isControlPlaneGuard} gate, which is
+* the only thing that distinguishes one — a middleware is otherwise an opaque function to Hono, and
+* inferring it from the path would be guessing about the one table this is meant to check.
+*/
+function undeclaredAdminRoutes(app, capabilities) {
+	const declared = /* @__PURE__ */ new Set();
+	for (const capability of capabilities) for (const route of capability.adminRoutes ?? []) declared.add(`${route.method} ${route.path}`);
+	const guarded = /* @__PURE__ */ new Map();
+	for (const route of app.routes) {
+		if (!isControlPlaneGuard(route.handler)) continue;
+		const method = route.method.toUpperCase();
+		guarded.set(`${method} ${route.path}`, {
+			method,
+			path: route.path
+		});
+	}
+	return [...guarded.entries()].filter(([key]) => !declared.has(key)).map(([, route]) => route);
+}
+//#endregion
+export { missingAdminRoutes, undeclaredAdminRoutes };