@intentius/chant 0.124.32 → 0.124.34

package/dist/components/wave-plan.js

@@ -13,6 +13,14 @@
  * (`componentPlanDigest`, ./gate-plan.ts, #2574), so a wave mixing roots and
  * other components still has one digest that moves when any of them does.
  *
+ * The files a step without a `plan` deploys from are bound too (#4155,
+ * ./deploy-inputs.ts). A component with no plannable step folds them into its
+ * composition digest. A component with one gets a member more,
+ * `<component>#inputs`, over its other steps' files, so a `lambda-deploy`
+ * source or a Helm chart beside a `cfn-deploy` moves the wave's digest. A step
+ * whose content chant can't name is a hole on that member, so the plan note
+ * lists it as unbound.
+ *
  * Known limit: a step input that reads an earlier step of the same
  * component (`@Phase.field`) has no value before the component runs, so it
  * plans as `undefined`. Cross-component wiring (`stackOutput()`,
@@ -20,13 +28,18 @@
  */
 import { resolveStepInput, unresolvedWiringSources } from "./driver.js";
 import { componentPlanDigest } from "./gate-plan.js";
-/** A part with no entries, for a member whose planner describes no changes. */
-function emptyPart(member) {
+import { componentDeployInputs } from "./deploy-inputs.js";
+import { computePlanDigest } from "../lifecycle/plan-digest.js";
+/** A part with no entries, for a member whose planner describes no changes. `unbound` steps become its holes (#4155). */
+function emptyPart(member, unbound = []) {
+    const holes = unbound.map((u) => ({ address: `${u.phase}/${u.kind}`, type: u.kind, reason: `unbound: ${u.reason}` }));
     return {
-        member: { member: member.member, lexicon: "chant", planner: "chant", status: "planned", planDigest: member.planDigest, holes: [] },
+        member: { member: member.member, lexicon: "chant", planner: "chant", status: "planned", planDigest: member.planDigest, holes },
         entries: [],
     };
 }
+/** The member a planning component's other steps add (#4155): their files, under the component's name. */
+export const inputsMemberName = (component) => `${component}#inputs`;
 /** Every capability step in a composition, nested phases included, gates left out. */
 export function capabilitySteps(phases) {
     const out = [];
@@ -75,17 +88,32 @@ export async function planWaveComponent(component, registry, ctx, componentOutpu
             if (planned.outputs)
                 outputs = mergePlannedOutputs(outputs, planned.outputs);
         }
+        // #4155: the steps without a plan, which no member above covers.
+        const planless = (step) => !registry.has(step.kind) || registry.resolve(step.kind).plan === undefined;
         if (members.length === 0) {
+            const read = componentDeployInputs(component.deploy, process.cwd());
             const member = {
                 member: component.name,
                 planDigest: componentPlanDigest({
                     environment: ctx.env,
                     component,
                     ...(ctx.vars ? { vars: ctx.vars } : {}),
+                    inputs: read.inputs,
                 }),
             };
             members.push(member);
-            parts.push(emptyPart(member));
+            parts.push(emptyPart(member, read.unbound));
+        }
+        else {
+            const read = componentDeployInputs(component.deploy, process.cwd(), planless);
+            if (read.inputs.length > 0 || read.unbound.length > 0) {
+                const member = {
+                    member: inputsMemberName(component.name),
+                    planDigest: computePlanDigest("component-inputs", { environment: ctx.env, component: component.name, inputs: read.inputs }),
+                };
+                members.push(member);
+                parts.push(emptyPart(member, read.unbound));
+            }
         }
         return { component: component.name, members, plans, parts, ...(outputs ? { outputs } : {}) };
     }

package/dist/graph-declared.d.ts

@@ -10,6 +10,10 @@ import { type GraphIR } from "./graph-ir.js";
  * that live side, build each stack's `src` in isolation and qualify its node ids
  * and edge endpoints the same way. Stacks are merged into one graph.
  *
+ * Each stack's exports and imports come along with their `node` qualified the
+ * same way (#4202), so a workspace viewer can still match an import in another
+ * member to an export here once an environment is picked.
+ *
  * A stack without `src` contributes nothing here — it has no declared source to
  * scope to (its live nodes still show as foreign in the overlay).
  */

package/dist/graph-declared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-declared.d.ts","sourceRoot":"","sources":["../src/graph-declared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,OAAO,EAAe,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CAuBlB"}
+{"version":3,"file":"graph-declared.d.ts","sourceRoot":"","sources":["../src/graph-declared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,OAAO,EAAe,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CA2BlB"}

package/dist/graph-declared.js

@@ -12,6 +12,10 @@ import { buildGraphIr } from "./graph-ir.js";
  * that live side, build each stack's `src` in isolation and qualify its node ids
  * and edge endpoints the same way. Stacks are merged into one graph.
  *
+ * Each stack's exports and imports come along with their `node` qualified the
+ * same way (#4202), so a workspace viewer can still match an import in another
+ * member to an export here once an environment is picked.
+ *
  * A stack without `src` contributes nothing here — it has no declared source to
  * scope to (its live nodes still show as foreign in the overlay).
  */
@@ -19,6 +23,8 @@ export async function buildDeclaredPerStack(stacks, projectPath) {
     var _a;
     const nodes = [];
     const edges = [];
+    const exports = [];
+    const imports = [];
     // Which nodes belong to which stack (#1433). This is not derived or guessed:
     // the stack is declared in config and every node here is being renamed with
     // its name on the line below. The membership was always known and thrown
@@ -37,9 +43,13 @@ export async function buildDeclaredPerStack(stacks, projectPath) {
         }
         for (const e of g.edges)
             edges.push({ ...e, from: q(e.from), to: q(e.to) });
+        for (const e of g.exports ?? [])
+            exports.push({ ...e, ...(e.node ? { node: q(e.node) } : {}) });
+        for (const i of g.imports ?? [])
+            imports.push({ ...i, node: q(i.node) });
     }
     for (const ids of Object.values(byStack))
         ids.sort();
     const groups = Object.keys(byStack).length ? { byStack } : {};
-    return { nodes, edges, groups };
+    return { nodes, edges, groups, ...(exports.length ? { exports } : {}), ...(imports.length ? { imports } : {}) };
 }

package/dist/graph-detail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-detail.d.ts","sourceRoot":"","sources":["../src/graph-detail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC,eAAO,MAAM,MAAM;aACjB,MAAM,EAAE,CAAC;aACT,UAAU,EAAE,CAAC;aACb,WAAW,EAAE,CAAC;aACd,UAAU,EAAE,CAAC;CACL,CAAC;AAEX,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAYpE;AA+LD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAYtF"}
+{"version":3,"file":"graph-detail.d.ts","sourceRoot":"","sources":["../src/graph-detail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC,eAAO,MAAM,MAAM;aACjB,MAAM,EAAE,CAAC;aACT,UAAU,EAAE,CAAC;aACb,WAAW,EAAE,CAAC;aACd,UAAU,EAAE,CAAC;CACL,CAAC;AAEX,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAYpE;AAyND;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAYtF"}

package/dist/graph-detail.js

@@ -90,27 +90,45 @@ function toDeclarables(ir) {
 /** 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) {
-    const idMap = new Map();
-    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) => `${n.compositeInstance}\0${n.compositeParent ?? ""}`;
     const instances = new Map();
     const plain = [];
     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();
+    for (const members of instances.values()) {
+        const inst = members[0].compositeInstance;
+        sharing.set(inst, (sharing.get(inst) ?? 0) + 1);
+    }
+    const collapsedId = new Map();
+    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();
+    for (const n of ir.nodes)
+        idMap.set(n.id, n.compositeInstance ? collapsedId.get(instanceKey(n)) : n.id);
     const nodes = [...plain];
-    for (const [inst, members] of instances) {
+    for (const [key, members] of instances) {
         const types = new Set(members.map((m) => m.compositeParent).filter(Boolean));
         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 },
@@ -163,11 +181,18 @@ function toComposites(ir) {
         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/dist/health.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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.js";
+/** The versioned shape `chant lifecycle health --json` prints. The JSON Schema is `./health.schema.json`. */
+export declare const HEALTH_SCHEMA = "chant-health/v1";
+/** The `$id` of `./health.schema.json`, which the package exports as `@intentius/chant/health.schema.json`. */
+export declare 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 declare function healthApplicable(plugin: HealthLexicon, entities: Map<string, {
+    entityType: string;
+    props: Record<string, unknown>;
+}>): Map<string, {
+    entityType: string;
+    props: Record<string, unknown>;
+}>;
+/**
+ * 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 declare function observeHealthFor(plugin: HealthLexicon, options: HealthReadOptions): Promise<HealthReadResult>;
+/**
+ * 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 declare function totalHealth(names: string[], result: HealthReadResult, types?: Map<string, {
+    entityType: string;
+}>): HealthReadResult;
+/** 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 declare function summarizeHealth(results: Iterable<HealthReadResult>): HealthSummary;
+/** A health entry, for a reader building its result. */
+export declare function healthEntry(type: string, state: HealthState, detail: string, observedAt: string, checkedAt?: string): HealthEntry;
+/** A hole, for a reader building its result. */
+export declare function healthHole(type: string, reason: UnobservedReason, detail: string): UnobservedEntity;
+//# sourceMappingURL=health.d.ts.map

package/dist/health.d.ts.map

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

package/dist/health.js

@@ -0,0 +1,105 @@
+/**
+ * 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 { unobservedAll } from "./observation.js";
+/** 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";
+/**
+ * The entities of one lexicon a health read applies to: those whose type the
+ * lexicon names in `healthTypes`.
+ */
+export function healthApplicable(plugin, entities) {
+    const types = new Set(plugin.healthTypes ?? []);
+    const out = new Map();
+    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, options) {
+    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;
+    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, result, types) {
+    const entities = {};
+    const unobserved = {};
+    const absentSet = new Set(result.absent ?? []);
+    const absent = [];
+    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 };
+}
+export function summarizeHealth(results) {
+    const summary = { 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, state, detail, observedAt, checkedAt) {
+    return { type, state, detail, observedAt, ...(checkedAt ? { checkedAt } : {}) };
+}
+/** A hole, for a reader building its result. */
+export function healthHole(type, reason, detail) {
+    return { type, reason, detail };
+}

package/dist/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/dist/lexicon.d.ts

@@ -41,6 +41,7 @@ export type { CommandGroup, CommandGroupCommand, CommandGroupContext } from "./c
 export type { ReferenceCatalog, IdentityRule, RefRule } from "./graph-refs.js";
 export type { IREdge } from "./graph-ir.js";
 export type { DescribeResourcesResult, ObservationResult, NormalizedObservation, UnobservedEntity, UnobservedReason, } from "./observation.js";
+export type { HealthEntry, HealthReadOptions, HealthReadResult, HealthState, } from "./health.js";
 export type { DescribeIdentityOptions, DescribeIdentityResult, ResolvedIdentity, UnresolvedIdentity, IdentityRow, IdentityStatus, } from "./identity.js";
 export type { Disruption, DisruptionQuery, DisruptionVerdict, DisruptionClassifier, } from "./lifecycle/disruption.js";
 export type { DeepObservationResult, DeepResourceObservation, NormalizedDeepObservation, DeepNormalizationHooks, DeepNode, DeepArrayElement, DeepSide, } from "./deep-observation.js";
@@ -589,6 +590,15 @@ export type OpTrigger = {
 } | {
     kind: "push";
     branches?: string[];
+    /**
+     * Which pushes run the Op (#4169), for an Op a `ci.green` phase names
+     * with `build` and the tick reads from chant runs. `every`: each
+     * commit, in a run of its own that no later push cancels. `newest`:
+     * one run at a time, the newest push waiting and the ones between
+     * dropped, plus a run at each `ci/build/<sha>` tag the tick or `ci run
+     * --at` pushes. Absent: one run at a time per Op, as before.
+     */
+    build?: "every" | "newest";
 };
 /**
  * One step a generated Op job runs between the checkout and the
@@ -1617,6 +1627,23 @@ export interface LexiconPlugin {
         /** Restrict to chant-owned resources (#119). A lexicon with no marker channel on this path says so. */
         owned?: boolean;
     }): Promise<DeepObservationResult>;
+    /**
+     * Entity types {@link observeHealth} reads (#4177). Data, not a method, so
+     * core picks the entities a health read applies to without calling it.
+     */
+    healthTypes?: readonly string[];
+    /**
+     * Whether each declared entity of a {@link healthTypes} type is up (#4177),
+     * read separately from drift: a service's running count, a health check's
+     * checkers, a revision's running state, a Ready condition.
+     *
+     * Every entity in `options.entities` lands in exactly one of `entities`,
+     * `unobserved` or `absent`. A read that failed is `unobserved` with a reason,
+     * never `unhealthy`: `unhealthy` is something the provider said. Throwing is
+     * the whole-lexicon failure, and core reports every entity `read-failed`.
+     * Endpoint overrides apply as on the other reads, so an emulator answers.
+     */
+    observeHealth?(options: import("./health.js").HealthReadOptions): Promise<import("./health.js").HealthReadResult>;
     /**
      * This lexicon's noise rules for deep observation (#1014): which fields are
      * read-only / server-populated / controller-managed / provider-defaulted, and