@intentius/chant 0.124.31 → 0.124.33

package/src/fold/subset.ts

@@ -461,6 +461,98 @@ export function unsupportedExpressionMessage(node: ts.Node): string {
   return `unsupported expression: ${ts.SyntaxKind[node.kind]}`;
 }
 
+/**
+ * chant#4011 — S-CallMethod's closed table of HOST methods, by receiver type.
+ * PROVISIONAL until typescript-as-data narrows F-Eval-CallMethod to the same
+ * table (INTENTIUS/typescript-as-data#264; see the module doc's provisional path).
+ *
+ * Since #1966 `fold()` called any function-valued property on a real
+ * receiver, so `[].constructor.constructor("return Date.now()")` reached
+ * `Function` and a `[fold:fold]` file could put the clock, `process.env` or
+ * `Math.random()` in its output. A method the JavaScript engine provides
+ * (a native function) now folds only when it is listed here for the
+ * receiver's type AND is the very function that type's prototype carries, so
+ * an own property cannot shadow a listed name. Every entry is deterministic
+ * given its receiver and arguments: no callbacks (`map`, `filter`), no
+ * mutation (`push`, `sort`), and no `toLocale*` or `localeCompare`, whose
+ * answer follows the host's locale and time zone.
+ *
+ * A method defined by a lexicon package's own code (the github lexicon's
+ * `Expression.prototype.toString`) is not a host method and is not looked up
+ * here; it is the same class of package code as an eager intrinsic call.
+ */
+export const FOLDABLE_HOST_METHODS: {
+  readonly string: ReadonlySet<string>;
+  readonly number: ReadonlySet<string>;
+  readonly boolean: ReadonlySet<string>;
+  readonly array: ReadonlySet<string>;
+  readonly object: ReadonlySet<string>;
+} = {
+  string: new Set([
+    "at",
+    "charAt",
+    "charCodeAt",
+    "codePointAt",
+    "concat",
+    "endsWith",
+    "includes",
+    "indexOf",
+    "lastIndexOf",
+    "padEnd",
+    "padStart",
+    "repeat",
+    "replace",
+    "replaceAll",
+    "slice",
+    "split",
+    "startsWith",
+    "substring",
+    "toLowerCase",
+    "toString",
+    "toUpperCase",
+    "trim",
+    "trimEnd",
+    "trimStart",
+    "valueOf",
+  ]),
+  number: new Set(["toExponential", "toFixed", "toPrecision", "toString", "valueOf"]),
+  boolean: new Set(["toString", "valueOf"]),
+  array: new Set(["at", "concat", "flat", "includes", "indexOf", "join", "lastIndexOf", "slice", "toString"]),
+  object: new Set(["hasOwnProperty", "toString", "valueOf"]),
+};
+
+/**
+ * chant#4011 — method names `fold()` refuses on every receiver, lexicon
+ * objects included. These are the names that reach `Function` (`constructor`,
+ * and `call`/`apply`/`bind` on whatever it returns) or read the host locale.
+ * Unlike {@link FOLDABLE_HOST_METHODS}, which needs the receiver's runtime
+ * type, a name in this set is decidable from syntax, so EVL001 refuses it too.
+ */
+export const REFUSED_METHOD_NAMES: ReadonlySet<string> = new Set([
+  "constructor",
+  "call",
+  "apply",
+  "bind",
+  "toLocaleString",
+  "toLocaleDateString",
+  "toLocaleTimeString",
+  "toLocaleUpperCase",
+  "toLocaleLowerCase",
+  "localeCompare",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__",
+]);
+
+/** The refusal for a method name in {@link REFUSED_METHOD_NAMES}, shared by `fold()` and EVL001. */
+export function refusedMethodMessage(methodName: string): string {
+  return (
+    `method call \`.${methodName}(...)\` is not foldable: it reaches \`Function\` or the host locale, ` +
+    "so its result is not determined by the source (chant#4011) — falls back to run"
+  );
+}
+
 /**
  * Classify one object-literal member (`{ a: 1 }`'s `a: 1`, `{ ...x }`'s
  * `...x`, or a shorthand `{ a }`). Checks the key's shape before the
@@ -720,7 +812,14 @@ export function findSubsetViolation(
     // a same-file `new` used as a value (#1169). Accepted here regardless of
     // the intrinsics registry, unlike the two cases just above: nothing about
     // whether a method call folds depends on a lexicon's registration.
+    //
+    // chant#4011 — except a name `fold()` refuses on every receiver, which is
+    // decidable here. The per-type host table needs the receiver's value, so
+    // it stays on `fold()`'s side, in the direction F-Direction allows.
     if (ts.isPropertyAccessExpression(node.expression)) {
+      if (REFUSED_METHOD_NAMES.has(node.expression.name.text)) {
+        return violation(node, refusedMethodMessage(node.expression.name.text));
+      }
       const v = findSubsetViolation(node.expression.expression, intrinsics);
       if (v) return v;
       for (const arg of node.arguments) {

package/src/graph-detail.test.ts

@@ -87,6 +87,63 @@ describe("applyDetail", () => {
     expect(ir.imports).toEqual([{ name: "pClusterArn", node: "pClusterArn" }]);
   });
 
+  test("T1 keeps exports, each on the node that now holds its producer (#4178)", () => {
+    const withExports: GraphIR = {
+      ...base,
+      version: 2,
+      meta: { _behaviour: { engine: "x" } },
+      exports: [
+        { name: "DbEndpoint", node: "dbDeployment", attr: "status" },
+        { name: "SubnetLink", node: "subnet", attr: "selfLink" },
+        { name: "Literal" },
+      ],
+    };
+    const ir = applyDetail(withExports, DETAIL.COMPOSITES);
+    expect(ir.exports).toEqual([
+      { name: "DbEndpoint", node: "db", attr: "status" },
+      { name: "SubnetLink", node: "subnet", attr: "selfLink" },
+      { name: "Literal" },
+    ]);
+    expect(ir.version).toBe(2);
+    expect(ir.meta).toEqual({ _behaviour: { engine: "x" } });
+  });
+
+  test("T1 keeps two same-named composites from different composite types apart (#4178)", () => {
+    const twoWebs: GraphIR = {
+      nodes: [
+        { id: "webAlb", kind: "AWS::ElasticLoadBalancingV2::LoadBalancer", lexicon: "aws", compositeParent: "FargateAlb", compositeInstance: "web", attrs: {} },
+        { id: "webService", kind: "AWS::ECS::Service", lexicon: "aws", compositeParent: "FargateAlb", compositeInstance: "web", attrs: {} },
+        { id: "webRun", kind: "RunService", lexicon: "gcp", compositeParent: "CloudRunServiceComposite", compositeInstance: "web", attrs: {} },
+        { id: "record", kind: "AWS::Route53::RecordSet", lexicon: "aws", attrs: {} },
+      ],
+      edges: [
+        { from: "record", to: "webAlb", kind: "ref", viaAttr: "AliasTarget" },
+        { from: "record", to: "webRun", kind: "ref", viaAttr: "ResourceRecords" },
+        { from: "webService", to: "webAlb", kind: "ref", viaAttr: "LoadBalancers" },
+      ],
+      groups: {},
+      exports: [{ name: "WebUri", node: "webRun", attr: "uri" }],
+    };
+    const ir = applyDetail(twoWebs, DETAIL.COMPOSITES);
+    expect(ir.nodes.map((n) => n.id)).toEqual(["record", "web@CloudRunServiceComposite", "web@FargateAlb"]);
+    expect(ir.nodes.find((n) => n.id === "web@FargateAlb")).toMatchObject({ kind: "FargateAlb", lexicon: "aws", attrs: { members: 2 } });
+    expect(ir.nodes.find((n) => n.id === "web@CloudRunServiceComposite")).toMatchObject({ kind: "CloudRunServiceComposite", lexicon: "gcp", attrs: { members: 1 } });
+    expect(ir.edges).toEqual(expect.arrayContaining([
+      { from: "record", to: "web@FargateAlb", kind: "ref" },
+      { from: "record", to: "web@CloudRunServiceComposite", kind: "ref" },
+    ]));
+    expect(ir.edges).toHaveLength(2);
+    expect(ir.exports).toEqual([{ name: "WebUri", node: "web@CloudRunServiceComposite", attr: "uri" }]);
+  });
+
+  test("T1 keeps one composite whose members span lexicons as one node", () => {
+    const ir = applyDetail({
+      ...base,
+      nodes: base.nodes.map((n) => (n.id === "dbNamespace" ? { ...n, lexicon: "gcp" } : n)),
+    }, DETAIL.COMPOSITES);
+    expect(ir.nodes.find((n) => n.id === "db")).toMatchObject({ kind: "DbStack", lexicon: "multi", attrs: { members: 2 } });
+  });
+
   test("T1 node count is between T0 and T2", () => {
     const t0 = applyDetail(base, DETAIL.STACKS).nodes.length;
     const t1 = applyDetail(base, DETAIL.COMPOSITES).nodes.length;

package/src/graph-detail.ts

@@ -127,27 +127,46 @@ function toDeclarables(ir: GraphIR): GraphIR {
 /** T1 — collapse each composite instance to one node; internal edges disappear.
  * Topology view: surviving plain nodes keep only overlay paint, not properties. */
 function toComposites(ir: GraphIR): GraphIR {
-  const idMap = new Map<string, string>();
-  for (const n of ir.nodes) idMap.set(n.id, n.compositeInstance ?? n.id);
-
+  // A composite instance is its export name plus the composite that made it:
+  // an AWS FargateAlb and a GCP CloudRunServiceComposite both exported as
+  // `web` are two instances (#4178). One composite whose members span
+  // lexicons stays one instance.
+  const instanceKey = (n: IRNode) => `${n.compositeInstance}\0${n.compositeParent ?? ""}`;
   const instances = new Map<string, IRNode[]>();
   const plain: IRNode[] = [];
   for (const n of ir.nodes) {
     if (n.compositeInstance) {
-      const arr = instances.get(n.compositeInstance) ?? [];
+      const key = instanceKey(n);
+      const arr = instances.get(key) ?? [];
       arr.push(n);
-      instances.set(n.compositeInstance, arr);
+      instances.set(key, arr);
     } else {
       plain.push({ ...n, attrs: paintAttrs(n.attrs) });
     }
   }
 
+  // The collapsed id is the instance name, or `<instance>@<composite>` when
+  // two composites share the name.
+  const sharing = new Map<string, number>();
+  for (const members of instances.values()) {
+    const inst = members[0].compositeInstance!;
+    sharing.set(inst, (sharing.get(inst) ?? 0) + 1);
+  }
+  const collapsedId = new Map<string, string>();
+  for (const [key, members] of instances) {
+    const { compositeInstance: inst, compositeParent: parent } = members[0];
+    collapsedId.set(key, sharing.get(inst!)! > 1 && parent ? `${inst}@${parent}` : inst!);
+  }
+
+  const idMap = new Map<string, string>();
+  for (const n of ir.nodes) idMap.set(n.id, n.compositeInstance ? collapsedId.get(instanceKey(n))! : n.id);
+
   const nodes: IRNode[] = [...plain];
-  for (const [inst, members] of instances) {
+  for (const [key, members] of instances) {
     const types = new Set(members.map((m) => m.compositeParent).filter(Boolean) as string[]);
     const lexicons = new Set(members.map((m) => m.lexicon));
     nodes.push({
-      id: inst,
+      id: collapsedId.get(key)!,
       kind: types.size === 1 ? [...types][0] : "Composite",
       lexicon: lexicons.size === 1 ? [...lexicons][0] : "multi",
       attrs: { members: members.length },
@@ -197,11 +216,18 @@ function toComposites(ir: GraphIR): GraphIR {
     }
     if (Object.keys(byPipeline).length) groups.byPipeline = byPipeline;
   }
+  // Exports (#4178) stay at this tier, each on the node that now holds its
+  // producer, so a viewer can still match another member's import to it.
+  const exports = ir.exports?.map((x) => (x.node ? { ...x, node: idMap.get(x.node) ?? x.node } : { ...x }));
   return {
+    ...(ir.version !== undefined ? { version: ir.version } : {}),
     nodes,
     edges: sortEdges([...seen.values()]),
     groups,
+    ...(ir.meta ? { meta: ir.meta } : {}),
+    ...(exports && exports.length ? { exports } : {}),
     ...(imports && imports.length ? { imports } : {}),
+    ...(ir.pipeline ? { pipeline: ir.pipeline } : {}),
     ...(dangling && dangling.length ? { dangling } : {}),
   };
 }

package/src/health.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/health/v1/health.schema.json",
+  "title": "chant-health/v1",
+  "description": "What `chant lifecycle health <env> --json` prints (#4177): whether each declared resource that has a health read is up, read separately from drift. Every entity a read applies to lands in exactly one of `entities` (read, with a state), `unobserved` (the read failed, never folded into unhealthy) or `absent` (the provider says it is not deployed). Entity names are the graph's node ids. A single-stack project puts `lexicons` at the top level; a multi-stack one nests them under `stacks`. Written by the first chant release after 0.124.32. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "type": "object",
+  "required": [
+    "schema",
+    "chantVersion",
+    "environment",
+    "observedAt",
+    "summary"
+  ],
+  "properties": {
+    "schema": {
+      "const": "chant-health/v1"
+    },
+    "chantVersion": {
+      "type": "string",
+      "description": "The chant that ran the read."
+    },
+    "environment": {
+      "type": "string",
+      "description": "The environment named on the command line."
+    },
+    "observedAt": {
+      "type": "string",
+      "description": "When the command started reading, ISO 8601 UTC."
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "healthy",
+        "unhealthy",
+        "unknown",
+        "unobserved",
+        "absent"
+      ],
+      "description": "Counts over every lexicon and stack.",
+      "properties": {
+        "healthy": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unhealthy": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unknown": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unobserved": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "absent": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "required": [
+        "lexicons"
+      ],
+      "properties": {
+        "lexicons": {
+          "$ref": "#/$defs/byLexicon"
+        }
+      }
+    },
+    {
+      "required": [
+        "stacks"
+      ],
+      "properties": {
+        "stacks": {
+          "type": "object",
+          "description": "Per stack name, the same per-lexicon results.",
+          "additionalProperties": {
+            "$ref": "#/$defs/byLexicon"
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "byLexicon": {
+      "type": "object",
+      "description": "Per lexicon name, that lexicon's read. A lexicon with no applicable entity is left out.",
+      "additionalProperties": {
+        "$ref": "#/$defs/read"
+      }
+    },
+    "read": {
+      "type": "object",
+      "required": [
+        "entities",
+        "unobserved",
+        "absent"
+      ],
+      "properties": {
+        "entities": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/entry"
+          }
+        },
+        "unobserved": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/hole"
+          }
+        },
+        "absent": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Entity names the provider says are not deployed."
+        }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "required": [
+        "type",
+        "state",
+        "detail",
+        "observedAt"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Entity type, such as AWS::ECS::Service."
+        },
+        "state": {
+          "enum": [
+            "healthy",
+            "unhealthy",
+            "unknown"
+          ],
+          "description": "healthy and unhealthy are what the provider reported. unknown means the read succeeded and the answer decides neither way: a rollout in progress, a service scaled to zero, a condition pending."
+        },
+        "detail": {
+          "type": "string",
+          "description": "One short line saying why, in the provider's terms."
+        },
+        "observedAt": {
+          "type": "string",
+          "description": "When chant read it, ISO 8601."
+        },
+        "checkedAt": {
+          "type": "string",
+          "description": "When the provider last checked or changed the state, when it says, ISO 8601."
+        }
+      }
+    },
+    "hole": {
+      "type": "object",
+      "required": [
+        "reason"
+      ],
+      "description": "A read that failed. Never counted as unhealthy.",
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "reason": {
+          "enum": [
+            "read-failed",
+            "no-credentials",
+            "no-binding",
+            "unsupported-kind",
+            "filtered"
+          ]
+        },
+        "detail": {
+          "type": "string"
+        },
+        "queried": {
+          "type": "string",
+          "description": "The address the read was issued against, when the lexicon reports it."
+        }
+      }
+    }
+  }
+}

package/src/health.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "vitest";
+import { healthApplicable, observeHealthFor, summarizeHealth, totalHealth, type HealthLexicon } from "./health";
+
+const entities = new Map([
+  ["web", { entityType: "AWS::ECS::Service", props: {} }],
+  ["check", { entityType: "AWS::Route53::HealthCheck", props: {} }],
+]);
+
+describe("health reads (#4177)", () => {
+  test("healthApplicable keeps only the types the lexicon names", () => {
+    const all = new Map([...entities, ["bucket", { entityType: "AWS::S3::Bucket", props: {} }]]);
+    const picked = healthApplicable({ name: "aws", healthTypes: ["AWS::ECS::Service"] }, all);
+    expect([...picked.keys()]).toEqual(["web"]);
+  });
+
+  test("a thrown reader is read-failed for every entity, never unhealthy", async () => {
+    const plugin: HealthLexicon = {
+      name: "aws",
+      healthTypes: ["AWS::ECS::Service"],
+      observeHealth: async () => {
+        throw new Error("connect ECONNREFUSED");
+      },
+    };
+    const r = await observeHealthFor(plugin, { environment: "dev", buildOutput: "", entities });
+    expect(r.entities).toEqual({});
+    expect(r.unobserved.web).toEqual({ reason: "read-failed", type: "AWS::ECS::Service", detail: "connect ECONNREFUSED" });
+    expect(Object.keys(r.unobserved)).toEqual(["web", "check"]);
+  });
+
+  test("a lexicon without a reader reports unsupported-kind", async () => {
+    const r = await observeHealthFor({ name: "aws" }, { environment: "dev", buildOutput: "", entities });
+    expect(r.unobserved.web?.reason).toBe("unsupported-kind");
+  });
+
+  test("the result is made total, and entities win over absent and unobserved", () => {
+    const r = totalHealth(["web", "check", "gone", "forgot"], {
+      entities: { web: { type: "AWS::ECS::Service", state: "healthy", detail: "1/1 running", observedAt: "t" } },
+      unobserved: { web: { reason: "read-failed" }, check: { reason: "no-credentials" } },
+      absent: ["gone", "web"],
+    });
+    expect(Object.keys(r.entities)).toEqual(["web"]);
+    expect(r.absent).toEqual(["gone"]);
+    expect(r.unobserved.check?.reason).toBe("no-credentials");
+    expect(r.unobserved.forgot?.reason).toBe("read-failed");
+    expect(r.unobserved.web).toBeUndefined();
+  });
+
+  test("summarizeHealth counts each place", () => {
+    const s = summarizeHealth([
+      {
+        entities: {
+          a: { type: "t", state: "healthy", detail: "", observedAt: "" },
+          b: { type: "t", state: "unhealthy", detail: "", observedAt: "" },
+          c: { type: "t", state: "unknown", detail: "", observedAt: "" },
+        },
+        unobserved: { d: { reason: "read-failed" } },
+        absent: ["e", "f"],
+      },
+    ]);
+    expect(s).toEqual({ healthy: 1, unhealthy: 1, unknown: 1, unobserved: 1, absent: 2 });
+  });
+});

package/src/health.ts

@@ -0,0 +1,178 @@
+/**
+ * Runtime health (#4177): whether a declared thing is up, read separately from
+ * drift.
+ *
+ * The observation family answers what is deployed (`describeResources`), what
+ * its properties are (`observeResourcesDeep`) and what it would do
+ * (`predictBehaviour`). None of them says whether a service is serving. A
+ * lexicon that can read that implements {@link HealthLexicon.observeHealth}
+ * for the types it names in `healthTypes`, and `chant lifecycle health` reports
+ * the answers in the {@link HEALTH_SCHEMA} shape.
+ *
+ * The verdicts follow #1089's rule. Every entity the caller asks about lands in
+ * exactly one place: `entities` (read, with a state), `unobserved` (the read
+ * failed, a hole with a reason) or `absent` (the provider says it is not
+ * deployed). A failed read is never `unhealthy`: `unhealthy` is something the
+ * provider said.
+ *
+ * Routing is not modelled. A consumer that wants rotation (a latency record
+ * whose health check is unhealthy is out of rotation) derives it from the
+ * graph's edges and these states.
+ */
+
+import type { UnobservedEntity, UnobservedReason } from "./observation";
+import { unobservedAll } from "./observation";
+
+/** The versioned shape `chant lifecycle health --json` prints. The JSON Schema is `./health.schema.json`. */
+export const HEALTH_SCHEMA = "chant-health/v1";
+
+/** The `$id` of `./health.schema.json`, which the package exports as `@intentius/chant/health.schema.json`. */
+export const HEALTH_SCHEMA_ID = "https://intentius.io/chant/schemas/health/v1/health.schema.json";
+
+/**
+ * `healthy` and `unhealthy` are what the provider reported. `unknown` means the
+ * read succeeded and the provider's answer does not decide either way (a
+ * deployment still rolling, a service scaled to zero, a condition pending).
+ */
+export type HealthState = "healthy" | "unhealthy" | "unknown";
+
+export interface HealthEntry {
+  /** Entity type, e.g. `AWS::ECS::Service`. */
+  type: string;
+  state: HealthState;
+  /** One short line saying why, in the provider's terms. */
+  detail: string;
+  /** When chant read it (ISO 8601). */
+  observedAt: string;
+  /** When the provider last checked or changed the state, when it says (ISO 8601). */
+  checkedAt?: string;
+}
+
+/** What one lexicon's health read returns. */
+export interface HealthReadResult {
+  /** Read, keyed by chant entity name, which is the graph's node id. */
+  entities: Record<string, HealthEntry>;
+  /** Could not be read. Never folded into `unhealthy`. */
+  unobserved: Record<string, UnobservedEntity>;
+  /** The provider says these are not deployed. */
+  absent: string[];
+}
+
+/** The options core passes a lexicon's health read. They mirror `observeResourcesDeep`'s. */
+export interface HealthReadOptions {
+  environment: string;
+  buildOutput: string;
+  /** Only entities whose type is in the lexicon's `healthTypes`. */
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  stack?: string;
+  region?: string;
+}
+
+/** The two plugin members a lexicon implements to answer a health read. */
+export interface HealthLexicon {
+  name: string;
+  /** Entity types {@link observeHealth} can read. Data, so core picks the entities without calling the reader. */
+  healthTypes?: readonly string[];
+  observeHealth?(options: HealthReadOptions): Promise<HealthReadResult>;
+}
+
+/**
+ * The entities of one lexicon a health read applies to: those whose type the
+ * lexicon names in `healthTypes`.
+ */
+export function healthApplicable(
+  plugin: HealthLexicon,
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>,
+): Map<string, { entityType: string; props: Record<string, unknown> }> {
+  const types = new Set(plugin.healthTypes ?? []);
+  const out = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+  for (const [name, entity] of entities) if (types.has(entity.entityType)) out.set(name, entity);
+  return out;
+}
+
+/**
+ * Run one lexicon's health read. Never throws: a thrown reader reports every
+ * applicable entity `read-failed`. The result is made total, so an entity the
+ * reader forgot comes back `unobserved` rather than missing.
+ */
+export async function observeHealthFor(
+  plugin: HealthLexicon,
+  options: HealthReadOptions,
+): Promise<HealthReadResult> {
+  const names = [...options.entities.keys()];
+  if (names.length === 0) return { entities: {}, unobserved: {}, absent: [] };
+  if (!plugin.observeHealth) {
+    return {
+      entities: {},
+      unobserved: unobservedAll(names, "unsupported-kind", `${plugin.name} has no health read`, options.entities),
+      absent: [],
+    };
+  }
+  let result: HealthReadResult;
+  try {
+    result = await plugin.observeHealth(options);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { entities: {}, unobserved: unobservedAll(names, "read-failed", message, options.entities), absent: [] };
+  }
+  return totalHealth(names, result, options.entities);
+}
+
+/**
+ * Put every asked-about name in exactly one of the three places. A name in
+ * `entities` wins over the others, then `absent`, then `unobserved`; a name in
+ * none of them becomes `read-failed`.
+ */
+export function totalHealth(
+  names: string[],
+  result: HealthReadResult,
+  types?: Map<string, { entityType: string }>,
+): HealthReadResult {
+  const entities: Record<string, HealthEntry> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  const absentSet = new Set(result.absent ?? []);
+  const absent: string[] = [];
+  for (const name of names) {
+    const entry = result.entities?.[name];
+    if (entry) entities[name] = entry;
+    else if (absentSet.has(name)) absent.push(name);
+    else if (result.unobserved?.[name]) unobserved[name] = result.unobserved[name];
+    else Object.assign(unobserved, unobservedAll([name], "read-failed", "the health read returned no answer for this entity", types));
+  }
+  return { entities, unobserved, absent };
+}
+
+/** Counts across a health read, for the summary line and `--json`. */
+export interface HealthSummary {
+  healthy: number;
+  unhealthy: number;
+  unknown: number;
+  unobserved: number;
+  absent: number;
+}
+
+export function summarizeHealth(results: Iterable<HealthReadResult>): HealthSummary {
+  const summary: HealthSummary = { healthy: 0, unhealthy: 0, unknown: 0, unobserved: 0, absent: 0 };
+  for (const r of results) {
+    for (const entry of Object.values(r.entities)) summary[entry.state]++;
+    summary.unobserved += Object.keys(r.unobserved).length;
+    summary.absent += r.absent.length;
+  }
+  return summary;
+}
+
+/** A health entry, for a reader building its result. */
+export function healthEntry(
+  type: string,
+  state: HealthState,
+  detail: string,
+  observedAt: string,
+  checkedAt?: string,
+): HealthEntry {
+  return { type, state, detail, observedAt, ...(checkedAt ? { checkedAt } : {}) };
+}
+
+/** A hole, for a reader building its result. */
+export function healthHole(type: string, reason: UnobservedReason, detail: string): UnobservedEntity {
+  return { type, reason, detail };
+}