@pithy-sh/core 0.1.0

package/src/controlPlane/discovery/configuration.ts

@@ -0,0 +1,280 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { InternalError } from "../../error/pithyError";
+
+/**
+ * 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.
+ */
+export 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.",
+  );
+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 const MANIFEST_CONFIG_VALUE_IS_SCALAR_ONLY: ScalarOnly<ManifestConfigValue> = 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.
+ */
+export 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.",
+  );
+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 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.",
+  );
+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.
+ */
+const manifestConfigSeam: unique symbol = Symbol("pithy.controlPlane.manifestConfig");
+
+/** 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 function defineManifestConfig(input: CapabilityManifestConfigInput): CapabilityManifestConfig {
+  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: ManifestConfigKey[] = [];
+  const declared = new Map<string, ManifestConfigKey>();
+  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) {
+    // `Object.hasOwn` rather than an `undefined` check. `ManifestConfigValues` parses to a plain object, so
+    // `values.toString` is a function off `Object.prototype` — and the key pattern admits `toString`,
+    // `valueOf` and `constructor`. A declaration named after one of them would read a method as its
+    // value and walk straight through the guard below, which is the one state the guard exists for.
+    const value = Object.hasOwn(values, key.key) ? values[key.key] : undefined;
+    if (value === undefined) {
+      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.",
+        // The value itself: the declaration already said it may be published, and knowing *which* value
+        // was refused is most of the diagnosis.
+        detail: `manifest config key ${key.key} was given ${JSON.stringify(value)}, which is not one of ${key.choices.join(", ")}`,
+      });
+    }
+  }
+  return { [manifestConfigSeam]: true, keys, values };
+}
+
+/** 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 function namedConfigValues(descriptor: {
+  configKeys: readonly ManifestConfigKey[];
+  config: ManifestConfigValues;
+}): NamedConfigValue[] {
+  const named: NamedConfigValue[] = [];
+  for (const key of descriptor.configKeys) {
+    // Own keys only, for the reason {@link defineManifestConfig} states: a declared `toString` with no
+    // value beside it would otherwise pair with `Object.prototype.toString`, and this function's whole
+    // promise is that a `value` is a scalar a client can render.
+    if (!Object.hasOwn(descriptor.config, key.key)) continue;
+    const value = descriptor.config[key.key];
+    if (value !== undefined) named.push({ key, value });
+  }
+  return named;
+}

package/src/controlPlane/discovery/drift.ts

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Hono } from "hono";
+import type { Capability } from "../../capability/capability";
+import { isControlPlaneGuard } from "../http/guard";
+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;
+}
+
+/** `app.routes` entries, reduced to the pairs worth comparing. */
+function mounted(app: Hono<never>): Set<string> {
+  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.
+ */
+export function missingAdminRoutes(app: Hono<never>, capabilities: readonly Capability[]): AdminRouteDrift[] {
+  const served = mounted(app);
+  const drift: AdminRouteDrift[] = [];
+  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.
+ */
+export function undeclaredAdminRoutes(app: Hono<never>, capabilities: readonly Capability[]): UndeclaredAdminRoute[] {
+  const declared = new Set<string>();
+  for (const capability of capabilities) {
+    for (const route of capability.adminRoutes ?? []) declared.add(`${route.method} ${route.path}`);
+  }
+
+  const guarded = new Map<string, UndeclaredAdminRoute>();
+  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);
+}

package/src/controlPlane/discovery/health.ts

@@ -0,0 +1,213 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { z } from "zod";
+import type { Capability, PithyHonoEnv } from "../../capability/capability";
+import { InternalError } from "../../error/pithyError";
+import {
+  type CapabilityHealthReport,
+  type HealthSummary,
+  HealthSummaryKey,
+  type HealthSummaryValue,
+} from "./healthSummary";
+
+/**
+ * The seam a capability implements to contribute a health summary to its own manifest entry (#317).
+ *
+ * The vocabulary itself — what a key may be called, what it may hold, what it costs, and the four
+ * states it travels in — is `./healthSummary`, and that argument is stated there in full. This is the
+ * other half: the branded declaration a `Capability` carries, the assembly-time check that a key
+ * inherits a scope its own routes already gate, and the per-request read that decides between a number,
+ * a withholding and a failure.
+ *
+ * **The two are separate modules because the compiler follows a type-only edge (#430).** Everything
+ * here needs `Capability`, `PithyHonoEnv` and `Context`, which reach D1, KV and Hono; nothing a browser
+ * imports needs any of it. Leaving the wire vocabulary in this file put all of that one `import type`
+ * away from every management client, through `adminRoute.ts`. Nothing in `./healthSummary` may import
+ * this module, and `tooling/browser-scopes` is the gate that says so.
+ */
+
+/**
+ * The brand only {@link defineCapabilityHealth} 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 declaration therefore cannot reach a manifest without having
+ * been parsed. An inline object literal on `Capability.health` is a compile error, which is what stops
+ * the next producer from re-inventing this with a key nothing validated — the failure mode every defect
+ * class in this kit has had in common.
+ *
+ * `Symbol()` rather than `Symbol.for()`, unlike the seam's `ANY_VERIFIED_CALLER`: that one is a
+ * requirement a route states and nobody may forge over the wire; this is a mark only this module applies.
+ */
+const healthSeam: unique symbol = Symbol("pithy.controlPlane.capabilityHealth");
+
+/** What a capability declares and how it produces it. Built only by {@link defineCapabilityHealth}. */
+export interface CapabilityHealth {
+  /** The brand. Present only on a declaration that went through the factory, and never serialized. */
+  readonly [healthSeam]: true;
+  /** The closed vocabulary: every key this capability may report, parsed. */
+  readonly keys: readonly HealthSummaryKey[];
+  /** Produce every declared key for this request. Bounded by the declaration, never by adopter data. */
+  readonly read: (c: Context<PithyHonoEnv>) => Promise<HealthSummary>;
+}
+
+/** The authoring shape — keys as written, before parsing. */
+export interface CapabilityHealthInput {
+  /** Every key this capability may report. At least one; an empty vocabulary is not a summary. */
+  keys: readonly z.input<typeof HealthSummaryKey>[];
+  /** Produce every declared key for this request. */
+  read: (c: Context<PithyHonoEnv>) => Promise<HealthSummary>;
+}
+
+/**
+ * Declare a capability's health summary. The one constructor, so every declaration in the tree is
+ * parsed — kind against states, cost against the closed vocabulary, key against the name pattern.
+ */
+export function defineCapabilityHealth(input: CapabilityHealthInput): CapabilityHealth {
+  if (input.keys.length === 0) {
+    throw new InternalError({
+      message: "A capability declared a health summary with no keys.",
+      action: "Declare at least one key, or omit the health seam entirely.",
+      detail: "defineCapabilityHealth received an empty key list; an empty vocabulary is not a summary.",
+    });
+  }
+  const keys = input.keys.map((key) => HealthSummaryKey.parse(key));
+  const seen = new Set<string>();
+  for (const key of keys) {
+    if (seen.has(key.key)) {
+      throw new InternalError({
+        message: "A capability declared the same health key twice.",
+        action: "Give each key one declaration — the second silently decides what the first meant.",
+        detail: `health key ${key.key} is declared more than once`,
+      });
+    }
+    seen.add(key.key);
+  }
+  return { [healthSeam]: true, keys, read: input.read };
+}
+
+/** One capability's contribution, as the seam holds it between assembly and a request. */
+export interface CapabilityHealthSource {
+  /** Which capability contributes it — named in every refusal, because the fix is always in that package. */
+  capability: string;
+  /** Its closed vocabulary. */
+  keys: readonly HealthSummaryKey[];
+  /** Its producer. */
+  read: (c: Context<PithyHonoEnv>) => Promise<HealthSummary>;
+}
+
+/**
+ * Every composed capability's health contribution, checked at assembly.
+ *
+ * **The check is that a summary inherits a scope, never invents one**, and it is compared against a
+ * different artifact than the one it polices: the capability's own `adminRoutes`. That is not a
+ * tidiness rule. `pithy dashboard connect` offers an adopter the scopes it reads off `adminRoutes`, so
+ * a key behind a scope no route requires is a number that could never be granted — permanently
+ * withheld, with nothing an adopter could do about it, and no error anywhere to say why. Failing at
+ * assembly turns that into a deploy that does not start.
+ */
+export function capabilityHealthSources(
+  capabilities: readonly Capability[],
+): ReadonlyMap<string, CapabilityHealthSource> {
+  const sources = new Map<string, CapabilityHealthSource>();
+  for (const capability of capabilities) {
+    const health = capability.health;
+    if (!health) continue;
+    const gated = new Set((capability.adminRoutes ?? []).flatMap((route) => (route.scope ? [route.scope] : [])));
+    for (const key of health.keys) {
+      if (!gated.has(key.scope)) {
+        throw new InternalError({
+          message: "A capability's health summary is behind a scope none of its admin routes requires.",
+          action: "Put the value behind a scope the capability already gates a read with.",
+          detail: `capability ${capability.name} declares health key ${key.key} behind ${key.scope}, which no admin route of that capability requires — an adopter is never offered it, so the value could never be granted`,
+        });
+      }
+    }
+    sources.set(capability.name, { capability: capability.name, keys: health.keys, read: health.read });
+  }
+  return sources;
+}
+
+/** Refuse a produced summary that its declaration cannot name. Total over what a producer may return. */
+function checked(source: CapabilityHealthSource, produced: HealthSummary): HealthSummary {
+  const declared = new Map(source.keys.map((key) => [key.key, key]));
+  for (const key of Object.keys(produced)) {
+    if (!declared.has(key)) {
+      throw new InternalError({
+        message: "A capability reported a health value it never declared.",
+        action: "Declare the key alongside the capability's routes, or stop reporting it.",
+        detail: `capability ${source.capability} produced health key ${key}, which its declaration does not name`,
+      });
+    }
+  }
+  for (const key of source.keys) {
+    const value = produced[key.key];
+    if (value === undefined) {
+      throw new InternalError({
+        message: "A capability omitted a health value it declared.",
+        action: "Produce every declared key, or remove the declaration.",
+        detail: `capability ${source.capability} declares health key ${key.key} and produced nothing for it`,
+      });
+    }
+    const ok =
+      key.kind === "count"
+        ? typeof value === "number" && Number.isInteger(value) && value >= 0
+        : typeof value === "string" && (key.states ?? []).includes(value);
+    if (!ok) {
+      throw new InternalError({
+        message: "A capability reported a health value its declaration does not permit.",
+        action: "Report a whole non-negative number for a count, or a declared member for a state.",
+        // The value itself, because it is a scalar the declaration already said may be published — and
+        // knowing *which* value was refused is most of the diagnosis.
+        detail: `capability ${source.capability} produced ${JSON.stringify(value)} for ${key.kind} key ${key.key}`,
+      });
+    }
+  }
+  return produced;
+}
+
+/**
+ * One capability's summary for one caller.
+ *
+ * **The producer is not called when no key is permitted**, so a caller with no grant costs the adopter's
+ * Worker nothing at all. When it *is* called, the whole of what it produced is checked before anything
+ * is withheld: a producer must not be able to hide a violation behind a scope the caller happens to
+ * lack.
+ *
+ * **A failure is caught here and goes no further.** The manifest is the read every other pane is built
+ * from, so one capability's bad afternoon must cost that capability's number and nothing else. Both
+ * kinds of failure land in the same state, because from a caller's side they are one fact — this
+ * capability could not say: the producer threw, or what it produced its own declaration does not
+ * permit. An author's mistake is not what this hides. The scope a key inherits, its name, its cost and
+ * the brand on the declaration are all checked at assembly, so the shape of a declaration fails a
+ * deploy rather than a request; what reaches here is data-dependent, which is the transient kind.
+ *
+ * **The caught error is dropped whole, and the `catch` takes no binding so that is visible rather than
+ * asserted.** It may be a `PithyError` whose `detail` names a row, a key id, or a query — throw-site
+ * context, which is exactly what a producer should put there and exactly what must not travel. Nothing
+ * derived from it reaches the manifest, a log, or a response: what survives is that this capability
+ * failed, and its name, which the manifest already carries in public. An adopter diagnoses it at their
+ * own throw site, where the context is theirs and stays theirs.
+ */
+export async function readCapabilityHealth(
+  source: CapabilityHealthSource | undefined,
+  grantedScopes: readonly string[],
+  produce: (source: CapabilityHealthSource) => Promise<HealthSummary>,
+): Promise<CapabilityHealthReport> {
+  if (!source) return { state: "undeclared" };
+  const permitted = source.keys.filter((key) => grantedScopes.includes(key.scope));
+  if (permitted.length === 0) return { state: "withheld" };
+  let produced: HealthSummary;
+  try {
+    produced = checked(source, await produce(source));
+  } catch {
+    return { state: "unavailable" };
+  }
+  const visible: HealthSummary = {};
+  for (const key of permitted) {
+    // Present: `checked` refused anything the declaration does not name and anything it omits.
+    visible[key.key] = produced[key.key] as HealthSummaryValue;
+  }
+  return { state: "reported", values: visible };
+}