@intentius/chant-lexicon-aws 0.124.32 → 0.124.33

package/dist/health.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Runtime health for AWS (#4177): Route 53 health checks and ECS services.
+ *
+ * The stack's own resource list maps each logical id (the graph's node id) to
+ * the physical id the health APIs take. A stack that does not exist yet means
+ * nothing is deployed, so every entity is absent. Any other stack failure is a
+ * hole for every entity, never `unhealthy`.
+ *
+ * - `AWS::Route53::HealthCheck`: `GetHealthCheckStatus`, aggregated as Route 53
+ *   does: healthy when more than 18% of the checkers report healthy.
+ * - `AWS::ECS::Service`: `DescribeServices`, `runningCount` against
+ *   `desiredCount`.
+ *
+ * Both go through the read transport's endpoint rule, so `AWS_ENDPOINT_URL`
+ * (Floci) answers them.
+ */
+import type { HealthEntry, HealthReadOptions, HealthReadResult } from "@intentius/chant/lexicon";
+import { type AwsReadClientOptions } from "./api/read-client.js";
+export declare const AWS_HEALTH_TYPES: readonly ["AWS::Route53::HealthCheck", "AWS::ECS::Service"];
+/** Injectable HTTP for both calls, so tests never reach the network. */
+export type AwsHealthHttp = (method: "GET" | "POST", url: string, init: {
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    status: number;
+    text: string;
+}>;
+export interface AwsHealthOptions extends HealthReadOptions {
+    http?: AwsHealthHttp;
+    /** Read client for the stack list and the signing decision. Tests inject `http` and `env` here. */
+    client?: AwsReadClientOptions;
+    now?: () => Date;
+}
+/** One checker's report, as `GetHealthCheckStatus` returns it. */
+export interface CheckerObservation {
+    region?: string;
+    ipAddress?: string;
+    status: string;
+    checkedTime?: string;
+}
+/** Parse `GetHealthCheckStatusResponse`'s observations. */
+export declare function parseHealthCheckStatus(xml: string): CheckerObservation[];
+/** Route 53's verdict over its checkers' observations. */
+export declare function healthCheckEntry(observations: CheckerObservation[], observedAt: string): HealthEntry;
+/** The parts of an ECS service `DescribeServices` returns that decide health. */
+export interface EcsServiceState {
+    status?: string;
+    desiredCount?: number;
+    runningCount?: number;
+    pendingCount?: number;
+    deployments?: Array<{
+        rolloutState?: string;
+        updatedAt?: number | string;
+    }>;
+}
+/** Running against desired. Scaled to zero is `unknown`: nothing is serving, by choice. */
+export declare function ecsServiceEntry(service: EcsServiceState, observedAt: string): HealthEntry;
+/** The cluster a service ARN names: `service/<cluster>/<name>`, or the default cluster for the old `service/<name>` form. */
+export declare function clusterOfServiceArn(arn: string): string;
+export declare function observeHealthAws(options: AwsHealthOptions): Promise<HealthReadResult>;
+//# 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":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAoB,MAAM,0BAA0B,CAAC;AACnH,OAAO,EASL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAI3B,eAAO,MAAM,gBAAgB,YAAI,2BAA2B,EAAE,mBAAmB,CAAU,CAAC;AAE5F,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,CAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,EACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAO/C,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,mGAAmG;IACnG,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAKD,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAcxE;AAOD,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,kBAAkB,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,CAepG;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7E;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,CAazF;AAED,6HAA6H;AAC7H,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvD;AAkED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgF3F"}

package/dist/health.js

@@ -0,0 +1,216 @@
+/**
+ * Runtime health for AWS (#4177): Route 53 health checks and ECS services.
+ *
+ * The stack's own resource list maps each logical id (the graph's node id) to
+ * the physical id the health APIs take. A stack that does not exist yet means
+ * nothing is deployed, so every entity is absent. Any other stack failure is a
+ * hole for every entity, never `unhealthy`.
+ *
+ * - `AWS::Route53::HealthCheck`: `GetHealthCheckStatus`, aggregated as Route 53
+ *   does: healthy when more than 18% of the checkers report healthy.
+ * - `AWS::ECS::Service`: `DescribeServices`, `runningCount` against
+ *   `desiredCount`.
+ *
+ * Both go through the read transport's endpoint rule, so `AWS_ENDPOINT_URL`
+ * (Floci) answers them.
+ */
+import { AwsReadError, describeStackResources, requestHeaders, serviceUrl, withChainCredentials, withEndpointOverride, xmlError, xmlLeaves, } from "./api/read-client.js";
+import { resolveCredentials, signRequest } from "./api/sigv4.js";
+import { stackDoesNotExist } from "./stack-errors.js";
+export const AWS_HEALTH_TYPES = ["AWS::Route53::HealthCheck", "AWS::ECS::Service"];
+const defaultHttp = async (method, url, init) => {
+    const res = await fetch(url, { method, headers: init.headers, ...(init.body !== undefined ? { body: init.body } : {}) });
+    return { status: res.status, text: await res.text() };
+};
+/** Route 53 treats an endpoint as healthy when more than this share of checkers says so. */
+const ROUTE53_HEALTHY_SHARE = 0.18;
+/** Parse `GetHealthCheckStatusResponse`'s observations. */
+export function parseHealthCheckStatus(xml) {
+    const out = [];
+    for (const m of xml.matchAll(/<HealthCheckObservation>([\s\S]*?)<\/HealthCheckObservation>/g)) {
+        const body = m[1] ?? "";
+        const report = xmlLeaves(body.match(/<StatusReport>([\s\S]*?)<\/StatusReport>/)?.[1] ?? "");
+        const top = xmlLeaves(body.replace(/<StatusReport>[\s\S]*?<\/StatusReport>/, ""));
+        out.push({
+            ...(top.Region ? { region: top.Region } : {}),
+            ...(top.IPAddress ? { ipAddress: top.IPAddress } : {}),
+            status: report.Status ?? "",
+            ...(report.CheckedTime ? { checkedTime: report.CheckedTime } : {}),
+        });
+    }
+    return out;
+}
+/** A checker's status text starts with `Success` when it found the endpoint healthy. */
+function checkerHealthy(o) {
+    return /^success/i.test(o.status.trim());
+}
+/** Route 53's verdict over its checkers' observations. */
+export function healthCheckEntry(observations, observedAt) {
+    const type = "AWS::Route53::HealthCheck";
+    if (observations.length === 0) {
+        return { type, state: "unknown", detail: "no checker has reported yet", observedAt };
+    }
+    const healthy = observations.filter(checkerHealthy).length;
+    const latest = [...observations].sort((a, b) => (b.checkedTime ?? "").localeCompare(a.checkedTime ?? ""))[0];
+    const state = healthy / observations.length > ROUTE53_HEALTHY_SHARE ? "healthy" : "unhealthy";
+    return {
+        type,
+        state,
+        detail: `${healthy}/${observations.length} checkers healthy; last: ${latest.status}`,
+        observedAt,
+        ...(latest.checkedTime ? { checkedAt: latest.checkedTime } : {}),
+    };
+}
+/** Running against desired. Scaled to zero is `unknown`: nothing is serving, by choice. */
+export function ecsServiceEntry(service, observedAt) {
+    const type = "AWS::ECS::Service";
+    const desired = service.desiredCount ?? 0;
+    const running = service.runningCount ?? 0;
+    const pending = service.pendingCount ?? 0;
+    const counts = `${running}/${desired} running${pending > 0 ? `, ${pending} pending` : ""}`;
+    const rollout = service.deployments?.find((d) => d.rolloutState)?.rolloutState;
+    const detail = `${counts}${rollout ? `, rollout ${rollout}` : ""}`;
+    if (service.status && service.status !== "ACTIVE") {
+        return { type, state: "unhealthy", detail: `service is ${service.status}; ${detail}`, observedAt };
+    }
+    if (desired === 0)
+        return { type, state: "unknown", detail: `desired count is 0; ${detail}`, observedAt };
+    return { type, state: running >= desired ? "healthy" : "unhealthy", detail, observedAt };
+}
+/** The cluster a service ARN names: `service/<cluster>/<name>`, or the default cluster for the old `service/<name>` form. */
+export function clusterOfServiceArn(arn) {
+    const resource = arn.split(":").slice(5).join(":");
+    const parts = resource.split("/");
+    return parts.length >= 3 ? parts[1] : "default";
+}
+function holeFrom(type, err) {
+    const detail = err instanceof AwsReadError && err.code ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
+    const reason = /credential|token|expired|AccessDenied|not authorized|Unauthorized/i.test(detail) ? "no-credentials" : "read-failed";
+    return { type, reason, detail: detail.slice(0, 200) };
+}
+async function getHealthCheckStatus(id, client, http) {
+    const options = await withChainCredentials(withEndpointOverride("route53", client));
+    // Route 53 is global: one host, signed in us-east-1.
+    const base = (options.endpoint ?? "https://route53.amazonaws.com").replace(/\/$/, "");
+    const url = `${base}/2013-04-01/healthcheck/${encodeURIComponent(id)}/status`;
+    const env = options.env ?? process.env;
+    const credentials = resolveCredentials(options.credentials, env);
+    const signable = credentials && (!options.endpoint || options.signEndpointOverride === true);
+    const headers = signable
+        ? signRequest({ method: "GET", url, headers: {}, body: "", service: "route53", region: "us-east-1", credentials, ...(options.now ? { now: options.now } : {}) })
+        : {};
+    const res = await http("GET", url, { headers });
+    const err = xmlError(res.text);
+    if (err || res.status >= 400) {
+        throw new AwsReadError(err?.message ?? `GetHealthCheckStatus failed with HTTP ${res.status}`, res.status, err?.code);
+    }
+    return parseHealthCheckStatus(res.text);
+}
+async function describeServices(cluster, arns, client, http) {
+    const options = await withChainCredentials(withEndpointOverride("ecs", client));
+    const url = serviceUrl("ecs", options.endpoint, options.region);
+    const body = JSON.stringify({ cluster, services: arns });
+    const headers = requestHeaders("ecs", url, body, { "content-type": "application/x-amz-json-1.1", "x-amz-target": "AmazonEC2ContainerServiceV20141113.DescribeServices" }, options);
+    const res = await http("POST", url, { headers, body });
+    let parsed = {};
+    try {
+        const value = JSON.parse(res.text);
+        if (value && typeof value === "object" && !Array.isArray(value))
+            parsed = value;
+    }
+    catch {
+        throw new AwsReadError("unparseable DescribeServices response", res.status);
+    }
+    const errType = typeof parsed.__type === "string" ? parsed.__type.split("#").pop() : undefined;
+    if (errType || res.status >= 400) {
+        const message = typeof parsed.message === "string" ? parsed.message : `DescribeServices failed with HTTP ${res.status}`;
+        throw new AwsReadError(message, res.status, errType);
+    }
+    return {
+        services: Array.isArray(parsed.services) ? parsed.services : [],
+        failures: Array.isArray(parsed.failures) ? parsed.failures : [],
+    };
+}
+export async function observeHealthAws(options) {
+    const http = options.http ?? defaultHttp;
+    const observedAt = (options.now?.() ?? new Date()).toISOString();
+    const client = { ...(options.client ?? {}), ...(options.region ? { region: options.region } : {}) };
+    const entities = {};
+    const unobserved = {};
+    const absent = [];
+    if (options.entities.size === 0)
+        return { entities, unobserved, absent };
+    const stackName = options.stack ?? options.environment;
+    let physical;
+    try {
+        const resources = await describeStackResources(stackName, client);
+        physical = new Map(resources.filter((r) => r.physicalId).map((r) => [r.logicalId, r.physicalId]));
+    }
+    catch (err) {
+        if (err instanceof AwsReadError && stackDoesNotExist(err.message))
+            return { entities, unobserved, absent: [...options.entities.keys()] };
+        for (const [name, { entityType }] of options.entities) {
+            unobserved[name] = holeFrom(entityType, err);
+            unobserved[name].detail = `DescribeStackResources failed for stack "${stackName}": ${unobserved[name].detail}`;
+        }
+        return { entities, unobserved, absent };
+    }
+    const services = new Map();
+    const checks = [];
+    for (const [name, { entityType }] of options.entities) {
+        const id = physical.get(name);
+        if (!id) {
+            absent.push(name);
+            continue;
+        }
+        if (entityType === "AWS::ECS::Service") {
+            const cluster = clusterOfServiceArn(id);
+            const list = services.get(cluster) ?? [];
+            list.push({ name, arn: id });
+            services.set(cluster, list);
+        }
+        else if (entityType === "AWS::Route53::HealthCheck") {
+            checks.push({ name, id });
+        }
+    }
+    await Promise.all(checks.map(async ({ name, id }) => {
+        try {
+            entities[name] = healthCheckEntry(await getHealthCheckStatus(id, client, http), observedAt);
+        }
+        catch (err) {
+            if (err instanceof AwsReadError && err.code === "NoSuchHealthCheck")
+                absent.push(name);
+            else
+                unobserved[name] = holeFrom("AWS::Route53::HealthCheck", err);
+        }
+    }));
+    await Promise.all([...services].map(async ([cluster, members]) => {
+        // DescribeServices takes at most ten services per call.
+        for (let i = 0; i < members.length; i += 10) {
+            const batch = members.slice(i, i + 10);
+            try {
+                const { services: found, failures } = await describeServices(cluster, batch.map((m) => m.arn), client, http);
+                for (const member of batch) {
+                    const service = found.find((s) => s.serviceArn === member.arn || s.serviceArn?.endsWith(`/${member.arn.split("/").pop()}`));
+                    const failure = failures.find((f) => f.arn === member.arn);
+                    if (service)
+                        entities[member.name] = ecsServiceEntry(service, observedAt);
+                    else if (failure?.reason === "MISSING")
+                        absent.push(member.name);
+                    else {
+                        unobserved[member.name] = {
+                            type: "AWS::ECS::Service",
+                            reason: "read-failed",
+                            detail: failure?.reason ? `DescribeServices: ${failure.reason}` : "DescribeServices did not return the service",
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                for (const member of batch)
+                    unobserved[member.name] = holeFrom("AWS::ECS::Service", err);
+            }
+        }
+    }));
+    return { entities, unobserved, absent };
+}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "8b5c3aa77344860ff255fdac525e40f63480383c88a4343a6b81d670be7e9621",
+    "manifest.json": "0ee5d3480fac8e9a938968dd5ddcc859a7e84cafa9bea700cedfa550dd4ef346",
     "meta.json": "3e18663eb9eb09920882f8014020432330a74ccd480689e7384c2022cbb10f39",
     "types/index.d.ts": "8651f9ae166668f4311eea1fe61c3fe235f345947951c1d23d1df24a4fd3384f",
     "rules/hardcoded-region.ts": "957eadcaa9f39cc17d21437565d7a94607d9b082cf28918b178fa067f07498a9",
@@ -73,5 +73,5 @@
     "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
     "skills/chant-aws-carve-terraform.md": "8780b94ce60aded935938d5ef20ea667738354051da1bf9ca6d70d9886f65d21"
   },
-  "composite": "bcbf6790bd0bbc10747eba452f59e6df06b46b350f8add6932ddf6f178ee1e0b"
+  "composite": "183d8f9b49de872c352a4daa986b8710ef256e152f04bea4d3b805515c53f657"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "aws",
-  "version": "0.124.32",
+  "version": "0.124.33",
   "chantVersion": ">=0.1.0",
   "namespace": "AWS",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAqQ,MAAM,0BAA0B,CAAC;AAwCjU;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBnD,eAAO,MAAM,SAAS,EAAE,aAujCvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAqQ,MAAM,0BAA0B,CAAC;AAwCjU;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBnD,eAAO,MAAM,SAAS,EAAE,aA+jCvB,CAAC"}

package/dist/plugin.js

@@ -791,6 +791,12 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     },
     /** The noise rules the deep pass applies to both the live and declared trees. */
     deepNormalizationHooks: awsDeepNormalizationHooks,
+    /** Runtime health (#4177): Route 53 health checks and ECS services. Implementation in ./health.ts. */
+    healthTypes: ["AWS::Route53::HealthCheck", "AWS::ECS::Service"],
+    async observeHealth(options) {
+        const { observeHealthAws } = await import("./health.js");
+        return observeHealthAws(options);
+    },
     async describeStackStatus(options) {
         const { getRuntime } = await import("@intentius/chant/runtime-adapter");
         const rt = getRuntime();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.124.32",
+  "version": "0.124.33",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,6 +80,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.32"
+    "@intentius/chant": "^0.124.33"
   }
 }

package/src/health.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "vitest";
+import {
+  clusterOfServiceArn,
+  ecsServiceEntry,
+  healthCheckEntry,
+  observeHealthAws,
+  parseHealthCheckStatus,
+  type AwsHealthHttp,
+} from "./health";
+import type { AwsReadHttp } from "./api/read-client";
+import { awsPlugin } from "./plugin";
+
+const AT = "2026-10-20T21:00:00.000Z";
+const now = () => new Date(AT);
+
+function stackXml(members: Array<{ logical: string; type: string; physical: string }>): string {
+  const body = members
+    .map((m) => `<member><LogicalResourceId>${m.logical}</LogicalResourceId><ResourceType>${m.type}</ResourceType><PhysicalResourceId>${m.physical}</PhysicalResourceId><ResourceStatus>CREATE_COMPLETE</ResourceStatus></member>`)
+    .join("");
+  return `<DescribeStackResourcesResponse><DescribeStackResourcesResult><StackResources>${body}</StackResources></DescribeStackResourcesResult></DescribeStackResourcesResponse>`;
+}
+
+function statusXml(obs: Array<{ region: string; status: string; time: string }>): string {
+  const body = obs
+    .map((o) => `<HealthCheckObservation><Region>${o.region}</Region><IPAddress>1.2.3.4</IPAddress><StatusReport><Status>${o.status}</Status><CheckedTime>${o.time}</CheckedTime></StatusReport></HealthCheckObservation>`)
+    .join("");
+  return `<GetHealthCheckStatusResponse><HealthCheckObservations>${body}</HealthCheckObservations></GetHealthCheckStatusResponse>`;
+}
+
+const ENV = { AWS_ENDPOINT_URL: "http://localhost:4566" };
+
+describe("aws health (#4177)", () => {
+  test("parses checker observations", () => {
+    const obs = parseHealthCheckStatus(statusXml([{ region: "us-east-1", status: "Success: HTTP Status Code 200, OK", time: "2026-10-20T20:59:00Z" }]));
+    expect(obs).toEqual([{ region: "us-east-1", ipAddress: "1.2.3.4", status: "Success: HTTP Status Code 200, OK", checkedTime: "2026-10-20T20:59:00Z" }]);
+  });
+
+  test("a health check is healthy only when more than 18% of checkers say so", () => {
+    const mk = (ok: number, total: number) =>
+      Array.from({ length: total }, (_, i) => ({ status: i < ok ? "Success: HTTP 200" : "Failure: timed out", checkedTime: `2026-10-20T20:5${i}:00Z` }));
+    expect(healthCheckEntry(mk(2, 10), AT).state).toBe("healthy");
+    expect(healthCheckEntry(mk(1, 10), AT).state).toBe("unhealthy");
+    const e = healthCheckEntry(mk(2, 10), AT);
+    expect(e.detail).toBe("2/10 checkers healthy; last: Failure: timed out");
+    expect(e.checkedAt).toBe("2026-10-20T20:59:00Z");
+    expect(healthCheckEntry([], AT).state).toBe("unknown");
+  });
+
+  test("an ECS service is running against desired", () => {
+    expect(ecsServiceEntry({ status: "ACTIVE", desiredCount: 2, runningCount: 2 }, AT)).toMatchObject({ state: "healthy", detail: "2/2 running" });
+    expect(ecsServiceEntry({ status: "ACTIVE", desiredCount: 3, runningCount: 1, pendingCount: 2 }, AT)).toMatchObject({ state: "unhealthy", detail: "1/3 running, 2 pending" });
+    expect(ecsServiceEntry({ status: "ACTIVE", desiredCount: 0, runningCount: 0 }, AT).state).toBe("unknown");
+    expect(ecsServiceEntry({ status: "DRAINING", desiredCount: 1, runningCount: 1 }, AT).state).toBe("unhealthy");
+  });
+
+  test("the cluster comes from the service ARN", () => {
+    expect(clusterOfServiceArn("arn:aws:ecs:us-east-1:000000000000:service/app/web")).toBe("app");
+    expect(clusterOfServiceArn("arn:aws:ecs:us-east-1:000000000000:service/web")).toBe("default");
+  });
+
+  test("reads both kinds through the endpoint override, keyed by logical id", async () => {
+    const cfn: AwsReadHttp = async (url) => {
+      expect(url).toBe("http://localhost:4566/");
+      return {
+        status: 200,
+        text: stackXml([
+          { logical: "web", type: "AWS::ECS::Service", physical: "arn:aws:ecs:us-east-1:000000000000:service/app/web" },
+          { logical: "webCheck", type: "AWS::Route53::HealthCheck", physical: "abc-123" },
+        ]),
+      };
+    };
+    const calls: string[] = [];
+    const http: AwsHealthHttp = async (method, url, init) => {
+      calls.push(`${method} ${url}`);
+      if (url.includes("/healthcheck/")) {
+        return { status: 200, text: statusXml([{ region: "us-east-1", status: "Success: HTTP 200", time: "2026-10-20T20:58:00Z" }]) };
+      }
+      expect(JSON.parse(init.body!)).toEqual({ cluster: "app", services: ["arn:aws:ecs:us-east-1:000000000000:service/app/web"] });
+      return {
+        status: 200,
+        text: JSON.stringify({ services: [{ serviceArn: "arn:aws:ecs:us-east-1:000000000000:service/app/web", status: "ACTIVE", desiredCount: 2, runningCount: 2 }], failures: [] }),
+      };
+    };
+    const r = await observeHealthAws({
+      environment: "dev",
+      buildOutput: "",
+      entities: new Map([
+        ["web", { entityType: "AWS::ECS::Service", props: {} }],
+        ["webCheck", { entityType: "AWS::Route53::HealthCheck", props: {} }],
+        ["later", { entityType: "AWS::ECS::Service", props: {} }],
+      ]),
+      http,
+      client: { http: cfn, env: ENV },
+      now,
+    });
+    expect(r.entities.web).toMatchObject({ state: "healthy", observedAt: AT });
+    expect(r.entities.webCheck).toMatchObject({ state: "healthy", checkedAt: "2026-10-20T20:58:00Z" });
+    expect(r.absent).toEqual(["later"]);
+    expect(calls).toContain("GET http://localhost:4566/2013-04-01/healthcheck/abc-123/status");
+  });
+
+  test("a missing stack is absent; a failed stack read is a hole for every entity", async () => {
+    const entities = new Map([["web", { entityType: "AWS::ECS::Service", props: {} }]]);
+    const missing: AwsReadHttp = async () => ({
+      status: 400,
+      text: "<ErrorResponse><Error><Code>ValidationError</Code><Message>Stack with id dev does not exist</Message></Error></ErrorResponse>",
+    });
+    const gone = await observeHealthAws({ environment: "dev", buildOutput: "", entities, client: { http: missing, env: ENV } });
+    expect(gone.absent).toEqual(["web"]);
+
+    const broken: AwsReadHttp = async () => {
+      throw new Error("connect ECONNREFUSED");
+    };
+    const hole = await observeHealthAws({ environment: "dev", buildOutput: "", entities, client: { http: broken, env: ENV } });
+    expect(hole.entities).toEqual({});
+    expect(hole.unobserved.web?.reason).toBe("read-failed");
+  });
+
+  test("a failed service read is a hole, never unhealthy", async () => {
+    const cfn: AwsReadHttp = async () => ({ status: 200, text: stackXml([{ logical: "web", type: "AWS::ECS::Service", physical: "arn:aws:ecs:us-east-1:0:service/app/web" }]) });
+    const http: AwsHealthHttp = async () => ({ status: 400, text: JSON.stringify({ __type: "ClusterNotFoundException", message: "Cluster not found." }) });
+    const r = await observeHealthAws({
+      environment: "dev",
+      buildOutput: "",
+      entities: new Map([["web", { entityType: "AWS::ECS::Service", props: {} }]]),
+      http,
+      client: { http: cfn, env: ENV },
+    });
+    expect(r.unobserved.web).toMatchObject({ reason: "read-failed", detail: "ClusterNotFoundException: Cluster not found." });
+  });
+
+  test("the plugin names the types it reads", () => {
+    expect(awsPlugin.healthTypes).toEqual(["AWS::Route53::HealthCheck", "AWS::ECS::Service"]);
+    expect(typeof awsPlugin.observeHealth).toBe("function");
+  });
+});

package/src/health.ts

@@ -0,0 +1,281 @@
+/**
+ * Runtime health for AWS (#4177): Route 53 health checks and ECS services.
+ *
+ * The stack's own resource list maps each logical id (the graph's node id) to
+ * the physical id the health APIs take. A stack that does not exist yet means
+ * nothing is deployed, so every entity is absent. Any other stack failure is a
+ * hole for every entity, never `unhealthy`.
+ *
+ * - `AWS::Route53::HealthCheck`: `GetHealthCheckStatus`, aggregated as Route 53
+ *   does: healthy when more than 18% of the checkers report healthy.
+ * - `AWS::ECS::Service`: `DescribeServices`, `runningCount` against
+ *   `desiredCount`.
+ *
+ * Both go through the read transport's endpoint rule, so `AWS_ENDPOINT_URL`
+ * (Floci) answers them.
+ */
+
+import type { HealthEntry, HealthReadOptions, HealthReadResult, UnobservedEntity } from "@intentius/chant/lexicon";
+import {
+  AwsReadError,
+  describeStackResources,
+  requestHeaders,
+  serviceUrl,
+  withChainCredentials,
+  withEndpointOverride,
+  xmlError,
+  xmlLeaves,
+  type AwsReadClientOptions,
+} from "./api/read-client";
+import { resolveCredentials, signRequest } from "./api/sigv4";
+import { stackDoesNotExist } from "./stack-errors";
+
+export const AWS_HEALTH_TYPES = ["AWS::Route53::HealthCheck", "AWS::ECS::Service"] as const;
+
+/** Injectable HTTP for both calls, so tests never reach the network. */
+export type AwsHealthHttp = (
+  method: "GET" | "POST",
+  url: string,
+  init: { headers: Record<string, string>; body?: string },
+) => Promise<{ status: number; text: string }>;
+
+const defaultHttp: AwsHealthHttp = async (method, url, init) => {
+  const res = await fetch(url, { method, headers: init.headers, ...(init.body !== undefined ? { body: init.body } : {}) });
+  return { status: res.status, text: await res.text() };
+};
+
+export interface AwsHealthOptions extends HealthReadOptions {
+  http?: AwsHealthHttp;
+  /** Read client for the stack list and the signing decision. Tests inject `http` and `env` here. */
+  client?: AwsReadClientOptions;
+  now?: () => Date;
+}
+
+/** Route 53 treats an endpoint as healthy when more than this share of checkers says so. */
+const ROUTE53_HEALTHY_SHARE = 0.18;
+
+/** One checker's report, as `GetHealthCheckStatus` returns it. */
+export interface CheckerObservation {
+  region?: string;
+  ipAddress?: string;
+  status: string;
+  checkedTime?: string;
+}
+
+/** Parse `GetHealthCheckStatusResponse`'s observations. */
+export function parseHealthCheckStatus(xml: string): CheckerObservation[] {
+  const out: CheckerObservation[] = [];
+  for (const m of xml.matchAll(/<HealthCheckObservation>([\s\S]*?)<\/HealthCheckObservation>/g)) {
+    const body = m[1] ?? "";
+    const report = xmlLeaves(body.match(/<StatusReport>([\s\S]*?)<\/StatusReport>/)?.[1] ?? "");
+    const top = xmlLeaves(body.replace(/<StatusReport>[\s\S]*?<\/StatusReport>/, ""));
+    out.push({
+      ...(top.Region ? { region: top.Region } : {}),
+      ...(top.IPAddress ? { ipAddress: top.IPAddress } : {}),
+      status: report.Status ?? "",
+      ...(report.CheckedTime ? { checkedTime: report.CheckedTime } : {}),
+    });
+  }
+  return out;
+}
+
+/** A checker's status text starts with `Success` when it found the endpoint healthy. */
+function checkerHealthy(o: CheckerObservation): boolean {
+  return /^success/i.test(o.status.trim());
+}
+
+/** Route 53's verdict over its checkers' observations. */
+export function healthCheckEntry(observations: CheckerObservation[], observedAt: string): HealthEntry {
+  const type = "AWS::Route53::HealthCheck";
+  if (observations.length === 0) {
+    return { type, state: "unknown", detail: "no checker has reported yet", observedAt };
+  }
+  const healthy = observations.filter(checkerHealthy).length;
+  const latest = [...observations].sort((a, b) => (b.checkedTime ?? "").localeCompare(a.checkedTime ?? ""))[0]!;
+  const state = healthy / observations.length > ROUTE53_HEALTHY_SHARE ? "healthy" : "unhealthy";
+  return {
+    type,
+    state,
+    detail: `${healthy}/${observations.length} checkers healthy; last: ${latest.status}`,
+    observedAt,
+    ...(latest.checkedTime ? { checkedAt: latest.checkedTime } : {}),
+  };
+}
+
+/** The parts of an ECS service `DescribeServices` returns that decide health. */
+export interface EcsServiceState {
+  status?: string;
+  desiredCount?: number;
+  runningCount?: number;
+  pendingCount?: number;
+  deployments?: Array<{ rolloutState?: string; updatedAt?: number | string }>;
+}
+
+/** Running against desired. Scaled to zero is `unknown`: nothing is serving, by choice. */
+export function ecsServiceEntry(service: EcsServiceState, observedAt: string): HealthEntry {
+  const type = "AWS::ECS::Service";
+  const desired = service.desiredCount ?? 0;
+  const running = service.runningCount ?? 0;
+  const pending = service.pendingCount ?? 0;
+  const counts = `${running}/${desired} running${pending > 0 ? `, ${pending} pending` : ""}`;
+  const rollout = service.deployments?.find((d) => d.rolloutState)?.rolloutState;
+  const detail = `${counts}${rollout ? `, rollout ${rollout}` : ""}`;
+  if (service.status && service.status !== "ACTIVE") {
+    return { type, state: "unhealthy", detail: `service is ${service.status}; ${detail}`, observedAt };
+  }
+  if (desired === 0) return { type, state: "unknown", detail: `desired count is 0; ${detail}`, observedAt };
+  return { type, state: running >= desired ? "healthy" : "unhealthy", detail, observedAt };
+}
+
+/** The cluster a service ARN names: `service/<cluster>/<name>`, or the default cluster for the old `service/<name>` form. */
+export function clusterOfServiceArn(arn: string): string {
+  const resource = arn.split(":").slice(5).join(":");
+  const parts = resource.split("/");
+  return parts.length >= 3 ? parts[1]! : "default";
+}
+
+function holeFrom(type: string, err: unknown): UnobservedEntity {
+  const detail = err instanceof AwsReadError && err.code ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
+  const reason = /credential|token|expired|AccessDenied|not authorized|Unauthorized/i.test(detail) ? "no-credentials" : "read-failed";
+  return { type, reason, detail: detail.slice(0, 200) };
+}
+
+async function getHealthCheckStatus(
+  id: string,
+  client: AwsReadClientOptions,
+  http: AwsHealthHttp,
+): Promise<CheckerObservation[]> {
+  const options = await withChainCredentials(withEndpointOverride("route53", client));
+  // Route 53 is global: one host, signed in us-east-1.
+  const base = (options.endpoint ?? "https://route53.amazonaws.com").replace(/\/$/, "");
+  const url = `${base}/2013-04-01/healthcheck/${encodeURIComponent(id)}/status`;
+  const env = options.env ?? process.env;
+  const credentials = resolveCredentials(options.credentials, env);
+  const signable = credentials && (!options.endpoint || options.signEndpointOverride === true);
+  const headers = signable
+    ? signRequest({ method: "GET", url, headers: {}, body: "", service: "route53", region: "us-east-1", credentials, ...(options.now ? { now: options.now } : {}) })
+    : {};
+  const res = await http("GET", url, { headers });
+  const err = xmlError(res.text);
+  if (err || res.status >= 400) {
+    throw new AwsReadError(err?.message ?? `GetHealthCheckStatus failed with HTTP ${res.status}`, res.status, err?.code);
+  }
+  return parseHealthCheckStatus(res.text);
+}
+
+async function describeServices(
+  cluster: string,
+  arns: string[],
+  client: AwsReadClientOptions,
+  http: AwsHealthHttp,
+): Promise<{ services: Array<EcsServiceState & { serviceArn?: string }>; failures: Array<{ arn?: string; reason?: string }> }> {
+  const options = await withChainCredentials(withEndpointOverride("ecs", client));
+  const url = serviceUrl("ecs", options.endpoint, options.region);
+  const body = JSON.stringify({ cluster, services: arns });
+  const headers = requestHeaders(
+    "ecs",
+    url,
+    body,
+    { "content-type": "application/x-amz-json-1.1", "x-amz-target": "AmazonEC2ContainerServiceV20141113.DescribeServices" },
+    options,
+  );
+  const res = await http("POST", url, { headers, body });
+  let parsed: Record<string, unknown> = {};
+  try {
+    const value: unknown = JSON.parse(res.text);
+    if (value && typeof value === "object" && !Array.isArray(value)) parsed = value as Record<string, unknown>;
+  } catch {
+    throw new AwsReadError("unparseable DescribeServices response", res.status);
+  }
+  const errType = typeof parsed.__type === "string" ? parsed.__type.split("#").pop() : undefined;
+  if (errType || res.status >= 400) {
+    const message = typeof parsed.message === "string" ? parsed.message : `DescribeServices failed with HTTP ${res.status}`;
+    throw new AwsReadError(message, res.status, errType);
+  }
+  return {
+    services: Array.isArray(parsed.services) ? (parsed.services as Array<EcsServiceState & { serviceArn?: string }>) : [],
+    failures: Array.isArray(parsed.failures) ? (parsed.failures as Array<{ arn?: string; reason?: string }>) : [],
+  };
+}
+
+export async function observeHealthAws(options: AwsHealthOptions): Promise<HealthReadResult> {
+  const http = options.http ?? defaultHttp;
+  const observedAt = (options.now?.() ?? new Date()).toISOString();
+  const client: AwsReadClientOptions = { ...(options.client ?? {}), ...(options.region ? { region: options.region } : {}) };
+  const entities: Record<string, HealthEntry> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  const absent: string[] = [];
+  if (options.entities.size === 0) return { entities, unobserved, absent };
+
+  const stackName = options.stack ?? options.environment;
+  let physical: Map<string, string>;
+  try {
+    const resources = await describeStackResources(stackName, client);
+    physical = new Map(resources.filter((r) => r.physicalId).map((r) => [r.logicalId, r.physicalId!]));
+  } catch (err) {
+    if (err instanceof AwsReadError && stackDoesNotExist(err.message)) return { entities, unobserved, absent: [...options.entities.keys()] };
+    for (const [name, { entityType }] of options.entities) {
+      unobserved[name] = holeFrom(entityType, err);
+      unobserved[name]!.detail = `DescribeStackResources failed for stack "${stackName}": ${unobserved[name]!.detail}`;
+    }
+    return { entities, unobserved, absent };
+  }
+
+  const services = new Map<string, Array<{ name: string; arn: string }>>();
+  const checks: Array<{ name: string; id: string }> = [];
+  for (const [name, { entityType }] of options.entities) {
+    const id = physical.get(name);
+    if (!id) {
+      absent.push(name);
+      continue;
+    }
+    if (entityType === "AWS::ECS::Service") {
+      const cluster = clusterOfServiceArn(id);
+      const list = services.get(cluster) ?? [];
+      list.push({ name, arn: id });
+      services.set(cluster, list);
+    } else if (entityType === "AWS::Route53::HealthCheck") {
+      checks.push({ name, id });
+    }
+  }
+
+  await Promise.all(
+    checks.map(async ({ name, id }) => {
+      try {
+        entities[name] = healthCheckEntry(await getHealthCheckStatus(id, client, http), observedAt);
+      } catch (err) {
+        if (err instanceof AwsReadError && err.code === "NoSuchHealthCheck") absent.push(name);
+        else unobserved[name] = holeFrom("AWS::Route53::HealthCheck", err);
+      }
+    }),
+  );
+
+  await Promise.all(
+    [...services].map(async ([cluster, members]) => {
+      // DescribeServices takes at most ten services per call.
+      for (let i = 0; i < members.length; i += 10) {
+        const batch = members.slice(i, i + 10);
+        try {
+          const { services: found, failures } = await describeServices(cluster, batch.map((m) => m.arn), client, http);
+          for (const member of batch) {
+            const service = found.find((s) => s.serviceArn === member.arn || s.serviceArn?.endsWith(`/${member.arn.split("/").pop()}`));
+            const failure = failures.find((f) => f.arn === member.arn);
+            if (service) entities[member.name] = ecsServiceEntry(service, observedAt);
+            else if (failure?.reason === "MISSING") absent.push(member.name);
+            else {
+              unobserved[member.name] = {
+                type: "AWS::ECS::Service",
+                reason: "read-failed",
+                detail: failure?.reason ? `DescribeServices: ${failure.reason}` : "DescribeServices did not return the service",
+              };
+            }
+          }
+        } catch (err) {
+          for (const member of batch) unobserved[member.name] = holeFrom("AWS::ECS::Service", err);
+        }
+      }
+    }),
+  );
+
+  return { entities, unobserved, absent };
+}

package/src/plugin.ts

@@ -911,6 +911,14 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
   /** The noise rules the deep pass applies to both the live and declared trees. */
   deepNormalizationHooks: awsDeepNormalizationHooks,
 
+  /** Runtime health (#4177): Route 53 health checks and ECS services. Implementation in ./health.ts. */
+  healthTypes: ["AWS::Route53::HealthCheck", "AWS::ECS::Service"],
+
+  async observeHealth(options) {
+    const { observeHealthAws } = await import("./health");
+    return observeHealthAws(options);
+  },
+
   async describeStackStatus(options: { environment: string; stack: string }): Promise<StackStatusObservation | null> {
     const { getRuntime } = await import("@intentius/chant/runtime-adapter");
     const rt = getRuntime();