@intentius/chant 0.124.32 → 0.124.33

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 };
+}

package/src/lexicon.ts

@@ -78,6 +78,15 @@ export type {
   UnobservedReason,
 } from "./observation";
 
+// The runtime-health contract (#4177), re-exported so a lexicon's
+// `observeHealth` types itself from the same entry.
+export type {
+  HealthEntry,
+  HealthReadOptions,
+  HealthReadResult,
+  HealthState,
+} from "./health";
+
 // The identity contract (#1982), re-exported from the same entry so a
 // lexicon's `describeIdentity` types itself without a second import path.
 // Runtime helpers live in `@intentius/chant/identity`.
@@ -691,7 +700,19 @@ export type OpFindingMode = "report" | "issue" | "comment" | "pull-request" | "m
 export type OpTrigger =
   | { kind: "cron"; schedule: string }
   | { kind: "pull_request"; branches?: string[] }
-  | { kind: "push"; branches?: string[] };
+  | {
+      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
@@ -1799,6 +1820,25 @@ export interface LexiconPlugin {
     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").HealthReadOptions): Promise<import("./health").HealthReadResult>;
+
   /**
    * This lexicon's noise rules for deep observation (#1014): which fields are
    * read-only / server-populated / controller-managed / provider-defaulted, and

package/src/lifecycle/merge-record.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Merge records (#4168 step 1) against temp git repos: written under the
+ * commit on chant/lifecycle, rewritten only when the record changed, read
+ * back, and validated against the schema; and where the change came from.
+ */
+
+import { describe, expect, test } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { MERGE_RECORD_CONTRACT, MERGE_RECORD_SCHEMA_ID, MERGES_DIR, mergeRecordFile, mergeSourceOf, readMergeRecord, writeMergeRecord, type MergeRecord } from "./merge-record";
+import { contract, validSchema } from "../workspace/__fixtures__/contract-repo";
+import schema from "../workspace/merge-record.schema.json";
+
+const { expectValid } = contract(schema);
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+function initRepo(dir: string): string {
+  git(dir, "init", "-q", "-b", "main");
+  git(dir, "config", "user.email", "test@chant.dev");
+  git(dir, "config", "user.name", "Test");
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  return git(dir, "rev-parse", "HEAD");
+}
+
+const record = (commit: string, over: Partial<MergeRecord> = {}): MergeRecord => ({
+  $schema: MERGE_RECORD_SCHEMA_ID,
+  contract: MERGE_RECORD_CONTRACT,
+  commit,
+  base: "b".repeat(40),
+  env: "prod",
+  source: { kind: "pull-request", pr: 12 },
+  op: "pr-12",
+  gate: "pr-apply",
+  digest: `jcs1-sha256:${"1".repeat(64)}`,
+  plan: "approved",
+  approvedBy: ["github:rev"],
+  components: ["net", "app"],
+  recordedAt: "2026-10-20T00:00:00.000Z",
+  ...over,
+});
+
+describe("the merge record schema", () => {
+  test("is a valid schema and names this module's id", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(MERGE_RECORD_SCHEMA_ID);
+  });
+
+  test("each source and plan status validates", () => {
+    const sha = "a".repeat(40);
+    expectValid(record(sha));
+    expectValid(record(sha, { source: { kind: "work-item", records: [{ kind: "work", id: "w-7" }] }, op: null, plan: "unapproved", approvedBy: [] }));
+    expectValid(record(sha, { source: { kind: "direct-push" }, op: null, digest: null, plan: "nothing", approvedBy: [], components: [] }));
+    expectValid(record(sha, { plan: "changed", approvedDigest: `jcs1-sha256:${"9".repeat(64)}`, approvedBy: [], authorApproved: ["github:carol"], member: "net" }));
+  });
+});
+
+describe("writeMergeRecord and readMergeRecord", () => {
+  test("writes the record under its commit, leaves the same record alone, and replaces a changed one", async () => {
+    await withTestDir(async (dir) => {
+      const sha = initRepo(dir);
+      expect(await readMergeRecord(sha, { cwd: dir })).toBeNull();
+      expect((await writeMergeRecord(record(sha), { cwd: dir })).written).toBe(true);
+      expect(git(dir, "ls-tree", "--name-only", `chant/lifecycle:${MERGES_DIR}`)).toBe(mergeRecordFile(sha));
+      expect(await readMergeRecord(sha, { cwd: dir })).toEqual(record(sha));
+
+      // The record job ran again: only the time differs, so nothing is written.
+      const tip = git(dir, "rev-parse", "chant/lifecycle");
+      expect((await writeMergeRecord(record(sha, { recordedAt: "2026-10-21T00:00:00.000Z" }), { cwd: dir })).written).toBe(false);
+      expect(git(dir, "rev-parse", "chant/lifecycle")).toBe(tip);
+
+      // A plan that moved since is a new record for the same commit.
+      const moved = record(sha, { plan: "changed", approvedDigest: `jcs1-sha256:${"9".repeat(64)}`, approvedBy: [] });
+      expect((await writeMergeRecord(moved, { cwd: dir })).written).toBe(true);
+      expect(await readMergeRecord(sha, { cwd: dir })).toEqual(moved);
+    });
+  });
+
+  test("a member's record sits under its own prefix", async () => {
+    await withTestDir(async (dir) => {
+      const sha = initRepo(dir);
+      await writeMergeRecord(record(sha, { member: "net" }), { cwd: dir, member: "net" });
+      expect(git(dir, "ls-tree", "-r", "--name-only", "chant/lifecycle")).toBe(`_members/net/${MERGES_DIR}/${mergeRecordFile(sha)}`);
+      expect(await readMergeRecord(sha, { cwd: dir, member: "net" })).toMatchObject({ member: "net" });
+      expect(await readMergeRecord(sha, { cwd: dir })).toBeNull();
+    });
+  });
+});
+
+describe("mergeSourceOf", () => {
+  test("a pull request first, then the work items a commit's trailers name, then a direct push", async () => {
+    await withTestDir(async (dir) => {
+      const plain = initRepo(dir);
+      expect(mergeSourceOf(dir, plain, 12)).toEqual({ kind: "pull-request", pr: 12 });
+      expect(mergeSourceOf(dir, plain, null)).toEqual({ kind: "direct-push" });
+      writeFileSync(join(dir, "a.txt"), "a\n");
+      git(dir, "add", ".");
+      git(dir, "commit", "-q", "-m", "carry out w-7\n\nChant-Record: work:w-7\nChant-Record: decision:d-1\nChant-Record: work:w-8\nChant-Record: work:w-7");
+      expect(mergeSourceOf(dir, git(dir, "rev-parse", "HEAD"), null)).toEqual({ kind: "work-item", records: [{ kind: "work", id: "w-7" }, { kind: "work", id: "w-8" }] });
+      expect(mergeSourceOf(dir, "f".repeat(40), null)).toEqual({ kind: "direct-push" });
+    });
+  });
+});