@intentius/chant-lexicon-azure 0.15.0 → 0.15.2

package/src/op/activities/az-apply.ts

@@ -6,13 +6,6 @@ import { safeHeartbeat } from "@intentius/chant/op";
 const DEFAULT_SUBSCRIPTION = "00000000-0000-0000-0000-000000000001";
 const DEFAULT_ENDPOINT = "https://management.azure.com";
 
-/** Context for evaluating the ARM template expressions chant emits. */
-export interface ArmContext {
-  subscriptionId: string;
-  resourceGroup: string;
-  location: string;
-}
-
 /** One ARM resource from a `deploymentTemplate.json` `resources[]`. */
 export interface ArmResource {
   type: string;
@@ -23,63 +16,100 @@ export interface ArmResource {
   sku?: unknown;
   kind?: unknown;
   tags?: Record<string, string>;
+  dependsOn?: unknown;
 }
 
-// ── ARM expression evaluation (the subset chant emits) ────────────────────────
+/** Injectable HTTP client — mirrors the GCP applier so tests avoid the network. */
+export type AzHttp = (
+  method: string,
+  url: string,
+  body?: unknown,
+  signal?: AbortSignal,
+) => Promise<{ status: number; text: string }>;
+
+const defaultHttp: AzHttp = async (method, url, body, signal) => {
+  const res = await fetch(url, {
+    method,
+    headers: body === undefined ? undefined : { "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal,
+  });
+  return { status: res.status, text: await res.text() };
+};
+
+// ── ARM expression evaluation ─────────────────────────────────────────────────
 
 /**
- * Evaluate an ARM template expression string (`"[...]"`). Supports the functions
- * chant's serializer emits: `concat`, `uniqueString`, `resourceGroup()` (`.id` /
- * `.location`), `subscription()` (`.subscriptionId`), and string literals. A
- * non-expression string is returned unchanged. Pure.
+ * Context for evaluating ARM template expressions. `deployed` holds the response
+ * bodies of resources already applied this run (keyed by evaluated name) so
+ * `reference()` resolves; `http`/`base` let `listKeys()` call the resource's
+ * key action.
  */
-export function evalArmString(s: string, ctx: ArmContext): string {
+export interface ArmEvalCtx {
+  subscriptionId: string;
+  resourceGroup: string;
+  location: string;
+  deployed: Map<string, unknown>;
+  http: AzHttp;
+  base: string;
+  signal?: AbortSignal;
+}
+
+/** Evaluate an ARM expression string (`"[...]"`); a plain string is returned as-is. */
+export async function evalArmString(s: string, ctx: ArmEvalCtx): Promise<unknown> {
   if (!(s.startsWith("[") && s.endsWith("]"))) return s;
-  // "[[" is an escaped literal "[".
-  if (s.startsWith("[[")) return s.slice(1);
-  return String(new ArmExpr(s.slice(1, -1), ctx).parse());
+  if (s.startsWith("[[")) return s.slice(1); // escaped literal "["
+  return new ArmExpr(s.slice(1, -1), ctx).parse();
 }
 
-/** Recursively evaluate every string in a value against the ARM context. Pure. */
-export function evalArm(value: unknown, ctx: ArmContext): unknown {
+/** Recursively evaluate every string in a value against the ARM context. */
+export async function evalArm(value: unknown, ctx: ArmEvalCtx): Promise<unknown> {
   if (typeof value === "string") return evalArmString(value, ctx);
-  if (Array.isArray(value)) return value.map((v) => evalArm(v, ctx));
+  if (Array.isArray(value)) return Promise.all(value.map((v) => evalArm(v, ctx)));
   if (value && typeof value === "object") {
     const out: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value)) out[k] = evalArm(v, ctx);
+    for (const [k, v] of Object.entries(value)) out[k] = await evalArm(v, ctx);
     return out;
   }
   return value;
 }
 
-/** Minimal recursive-descent evaluator for the ARM function subset. */
+/**
+ * Recursive-descent evaluator for the ARM function subset chant emits:
+ * `concat`, `uniqueString`, `resourceGroup()`, `subscription()`, `resourceId`,
+ * `reference` (runtime state of an applied resource), and `listKeys` (async key
+ * action), with `.prop` and `[index]` access.
+ */
 class ArmExpr {
   private i = 0;
-  constructor(private readonly src: string, private readonly ctx: ArmContext) {}
+  constructor(private readonly src: string, private readonly ctx: ArmEvalCtx) {}
 
-  parse(): unknown {
-    const v = this.expr();
-    return v;
+  async parse(): Promise<unknown> {
+    return this.access(await this.atom());
   }
 
-  private expr(): unknown {
+  private async atom(): Promise<unknown> {
     this.ws();
-    let v: unknown;
-    if (this.src[this.i] === "'") {
-      v = this.stringLiteral();
-    } else {
-      v = this.call();
-    }
-    // Property access: resourceGroup().location, subscription().subscriptionId
-    while (this.peek() === ".") {
-      this.i++;
-      const prop = this.ident();
-      v = (v as Record<string, unknown>)?.[prop];
+    return this.src[this.i] === "'" ? this.stringLiteral() : this.call();
+  }
+
+  /** Postfix `.prop` / `[index]` access. */
+  private async access(v: unknown): Promise<unknown> {
+    for (;;) {
+      const c = this.peek();
+      if (c === ".") {
+        this.i++;
+        v = (v as Record<string, unknown> | undefined)?.[this.ident()];
+      } else if (c === "[") {
+        this.i++;
+        v = (v as unknown[] | undefined)?.[this.indexNumber()];
+      } else {
+        return v;
+      }
     }
-    return v;
   }
 
-  private call(): unknown {
+  private async call(): Promise<unknown> {
     const name = this.ident();
     this.ws();
     const args: unknown[] = [];
@@ -87,11 +117,11 @@ class ArmExpr {
       this.i++;
       this.ws();
       if (this.peek() !== ")") {
-        args.push(this.expr());
+        args.push(await this.parse());
         this.ws();
         while (this.peek() === ",") {
           this.i++;
-          args.push(this.expr());
+          args.push(await this.parse());
           this.ws();
         }
       }
@@ -100,7 +130,7 @@ class ArmExpr {
     return this.applyFn(name, args);
   }
 
-  private applyFn(name: string, args: unknown[]): unknown {
+  private async applyFn(name: string, args: unknown[]): Promise<unknown> {
     switch (name) {
       case "concat":
         return args.map(String).join("");
@@ -110,6 +140,25 @@ class ArmExpr {
         return { location: this.ctx.location, id: `/subscriptions/${this.ctx.subscriptionId}/resourceGroups/${this.ctx.resourceGroup}`, name: this.ctx.resourceGroup };
       case "subscription":
         return { subscriptionId: this.ctx.subscriptionId, id: `/subscriptions/${this.ctx.subscriptionId}` };
+      case "resourceId":
+        // resourceId('Microsoft.X/y', 'name'[, 'child']) → the resource-id path.
+        return `/subscriptions/${this.ctx.subscriptionId}/resourceGroups/${this.ctx.resourceGroup}/providers/${args.map(String).join("/")}`;
+      case "reference": {
+        // reference('name') → the runtime `properties` of an already-applied resource.
+        const dep = this.ctx.deployed.get(String(args[0]));
+        return (dep as { properties?: unknown } | undefined)?.properties ?? dep;
+      }
+      case "listKeys": {
+        // listKeys(resourceId, apiVersion) → POST the resource's key action.
+        const resId = String(args[0]);
+        const apiVersion = String(args[1] ?? "2023-01-01");
+        const res = await this.ctx.http("POST", `${this.ctx.base}${resId}/listKeys?api-version=${apiVersion}`, {}, this.ctx.signal);
+        try {
+          return JSON.parse(res.text);
+        } catch {
+          return {};
+        }
+      }
       default:
         throw new Error(`unsupported ARM function: ${name}`);
     }
@@ -130,6 +179,15 @@ class ArmExpr {
     return out;
   }
 
+  private indexNumber(): number {
+    this.ws();
+    let n = "";
+    while (this.i < this.src.length && /[0-9]/.test(this.src[this.i])) n += this.src[this.i++];
+    this.ws();
+    if (this.peek() === "]") this.i++;
+    return parseInt(n, 10);
+  }
+
   private ws(): void {
     while (this.i < this.src.length && /\s/.test(this.src[this.i])) this.i++;
   }
@@ -140,40 +198,70 @@ class ArmExpr {
   }
 }
 
-// ── HTTP + apply ──────────────────────────────────────────────────────────────
+// ── Dependency ordering ───────────────────────────────────────────────────────
 
-/** Injectable HTTP client — mirrors the GCP applier so tests avoid the network. */
-export type AzHttp = (
-  method: string,
-  url: string,
-  body?: unknown,
-  signal?: AbortSignal,
-) => Promise<{ status: number; text: string }>;
+/** Resource names this resource references via `resourceId('type','name')` / `reference('name')`. Pure. */
+export function armDependencies(resource: ArmResource, names: Set<string>): string[] {
+  const deps = new Set<string>();
+  const scan = (v: unknown): void => {
+    if (typeof v === "string") {
+      for (const m of v.matchAll(/resourceId\(\s*'[^']*'\s*,\s*'([^']*)'/g)) if (names.has(m[1])) deps.add(m[1]);
+      for (const m of v.matchAll(/reference\(\s*'([^']*)'/g)) if (names.has(m[1])) deps.add(m[1]);
+    } else if (Array.isArray(v)) {
+      v.forEach(scan);
+    } else if (v && typeof v === "object") {
+      Object.values(v).forEach(scan);
+    }
+  };
+  scan(resource);
+  deps.delete(resource.name);
+  return [...deps];
+}
 
-const defaultHttp: AzHttp = async (method, url, body, signal) => {
-  const res = await fetch(url, {
-    method,
-    headers: body === undefined ? undefined : { "content-type": "application/json" },
-    body: body === undefined ? undefined : JSON.stringify(body),
-    signal,
-  });
-  return { status: res.status, text: await res.text() };
-};
+/**
+ * Topologically order ARM resources so a referenced resource is applied before
+ * the resource that references it. Names that are expressions are ordered as-is
+ * (they don't match a literal reference). Throws on a cycle. Pure.
+ */
+export function orderArmResources(resources: ArmResource[]): ArmResource[] {
+  const byName = new Map<string, ArmResource>();
+  for (const r of resources) byName.set(r.name, r);
+  const names = new Set(resources.map((r) => r.name));
+  const ordered: ArmResource[] = [];
+  const done = new Set<ArmResource>();
+  const active = new Set<ArmResource>();
+  const visit = (r: ArmResource): void => {
+    if (done.has(r)) return;
+    if (active.has(r)) throw new Error(`ARM reference cycle involving ${r.name}`);
+    active.add(r);
+    for (const dep of armDependencies(r, names)) {
+      const target = byName.get(dep);
+      if (target && target !== r) visit(target);
+    }
+    active.delete(r);
+    done.add(r);
+    ordered.push(r);
+  };
+  for (const r of resources) visit(r);
+  return ordered;
+}
 
-/** The ARM resource-ID PUT URL for a resource under a resource group. Pure. */
-export function armResourceUrl(resource: ArmResource, ctx: ArmContext, base: string): string {
-  const name = evalArmString(resource.name, ctx);
-  return `${base}/subscriptions/${ctx.subscriptionId}/resourceGroups/${ctx.resourceGroup}/providers/${resource.type}/${name}?api-version=${resource.apiVersion}`;
+// ── URL + body + apply ────────────────────────────────────────────────────────
+
+/** The ARM resource-ID PUT URL for a resource (name expression evaluated). */
+export async function armResourceUrl(resource: ArmResource, ctx: ArmEvalCtx): Promise<string> {
+  const name = await evalArmString(resource.name, ctx);
+  return `${ctx.base}/subscriptions/${ctx.subscriptionId}/resourceGroups/${ctx.resourceGroup}/providers/${resource.type}/${name}?api-version=${resource.apiVersion}`;
 }
 
-/** The ARM resource PUT body (location/properties/sku/kind/tags), expressions evaluated. Pure. */
-export function armResourceBody(resource: ArmResource, ctx: ArmContext): Record<string, unknown> {
+/** The ARM resource PUT body (location/properties/sku/kind/tags), expressions evaluated. */
+export async function armResourceBody(resource: ArmResource, ctx: ArmEvalCtx): Promise<Record<string, unknown>> {
   const body: Record<string, unknown> = {};
-  if (resource.location) body.location = evalArmString(resource.location, ctx);
-  if (resource.properties !== undefined) body.properties = evalArm(resource.properties, ctx);
-  if (resource.sku !== undefined) body.sku = evalArm(resource.sku, ctx);
-  if (resource.kind !== undefined) body.kind = resource.kind;
-  if (resource.tags !== undefined) body.tags = resource.tags;
+  if (resource.location) body.location = await evalArmString(resource.location, ctx);
+  if (resource.properties !== undefined) body.properties = await evalArm(resource.properties, ctx);
+  if (resource.sku !== undefined) body.sku = await evalArm(resource.sku, ctx);
+  if (resource.kind !== undefined) body.kind = await evalArm(resource.kind, ctx);
+  if (resource.tags !== undefined) body.tags = await evalArm(resource.tags, ctx);
   return body;
 }
 
@@ -188,26 +276,36 @@ export interface AzApplyArgs {
   endpoint?: string;
   /** Subscription id. Default: floci-az's local subscription. */
   subscriptionId?: string;
+  /**
+   * Delete chant-owned resources of a templated type that are no longer in the
+   * template (owned-only prune). Destructive — off by default. Foreign
+   * (non-chant) resources are never touched.
+   */
+  prune?: boolean;
 }
 
 /**
  * The native Azure applier — read a built ARM template and PUT each resource
- * directly to the ARM resource-CRUD API, resolving ARM expressions first. This
- * is the direct-apply path (the Azure twin of `gcpApply`): it targets floci-az's
- * ARM resource endpoints — which `az deployment` cannot, since floci-az has no
- * `Microsoft.Resources/deployments` provider — or real Azure by endpoint override.
- * The resource group is ensured first. `http` is injectable for tests.
+ * directly to the ARM resource-CRUD API, in dependency order, resolving ARM
+ * expressions (including `reference()`/`listKeys()` against resources applied
+ * earlier this run). The Azure twin of `gcpApply`: it targets floci-az (which
+ * `az deployment` can't, floci-az having no deployments provider) or real Azure
+ * by endpoint override; the resource group is ensured first.
  */
 export async function azApply(
   args: AzApplyArgs,
   signal?: AbortSignal,
   http: AzHttp = defaultHttp,
-): Promise<{ applied: Array<{ type: string; name: string }> }> {
+): Promise<{ applied: Array<{ type: string; name: string }>; pruned: Array<{ type: string; name: string; deleted: boolean }> }> {
   const base = (args.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
-  const ctx: ArmContext = {
+  const ctx: ArmEvalCtx = {
     subscriptionId: args.subscriptionId ?? DEFAULT_SUBSCRIPTION,
     resourceGroup: args.resourceGroup,
     location: args.location ?? "eastus",
+    deployed: new Map(),
+    http,
+    base,
+    signal,
   };
 
   // Ensure the resource group exists (ARM rejects resource PUTs without it).
@@ -219,16 +317,152 @@ export async function azApply(
   );
 
   const template = JSON.parse(readFileSync(args.templatePath, "utf8")) as { resources?: ArmResource[] };
+  const resources = template.resources ?? [];
   const applied: Array<{ type: string; name: string }> = [];
-  for (const resource of template.resources ?? []) {
-    const name = evalArmString(resource.name, ctx);
+  for (const resource of orderArmResources(resources)) {
+    const name = String(await evalArmString(resource.name, ctx));
     safeHeartbeat({ step: "azApply", type: resource.type, name });
-    const res = await http("PUT", armResourceUrl(resource, ctx, base), armResourceBody(resource, ctx), signal);
+    // Stamp chant ownership so a later prune can tell chant-managed resources
+    // apart from foreign ones in the same group.
+    const body = await armResourceBody(resource, ctx);
+    body.tags = { ...((body.tags as Record<string, string> | undefined) ?? {}), ...chantOwnershipTags() };
+    const res = await http("PUT", await armResourceUrl(resource, ctx), body, signal);
     if (res.status >= 300) {
       throw new Error(`${resource.type} ${name} apply failed (${res.status}): ${res.text}`);
     }
+    // Capture the applied resource so later reference()/dependents resolve.
+    try {
+      ctx.deployed.set(name, JSON.parse(res.text));
+    } catch {
+      // non-JSON response — reference() to this resource resolves to undefined
+    }
     console.log(`applied: ${resource.type}/${name} (${base})`);
     applied.push({ type: resource.type, name });
   }
-  return { applied };
+
+  const pruned = args.prune ? await pruneArmOrphans(resources, ctx, http, signal) : [];
+  return { applied, pruned };
+}
+
+// ── Ownership + prune + delete ────────────────────────────────────────────────
+
+// chant stamps this tag on every resource it applies; prune only ever deletes
+// resources carrying it, so a foreign resource sharing the group is never
+// touched. Real Azure persists resource tags; note that floci-az currently drops
+// them, so owned-only prune only takes effect against real Azure (the delete
+// mechanics themselves work against either — see azDelete).
+const OWNERSHIP_TAG_KEY = "managed-by";
+const OWNERSHIP_TAG_VALUE = "chant";
+
+/** The ownership tag azApply stamps on every resource it applies. */
+export function chantOwnershipTags(): Record<string, string> {
+  return { [OWNERSHIP_TAG_KEY]: OWNERSHIP_TAG_VALUE };
+}
+
+/** Whether a resource's tags mark it chant-owned. */
+export function isChantOwned(tags: Record<string, string> | null | undefined): boolean {
+  return tags?.[OWNERSHIP_TAG_KEY] === OWNERSHIP_TAG_VALUE;
+}
+
+/** One resource from the ARM resource-group listing. */
+export interface ArmListItem {
+  id: string;
+  name: string;
+  type: string;
+  tags?: Record<string, string>;
+}
+
+/** List the resources in the group via the ARM resource-list endpoint. */
+export async function listGroupResources(ctx: ArmEvalCtx, http: AzHttp = defaultHttp, signal?: AbortSignal): Promise<ArmListItem[]> {
+  const url = `${ctx.base}/subscriptions/${ctx.subscriptionId}/resourceGroups/${ctx.resourceGroup}/resources?api-version=2021-04-01`;
+  const res = await http("GET", url, undefined, signal);
+  if (res.status >= 300) return [];
+  try {
+    return ((JSON.parse(res.text) as { value?: ArmListItem[] }).value ?? []).filter((r) => r?.type && r?.name);
+  } catch {
+    return [];
+  }
+}
+
+/** Idempotently delete one ARM resource by type/name/apiVersion. A 404 means it is already gone. */
+export async function deleteArmResource(
+  type: string,
+  name: string,
+  apiVersion: string,
+  ctx: ArmEvalCtx,
+  http: AzHttp = defaultHttp,
+  signal?: AbortSignal,
+): Promise<{ type: string; name: string; deleted: boolean }> {
+  const url = `${ctx.base}/subscriptions/${ctx.subscriptionId}/resourceGroups/${ctx.resourceGroup}/providers/${type}/${name}?api-version=${apiVersion}`;
+  const res = await http("DELETE", url, undefined, signal);
+  if (res.status === 404) return { type, name, deleted: false };
+  if (res.status >= 300) throw new Error(`${type} ${name} delete failed (${res.status}): ${res.text}`);
+  return { type, name, deleted: true };
+}
+
+/**
+ * Owned-only prune: for each resource type present in the template, delete the
+ * chant-owned live resources of that type whose (evaluated) name is not in the
+ * template. Scoped to templated types — like the GCP applier — so a type chant
+ * isn't managing this run is left alone, and the type's `apiVersion` is taken
+ * from the template. Foreign (non-chant) resources are never touched.
+ */
+export async function pruneArmOrphans(
+  desired: ArmResource[],
+  ctx: ArmEvalCtx,
+  http: AzHttp = defaultHttp,
+  signal?: AbortSignal,
+): Promise<Array<{ type: string; name: string; deleted: boolean }>> {
+  const byType = new Map<string, { keep: Set<string>; apiVersion: string }>();
+  for (const r of desired) {
+    const name = String(await evalArmString(r.name, ctx));
+    const entry = byType.get(r.type) ?? { keep: new Set<string>(), apiVersion: r.apiVersion };
+    entry.keep.add(name);
+    byType.set(r.type, entry);
+  }
+
+  const pruned: Array<{ type: string; name: string; deleted: boolean }> = [];
+  for (const item of await listGroupResources(ctx, http, signal)) {
+    const entry = byType.get(item.type);
+    if (!entry || !isChantOwned(item.tags) || entry.keep.has(item.name)) continue;
+    safeHeartbeat({ step: "azPrune", type: item.type, name: item.name });
+    const result = await deleteArmResource(item.type, item.name, entry.apiVersion, ctx, http, signal);
+    console.log(`pruned: ${item.type}/${item.name} (${ctx.base})`);
+    pruned.push(result);
+  }
+  return pruned;
+}
+
+/**
+ * The inverse of {@link azApply} — read a built ARM template and delete the
+ * resources it declares, in reverse dependency order (a referrer goes before the
+ * resource it references). Idempotent: already-absent resources are a no-op. The
+ * Azure twin of `gcpDelete`; `http` is injectable for tests.
+ */
+export async function azDelete(
+  args: AzApplyArgs,
+  signal?: AbortSignal,
+  http: AzHttp = defaultHttp,
+): Promise<{ deleted: Array<{ type: string; name: string; deleted: boolean }> }> {
+  const base = (args.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
+  const ctx: ArmEvalCtx = {
+    subscriptionId: args.subscriptionId ?? DEFAULT_SUBSCRIPTION,
+    resourceGroup: args.resourceGroup,
+    location: args.location ?? "eastus",
+    deployed: new Map(),
+    http,
+    base,
+    signal,
+  };
+
+  const template = JSON.parse(readFileSync(args.templatePath, "utf8")) as { resources?: ArmResource[] };
+  const deleted: Array<{ type: string; name: string; deleted: boolean }> = [];
+  for (const resource of orderArmResources(template.resources ?? []).reverse()) {
+    const name = String(await evalArmString(resource.name, ctx));
+    safeHeartbeat({ step: "azDelete", type: resource.type, name });
+    const result = await deleteArmResource(resource.type, name, resource.apiVersion, ctx, http, signal);
+    console.log(`${result.deleted ? "deleted" : "absent"}: ${resource.type}/${name} (${base})`);
+    deleted.push(result);
+  }
+  return { deleted };
 }

package/src/op/activities/floci-az.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect } from "vitest";
+import {
+  flociAzRunCommand,
+  flociAzRmCommand,
+  flociAzExistsCommand,
+  flociAzHealthUrl,
+  flociAzEndpoint,
+} from "./floci-az";
+
+describe("floci-az lifecycle commands (typed emulator, not shell)", () => {
+  test("run command uses defaults and maps the port", () => {
+    expect(flociAzRunCommand({})).toBe(
+      "docker run -d --rm --name chant-floci-az -p 4577:4577 floci/floci-az:latest",
+    );
+  });
+
+  test("run command honors name/port/image overrides", () => {
+    expect(flociAzRunCommand({ name: "az2", port: 4599, image: "floci/floci-az:0.8.0" })).toBe(
+      "docker run -d --rm --name az2 -p 4599:4577 floci/floci-az:0.8.0",
+    );
+  });
+
+  test("rm / exists / health / endpoint", () => {
+    expect(flociAzRmCommand("az2")).toBe("docker rm -f az2");
+    expect(flociAzExistsCommand("az2")).toBe("docker ps -q -f name=az2");
+    expect(flociAzHealthUrl(4577)).toBe("http://localhost:4577/_floci/health");
+    expect(flociAzEndpoint(4577)).toBe("http://localhost:4577");
+  });
+});

package/src/op/activities/floci-az.ts

@@ -0,0 +1,123 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { safeHeartbeat, sleep } from "@intentius/chant/op";
+
+const execAsync = promisify(exec);
+
+const DEFAULT_NAME = "chant-floci-az";
+const DEFAULT_PORT = 4577;
+const DEFAULT_IMAGE = "floci/floci-az:latest";
+
+export interface FlociAzUpArgs {
+  /** Container name. Default: `chant-floci-az`. */
+  name?: string;
+  /** Host port mapped to the emulator's `:4577`. Default: `4577`. */
+  port?: number;
+  /** Image. Default: `floci/floci-az:latest`. */
+  image?: string;
+  /** Readiness timeout in ms. Default: `60000`. */
+  timeoutMs?: number;
+  /** Health poll interval in ms. Default: `2000`. */
+  intervalMs?: number;
+}
+
+export interface FlociAzDownArgs {
+  /** Container name to remove. Default: `chant-floci-az`. */
+  name?: string;
+}
+
+/** `docker ps -q -f name=<name>` — non-empty stdout means the container is running. */
+export function flociAzExistsCommand(name: string): string {
+  return `docker ps -q -f name=${name}`;
+}
+
+/** Build the `docker run` command that boots floci-az. */
+export function flociAzRunCommand(args: FlociAzUpArgs): string {
+  const name = args.name ?? DEFAULT_NAME;
+  const port = args.port ?? DEFAULT_PORT;
+  const image = args.image ?? DEFAULT_IMAGE;
+  return ["docker", "run", "-d", "--rm", "--name", name, "-p", `${port}:4577`, image].join(" ");
+}
+
+/** Build the `docker rm -f` command. */
+export function flociAzRmCommand(name: string): string {
+  return `docker rm -f ${name}`;
+}
+
+/** The floci-az health endpoint URL for a host port. */
+export function flociAzHealthUrl(port: number): string {
+  return `http://localhost:${port}/_floci/health`;
+}
+
+/** The ARM endpoint URL (what `azApply`'s `endpoint` should point at). */
+export function flociAzEndpoint(port: number): string {
+  return `http://localhost:${port}`;
+}
+
+/**
+ * Boot a local floci-az (Azure emulator) in Docker and return its ARM endpoint.
+ *
+ * Idempotent: reuses a running container of the same name. Waits for the health
+ * endpoint to answer, then returns `{ endpoint }` for `azApply({ endpoint })`.
+ * The typed twin of the AWS `flociUp` — replaces a raw `docker run` shell step so
+ * the emulator lifecycle is modeled, not scripted. Uses longInfra profile — 20m
+ * timeout, heartbeat every poll (the image may pull).
+ */
+export async function flociAzUp(args: FlociAzUpArgs, signal?: AbortSignal): Promise<{ endpoint: string }> {
+  const name = args.name ?? DEFAULT_NAME;
+  const port = args.port ?? DEFAULT_PORT;
+  const timeoutMs = args.timeoutMs ?? 60_000;
+  const intervalMs = args.intervalMs ?? 2_000;
+
+  let running = false;
+  try {
+    const { stdout } = await execAsync(flociAzExistsCommand(name), { signal });
+    running = Boolean(stdout.trim());
+  } catch {
+    // `docker ps` failed — assume not running and try to start it.
+  }
+
+  if (running) {
+    console.log(`floci-az container "${name}" already running — reusing`);
+  } else {
+    await execAsync(flociAzRunCommand({ ...args, name, port }), { signal });
+  }
+
+  const url = flociAzHealthUrl(port);
+  const deadline = Date.now() + timeoutMs;
+  let ready = false;
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error("flociAzUp aborted");
+    safeHeartbeat({ step: "flociAzUp", container: name });
+    try {
+      const res = await fetch(url, { signal });
+      if (res.ok) {
+        ready = true;
+        break;
+      }
+    } catch {
+      // Not up yet (connection refused / non-2xx) — retry.
+    }
+    await sleep(intervalMs, signal);
+  }
+  if (!ready) {
+    throw new Error(`floci-az "${name}" did not become ready within ${timeoutMs}ms`);
+  }
+
+  const endpoint = flociAzEndpoint(port);
+  console.log(`floci-az ready on ${endpoint}`);
+  return { endpoint };
+}
+
+/**
+ * Stop and remove the local floci-az container. A no-op success when the
+ * container is already gone. Uses fastIdempotent profile — 5m timeout.
+ */
+export async function flociAzDown(args: FlociAzDownArgs, signal?: AbortSignal): Promise<void> {
+  const name = args.name ?? DEFAULT_NAME;
+  try {
+    await execAsync(flociAzRmCommand(name), { signal });
+  } catch {
+    // Already removed (`--rm` on exit, or never started) — treat as success.
+  }
+}