@pithy-sh/core 0.1.2 → 0.1.3

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

@@ -0,0 +1,99 @@
+import type { Context } from "hono";
+import type { z } from "zod";
+import type { Capability, PithyHonoEnv } from "../../capability/capability";
+import { type CapabilityHealthReport, type HealthSummary, HealthSummaryKey } 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.
+ */
+declare const healthSeam: unique symbol;
+/** 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 declare function defineCapabilityHealth(input: CapabilityHealthInput): CapabilityHealth;
+/** 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 declare function capabilityHealthSources(capabilities: readonly Capability[]): ReadonlyMap<string, CapabilityHealthSource>;
+/**
+ * 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 declare function readCapabilityHealth(source: CapabilityHealthSource | undefined, grantedScopes: readonly string[], produce: (source: CapabilityHealthSource) => Promise<HealthSummary>): Promise<CapabilityHealthReport>;
+export {};
+//# sourceMappingURL=health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/health.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE5E,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,gBAAgB,EAEjB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,UAAU,EAAE,OAAO,MAAsD,CAAC;AAEhF,uGAAuG;AACvG,MAAM,WAAW,gBAAgB;IAC/B,oGAAoG;IACpG,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC3C,sGAAsG;IACtG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CACrE;AAED,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,gGAAgG;IAChG,IAAI,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,EAAE,CAAC;IAClD,mDAAmD;IACnD,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CAC5D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,CAqBrF;AAED,0FAA0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,2GAA2G;IAC3G,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,IAAI,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClC,oBAAoB;IACpB,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CAC5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,SAAS,UAAU,EAAE,GAClC,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAkB7C;AAwCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,sBAAsB,GAAG,SAAS,EAC1C,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,aAAa,CAAC,GAClE,OAAO,CAAC,sBAAsB,CAAC,CAgBjC"}

package/dist/controlPlane/discovery/health.js

@@ -0,0 +1,151 @@
+import { InternalError } from "../../error/pithyError.js";
+import { HealthSummaryKey } from "./healthSummary.js";
+//#region src/controlPlane/discovery/health.ts
+/**
+* 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 = Symbol("pithy.controlPlane.capabilityHealth");
+/**
+* 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.
+*/
+function defineCapabilityHealth(input) {
+	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 = /* @__PURE__ */ new Set();
+	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
+	};
+}
+/**
+* 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.
+*/
+function capabilityHealthSources(capabilities) {
+	const sources = /* @__PURE__ */ new Map();
+	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, produced) {
+	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 === void 0) 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`
+		});
+		if (!(key.kind === "count" ? typeof value === "number" && Number.isInteger(value) && value >= 0 : typeof value === "string" && (key.states ?? []).includes(value))) 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.",
+			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.
+*/
+async function readCapabilityHealth(source, grantedScopes, produce) {
+	if (!source) return { state: "undeclared" };
+	const permitted = source.keys.filter((key) => grantedScopes.includes(key.scope));
+	if (permitted.length === 0) return { state: "withheld" };
+	let produced;
+	try {
+		produced = checked(source, await produce(source));
+	} catch {
+		return { state: "unavailable" };
+	}
+	const visible = {};
+	for (const key of permitted) visible[key.key] = produced[key.key];
+	return {
+		state: "reported",
+		values: visible
+	};
+}
+//#endregion
+export { capabilityHealthSources, defineCapabilityHealth, readCapabilityHealth };

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

@@ -0,0 +1,236 @@
+import { z } from "zod";
+/** What kind of scalar a key reports. */
+export declare const HealthValueKind: z.ZodEnum<{
+    count: "count";
+    state: "state";
+}>;
+export type HealthValueKind = z.output<typeof HealthValueKind>;
+/**
+ * What producing one value costs on a manifest read.
+ *
+ * **There is deliberately no member for a scan.** That is the whole constraint expressed as a
+ * vocabulary: a capability whose number would need one cannot state its cost, so it cannot declare the
+ * key, so the manifest stays cheap by construction rather than by everybody remembering.
+ */
+export declare const HealthValueCost: z.ZodEnum<{
+    indexed: "indexed";
+    memory: "memory";
+}>;
+export type HealthValueCost = z.output<typeof HealthValueCost>;
+/**
+ * One value a summary may carry. A number or a member of a declared enum — never anything else.
+ *
+ * This is the rule the issue asked to be in the type: `number | string` has no room for a row, an id, a
+ * nested object, or a collection that grows with an adopter's data.
+ */
+export declare const HealthSummaryValue: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+export type HealthSummaryValue = z.output<typeof HealthSummaryValue>;
+/** 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 HealthSummaryValue} is ever widened.
+ *
+ * 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.
+ */
+export 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 HEALTH_SUMMARY_IS_SCALAR_ONLY: ScalarOnly<HealthSummaryValue>;
+/**
+ * What a count must be for its key to be nominal — a bound, in either direction or both.
+ *
+ * **Both are optional and at least one is required**, which is the whole of the shape. `atMost: 0` is
+ * `secretsDueForRotation`, where zero is the good answer; `atLeast: 1` is a count of things that must
+ * exist, where zero is the fault. A declaration carrying neither is a claim with no content, and one
+ * carrying an inverted pair is a claim nothing can satisfy — both would make every value on that key
+ * want attention forever, which is worse than declaring nothing.
+ *
+ * Inclusive at the edge. A cadence saying *no more than zero overdue* means zero is fine.
+ */
+export declare const HealthCountNominal: z.ZodObject<{
+    atMost: z.ZodOptional<z.ZodNumber>;
+    atLeast: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type HealthCountNominal = z.output<typeof HealthCountNominal>;
+/**
+ * What a key claims a nominal value is, or null where it makes no claim at all.
+ *
+ * **Null is the default and stays supported forever.** Some measures genuinely have no good or bad
+ * value — a count of things that simply exist — and a vocabulary that forced a claim would collect
+ * invented ones. What must never happen is a client reading null as *fine*; {@link standingOf} answers
+ * `unknowable` for it, and that is the point of this whole field.
+ */
+export declare const HealthNominal: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+    atMost: z.ZodOptional<z.ZodNumber>;
+    atLeast: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodArray<z.ZodString>]>>;
+export type HealthNominal = z.output<typeof HealthNominal>;
+/**
+ * One key a capability may report, declared alongside its routes.
+ *
+ * `scope` is **not nullable**, unlike an admin route's. A route may need only a verified caller — the
+ * seam's `ping` does — but a number about somebody's posture never may, and an optional field here is a
+ * field somebody forgets.
+ */
+export declare const HealthSummaryKey: z.ZodObject<{
+    key: z.ZodString;
+    kind: z.ZodEnum<{
+        count: "count";
+        state: "state";
+    }>;
+    states: z.ZodNullable<z.ZodArray<z.ZodString>>;
+    scope: z.ZodString;
+    cost: z.ZodEnum<{
+        indexed: "indexed";
+        memory: "memory";
+    }>;
+    summary: z.ZodString;
+    nominal: z.ZodDefault<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        atMost: z.ZodOptional<z.ZodNumber>;
+        atLeast: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodArray<z.ZodString>]>>>;
+}, z.core.$strip>;
+export type HealthSummaryKey = z.output<typeof HealthSummaryKey>;
+/**
+ * A capability's summary as the manifest carries it: declared key → scalar.
+ *
+ * A record rather than a closed object, because the vocabulary is federated the way scopes and audit
+ * actions are. **Parsing tolerates a key it has never heard of on purpose** — a client reading a newer
+ * Worker must render the unknown one as nothing rather than fail the whole manifest.
+ */
+export declare const HealthSummary: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+export type HealthSummary = z.output<typeof HealthSummary>;
+/**
+ * What one capability's summary is, for one caller. Four states, and the value carries which.
+ *
+ * A discriminated union rather than a nullable record with a flag beside it, and that is the whole
+ * point of #350. A flag is the same information and the opposite property: correct for whoever
+ * remembered to read it, and a zero for everybody else. Here the scalars are unreachable without
+ * narrowing on `state`, so forgetting the sick case is a type error rather than a screen that says
+ * everything is fine.
+ *
+ * - `undeclared` — the capability contributes no summary. Nothing to show, and nothing wrong.
+ * - `withheld` — it declares one, and this connection was not granted the scope it sits behind. Read
+ *   `healthKeys` beside this and a client can say a number exists that it may not see.
+ * - `reported` — the values, each one named by a declaration that travels with it. Zero is one of these.
+ * - `unavailable` — producing the summary failed. Not zero, not withheld, and never both.
+ */
+export declare const CapabilityHealthReport: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"undeclared">;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"withheld">;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"reported">;
+    values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unavailable">;
+}, z.core.$strip>], "state">;
+export type CapabilityHealthReport = z.output<typeof CapabilityHealthReport>;
+/** A manifest entry's health as the wire carries it: the #317 fields, plus the flag #350 added. */
+export interface CapabilityHealthWire {
+    /** The closed vocabulary this capability may report. Empty when it declares none. */
+    healthKeys: readonly HealthSummaryKey[];
+    /** The values this caller may see, or null when there are none to give. Null is never zero. */
+    health: HealthSummary | null;
+    /** Whether producing the summary failed on this read. */
+    healthUnavailable: boolean;
+}
+/**
+ * Read the four states off a manifest entry.
+ *
+ * **The failure flag is checked first and wins.** A Worker that sends both a failure and values is
+ * describing a producer that did not finish, and reading what it sent anyway is reading whatever the
+ * failure left behind.
+ *
+ * A Worker deployed before #350 sends no flag, which defaults to false, and lands on the three states
+ * it already had. A Worker deployed before #317 sends neither field and lands on `undeclared`.
+ */
+export declare function healthReport(entry: CapabilityHealthWire): CapabilityHealthReport;
+/**
+ * Put a report back on the wire.
+ *
+ * The one place the two fields are written, so a handler cannot set the values and forget the flag.
+ * `undeclared` and `withheld` encode alike on purpose — `healthKeys` rides in the same entry and tells
+ * them apart, which is the arrangement #317 chose and this does not disturb.
+ */
+export declare function healthWire(report: CapabilityHealthReport): {
+    health: HealthSummary | null;
+    healthUnavailable: boolean;
+};
+/** One value with the declaration that says how to render it. */
+export interface NamedHealthValue {
+    /** The declaration — its kind, its closed list, what it means, and what it cost. */
+    key: HealthSummaryKey;
+    /** The scalar reported for it. */
+    value: HealthSummaryValue;
+}
+/**
+ * Pair a capability's reported values with their declarations, dropping any value nothing declares.
+ *
+ * This is how "an unknown summary key is renderable as nothing rather than as an error" is real rather
+ * than aspirational: a client renders what this returns, so a key from a Worker newer than its
+ * declaration simply is not in the list.
+ *
+ * **Only `reported` has values.** A withheld summary and a failed one both name nothing here, which is
+ * right for a list of numbers — and it is why a surface that must say *why* there is no number reads
+ * `state` rather than the length of this.
+ */
+export declare function namedHealthValues(descriptor: {
+    healthKeys: readonly HealthSummaryKey[];
+    health: CapabilityHealthReport;
+}): NamedHealthValue[];
+/**
+ * Where one value stands against its own declaration — #471.
+ *
+ * Three answers, and the third is the reason this exists.
+ *
+ * - `nominal` — the value is what the capability said it should be.
+ * - `attention` — it is not.
+ * - `unknowable` — **nobody said what it should be**, so nothing can be concluded.
+ *
+ * **`unknowable` is never `nominal`, and a client must not collapse them.** A key that declares no
+ * bound is a key nobody can grade; answering `nominal` for it would let a management client read
+ * healthy because nothing told it otherwise, which is the defect this whole field was filed to remove
+ * rather than relocate. #350 made the four report states a discriminated union for the same reason —
+ * so a consumer that forgets the sick case gets a type error instead of a screen that lies — and this
+ * is the same choice one level down.
+ *
+ * It is also the answer for a value whose **type** contradicts its `kind` — a string where a count was
+ * declared. `checked()` refuses that on the producing side, but a client parses manifests from Workers
+ * it does not control, and grading a value that is not the kind of thing being graded is inventing an
+ * answer about it.
+ *
+ * **A `state` value outside its own `states` is a different case and is `attention`, deliberately.** It
+ * is a string, so it is the kind of thing being graded; it is simply not one the capability said it
+ * would send. Answering `unknowable` there would file a Worker reporting `storeState: "exploded"` under
+ * *nothing can be concluded*, when what can be concluded is that something is wrong.
+ */
+export type HealthStanding = "nominal" | "attention" | "unknowable";
+/** Where {@link HealthSummaryValue} stands against the key that declared it. See {@link HealthStanding}. */
+export declare function standingOf(key: HealthSummaryKey, value: HealthSummaryValue): HealthStanding;
+/**
+ * Every value this capability reported that wants somebody's attention, in declaration order.
+ *
+ * `namedHealthValues` one filter later, and here rather than in every client so the filter is written
+ * once. The three stateless reports answer empty: `undeclared`, `withheld` and `unavailable` are states
+ * of the *report* rather than of any value, and folding one of them into a list of graded measures is
+ * exactly the collapse #350 and #471 each exist to prevent — a withheld number is not a bad number, and
+ * a failed read is not a finding about the thing that failed to be read.
+ *
+ * A value standing at `unknowable` is not here either. The list is what wants attention, and a measure
+ * nobody grades cannot want it.
+ *
+ * **So an empty list is not a clean bill of health, and a client that renders it as one has rebuilt
+ * #471 one layer up.** Five situations answer `[]`: nothing declared, withheld, unavailable, everything
+ * nominal, and everything ungradeable. Three of those are *could not look* rather than *nothing is
+ * wrong*. A surface that wants to tell them apart has what it needs — the report's own state separates
+ * the first three, and mapping {@link namedHealthValues} through {@link standingOf} separates the last
+ * two — but it has to ask, and this function deliberately does not answer it.
+ */
+export declare function healthAttention(descriptor: {
+    healthKeys: readonly HealthSummaryKey[];
+    health: CapabilityHealthReport;
+}): NamedHealthValue[];
+export {};
+//# sourceMappingURL=healthSummary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"healthSummary.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/healthSummary.ts"],"names":[],"mappings":"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"}