@intentius/chant 0.124.31 → 0.124.33

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-module.d.ts

@@ -97,6 +97,9 @@ export declare function resetLexiconModules(): void;
  * `typeScript: false` imports it with plain node, without registering tsx
  * (#3276): tsx's ESM hooks run on a thread of their own, which costs the
  * compiled CLI about 200 MB, so a caller whose module is JavaScript says so.
+ * Left out, the module's extension decides (#3981): a `.js` or `.mjs` module
+ * imports with plain node, and anything else (`.ts`, or no extension, which
+ * only tsx's resolver completes) registers tsx first.
  */
 export declare function importLexiconModule(name: string, options?: {
     typeScript?: boolean;
@@ -133,6 +136,13 @@ export declare function resolveFromProject(spec: string, fromDir?: string): stri
  * that installs its lexicons in its own node_modules, it is resolved from
  * `fromDir` (the project) and imported from there. Any other failure, and a
  * package the project doesn't have either, rethrows the first error.
+ *
+ * #3981 — tsx is registered only when the module resolves to TypeScript. A
+ * lexicon that ships compiled JS imports with plain node. The module is
+ * resolved before it is imported, because a failed import is cached: one
+ * tried without tsx cannot be tried again with it. A resolution that fails
+ * for any reason but a missing package registers tsx, whose resolver may
+ * still complete it.
  */
 export declare function importLexiconPackage(spec: string, fromDir?: string): Promise<Record<string, unknown>>;
 //# sourceMappingURL=lexicon-module.d.ts.map

package/dist/lexicon-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lexicon-module.d.ts","sourceRoot":"","sources":["../src/lexicon-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F,mEAAmE;AACnE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAExE;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,EAAE,CAAC;AAC/E,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAiBvG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACxC,OAAO,EAAE,MAAM,EACf,SAAS,SAAM,GACd;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAgBrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,EAClD,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3G;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5D;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAElE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAY9C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAsB,EAC/B,KAAK,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAe,GAC/C,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAe,GAC/C,MAAM,EAAE,CAEV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI9D;AAUD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,MAAM,GAAG,SAAS,CAMpG;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAW1H"}
+{"version":3,"file":"lexicon-module.d.ts","sourceRoot":"","sources":["../src/lexicon-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AASH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F,mEAAmE;AACnE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAExE;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,EAAE,CAAC;AAC/E,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAiBvG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACxC,OAAO,EAAE,MAAM,EACf,SAAS,SAAM,GACd;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAgBrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,EAClD,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AAMD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3G;AAED,2DAA2D;AAC3D,wBAAgB,sBAAsB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5D;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAElE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAa9C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAsB,EAC/B,KAAK,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAe,GAC/C,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAe,GAC/C,MAAM,EAAE,CAEV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI9D;AAUD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,MAAM,GAAG,SAAS,CAMpG;AAcD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqB1H"}

package/dist/lexicon-module.js

@@ -26,8 +26,9 @@
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
-import { ensureTypeScriptLoader } from "./ts-loader.js";
+import { ensureTypeScriptLoader, ensureTypeScriptLoaderFor, typeScriptLoaderPending } from "./ts-loader.js";
 import { esModuleNamespace } from "./module-interop.js";
+import { isJavaScriptModule } from "./module-source.js";
 /** The lexicon name an entry declares, whichever form it takes. */
 export function lexiconDeclarationName(entry) {
     return typeof entry === "string" ? entry : entry.name;
@@ -154,13 +155,17 @@ export function resetLexiconModules() {
  * `typeScript: false` imports it with plain node, without registering tsx
  * (#3276): tsx's ESM hooks run on a thread of their own, which costs the
  * compiled CLI about 200 MB, so a caller whose module is JavaScript says so.
+ * Left out, the module's extension decides (#3981): a `.js` or `.mjs` module
+ * imports with plain node, and anything else (`.ts`, or no extension, which
+ * only tsx's resolver completes) registers tsx first.
  */
 export async function importLexiconModule(name, options = {}) {
     const path = modulePaths.get(name);
     if (path === undefined)
         return undefined;
     try {
-        if (options.typeScript !== false)
+        const typeScript = options.typeScript ?? !isJavaScriptModule(path);
+        if (typeScript)
             ensureTypeScriptLoader();
         return esModuleNamespace((await import(path)));
     }
@@ -221,6 +226,19 @@ export function resolveFromProject(spec, fromDir = process.cwd()) {
         return undefined;
     }
 }
+/**
+ * #3981 — where `spec` resolves from this module, as `import(spec)` here
+ * would resolve it. Throws as the import would when it cannot be resolved.
+ * An absolute path is its own file URL.
+ */
+function resolveImport(spec) {
+    if (isAbsolute(spec))
+        return pathToFileURL(spec).href;
+    const resolveMeta = import.meta.resolve;
+    if (typeof resolveMeta === "function")
+        return resolveMeta(spec);
+    return pathToFileURL(createRequire(import.meta.url).resolve(spec)).href;
+}
 /**
  * chant#2845 — import a lexicon package, or one of its subpaths, by its bare
  * specifier. chant's own install is tried first, as a bare `import()` always
@@ -229,19 +247,46 @@ export function resolveFromProject(spec, fromDir = process.cwd()) {
  * that installs its lexicons in its own node_modules, it is resolved from
  * `fromDir` (the project) and imported from there. Any other failure, and a
  * package the project doesn't have either, rethrows the first error.
+ *
+ * #3981 — tsx is registered only when the module resolves to TypeScript. A
+ * lexicon that ships compiled JS imports with plain node. The module is
+ * resolved before it is imported, because a failed import is cached: one
+ * tried without tsx cannot be tried again with it. A resolution that fails
+ * for any reason but a missing package registers tsx, whose resolver may
+ * still complete it.
  */
 export async function importLexiconPackage(spec, fromDir = process.cwd()) {
+    const pkg = packageNameOf(spec);
+    if (typeScriptLoaderPending()) {
+        let resolved;
+        try {
+            resolved = resolveImport(spec);
+        }
+        catch (err) {
+            if (pkg === undefined || !isPackageNotFound(err, pkg)) {
+                ensureTypeScriptLoader();
+            }
+            else {
+                return importFromProject(spec, fromDir, err);
+            }
+        }
+        if (resolved !== undefined)
+            ensureTypeScriptLoaderFor(resolved);
+    }
     try {
-        ensureTypeScriptLoader();
         return esModuleNamespace((await import(spec)));
     }
     catch (err) {
-        const pkg = packageNameOf(spec);
         if (pkg === undefined || !isPackageNotFound(err, pkg))
             throw err;
-        const resolved = resolveFromProject(spec, fromDir);
-        if (resolved === undefined)
-            throw err;
-        return esModuleNamespace((await import(pathToFileURL(resolved).href)));
+        return importFromProject(spec, fromDir, err);
     }
 }
+/** The project's copy of `spec`, for {@link importLexiconPackage}. Rethrows `err` when the project has none. */
+async function importFromProject(spec, fromDir, err) {
+    const resolved = resolveFromProject(spec, fromDir);
+    if (resolved === undefined)
+        throw err;
+    ensureTypeScriptLoaderFor(resolved);
+    return esModuleNamespace((await import(pathToFileURL(resolved).href)));
+}

package/dist/lexicon-plugin-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lexicon-plugin-helpers.d.ts","sourceRoot":"","sources":["../src/lexicon-plugin-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI/C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG;IAC7D,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,aAAa,EAAE,GACrB,MAAM,eAAe,EAAE,CAYzB;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,mBAAmB,CAsBrB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAClB,uBAAuB,CAmBzB"}
+{"version":3,"file":"lexicon-plugin-helpers.d.ts","sourceRoot":"","sources":["../src/lexicon-plugin-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI/C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG;IAC7D,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,aAAa,EAAE,GACrB,MAAM,eAAe,EAAE,CAazB;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,mBAAmB,CAsBrB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAClB,uBAAuB,CAoBzB"}

package/dist/lexicon-plugin-helpers.js

@@ -6,8 +6,8 @@
  * MCP diff tool, and MCP catalog resource.
  */
 import { readFileSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { join } from "path";
+import { moduleSourceDir } from "./module-source.js";
 /**
  * Create a skills loader that reads .md files from a lexicon's skills directory.
  *
@@ -25,7 +25,8 @@ import { fileURLToPath } from "url";
  */
 export function createSkillsLoader(importMetaUrl, specs) {
     return () => {
-        const skillsDir = join(dirname(fileURLToPath(importMetaUrl)), "skills");
+        // Skills are markdown beside the source; a compiled plugin finds them under src/ (#3981).
+        const skillsDir = join(moduleSourceDir(importMetaUrl), "skills");
         return specs.map(({ file, ...meta }) => {
             try {
                 const content = readFileSync(join(skillsDir, file), "utf-8");
@@ -91,7 +92,8 @@ export function createCatalogResource(importMetaUrl, name, description, lexiconJ
         description,
         mimeType: "application/json",
         async handler() {
-            const dir = dirname(fileURLToPath(importMetaUrl));
+            // Generated JSON sits beside the source; a compiled plugin finds it under src/ (#3981).
+            const dir = moduleSourceDir(importMetaUrl);
             const lexicon = JSON.parse(readFileSync(join(dir, "generated", lexiconJsonFile), "utf-8"));
             const entries = Object.entries(lexicon).map(([className, entry]) => ({
                 className,

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";
@@ -470,6 +471,8 @@ export interface ComponentPipelineOptions {
      * `wave-<k>` runs `chant components fan-out --wave-gate <gate> --wave <k>`
      * and hands the attempt record to the next job. See
      * `components/gated-wave-pipeline.ts`. Unset, the pipeline is unchanged.
+     * Beside `prLoop` (#4003) it gives the pull request's apply a gate per
+     * wave instead: one apply job per wave (`prLoopWithWaves`).
      */
     gatedWaves?: GatedWavePipelineOptions;
     /**
@@ -587,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
@@ -1615,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