@intentius/chant 0.101.0 → 0.104.0

package/src/op/activity-contract.ts

@@ -150,14 +150,22 @@ function isStepOutputRefValue(value: unknown): boolean {
   return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[STEP_OUTPUT_REF_BRAND] === true;
 }
 
-/** The value at `path` (a zod issue's `.path`) inside `obj`, or `undefined` if any segment doesn't resolve. */
-function valueAtPath(obj: unknown, path: ReadonlyArray<PropertyKey>): unknown {
+/**
+ * Does any prefix of `path` (a zod issue's `.path`) inside `obj` land on a
+ * step-output reference? A reference stands in for the whole value at its
+ * position, so an issue at or below it describes the placeholder, not the
+ * value it resolves to. "Below" matters for a whole-value reference in a
+ * record-typed arg (`inputs: step.out.json`, #3299): zod walks the
+ * reference's own keys, brand symbol included, and reports issues inside it.
+ */
+function pathCrossesStepOutputRef(obj: unknown, path: ReadonlyArray<PropertyKey>): boolean {
   let current = obj;
   for (const segment of path) {
-    if (current === null || typeof current !== "object") return undefined;
+    if (current === null || typeof current !== "object") return false;
     current = (current as Record<PropertyKey, unknown>)[segment];
+    if (isStepOutputRefValue(current)) return true;
   }
-  return current;
+  return false;
 }
 
 /** Unwrap `ZodOptional`/`ZodNullable`/`ZodDefault` (and similar) down to the schema they wrap. */
@@ -270,16 +278,18 @@ export function validateActivitySteps(
       const parsed = contract.args.safeParse(step.args ?? {});
       if (!parsed.success) {
         for (const issue of parsed.error.issues) {
-          // A step-output reference (#1290) sitting at this path is a
-          // placeholder object at build time, not the value it will
-          // resolve to — so an args-schema type mismatch here is a false
+          // A step-output reference (#1290) sitting at this path, or above
+          // it, is a placeholder object at build time, not the value it
+          // will resolve to — so an args-schema issue there is a false
           // positive; OPS013 (`validateStepOutputRefs`) is what validates
           // a reference, against the *producer's* declared return schema.
           // An unrecognized-key issue's path is the parent object (`[]`
           // for a top-level extra key), which is never itself a reference,
           // so a genuinely misspelled key is still caught either way.
-          if (isStepOutputRefValue(valueAtPath(step.args, issue.path))) continue;
-          const path = issue.path.length > 0 ? issue.path.join(".") : "(args)";
+          if (pathCrossesStepOutputRef(step.args, issue.path)) continue;
+          // String(), not join(): a zod path can hold a symbol key, and
+          // join() throws converting one (#3299).
+          const path = issue.path.length > 0 ? issue.path.map((segment) => String(segment)).join(".") : "(args)";
           issues.push({ opName: config.name, phase: phase.name, fn: step.fn, message: `args.${path}: ${issue.message}` });
         }
       }

package/src/op/builders.ts

@@ -18,6 +18,7 @@ import type { PolicyGateArgs } from "./activities/policy";
 import type { GuardValidateArgs } from "./activities/guard-validate";
 import type { WorkEvidenceArgs } from "./activities/work-evidence";
 import type { DecideArgs } from "./activities/decide";
+import type { ComposeChangeSetArgs, LifecyclePlanChangeSetArgs, ReadChangeSetPartArgs } from "./activities/change-set";
 import { isValidCronExpression, cronSyntaxMessage } from "./cron";
 
 /** An `activity()` result — the plain `ActivityStep` shape plus the `.out` reference sugar (#1290). */
@@ -398,6 +399,28 @@ export const releasePlan = (args: WithStepRefs<ReleasePlanArgs> & StepOpts): Nam
   return activity("releasePlan", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
 };
 
+/**
+ * Join members' change-set parts into one document (#3181). Its `digest` is
+ * what a combined run's gate binds: `gate("approve", { plan:
+ * changeSet.out.digest })`. Defaults to the `fastIdempotent` profile.
+ */
+export const composeChangeSet = (args: WithStepRefs<ComposeChangeSetArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("composeChangeSet", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
+/** A chant member's change-set part, from `chant lifecycle plan <env> --json` (#3181). Its `part` feeds {@link composeChangeSet}. */
+export const lifecyclePlanChangeSet = (args: WithStepRefs<LifecyclePlanChangeSetArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("lifecyclePlanChangeSet", rest, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/** A member's change-set part from a plan file a chant or warden run wrote (#3181). Its `part` feeds {@link composeChangeSet}. */
+export const readChangeSetPart = (args: WithStepRefs<ReadChangeSetPartArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("readChangeSetPart", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
 /**
  * Record a release in the release ledger with its plan (#2782, ws-055), once:
  * a retry whose release the ledger already names records nothing. Defaults to

package/src/op/composites/apply-op.ts

@@ -10,8 +10,11 @@
  * the ownership tag on `arm` (chant #1448 — previously `--mode Complete`, which
  * removed resources chant never applied), the ownership label on `gcp`
  * (chant #1449), the metadata marker (machines) and managed app
- * (volumes/ips/certs/secrets) on `fly` (chant #1449), and the stack itself on
- * `cloudformation`, which a resource CFN did not create is not in. All of
+ * (volumes/ips/certs/secrets) on `fly` (chant #1449), the ownership labels on
+ * `grafana` (chant #3011), the comment marker on `clickhouse` (chant #3208)
+ * and `postgres` (chant #3280),
+ * and the stack itself on `cloudformation`, which a
+ * resource CFN did not create is not in. All of
  * them are owned-only. See {@link DeleteMode}.
  *
  * A gate is a fact, not a wait (#2119): the local executor reads the gate
@@ -52,14 +55,18 @@ import { defaultOutput, hasNativeRollback, type ApplyTarget, type DeleteMode } f
 export interface ApplyOpConfig {
   /** Op name (kebab-case). */
   name: string;
-  /** Environment — CFN stack name / ARM resource group / kube context env;
-   * a log label on `gcp` and `fly`. */
+  /** Environment — CFN stack name / ARM resource group / kube context env /
+   * the `grafana.profiles.<env>` entry on `grafana` / the `sql.profiles.<env>`
+   * entry on `clickhouse` and `postgres`; a log label on `gcp` and
+   * `fly`. */
   env: string;
   /** Native apply mechanism. Default: "kubectl". */
   target?: ApplyTarget;
   /** Built manifest/template path. Default per target: `dist` (dir) for kubectl,
    * `template.json` (file) for CloudFormation/ARM, `dist/gcp.yaml` for gcp,
-   * `dist/fly.json` for fly. Must match your build output. */
+   * `dist/fly.json` for fly, `dist/grafana.json` (the build index) for
+   * grafana, `dist/schema.json` for clickhouse and postgres. Must match your
+   * build output. */
   output?: string;
   /** Project directory to build. Default: ".". */
   path?: string;

package/src/op/composites/composites.test.ts

@@ -157,6 +157,33 @@ describe("ApplyOp: shape", () => {
     expect(applyStep.fn).toBe("nativeApply");
     expect(applyStep.args).toEqual({ target: "kubectl", env: "prod", output: "dist", deleteMode: "never" });
   });
+
+  test("target clickhouse applies the sql build output, dist/schema.json by default (#3208)", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "clickhouse", delete: "owned-only" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const applyStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(applyStep.fn).toBe("nativeApply");
+    expect(applyStep.args).toEqual({ target: "clickhouse", env: "prod", output: "dist/schema.json", deleteMode: "owned-only" });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
+
+  test("target postgres applies the sql build output, dist/schema.json by default (#3280)", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "postgres", delete: "owned-only" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const applyStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(applyStep.fn).toBe("nativeApply");
+    expect(applyStep.args).toEqual({ target: "postgres", env: "prod", output: "dist/schema.json", deleteMode: "owned-only" });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
+
+  test("target grafana applies the build index, dist/grafana.json by default (#3011)", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "grafana", delete: "owned-only" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const applyStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(applyStep.fn).toBe("nativeApply");
+    expect(applyStep.args).toEqual({ target: "grafana", env: "prod", output: "dist/grafana.json", deleteMode: "owned-only" });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
 });
 
 describe("ApplyOp: gating + deletes", () => {
@@ -274,7 +301,7 @@ describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {
   });
 
   test("compensate: true is refused at build time for every rollback-less target (#1449)", () => {
-    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly"] as const) {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "grafana", "clickhouse", "postgres"] as const) {
       expect(() => ApplyOp({ name: "p", env: "prod", target, compensate: true })).toThrow(
         new RegExp(`ApplyOp "p": compensate is enabled, but target "${target}" has no automatic rollback`),
       );
@@ -296,7 +323,7 @@ describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {
   });
 
   test("an object without a command is refused the same way as true", () => {
-    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly"] as const) {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "grafana", "clickhouse", "postgres"] as const) {
       expect(() => ApplyOp({ name: "p", env: "prod", target, compensate: {} })).toThrow(
         /has no automatic rollback/,
       );
@@ -304,7 +331,7 @@ describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {
   });
 
   test("a command lifts the refusal on every target", () => {
-    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "cloudformation"] as const) {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "grafana", "clickhouse", "postgres", "cloudformation"] as const) {
       const { op } = ApplyOp({
         name: "p",
         env: "prod",

package/src/op/composites/lexicon-upgrade-op.test.ts

@@ -49,17 +49,22 @@ describe("LexiconUpgradeOp composite (#527)", () => {
     expect(phases[0].steps[0].outcomeAttribute).toEqual({ name: "HasUpgrade", from: "hasUpgrade" });
   });
 
-  test("in-scope set is exactly the 9 lexicons (helm/forgejo excluded)", () => {
+  test("known set is exactly the 11 lexicons (helm/forgejo excluded)", () => {
     // cedar joined with #1650: it pins `CEDAR_WASM_VERSION`, a dependency
     // rather than a downloaded spec, but the pinned-constant machinery the Op
     // drives is identical. helm/forgejo still have no upstream at all.
     expect([...IN_SCOPE_LEXICONS].sort()).toEqual(
-      ["aws", "azure", "cedar", "docker", "fly", "gcp", "github", "gitlab", "k8s"].sort(),
+      ["aws", "azure", "cedar", "docker", "fly", "gcp", "github", "gitlab", "k3s", "k8s", "sql"].sort(),
     );
     expect(IN_SCOPE_LEXICONS).not.toContain("helm");
     expect(IN_SCOPE_LEXICONS).not.toContain("forgejo");
   });
 
+  test("accepts a pinned lexicon by name, discovered at run time", () => {
+    expect(() => LexiconUpgradeOp({ lexicon: "sql" })).not.toThrow();
+    expect(() => LexiconUpgradeOp({ lexicon: "k3s" })).not.toThrow();
+  });
+
   test("rejects out-of-scope lexicons at construction", () => {
     for (const l of ["helm", "forgejo"]) {
       expect(() => LexiconUpgradeOp({ lexicon: l as never })).toThrow(/not in scope/);

package/src/op/composites/lexicon-upgrade-op.ts

@@ -13,9 +13,13 @@
  * lands on the Op itself (#2120).
  *
  * Lexicon classification (which check the activity dispatches to):
- *   PINNED  {k8s, gcp, docker, gitlab} → checkPinnedUpgrade
- *   ROLLING {aws, azure, github}       → checkRollingUpgrade
- * helm / forgejo are excluded — no upstream spec.
+ *   ROLLING {aws, azure, github, fly}  → checkRollingUpgrade
+ *   PINNED  any other lexicon whose plugin declares `upstreamPin`
+ *           (k8s, k3s, gcp, docker, gitlab, cedar, sql, ...) → checkPinnedUpgrade
+ * The pinned set is discovered from the plugin at run time, the way `chant dev
+ * pinned-upgrade` does. A pin that moves with other constants (`alsoMoves`, as
+ * sql's version plus digest) is report-only. helm / forgejo are excluded: no
+ * upstream spec.
  *
  * Finding-modes mirror ReconcileOp: `report` (default, no external services)
  * | `issue` | `pull-request`. For the epic goal, `pull-request` opens/updates a
@@ -43,9 +47,15 @@ import { Op, phase } from "../builders";
 import type { OpResource } from "../resource";
 import type { LexiconUpgradeMode, SupportedLexicon } from "../activities/lexicon-upgrade";
 
-/** The in-scope lexicons. helm / forgejo are excluded (no upstream spec). */
+/**
+ * The lexicons known to be in scope. This is not a gate: a lexicon that declares
+ * `upstreamPin` is dispatched without being listed. helm / forgejo are excluded
+ * (no upstream spec).
+ */
 export const IN_SCOPE_LEXICONS: readonly SupportedLexicon[] = [
   "k8s",
+  "k3s",
+  "sql",
   "gcp",
   "docker",
   "gitlab",
@@ -74,6 +84,12 @@ export interface LexiconUpgradeOpConfig {
    * `<cwd>/lexicons/<lexicon>` at run time.
    */
   lexiconDir?: string;
+  /**
+   * Label of one pin to check, for a lexicon whose plugin declares several
+   * (`upstreamPins`; sql has `clickhouse` and `postgres-14` to `postgres-18`).
+   * Omit to check every pin.
+   */
+  pin?: string;
   /**
    * What to produce on findings. Default: "report".
    * @default "report"
@@ -86,15 +102,19 @@ export interface LexiconUpgradeOpResources {
   op: InstanceType<typeof OpResource>;
 }
 
+const EXCLUDED_LEXICONS: ReadonlySet<string> = new Set(["helm", "forgejo"]);
+
 /**
- * Build a LexiconUpgradeOp for one lexicon. Rejects out-of-scope lexicons at
- * construction time so a typo never silently produces a no-op Op.
+ * Build a LexiconUpgradeOp for one lexicon. Rejects the lexicons with no
+ * upstream spec at construction time. Whether any other name declares a pin is
+ * only known by loading its plugin, so the activity checks that at run time and
+ * fails with a clear message for a name that has none.
  */
 export function LexiconUpgradeOp(config: LexiconUpgradeOpConfig): LexiconUpgradeOpResources {
-  if (!IN_SCOPE_LEXICONS.includes(config.lexicon)) {
+  if (EXCLUDED_LEXICONS.has(config.lexicon)) {
     throw new Error(
       `LexiconUpgradeOp: "${config.lexicon}" is not in scope. ` +
-        `In-scope lexicons: ${IN_SCOPE_LEXICONS.join(", ")} ` +
+        `Known lexicons: ${IN_SCOPE_LEXICONS.join(", ")}, and any lexicon declaring upstreamPin ` +
         `(helm, forgejo have no upstream spec).`,
     );
   }
@@ -119,6 +139,7 @@ export function LexiconUpgradeOp(config: LexiconUpgradeOpConfig): LexiconUpgrade
           args: {
             lexicon: config.lexicon,
             ...(config.lexiconDir ? { lexiconDir: config.lexiconDir } : {}),
+            ...(config.pin ? { pin: config.pin } : {}),
             mode: onFinding,
           },
           // Surface whether a PR-worthy upgrade was found as the run's

package/src/op/decide-backend.ts

@@ -6,9 +6,13 @@
  * POST <url>/v1/systemone          Authorization: Bearer <key>
  * { "model": "jev-1.13.0", "state": {...}, "questions": { "<name>": { "type": "noul" | "choice" | "score", "instructions": ..., "criteria": ... } } }
  *
- * { "model": "jev-1.13.0", "answers": { "<name>": { "type": "noul", "noul": 0.22 } | { "type": "choice", "choice": ..., "probabilities": {...}, "confidence": ... } | { "type": "score", ... } } }
+ * { "model": "jev-1.13.0", "answers": { "<name>": { "type": "noul", "noul": 0.22, "reason"?: ... } | { "type": "choice", "choice": ..., "probabilities": {...}, "confidence": ..., "reason"?: ... } | { "type": "score", ..., "reason"?: ... } } }
  * ```
  *
+ * `reason` is optional: the model's own explanation of its answer (#3345).
+ * Core keeps it in the answer record beside a proposal, or as `model_reason`
+ * in the escalation entry of an answer below the threshold.
+ *
  * {@link backendAsk} turns a set of backends into core's `ModelAsk`, the
  * model call `askPoint` takes (`../workspace/points.ts`). This file
  * only speaks the wire format: whether an answer is observed, proposed or

package/src/op/decide-read-inputs.ts

@@ -10,10 +10,12 @@
  *
  * Read by id or name here:
  *
- *   record, decision, work-item   a record, by id, from the declared record kinds (`records --json`)
+ *   record, decision, work-item   a record, by id, from the declared record kinds (`records --json`);
+ *                                 a work item also has its size, `criteria`, `files`, `words` and
+ *                                 `fits_<tier>`, for the slice-tier point (`../workspace/work-size.ts`, #3150)
  *   member                        a member, by name (`ls --json`)
  *
- * The other outputs a point may name (finding, region, commit, gate, release,
+ * The other outputs a point may name (finding, region, commit, node, gate, release,
  * environment, component) are passed in `inputs`, as the output printed them.
  * These reads never call a model, and never write. The module loads code
  * under `workspace/`, so the `decide` activity imports it on first call.
@@ -22,6 +24,11 @@
 import { declaredKindFiles, queryDeclaredRecords } from "../workspace/records-cli";
 import { listWorkspace } from "../workspace/ls";
 import { inputOutput } from "../workspace/points";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { bodyText, loadRecordKind } from "../workspace/records";
+import { locateWorkspace } from "../workspace/which-chant";
+import { DEFAULT_TIER_LIMITS, measureWorkItem, sizeFields } from "../workspace/work-size";
 
 /** The outputs {@link readInputs} reads by id or name. */
 export const READABLE_OUTPUTS = ["record", "decision", "work-item", "member"] as const;
@@ -45,19 +52,40 @@ export function fieldOf(value: unknown, path: string): unknown {
 }
 
 async function readRecord(id: string, cwd: string, output: string): Promise<Record<string, unknown>> {
-  const set = await queryDeclaredRecords(declaredKindFiles(cwd), { cwd });
+  const files = declaredKindFiles(cwd);
+  const set = await queryDeclaredRecords(files, { cwd });
   const unread: string[] = [];
-  for (const doc of set.kinds) {
+  for (const [i, doc] of set.kinds.entries()) {
     if ("error" in doc) {
       unread.push(`${doc.declared.path}: ${doc.error.code}`);
       continue;
     }
     const found = doc.records.find((r) => r.id === id);
-    if (found) return found as unknown as Record<string, unknown>;
+    if (found) {
+      const record = found as unknown as Record<string, unknown>;
+      // A work item's size, for the slice-tier point (#3150): criteria, files, words and fits_<tier>.
+      return output === "work-item" ? { ...record, ...(await workItemSizeFields(files[i].file, found.path, found.data, cwd)) } : record;
+    }
   }
   throw new InputReadError(`no declared record kind holds a record with id ${id} (read for ${output})${unread.length ? `; not read: ${unread.join(", ")}` : ""}`);
 }
 
+/** The size fields of a work item of the kind at `kindFile`, measured from its record file. Empty for a kind with no work block. */
+async function workItemSizeFields(kindFile: string, path: string, data: Record<string, unknown> | null, cwd: string): Promise<Record<string, unknown>> {
+  const loaded = await loadRecordKind(kindFile, cwd);
+  const work = loaded.kind.work;
+  if (!work) return {};
+  const located = locateWorkspace(cwd);
+  let body = "";
+  try {
+    body = bodyText(readFileSync(join(located.top ?? located.rootOnDisk, ...path.split("/")), "utf-8"));
+  } catch {
+    // A record that can't be read again is measured from its front matter alone.
+  }
+  const size = measureWorkItem(data, body, work.acceptance?.field ?? "acceptance");
+  return sizeFields(size, work.tier?.limits ?? DEFAULT_TIER_LIMITS);
+}
+
 function readMember(name: string, cwd: string): Record<string, unknown> {
   const doc = listWorkspace({ cwd });
   if ("error" in doc) throw new InputReadError(`the workspace can't be listed: ${doc.error.code}: ${doc.error.message}`);

package/src/op/emulator-lifecycle.test.ts

@@ -39,3 +39,26 @@ describe("emulatorLifecycle command builders", () => {
     expect(emu.endpoint(4599)).toBe("http://localhost:4599");
   });
 });
+
+describe("an emulator reached by its own client, not over HTTP", () => {
+  const pg = emulatorLifecycle({
+    name: "chant-postgres",
+    image: "postgres:18",
+    containerPort: 5432,
+    readyCommand: ["pg_isready", "-h", "127.0.0.1"],
+    endpoint: (port) => `postgres://postgres@localhost:${port}/postgres`,
+  });
+
+  test("readiness is a command run in the container", () => {
+    expect(pg.readyExecCommand("chant-postgres")).toBe("docker exec chant-postgres pg_isready -h 127.0.0.1");
+    expect(emulatorLifecycle({ name: "x", image: "x:1", containerPort: 1, healthPath: "/h" }).readyExecCommand("x")).toBeUndefined();
+  });
+
+  test("the endpoint is the declared one, not an http URL", () => {
+    expect(pg.endpoint(55432)).toBe("postgres://postgres@localhost:55432/postgres");
+  });
+
+  test("a spec with neither a health path nor a ready command is refused", () => {
+    expect(() => emulatorLifecycle({ name: "x", image: "x:1", containerPort: 1 })).toThrow(/neither a healthPath nor a readyCommand/);
+  });
+});

package/src/op/emulator-lifecycle.ts

@@ -16,8 +16,25 @@ export interface EmulatorSpec {
   image: string;
   /** Port the emulator listens on inside the container (e.g. 4566, 4280). */
   containerPort: number;
-  /** Health path on the host port (e.g. `/_localstack/health`, `/_mudflaps/health`). */
-  healthPath: string;
+  /**
+   * Health path on the host port (e.g. `/_localstack/health`, `/_mudflaps/health`).
+   * Required unless {@link readyCommand} is set: an emulator is reached over
+   * HTTP or checks itself inside its container, one or the other.
+   */
+  healthPath?: string;
+  /**
+   * A command run inside the container (`docker exec <name> ...`) whose exit
+   * status 0 means ready, for an emulator with no HTTP health endpoint: a
+   * database server answers its own client (`pg_isready`), not a URL. When
+   * set, it replaces the HTTP poll of {@link healthPath}.
+   */
+  readyCommand?: readonly string[];
+  /**
+   * The endpoint a tool connects to, for an emulator that is not reached over
+   * HTTP, e.g. a `postgres://` URL for a database server.
+   * Default: `http://localhost:<port>`.
+   */
+  endpoint?: (port: number) => string;
   /** Readiness predicate over the health body. Default: any 200 response is ready. */
   ready?: (healthBody: string) => boolean;
   /** Extra `docker run` args inserted before the image (e.g. a socket mount). */
@@ -102,6 +119,8 @@ export interface EmulatorLifecycle {
   existsCommand(name: string): string;
   rmCommand(name: string): string;
   healthUrl(port: number): string;
+  /** `docker exec <name> <readyCommand...>`, or undefined for an emulator polled over HTTP. */
+  readyExecCommand(name: string): string | undefined;
   endpoint(port: number): string;
   up(args?: EmulatorUpArgs, signal?: AbortSignal): Promise<{ endpoint: string }>;
   down(args?: { name?: string }, signal?: AbortSignal): Promise<void>;
@@ -116,6 +135,9 @@ export interface EmulatorLifecycle {
  */
 export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
   const ready = spec.ready ?? (() => true);
+  if (spec.healthPath === undefined && !spec.readyCommand?.length) {
+    throw new Error(`emulator "${spec.name}" declares neither a healthPath nor a readyCommand, so nothing can tell when it is ready`);
+  }
 
   const runCommand = (args: EmulatorUpArgs = {}): string => {
     const name = args.name ?? spec.name;
@@ -128,8 +150,30 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
   };
   const existsCommand = (name: string): string => `docker ps -q -f name=${name}`;
   const rmCommand = (name: string): string => `docker rm -f ${name}`;
-  const healthUrl = (port: number): string => `http://localhost:${port}${spec.healthPath}`;
-  const endpoint = (port: number): string => `http://localhost:${port}`;
+  const healthUrl = (port: number): string => `http://localhost:${port}${spec.healthPath ?? ""}`;
+  const endpoint = (port: number): string => (spec.endpoint ? spec.endpoint(port) : `http://localhost:${port}`);
+  const readyExecCommand = (name: string): string | undefined =>
+    spec.readyCommand?.length ? ["docker", "exec", name, ...spec.readyCommand].join(" ") : undefined;
+
+  /** One readiness probe: the in-container command when declared, else the HTTP health path. */
+  async function probe(name: string, port: number, signal?: AbortSignal): Promise<boolean> {
+    const command = readyExecCommand(name);
+    if (command) {
+      try {
+        await execAsync(command, { signal });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    try {
+      const res = await fetch(healthUrl(port), { signal });
+      return res.ok && ready(await res.text());
+    } catch {
+      // Not up yet (connection refused / non-2xx) — retry.
+      return false;
+    }
+  }
 
   async function up(args: EmulatorUpArgs = {}, signal?: AbortSignal): Promise<{ endpoint: string }> {
     const name = args.name ?? spec.name;
@@ -153,19 +197,13 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
       await execAsync(runCommand({ ...args, name, port }), { signal });
     }
 
-    const url = healthUrl(port);
     const deadline = Date.now() + timeoutMs;
     let ok = false;
     while (Date.now() < deadline) {
       if (signal?.aborted) throw new Error(`emulator "${name}" wait aborted`);
-      try {
-        const res = await fetch(url, { signal });
-        if (res.ok && ready(await res.text())) {
-          ok = true;
-          break;
-        }
-      } catch {
-        // Not up yet (connection refused / non-2xx) — retry.
+      if (await probe(name, port, signal)) {
+        ok = true;
+        break;
       }
       await sleep(intervalMs, signal);
     }
@@ -187,5 +225,5 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
     }
   }
 
-  return { runCommand, existsCommand, rmCommand, healthUrl, endpoint, up, down };
+  return { runCommand, existsCommand, rmCommand, healthUrl, readyExecCommand, endpoint, up, down };
 }