@intentius/chant 0.57.0 → 0.59.0

package/src/op/activity-profiles.ts

@@ -0,0 +1,116 @@
+/**
+ * Activity timeout and retry profiles.
+ *
+ * A profile is a named retry/timeout shape an Op step opts into
+ * (`activity("chantBuild", …, "fastIdempotent")`), so tuning lives in one table
+ * instead of inline at every call site. The six names cover the shapes infra
+ * steps actually take: fast idempotent work, long infra, K8s wait loops, a
+ * human gate, an Argo sync wait, and a deterministic policy check.
+ *
+ * These lived in a hosting lexicon, under its own prefixed name, until chant
+ * #2114 moved the base activities into core. Nothing about a timeout or a
+ * backoff coefficient belonged to that runtime, so the table came with them and
+ * lost the prefix. `heartbeatTimeout` did not come along: it configured a
+ * liveness protocol between a worker and a server, and no in-process step
+ * heartbeats to anything.
+ */
+
+export interface ActivityProfile {
+  /** Maximum time allowed for a single activity execution attempt (e.g. `"20m"`). */
+  timeout: string;
+  /** Retry policy for failed activity attempts. */
+  retry?: {
+    /** Initial wait before the first retry (e.g. "5s"). */
+    initialInterval?: string;
+    /** Multiplier applied to the interval on each retry (e.g. 2). */
+    backoffCoefficient?: number;
+    /** Maximum number of attempts including the first (0 = unlimited). */
+    maximumAttempts?: number;
+    /** Cap on retry intervals (e.g. "5m"). */
+    maximumInterval?: string;
+    /**
+     * Error names (`Error.name`) that fail immediately without retry — the
+     * executor short-circuits its retry loop on a match.
+     */
+    nonRetryableErrorTypes?: string[];
+  };
+}
+
+/** Named activity profiles for common infrastructure step patterns. */
+export const ACTIVITY_PROFILES = {
+  /**
+   * Fast, idempotent operations: `chant build`, `kubectl apply` without `--wait`,
+   * fetching nameservers, reading cluster status.
+   */
+  fastIdempotent: {
+    timeout: "5m",
+    retry: { maximumAttempts: 3, initialInterval: "5s", backoffCoefficient: 2 },
+  },
+
+  /**
+   * Long-running infra: GKE cluster creation via Config Connector (~10-20 min),
+   * `kubectl apply --wait` for large resource sets, Helm installs.
+   */
+  longInfra: {
+    timeout: "20m",
+    retry: { maximumAttempts: 3, initialInterval: "30s", backoffCoefficient: 2 },
+  },
+
+  /**
+   * K8s wait loops: polling for StatefulSet rollout, ExternalDNS A-records,
+   * DNS propagation.
+   */
+  k8sWait: {
+    timeout: "15m",
+    // A terminal-state resource (waitForReady's ReadinessFailedError) will never
+    // become ready — fail fast instead of exhausting retries.
+    retry: {
+      maximumAttempts: 3,
+      initialInterval: "10s",
+      backoffCoefficient: 2,
+      nonRetryableErrorTypes: ["ReadinessFailedError"],
+    },
+  },
+
+  /**
+   * Human-gate steps: waiting for an operator action (DNS delegation, approval).
+   * Very long timeout, single attempt — no retry on human-gate timeouts.
+   */
+  humanGate: {
+    timeout: "48h",
+    retry: { maximumAttempts: 1 },
+  },
+
+  /**
+   * Argo CD sync waits: poll an Application until `health=Healthy && sync=Synced`
+   * (`waitForArgoSync`). Long timeout for slow first syncs, cheap idempotent
+   * retries — re-polling is free. A terminal-unhealthy Application fails fast
+   * via `ArgoSyncFailedError` (non-retryable).
+   */
+  argoSync: {
+    timeout: "30m",
+    retry: {
+      maximumAttempts: 5,
+      initialInterval: "10s",
+      backoffCoefficient: 2,
+      maximumInterval: "1m",
+      nonRetryableErrorTypes: ["ArgoSyncFailedError"],
+    },
+  },
+
+  /**
+   * Organizational policy gate (`policyGate`): build the project and evaluate
+   * `lint.policies`. Deterministic — a violation is the same on every attempt —
+   * so a single attempt, short timeout, no retry.
+   */
+  policyCheck: {
+    timeout: "5m",
+    retry: { maximumAttempts: 1 },
+  },
+} as const satisfies Record<string, ActivityProfile>;
+
+/** The name of a built-in activity profile — the union `ActivityStep.profile` admits. */
+export type ActivityProfileName = keyof typeof ACTIVITY_PROFILES;
+
+/** Every profile name, as a runtime list (`KNOWN_ACTIVITY_PROFILES`'s source). */
+export const ACTIVITY_PROFILE_NAMES = Object.keys(ACTIVITY_PROFILES) as ActivityProfileName[];

package/src/op/activity-registry.test.ts

@@ -1,15 +1,11 @@
-import { describe, test, expect, vi, afterEach } from "vitest";
-import { loadActivities, resolveActivity, type ActivityFn } from "./activity-registry";
+import { describe, test, expect } from "vitest";
+import { loadActivities, loadProfiles, resolveActivity, type ActivityFn } from "./activity-registry";
+import { ACTIVITY_PROFILES } from "./activity-profiles";
 
 describe("loadActivities", () => {
-  afterEach(() => {
-    vi.resetModules();
-    vi.doUnmock("@intentius/chant-lexicon-temporal/op/activities");
-  });
-
-  test("loads the lexicon activity library keyed by export name", async () => {
+  test("loads core's own activity library keyed by export name", async () => {
     const activities = await loadActivities();
-    // Real export names from lexicons/temporal/src/op/activities.
+    // Real export names from packages/core/src/op/activities.
     expect(activities.has("shellCmd")).toBe(true);
     expect(activities.has("chantBuild")).toBe(true);
     expect(activities.has("waitForStack")).toBe(true);
@@ -17,15 +13,27 @@ describe("loadActivities", () => {
     expect(typeof activities.get("shellCmd")).toBe("function");
   });
 
-  test("throws a friendly error when the lexicon is not installed", async () => {
-    vi.resetModules();
-    vi.doMock("@intentius/chant-lexicon-temporal/op/activities", () => {
-      throw new Error("Cannot find module");
-    });
-    const { loadActivities: fresh } = await import("./activity-registry");
-    await expect(fresh()).rejects.toThrow(
-      "no activities registered — install `@intentius/chant-lexicon-temporal`",
-    );
+  /**
+   * chant #2114 — the base library used to live in a hosting lexicon,
+   * dynamically imported, and `loadActivities` threw "no activities
+   * registered" without it. The activities are core's own now and the
+   * import is static, so an empty lexicon list resolves the whole base surface in
+   * a project that has installed nothing but chant.
+   */
+  test("every base activity resolves with no lexicons configured", async () => {
+    const a = await loadActivities([]);
+    for (const fn of [
+      "shellCmd", "chantBuild", "waitForStack", "lifecycleSnapshot", "lifecycleDiff",
+      "httpCheck", "chantTeardown", "envTeardown", "convergeTick", "reconcilePr",
+      "guardValidate", "policyGate", "workflowSupplyChainAudit", "pipelineSupplyChainAudit",
+      "lexiconUpgrade", "nativeApply",
+    ]) {
+      expect(typeof a.get(fn), `${fn} should resolve from the base library`).toBe("function");
+    }
+  });
+
+  test("loadProfiles returns core's table", async () => {
+    expect(await loadProfiles()).toBe(ACTIVITY_PROFILES);
   });
 });
 
@@ -47,25 +55,26 @@ describe("resolveActivity", () => {
   });
 });
 
-describe("loadActivities — heartbeat-shim safety", () => {
-  test("the activity library loads without @temporalio/activity installed", async () => {
-    // waitForStack (and the relocated kubectlApply/helmInstall/gitlabPipeline)
-    // heartbeat via the lazy shim; if the shim statically required the SDK, this
-    // import would throw (the SDK is not installed in this environment).
+describe("loadActivities — no runtime SDK on the path", () => {
+  test("the activity library loads with no orchestrator SDK installed", async () => {
+    // The base activities used to reach an orchestrator SDK for heartbeats and
+    // its non-retryable failure type. Neither is a core dependency, and this
+    // import would throw if one crept back in.
     const activities = await loadActivities();
     expect(activities.has("waitForStack")).toBe(true);
     expect(activities.has("chantBuild")).toBe(true);
+    expect(activities.has("policyGate")).toBe(true);
   });
 });
 
-// Cloud appliers were relocated out of the temporal lexicon into their own
+// Cloud appliers were relocated out of a single lexicon into their own
 // lexicons (#706); the loader pulls them in per the project's configured
 // `lexicons`. Proves the relocation resolves end-to-end.
 describe("loadActivities — multi-lexicon (#706)", () => {
-  test("base (no lexicons): temporal activities present, product activities absent", async () => {
+  test("base (no lexicons): core activities present, product activities absent", async () => {
     const a = await loadActivities();
-    expect(a.has("waitForStack")).toBe(true); // temporal base
-    expect(a.has("shellCmd")).toBe(true); // temporal base
+    expect(a.has("waitForStack")).toBe(true); // core base
+    expect(a.has("shellCmd")).toBe(true); // core base
     expect(a.has("kubectlApply")).toBe(false); // relocated to k8s (#809)
     expect(a.has("k3dUp")).toBe(false); // relocated to k8s (#809), then k3d (#1410)
     expect(a.has("gcpApply")).toBe(false); // relocated to gcp
@@ -117,6 +126,6 @@ describe("loadActivities — multi-lexicon (#706)", () => {
 
   test("unknown lexicon is skipped without throwing", async () => {
     const a = await loadActivities(["definitely-not-a-lexicon"]);
-    expect(a.has("waitForStack")).toBe(true); // temporal base still loads
+    expect(a.has("waitForStack")).toBe(true); // core base still loads
   });
 });

package/src/op/activity-registry.ts

@@ -2,17 +2,24 @@
  * Activity registry — resolves an Op step's `fn` name to a callable activity
  * implementation for local execution.
  *
- * Activities live in the Temporal lexicon (`@intentius/chant-lexicon-temporal`)
- * but are plain async functions taking a single args object — Temporal-free to
- * call. Local mode loads them by name instead of registering them with a worker.
+ * The base activities are core's own (`./activities`): plain async functions
+ * taking a single args object, with no workflow engine anywhere in the call
+ * path. They are imported statically, so `loadActivities([])` works in a
+ * project that has installed nothing but chant. Product-specific appliers stay
+ * in their owning lexicon (#809) and are pulled in dynamically per the
+ * project's configured lexicon list.
  */
 
+import * as baseActivities from "./activities";
+import { ACTIVITY_PROFILES, type ActivityProfile } from "./activity-profiles";
+
+export type { ActivityProfile } from "./activity-profiles";
+
 /**
  * An activity is an async function taking a single args object and an optional
  * `AbortSignal`. Local execution passes a signal that fires on timeout or
- * Ctrl-C so the activity can kill in-flight child processes; the Temporal
- * worker invokes activities with args only (cancellation comes from its own
- * `Context`), so the signal is always optional.
+ * Ctrl-C so the activity can kill in-flight child processes; a hosted runtime
+ * may invoke activities with args only, so the signal is always optional.
  */
 export type ActivityFn = (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
 
@@ -26,33 +33,24 @@ function collectActivities(mod: Record<string, unknown>, into: Map<string, Activ
 }
 
 /**
- * Build the activity map for local execution by importing activity libraries and
- * keying every exported function by name (`shellCmd`, `kubectlApply`, `gcpApply`, …).
+ * Build the activity map for local execution: core's base activities plus every
+ * activity module the project's configured lexicons contribute, keyed by export
+ * name (`shellCmd`, `kubectlApply`, `gcpApply`, …).
  *
- * The base activities always live in the temporal lexicon. Cloud-specific
- * appliers live in their own lexicon (aws → `flociUp`/`flociDown`, gcp →
- * `gcpApply`, azure → `azGroupEnsure`/`azGroupDelete`), so `lexicons` — the
- * project's configured lexicon list — is consulted to pull those in. A lexicon
- * that ships no `op/activities` module is skipped.
+ * Cloud-specific appliers live in their own lexicon (aws → `flociUp`/`flociDown`,
+ * gcp → `gcpApply`, azure → `azGroupEnsure`/`azGroupDelete`), so `lexicons` —
+ * the project's configured lexicon list — is consulted to pull those in. A
+ * lexicon that ships no `op/activities` module is skipped.
  *
- * Throws only if the temporal base library is missing — local execution needs
- * the activity implementations even though it never starts a worker.
+ * Never throws: the base library is a static import, so there is no "no
+ * activities registered" state to report.
  */
 export async function loadActivities(lexicons: string[] = []): Promise<Map<string, ActivityFn>> {
   const activities = new Map<string, ActivityFn>();
 
-  try {
-    // Variable specifier so tsc does not statically resolve the optional dep.
-    const spec = "@intentius/chant-lexicon-temporal/op/activities";
-    collectActivities((await import(spec)) as Record<string, unknown>, activities);
-  } catch {
-    throw new Error(
-      "no activities registered — install `@intentius/chant-lexicon-temporal`",
-    );
-  }
+  collectActivities(baseActivities as unknown as Record<string, unknown>, activities);
 
   for (const name of lexicons) {
-    if (name === "temporal") continue;
     try {
       const spec = `@intentius/chant-lexicon-${name}/op/activities`;
       collectActivities((await import(spec)) as Record<string, unknown>, activities);
@@ -64,40 +62,13 @@ export async function loadActivities(lexicons: string[] = []): Promise<Map<strin
   return activities;
 }
 
-/** Structural shape of a TEMPORAL_ACTIVITY_PROFILES entry (timeout + retry). */
-export interface ActivityProfile {
-  startToCloseTimeout?: string;
-  heartbeatTimeout?: string;
-  retry?: {
-    initialInterval?: string;
-    backoffCoefficient?: number;
-    maximumAttempts?: number;
-    maximumInterval?: string;
-    /** Error names (`Error.name`) that should fail immediately without retry. */
-    nonRetryableErrorTypes?: string[];
-  };
-}
-
 /**
- * Dynamically import the lexicon's `TEMPORAL_ACTIVITY_PROFILES` (pure data, no
- * Temporal SDK). Returns an empty record if the lexicon is absent — the
- * executor then falls back to built-in defaults per step.
- *
- * Imports the lexicon's `/config` entry, not its root index. `/config` is a
- * side-effect-free data module; the root index pulls in the plugin, serializer,
- * composites, and re-exported Op machinery, any of which could throw on load
- * and make this silently return `{}` — which would drop every profiled step to
- * the 5-minute default while the Temporal path (reading the same table) kept the
- * declared timeout. Importing the narrow module keeps the two executors agreed.
+ * The built-in profile table. Kept async because it is awaited on the CLI's
+ * run path alongside {@link loadActivities}, and because a hosted runtime may
+ * one day resolve profiles from somewhere less immediate.
  */
 export async function loadProfiles(): Promise<Record<string, ActivityProfile>> {
-  try {
-    const spec = "@intentius/chant-lexicon-temporal/config";
-    const mod = (await import(spec)) as { TEMPORAL_ACTIVITY_PROFILES?: Record<string, ActivityProfile> };
-    return mod.TEMPORAL_ACTIVITY_PROFILES ?? {};
-  } catch {
-    return {};
-  }
+  return ACTIVITY_PROFILES as unknown as Record<string, ActivityProfile>;
 }
 
 /**

package/src/op/activity-runtime.ts

@@ -1,54 +1,10 @@
 /**
  * Activity runtime helpers shared by every Op activity implementation, wherever
- * it lives — the base activities in the temporal lexicon and the cloud-specific
- * appliers relocated into the aws/gcp/azure lexicons. Hosting them in core keeps
- * a cloud lexicon from having to depend on the temporal lexicon just to
- * heartbeat or sleep.
+ * it lives — the base activities in `./activities` and the product-specific
+ * appliers in the aws/gcp/azure/k8s/fly lexicons. Hosting them in core keeps a
+ * lexicon from depending on another lexicon just to sleep between polls.
  */
 
-interface ActivityContext {
-  current(): { heartbeat(details?: unknown): void };
-}
-
-// undefined = not yet attempted; null = unavailable; object = resolved Context.
-let cachedContext: ActivityContext | null | undefined;
-let loading: Promise<void> | undefined;
-
-function ensureContext(): void {
-  if (cachedContext !== undefined || loading) return;
-  // Variable specifier so bundlers/tsc do not statically require the optional dep.
-  const spec = "@temporalio/activity";
-  loading = import(spec)
-    .then((mod: unknown) => {
-      cachedContext = (mod as { Context?: ActivityContext }).Context ?? null;
-    })
-    .catch(() => {
-      cachedContext = null;
-    });
-}
-
-/**
- * Emit an activity heartbeat if running under a Temporal worker; otherwise no-op.
- *
- * The first call kicks off a one-time lazy load of `@temporalio/activity` and
- * returns immediately; once resolved, subsequent calls heartbeat. Heartbeats
- * are periodic (every ~15s, well inside the 60s heartbeat timeout), so the
- * single missed first tick is harmless. Under chant's local executor (no
- * Temporal SDK present) it no-ops, and the module imports cleanly without the SDK.
- */
-export function safeHeartbeat(details?: unknown): void {
-  if (cachedContext === undefined) {
-    ensureContext();
-    return;
-  }
-  if (cachedContext === null) return;
-  try {
-    cachedContext.current().heartbeat(details);
-  } catch {
-    // Not inside an activity execution context — nothing to do.
-  }
-}
-
 /**
  * Sleep for `ms`, rejecting early if `signal` aborts. Polling activities use
  * this between attempts so a local-executor timeout or Ctrl-C interrupts the

package/src/op/builders-exports.test.ts

@@ -1,6 +1,4 @@
 import { describe, test, expect } from "vitest";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 import * as opIndex from "./index";
 import * as builders from "./builders";
 
@@ -26,51 +24,4 @@ describe("op builders are all reachable (#1715)", () => {
         `export list at the top of op/index.ts, or a project cannot use them:\n  ${missing.join("\n  ")}`,
     ).toEqual([]);
   });
-
-  test("the temporal lexicon re-exports the same set", () => {
-    // The lexicon is what a project actually imports from
-    // (`@intentius/chant-lexicon-temporal`), and it re-states the list a third
-    // time rather than re-exporting wholesale — so it can drift independently.
-    const src = readFileSync(
-      join(import.meta.dirname, "../../../../lexicons/temporal/src/index.ts"),
-      "utf-8",
-    );
-    const block = src.match(/export \{([^}]*)\} from "@intentius\/chant\/op";/)?.[1] ?? "";
-    const reExported = new Set(
-      block.split(",").map((s) => s.trim()).filter(Boolean),
-    );
-    // The sprites family reaches projects through the fly lexicon, not this
-    // one. Named rather than prefix-matched, because `listCheckpoints` is one
-    // of them and does not look like one — which this test caught on its
-    // first run.
-    const FLY_SURFACE = new Set([
-      "spriteCreate", "spriteExec", "spriteCheckpoint", "spriteRestore",
-      "listCheckpoints", "spriteDestroy", "spriteWriteFile", "spriteReadFile",
-      "spriteListDir", "spriteRemove", "spriteApplyNetworkPolicy",
-      "spriteApplyServices", "spriteTaskCreate", "spriteTaskRefresh",
-      "spriteTaskRelease", "spritesUp", "spritesDown",
-    ]);
-    // chant #1288 Stage 2 — these are the temporal lexicon's OWN activities
-    // (build.ts, shell.ts, wait.ts, ...), so its barrel re-exports a fully
-    // typed twin from its own `./op/builders` instead of core's untyped
-    // original — same name, same import path, deliberately not sourced from
-    // `@intentius/chant/op` any more. See `lexicons/temporal/src/index.ts`
-    // and `lexicons/temporal/src/op/builders.ts`.
-    const TEMPORAL_TYPED_SURFACE = new Set([
-      "build", "shell", "waitForStack", "lifecycleSnapshot", "teardown", "envTeardown", "httpCheck", "policyGate",
-    ]);
-    // chant #1288 Stage 2 — an internal helper (`takeProfile`'s sibling) for
-    // the lexicon-owned typed step-builder wrappers to reuse, not an
-    // Op-authoring primitive itself; nothing authors an Op with it directly,
-    // so it has no place in the Op-authoring barrel.
-    const INTERNAL_HELPERS = new Set(["takeProfileAndId"]);
-    const expected = Object.keys(builders).filter(
-      (n) => !FLY_SURFACE.has(n) && !TEMPORAL_TYPED_SURFACE.has(n) && !INTERNAL_HELPERS.has(n),
-    );
-    const missing = expected.filter((name) => !reExported.has(name));
-    expect(
-      missing,
-      `lexicons/temporal/src/index.ts does not re-export these builders:\n  ${missing.join("\n  ")}`,
-    ).toEqual([]);
-  });
 });

package/src/op/builders-typed.test.ts

@@ -0,0 +1,164 @@
+/**
+ * The typed step-builder wrappers over core's own base activities (chant #1288
+ * Stage 2, moved here from a hosting lexicon by #2114). `opts` in each is
+ * the activity's own `*Args` interface (`./activities/*.ts`) via `Omit`/
+ * `WithStepRefs`, never a hand-restated mirror, so a signature change in the
+ * activity is a compile error at the builder rather than a silently-dropped arg.
+ *
+ * These are asserted against the `ActivityStep` they emit — the fixed profiles
+ * (`policyGate`/`guardValidate` on `policyCheck`, `teardown` on `longInfra`)
+ * and defaults (`waitForStack` → `k8sWait`, `httpCheck`/`envTeardown`) are
+ * pinned here, since there is no longer a second, untyped implementation to
+ * compare against.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  build,
+  shell,
+  waitForStack,
+  lifecycleSnapshot,
+  teardown,
+  envTeardown,
+  httpCheck,
+  policyGate,
+  guardValidate,
+  stepOutput,
+  type StepOutputRef,
+} from "./index";
+
+describe("typed step builders over the base activities", () => {
+  test("build: names chantBuild, path is positional, opts spread into args", () => {
+    expect(build("examples/gitlab-aws-alb-infra")).toMatchObject({
+      kind: "activity",
+      fn: "chantBuild",
+      args: { path: "examples/gitlab-aws-alb-infra" },
+    });
+    expect(build(".", { script: "build:aws", env: { NODE_ENV: "production" } })).toMatchObject({
+      fn: "chantBuild",
+      args: { path: ".", script: "build:aws", env: { NODE_ENV: "production" } },
+    });
+  });
+
+  test("shell: names shellCmd; env and profile route where they belong", () => {
+    expect(shell("npm run db:seed")).toMatchObject({ fn: "shellCmd", args: { cmd: "npm run db:seed" } });
+    const step = shell("docker push image", { env: { FOO: "bar" }, profile: "longInfra" });
+    expect(step.args).toEqual({ cmd: "docker push image", env: { FOO: "bar" } });
+    expect(step.profile).toBe("longInfra");
+  });
+
+  test("shell: cwd is reachable (the untyped builder this replaced dropped it)", () => {
+    const step = shell("ls", { cwd: "/tmp" });
+    expect(step.args?.cwd).toBe("/tmp");
+  });
+
+  test("waitForStack: defaults to the k8sWait profile", () => {
+    const step = waitForStack("alb-api", { namespace: "alb" });
+    expect(step).toMatchObject({ fn: "waitForStack", args: { name: "alb-api", namespace: "alb" } });
+    expect(step.profile).toBe("k8sWait");
+  });
+
+  test("lifecycleSnapshot: env is the only arg", () => {
+    expect(lifecycleSnapshot("staging")).toMatchObject({
+      fn: "lifecycleSnapshot",
+      args: { env: "staging" },
+    });
+  });
+
+  test("lifecycleSnapshot: .out is reachable via an id", () => {
+    const step = lifecycleSnapshot("staging", { id: "snap" });
+    const ref: StepOutputRef = step.out.env;
+    expect(ref.step).toBe("snap");
+    expect(ref.path).toBe("env");
+  });
+
+  test("teardown: fixed longInfra profile", () => {
+    const step = teardown("examples/getting-started");
+    expect(step).toMatchObject({ fn: "chantTeardown", args: { path: "examples/getting-started" } });
+    expect(step.profile).toBe("longInfra");
+  });
+
+  test("envTeardown: defaults to longInfra, confirmProd passes through", () => {
+    const step = envTeardown("prod", { confirmProd: true });
+    expect(step.args).toEqual({ env: "prod", confirmProd: true });
+    expect(step.profile).toBe("longInfra");
+  });
+
+  test("httpCheck: defaults to fastIdempotent", () => {
+    const step = httpCheck("https://example.com/health", { status: 200, contains: "ok" });
+    expect(step.args).toEqual({ url: "https://example.com/health", status: 200, contains: "ok" });
+    expect(step.profile).toBe("fastIdempotent");
+  });
+
+  test("policyGate: fixed policyCheck profile, path defaults to '.'", () => {
+    expect(policyGate()).toMatchObject({ fn: "policyGate", args: { path: "." }, profile: "policyCheck" });
+    expect(policyGate({ env: "staging" }).args).toEqual({ path: ".", env: "staging" });
+  });
+
+  test("waitForStack: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("build-step", "namespace");
+    const step = waitForStack("alb-api", { namespace: ref });
+    expect(step.args?.namespace).toBe(ref);
+  });
+
+  test("guardValidate: builds an activity step naming the guardValidate activity", () => {
+    const step = guardValidate("rules.guard");
+    expect(step.kind).toBe("activity");
+    expect(step.fn).toBe("guardValidate");
+    expect(step.args).toEqual({ rules: "rules.guard" });
+    expect(step.profile).toBe("policyCheck");
+  });
+
+  test("guardValidate: template/binary/onFinding pass through as args; id routes to the step, not args", () => {
+    const step = guardValidate("rules.guard", { template: "dist/out.json", binary: "/opt/bin/cfn-guard", onFinding: "report", id: "guard" });
+    expect(step.args).toEqual({
+      rules: "rules.guard",
+      template: "dist/out.json",
+      binary: "/opt/bin/cfn-guard",
+      onFinding: "report",
+    });
+    expect(step.id).toBe("guard");
+    expect(step.profile).toBe("policyCheck");
+  });
+
+  test("guardValidate: .out is reachable once the step is given an id", () => {
+    const step = guardValidate("rules.guard", { id: "guard" });
+    const ref: StepOutputRef = step.out.findings;
+    expect(ref.step).toBe("guard");
+    expect(ref.path).toBe("findings");
+  });
+
+  test("guardValidate: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("build-step", "outPath");
+    const step = guardValidate("rules.guard", { template: ref });
+    expect(step.args?.template).toBe(ref);
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error — "environment" is not a key of ChantBuildArgs (the
+  // exact typo class chant #1288 names: `env` is the field, not
+  // `environment` — e.g. activity("lifecycleDiff", { environment: "prod" })
+  // silently ignored the whole arg before this).
+  build(".", { environment: "prod" });
+
+  // @ts-expect-error — waitForStack's intervalMs must be a number.
+  waitForStack("alb-api", { intervalMs: "5000" });
+
+  // @ts-expect-error — httpCheck's status must be a number.
+  httpCheck("https://example.com", { status: "200" });
+
+  // @ts-expect-error — policyGate has no `profile` override (fixed to
+  // policyCheck, single-attempt).
+  policyGate({ profile: "fastIdempotent" });
+
+  // @ts-expect-error — guardValidate has no `profile` override either
+  // (fixed to policyCheck, same reasoning as policyGate).
+  guardValidate("rules.guard", { profile: "fastIdempotent" });
+
+  // @ts-expect-error — onFinding only admits "report" today (#522 leaves
+  // issue/pull-request modes to a follow-up).
+  guardValidate("rules.guard", { onFinding: "issue" });
+}
+void _typeChecksOnly;