@intentius/chant-lexicon-azure 0.44.14 → 0.46.0

package/src/lifecycle-integration.test.ts

@@ -164,5 +164,45 @@ describeObservationConformance({
         });
       },
     },
+    {
+      name: "a marker-stamped ARM envelope surfaces its stack/env identity (#1222)",
+      declared: ["myStore"],
+      expectPresent: ["myStore"],
+      expectMarker: { myStore: { stack: "shop", env: "prod" } },
+      run: () => {
+        stubArm(() => ({
+          status: 200,
+          text: JSON.stringify({
+            ...resourceShow,
+            tags: { "chant-managed-by": "chant", "chant-stack": "shop", "chant-env": "prod" },
+          }),
+        }));
+        return azurePlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["myStore"],
+          entities: new Map([
+            ["myStore", { entityType: "Microsoft.Storage/storageAccounts", props: { name: "mystore" } }],
+          ]),
+        });
+      },
+    },
+    {
+      name: "an untagged ARM envelope surfaces no marker — never a guess (#1222)",
+      declared: ["myStore"],
+      expectPresent: ["myStore"],
+      expectNoMarker: ["myStore"],
+      run: () => {
+        stubArm(() => ({ status: 200, text: JSON.stringify(resourceShow) }));
+        return azurePlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["myStore"],
+          entities: new Map([
+            ["myStore", { entityType: "Microsoft.Storage/storageAccounts", props: { name: "mystore" } }],
+          ]),
+        });
+      },
+    },
   ],
 });

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

@@ -19,7 +19,9 @@ import {
   type ArmEvalCtx,
   type ArmResource,
   type AzHttp,
+  providerApiVersion,
 } from "./az-apply";
+import { lookupApiVersion } from "../../serializer";
 
 const noHttp: AzHttp = async () => ({ status: 200, text: "{}" });
 
@@ -278,7 +280,7 @@ describe("pruneArmOrphans (#azure-prune)", () => {
         { id: "/1", name: "keep1", type: "Microsoft.Storage/storageAccounts", tags: { "managed-by": "chant" } }, // in template → keep
         { id: "/2", name: "orphan1", type: "Microsoft.Storage/storageAccounts", tags: { "managed-by": "chant" } }, // owned, not in template → prune
         { id: "/3", name: "foreign", type: "Microsoft.Storage/storageAccounts", tags: {} }, // not owned → skip
-        { id: "/4", name: "othertype", type: "Microsoft.Web/sites", tags: { "managed-by": "chant" } }, // type not templated → skip
+        { id: "/4", name: "othertype", type: "Microsoft.Web/sites", tags: { "managed-by": "chant" } }, // type not templated → registry apiVersion
       ],
     };
     const deletes: string[] = [];
@@ -287,15 +289,16 @@ describe("pruneArmOrphans (#azure-prune)", () => {
       return { status: 200, text: method === "GET" ? JSON.stringify(live) : "" };
     };
     const { pruned, notPrunable } = await pruneArmOrphans(desired, ctx(), http);
-    expect(pruned).toEqual([{ type: "Microsoft.Storage/storageAccounts", name: "orphan1", deleted: true }]);
-    expect(deletes).toHaveLength(1);
-    expect(deletes[0]).toContain("/storageAccounts/orphan1?api-version=2023-01-01"); // apiVersion from the template
-    // #1457: "othertype" is chant-owned and undeclared, and its TYPE is absent
-    // from the template — so there is no apiVersion to delete it with. It used
-    // to be dropped by the `!entry` guard in silence; now it is reported.
-    expect(notPrunable).toEqual([
-      { type: "Microsoft.Web/sites", name: "othertype", reason: "no-api-version" },
+    expect(pruned).toEqual([
+      { type: "Microsoft.Storage/storageAccounts", name: "orphan1", deleted: true },
+      { type: "Microsoft.Web/sites", name: "othertype", deleted: true },
     ]);
+    expect(deletes).toHaveLength(2);
+    expect(deletes[0]).toContain("/storageAccounts/orphan1?api-version=2023-01-01"); // apiVersion from the template
+    // #1472: "othertype" is chant-owned and undeclared, and its TYPE is absent
+    // from the template — the apiVersion comes from the lexicon registry instead.
+    expect(deletes[1]).toContain(`/sites/othertype?api-version=${lookupApiVersion("Microsoft.Web/sites")}`);
+    expect(notPrunable).toEqual([]);
   });
 
   // #1448 routes ApplyOp's `arm` target here, so this is now the delete scope for
@@ -412,7 +415,7 @@ describe("azDelete (#azure-prune)", () => {
  * unreachable by prune forever. Prune one of SEVERAL and it works, which is why
  * this survived testing.
  */
-describe("pruneArmOrphans: a type that left the template (#1457)", () => {
+describe("pruneArmOrphans: a type that left the template (#1457, #1472)", () => {
   const ctx = (): ArmEvalCtx => ({
     subscriptionId: "sub",
     resourceGroup: "rg",
@@ -422,30 +425,193 @@ describe("pruneArmOrphans: a type that left the template (#1457)", () => {
     base: "http://x",
   });
 
-  const liveHttp = (value: unknown[], deletes: string[]): AzHttp => async (method, url) => {
-    if (method === "DELETE") deletes.push(url);
-    return { status: 200, text: method === "GET" ? JSON.stringify({ value }) : "" };
-  };
+  // Only the resource-group listing answers; the provider-metadata endpoint
+  // 404s, the way floci-az does.
+  const liveHttp = (value: unknown[], deletes: string[], providers: string[] = []): AzHttp =>
+    async (method, url) => {
+      if (method === "DELETE") deletes.push(url);
+      if (method === "GET" && url.includes("/resources?")) return { status: 200, text: JSON.stringify({ value }) };
+      if (method === "GET" && url.includes("/providers/")) {
+        providers.push(url);
+        return { status: 404, text: "" };
+      }
+      return { status: 200, text: "" };
+    };
 
-  test("an owned orphan whose type is gone is reported, not silently skipped", async () => {
+  test("an owned orphan whose type is gone is deleted with the registry apiVersion", async () => {
     // The template now declares a DIFFERENT type entirely — the storage account
-    // was the last of its kind and has been removed from source.
+    // was the last of its kind and has been removed from source. #1457 only
+    // reported this; the registry the serializer pins from now supplies the
+    // apiVersion, so the orphan is actually deleted.
     const desired: ArmResource[] = [
       { type: "Microsoft.Web/sites", apiVersion: "2022-03-01", name: "site" },
     ];
     const deletes: string[] = [];
+    const providers: string[] = [];
     const http = liveHttp(
       [{ id: "/1", name: "leftover", type: "Microsoft.Storage/storageAccounts", tags: { "managed-by": "chant" } }],
       deletes,
+      providers,
     );
     const { pruned, notPrunable } = await pruneArmOrphans(desired, ctx(), http);
-    expect(pruned).toEqual([]);
-    expect(notPrunable).toEqual([
-      { type: "Microsoft.Storage/storageAccounts", name: "leftover", reason: "no-api-version" },
+    expect(pruned).toEqual([{ type: "Microsoft.Storage/storageAccounts", name: "leftover", deleted: true }]);
+    expect(notPrunable).toEqual([]);
+    const registryVersion = lookupApiVersion("Microsoft.Storage/storageAccounts");
+    expect(registryVersion).toBeDefined();
+    expect(deletes).toEqual([
+      `http://x/subscriptions/sub/resourceGroups/rg/providers/Microsoft.Storage/storageAccounts/leftover?api-version=${registryVersion}`,
+    ]);
+    // The registry answered, so ARM's provider metadata was never consulted.
+    expect(providers).toEqual([]);
+  });
+
+  test("the live listing's type casing need not match the registry's", async () => {
+    const desired: ArmResource[] = [];
+    const deletes: string[] = [];
+    const http = liveHttp(
+      [{ id: "/1", name: "leftover", type: "microsoft.storage/storageaccounts", tags: { "managed-by": "chant" } }],
+      deletes,
+    );
+    const { pruned, notPrunable } = await pruneArmOrphans(desired, ctx(), http);
+    expect(pruned).toEqual([{ type: "microsoft.storage/storageaccounts", name: "leftover", deleted: true }]);
+    expect(notPrunable).toEqual([]);
+    expect(deletes[0]).toContain(`?api-version=${lookupApiVersion("Microsoft.Storage/storageAccounts")}`);
+  });
+
+  test("a type the registry does not know falls back to ARM provider metadata, newest stable", async () => {
+    const desired: ArmResource[] = [];
+    const deletes: string[] = [];
+    const gets: string[] = [];
+    const http: AzHttp = async (method, url) => {
+      if (method === "DELETE") deletes.push(url);
+      if (method === "GET") gets.push(url);
+      if (method === "GET" && url.includes("/resources?")) {
+        return {
+          status: 200,
+          text: JSON.stringify({
+            value: [
+              { id: "/1", name: "a", type: "Microsoft.Example/widgets", tags: { "managed-by": "chant" } },
+              { id: "/2", name: "b", type: "Microsoft.Example/widgets", tags: { "managed-by": "chant" } },
+            ],
+          }),
+        };
+      }
+      if (method === "GET" && url.includes("/providers/Microsoft.Example?")) {
+        return {
+          status: 200,
+          text: JSON.stringify({
+            namespace: "Microsoft.Example",
+            resourceTypes: [
+              { resourceType: "widgets", apiVersions: ["2024-05-01-preview", "2023-09-01", "2024-01-01", "2022-01-01"] },
+              { resourceType: "gadgets", apiVersions: ["2020-01-01"] },
+            ],
+          }),
+        };
+      }
+      return { status: 200, text: "" };
+    };
+    const { pruned, notPrunable } = await pruneArmOrphans(desired, ctx(), http);
+    expect(pruned).toEqual([
+      { type: "Microsoft.Example/widgets", name: "a", deleted: true },
+      { type: "Microsoft.Example/widgets", name: "b", deleted: true },
     ]);
-    // Still not deleted — the apiVersion genuinely is not available. The fix is
-    // that it is now visible rather than that it is now deleted.
+    expect(notPrunable).toEqual([]);
+    // Newest STABLE wins over the newer preview.
+    expect(deletes).toEqual([
+      "http://x/subscriptions/sub/resourceGroups/rg/providers/Microsoft.Example/widgets/a?api-version=2024-01-01",
+      "http://x/subscriptions/sub/resourceGroups/rg/providers/Microsoft.Example/widgets/b?api-version=2024-01-01",
+    ]);
+    // One provider-metadata call per namespace per run, not per orphan.
+    expect(gets.filter((u) => u.includes("/providers/Microsoft.Example?api-version=2021-04-01"))).toHaveLength(1);
+    expect(gets.find((u) => u.includes("/providers/Microsoft.Example?"))).toBe(
+      "http://x/subscriptions/sub/providers/Microsoft.Example?api-version=2021-04-01",
+    );
+  });
+
+  test("no template, no registry entry, no provider metadata → still reported, never deleted", async () => {
+    const desired: ArmResource[] = [];
+    const deletes: string[] = [];
+    const providers: string[] = [];
+    const http = liveHttp(
+      [{ id: "/1", name: "mystery", type: "Microsoft.Nowhere/things", tags: { "managed-by": "chant" } }],
+      deletes,
+      providers,
+    );
+    const { pruned, notPrunable } = await pruneArmOrphans(desired, ctx(), http);
+    expect(pruned).toEqual([]);
+    expect(notPrunable).toEqual([{ type: "Microsoft.Nowhere/things", name: "mystery", reason: "no-api-version" }]);
     expect(deletes).toEqual([]);
+    // All three sources were tried; the last one is the provider endpoint.
+    expect(providers).toEqual(["http://x/subscriptions/sub/providers/Microsoft.Nowhere?api-version=2021-04-01"]);
+  });
+
+  test("providerApiVersion: preview-only types, missing types, and failed calls", async () => {
+    const cache = new Map<string, Map<string, string>>();
+    let calls = 0;
+    const http: AzHttp = async () => {
+      calls++;
+      return {
+        status: 200,
+        text: JSON.stringify({
+          resourceTypes: [{ resourceType: "previewOnly", apiVersions: ["2023-01-01-preview", "2024-01-01-preview"] }],
+        }),
+      };
+    };
+    expect(await providerApiVersion("Microsoft.P/previewOnly", ctx(), http, undefined, cache)).toBe("2024-01-01-preview");
+    expect(await providerApiVersion("Microsoft.P/absent", ctx(), http, undefined, cache)).toBeUndefined();
+    expect(calls).toBe(1);
+    expect(await providerApiVersion("notatype", ctx(), http)).toBeUndefined();
+    const failing: AzHttp = async () => { throw new Error("network"); };
+    expect(await providerApiVersion("Microsoft.P/previewOnly", ctx(), failing)).toBeUndefined();
+  });
+
+  test("azApply end to end: declare one storage account, apply, remove it, prune → deleted", async () => {
+    // The Floci-az style fake: PUT records the resource (with the ownership tag
+    // chant stamps), the group listing echoes what was recorded, DELETE removes
+    // it. The provider-metadata endpoint is absent, as on floci-az.
+    const store = new Map<string, { id: string; name: string; type: string; tags?: Record<string, string> }>();
+    const deletes: string[] = [];
+    const http: AzHttp = async (method, url, body) => {
+      const m = url.match(/\/providers\/([^/]+\/[^/]+)\/([^/?]+)\?api-version=([^&]+)$/);
+      if (method === "PUT" && m) {
+        const tags = (body as { tags?: Record<string, string> }).tags;
+        store.set(`${m[1]}/${m[2]}`, { id: `/${m[2]}`, name: m[2], type: m[1], tags });
+        return { status: 200, text: JSON.stringify({ properties: {} }) };
+      }
+      if (method === "DELETE" && m) {
+        deletes.push(url);
+        const had = store.delete(`${m[1]}/${m[2]}`);
+        return { status: had ? 200 : 404, text: "" };
+      }
+      if (method === "GET" && url.includes("/resources?")) {
+        return { status: 200, text: JSON.stringify({ value: [...store.values()] }) };
+      }
+      return { status: 404, text: "" };
+    };
+    const path = `/tmp/chant-1472-az-${process.pid}.json`;
+    const account = { type: "Microsoft.Storage/storageAccounts", apiVersion: "2023-01-01", name: "lastone" };
+    try {
+      writeFileSync(path, JSON.stringify({ resources: [account] }));
+      const first = await azApply({ templatePath: path, resourceGroup: "rg", endpoint: "http://x", prune: true }, undefined, http);
+      expect(first.applied).toEqual([{ type: account.type, name: "lastone" }]);
+      expect(store.size).toBe(1);
+
+      // Remove the only storage account from source: the template now declares
+      // no resource of that type at all.
+      writeFileSync(path, JSON.stringify({ resources: [] }));
+      const second = await azApply({ templatePath: path, resourceGroup: "rg", endpoint: "http://x", prune: true }, undefined, http);
+      expect(second.applied).toEqual([]);
+      expect(second.pruned).toEqual([{ type: account.type, name: "lastone", deleted: true }]);
+      expect(second.notPrunable).toEqual([]);
+      expect(store.size).toBe(0);
+      expect(deletes).toEqual([
+        `http://x/subscriptions/${"00000000-0000-0000-0000-000000000001"}/resourceGroups/rg/providers/Microsoft.Storage/storageAccounts/lastone?api-version=${lookupApiVersion(account.type)}`,
+      ]);
+      // Core's envelope agrees: nothing left over that could not be attempted.
+      expect(toApplyResult(second).notAttempted ?? []).toEqual([]);
+    } finally {
+      unlinkSync(path);
+    }
   });
 
   test("pruning one of several of a type still works — the case that hid this", async () => {

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

@@ -3,6 +3,8 @@ import { createHash } from "node:crypto";
 import { safeHeartbeat } from "@intentius/chant/op";
 import { hasOwnershipMarker, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
 import { AZURE_TAG_OWNERSHIP_KEYS } from "../../ownership";
+import { lookupApiVersion } from "../../serializer";
+import { compareApiDates } from "../../spec/api-versions";
 import {
   applyResult,
   type ApplyResult,
@@ -501,38 +503,96 @@ export interface AzNotPrunable {
   type: string;
   name: string;
   /**
-   * `no-api-version` — the resource is owned and undeclared, but its type is
-   * absent from the current template, which is the only place an `apiVersion`
-   * comes from. `deleteArmResource` cannot build a URL without one.
+   * `no-api-version` — the resource is owned and undeclared, but no apiVersion
+   * could be found for its type: the current template does not declare the
+   * type, the lexicon's pinned registry has no entry for it, and ARM's
+   * provider metadata listed no apiVersion for it (or the call failed).
+   * `deleteArmResource` cannot build a URL without one.
    */
   reason: "no-api-version";
 }
 
+/** The ARM provider-metadata apiVersion (`GET /subscriptions/{sub}/providers/{ns}`). */
+const PROVIDER_METADATA_API_VERSION = "2021-04-01";
+
+/**
+ * Resolve an apiVersion for a live resource type from ARM's provider metadata:
+ * `GET /subscriptions/{sub}/providers/{namespace}?api-version=2021-04-01`
+ * returns `resourceTypes[].apiVersions[]`. Picks the newest stable version,
+ * falling back to the newest preview when no stable one exists. One call per
+ * namespace per prune run; the result is memoised in `cache` so a group with
+ * many orphans of one provider costs one round trip. Returns `undefined` when
+ * the endpoint is unavailable (floci-az does not implement it) or the type is
+ * not listed.
+ */
+export async function providerApiVersion(
+  resourceType: string,
+  ctx: ArmEvalCtx,
+  http: AzHttp = defaultHttp,
+  signal?: AbortSignal,
+  cache: Map<string, Map<string, string>> = new Map(),
+): Promise<string | undefined> {
+  const slash = resourceType.indexOf("/");
+  if (slash < 0) return undefined;
+  const namespace = resourceType.slice(0, slash);
+  const typeName = resourceType.slice(slash + 1).toLowerCase();
+  let byType = cache.get(namespace.toLowerCase());
+  if (!byType) {
+    byType = new Map();
+    cache.set(namespace.toLowerCase(), byType);
+    const url = `${ctx.base}/subscriptions/${ctx.subscriptionId}/providers/${namespace}?api-version=${PROVIDER_METADATA_API_VERSION}`;
+    let res: { status: number; text: string };
+    try {
+      res = await http("GET", url, undefined, signal);
+    } catch {
+      return undefined;
+    }
+    if (res.status >= 300) return undefined;
+    let parsed: { resourceTypes?: Array<{ resourceType?: string; apiVersions?: string[] }> };
+    try {
+      parsed = JSON.parse(res.text);
+    } catch {
+      return undefined;
+    }
+    for (const rt of parsed.resourceTypes ?? []) {
+      if (!rt?.resourceType || !Array.isArray(rt.apiVersions) || rt.apiVersions.length === 0) continue;
+      const versions = rt.apiVersions.filter((v): v is string => typeof v === "string");
+      const stable = versions.filter((v) => !v.endsWith("-preview"));
+      const pool = stable.length > 0 ? stable : versions;
+      if (pool.length === 0) continue;
+      const newest = pool.reduce((a, b) => (compareApiDates(b, a) > 0 ? b : a));
+      byType.set(rt.resourceType.toLowerCase(), newest);
+    }
+  }
+  return byType.get(typeName);
+}
+
 /**
- * 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. Foreign (non-chant) resources are never touched.
+ * Owned-only prune: delete every chant-owned live resource in the group whose
+ * (evaluated) name is not declared in the template. Foreign (non-chant)
+ * resources are never touched.
+ *
+ * ## Where the apiVersion comes from (#1457, #1472)
  *
- * ## The type-left-the-template hole (#1457)
+ * `deleteArmResource` needs an `apiVersion`, and ARM's resource-group listing
+ * does not return one per resource. The template is the obvious source, but it
+ * only covers types it still declares: declare one storage account, apply,
+ * delete it from source, and the template has zero resources of that type.
+ * Keying the delete scope off the template alone made the last resource of a
+ * type a permanent orphan (#1457 made that a reported skip rather than a
+ * silent one).
  *
- * `byType` is keyed off the resources the template CURRENTLY declares, and the
- * `!entry` guard skipped any live resource of a type the template no longer
- * mentions — before `isChantOwned` was ever consulted.
+ * So the apiVersion is resolved in order:
  *
- * So: declare one storage account, apply, then delete it from source. The
- * template now has zero resources of that type, `byType` has no entry, and the
- * live account is skipped. It is owned, it is undeclared, and prune would never
- * touch it — on that run or any future one. **Prune the last resource of a type
- * and you created a permanent orphan.** Prune one of several and it works,
- * which is why it survived testing.
+ * 1. the template, when it still declares the type;
+ * 2. the lexicon's pinned per-provider registry (`lookupApiVersion`, the same
+ *    registry the serializer stamps into the template) — deterministic, no
+ *    extra call, covers every type the lexicon can emit;
+ * 3. ARM's provider metadata (`providerApiVersion`) — covers a type the
+ *    lexicon has never heard of, at one extra call per namespace per run.
  *
- * The guard cannot simply be removed: `deleteArmResource` needs an
- * `apiVersion`, and the template is the only source of one — ARM's
- * resource-group listing does not return it per resource. So the skip stays,
- * and is now REPORTED rather than silent: a permanent invisible orphan becomes
- * a permanent visible one, which is the difference between a bug and a known
- * limitation. Resolving it properly wants a per-type apiVersion source (the
- * provider metadata endpoint, or a lexicon-side map).
+ * Only when all three come up empty is the resource reported as
+ * `notPrunable: no-api-version`.
  *
  * This matters more since #1448, which routed `ApplyOp`'s `arm` target through
  * `azApply` — before that, the composite reached `--mode Complete` and never
@@ -555,24 +615,39 @@ export async function pruneArmOrphans(
     byType.set(r.type, entry);
   }
 
+  const providerCache = new Map<string, Map<string, string>>();
+  const resolveApiVersion = async (type: string): Promise<string | undefined> => {
+    const fromTemplate = byType.get(type)?.apiVersion;
+    if (fromTemplate) return fromTemplate;
+    let fromRegistry: string | undefined;
+    try {
+      fromRegistry = lookupApiVersion(type);
+    } catch {
+      // A missing registry is the serializer's problem to report; prune still
+      // has the provider metadata to fall back on.
+    }
+    if (fromRegistry) return fromRegistry;
+    return providerApiVersion(type, ctx, http, signal, providerCache);
+  };
+
   const pruned: Array<{ type: string; name: string; deleted: boolean }> = [];
   const notPrunable: AzNotPrunable[] = [];
   for (const item of await listGroupResources(ctx, http, signal)) {
     // Ownership first, so a foreign resource never reaches the report either —
     // it is not an orphan chant failed to prune, it is simply not chant's.
     if (!isChantOwned(item.tags)) continue;
-    const entry = byType.get(item.type);
-    if (!entry) {
+    if (byType.get(item.type)?.keep.has(item.name)) continue;
+    const apiVersion = await resolveApiVersion(item.type);
+    if (!apiVersion) {
       console.log(
-        `prune: ${item.type}/${item.name} is chant-owned and undeclared, but its type is absent ` +
-          `from the template so no apiVersion is available — not deleted`,
+        `prune: ${item.type}/${item.name} is chant-owned and undeclared, but no apiVersion is ` +
+          `available for its type (not in the template, the lexicon registry, or ARM provider metadata) — not deleted`,
       );
       notPrunable.push({ type: item.type, name: item.name, reason: "no-api-version" });
       continue;
     }
-    if (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);
+    const result = await deleteArmResource(item.type, item.name, apiVersion, ctx, http, signal);
     console.log(`pruned: ${item.type}/${item.name} (${ctx.base})`);
     pruned.push(result);
   }

package/src/op/activities/index.ts

@@ -23,6 +23,7 @@ export {
   azApply,
   azDelete,
   pruneArmOrphans,
+  providerApiVersion,
   toApplyResult,
   deleteArmResource,
   listGroupResources,

package/src/serializer-api-versions.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { execFileSync } from "child_process";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import {
+  azureSerializer,
+  apiVersionRegistryCandidates,
+  getApiVersion,
+  loadApiVersions,
+  resetApiVersionCache,
+} from "./serializer";
+import { PROVIDER_VERSION_OVERRIDES } from "./spec/api-versions";
+
+function makeEntity(entityType: string, props: Record<string, unknown> = {}): any {
+  return { [DECLARABLE_MARKER]: true, lexicon: "azure", entityType, kind: "resource", props };
+}
+
+// This file runs as ESM (package.json "type": "module"), so `require` is not
+// defined in module scope — the path #1581 broke.
+describe("apiVersion registry under ESM (#1581)", () => {
+  afterEach(() => resetApiVersionCache());
+
+  it("resolves pinned versions in a real ESM process (no require shim)", () => {
+    // vitest defines a module-scope `require`, which hid #1581. Run the
+    // serializer under plain tsx ESM, where `require` is undefined.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const script = [
+      `import { azureSerializer } from ${JSON.stringify(join(here, "serializer.ts"))};`,
+      `import { DECLARABLE_MARKER } from "@intentius/chant/declarable";`,
+      `const entities = new Map();`,
+      `entities.set("vm", { [DECLARABLE_MARKER]: true, lexicon: "azure", entityType: "Microsoft.Compute/virtualMachines", kind: "resource", props: { name: "vm", location: "eastus" } });`,
+      `const t = JSON.parse(azureSerializer.serialize(entities));`,
+      `console.log(JSON.stringify({ req: typeof require, apiVersion: t.resources[0].apiVersion }));`,
+    ].join("\n");
+    const dir = mkdtempSync(join(tmpdir(), "azure-esm-"));
+    try {
+      const file = join(dir, "probe.mts");
+      writeFileSync(file, script);
+      const out = execFileSync("npx", ["tsx", file], { cwd: here, encoding: "utf-8", timeout: 120_000 });
+      const { req, apiVersion } = JSON.parse(out.trim().split("\n").pop()!);
+      expect(req).toBe("undefined");
+      expect(PROVIDER_VERSION_OVERRIDES["Microsoft.Compute"]).toContain(apiVersion);
+      expect(apiVersion).not.toBe("2023-01-01");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("loads the registry via import.meta.url and uses pinned versions", () => {
+    const versions = loadApiVersions();
+    expect(versions.size).toBeGreaterThan(100);
+
+    // The pinned Microsoft.Compute version (spec/api-versions.ts) must reach
+    // the serializer, not the uniform 2023-01-01 fallback.
+    const computePins = PROVIDER_VERSION_OVERRIDES["Microsoft.Compute"];
+    expect(computePins?.length).toBeGreaterThan(0);
+    expect(computePins).toContain(versions.get("Microsoft.Compute/virtualMachines"));
+
+    const entities = new Map<string, any>();
+    entities.set("vm", makeEntity("Microsoft.Compute/virtualMachines", { name: "vm", location: "eastus" }));
+    entities.set("sa", makeEntity("Microsoft.Storage/storageAccounts", { name: "sa", location: "eastus" }));
+    const template = JSON.parse(azureSerializer.serialize(entities) as string);
+    const byType = Object.fromEntries(template.resources.map((r: any) => [r.type, r.apiVersion]));
+    expect(computePins).toContain(byType["Microsoft.Compute/virtualMachines"]);
+    expect(byType["Microsoft.Storage/storageAccounts"]).toBe(versions.get("Microsoft.Storage/storageAccounts"));
+    expect(byType["Microsoft.Storage/storageAccounts"]).not.toBe("2023-01-01");
+  });
+
+  it("throws loudly when no registry can be found", () => {
+    const dir = mkdtempSync(join(tmpdir(), "azure-apiv-"));
+    try {
+      expect(() => loadApiVersions(apiVersionRegistryCandidates(dir))).toThrow(/apiVersion registry not found/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws on an empty registry rather than falling back uniformly", () => {
+    const dir = mkdtempSync(join(tmpdir(), "azure-apiv-"));
+    try {
+      writeFileSync(join(dir, "meta.json"), "{}");
+      expect(() => loadApiVersions([join(dir, "meta.json")])).toThrow(/registry is empty/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps explicit overrides ahead of the registry", () => {
+    expect(getApiVersion("Microsoft.Authorization/roleAssignments")).toBe("2022-04-01");
+  });
+});