@intentius/chant-lexicon-azure 0.34.1 → 0.37.0

package/dist/api/read-client.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The native Azure read transport (#1212) — the read half of what
+ * `op/activities/az-apply.ts` already does for writes.
+ *
+ * Azure's observers shelled `az resource show`, once per declared entity,
+ * serially, and read the failure out of the CLI's stderr. The applier does
+ * not: `azApply` PUTs each resource at its ARM URL over `fetch`, honours an
+ * endpoint override, and is injectable for tests. Since `az resource show`
+ * returns the ARM JSON that endpoint would have returned anyway, this is
+ * transport only — the payload the readers normalize is unchanged, which is
+ * what made Azure the cheapest of the three observers to move.
+ *
+ * ## Signing
+ *
+ * Requests are unsigned, exactly like `azApply`'s. That is what makes the
+ * emulator lane work with no credential plumbing, and the reason this is
+ * scoped to floci-az rather than announced as a real-ARM read path: real ARM
+ * wants a bearer token. The `az` CLI path remains for a signed read until
+ * token acquisition lands here.
+ */
+import { type AzHttp } from "../op/activities/az-apply.js";
+export interface AzureReadClientOptions {
+    /** Endpoint override (floci-az `http://localhost:4577`). Omit for real ARM. */
+    endpoint?: string;
+    subscriptionId?: string;
+    /** Resource group the environment maps to. */
+    resourceGroup: string;
+    http?: AzHttp;
+    signal?: AbortSignal;
+}
+/** A failed read, carrying the status and ARM's own error code where it sent one. */
+export declare class AzureReadError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+/** True when the read failed only because the resource is not there. */
+export declare function isNotFound(err: unknown): boolean;
+/** The ARM URL for one resource in the group — the same shape the applier PUTs to. */
+export declare function armResourceReadUrl(options: AzureReadClientOptions, type: string, name: string, apiVersion?: string): string;
+/** One resource as ARM returns it. */
+export interface ArmResourceBody {
+    id?: string;
+    name?: string;
+    type?: string;
+    location?: string;
+    tags?: Record<string, string>;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** GET one resource. Throws {@link AzureReadError}; 404 means absent, which callers check with {@link isNotFound}. */
+export declare function getResource(options: AzureReadClientOptions, type: string, name: string, apiVersion?: string): Promise<ArmResourceBody>;
+//# sourceMappingURL=read-client.d.ts.map

package/dist/api/read-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-client.d.ts","sourceRoot":"","sources":["../../src/api/read-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,2BAA2B,CAAC;AASxD,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qFAAqF;AACrF,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBAFtB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAKzB;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEhD;AAgBD,sFAAsF;AACtF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,SAAsB,GAC/B,MAAM,CAIR;AAwBD,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,sHAAsH;AACtH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,sBAAsB,EAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CAa1B"}

package/dist/codegen/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqEH;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9E"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyFH;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9E"}

package/dist/deep-observe.d.ts

@@ -42,9 +42,12 @@
  *
  * ## Nothing here talks to real Azure on its own terms
  *
- * `node:child_process` `exec`, exactly like the thin path — no ARM SDK, no
- * ambient token. Every test replaces `child_process.exec`.
+ * ARM over the applier's own transport (`./api/read-client.ts`), exactly like
+ * the thin path (#1212) — no CLI, no ARM SDK, no ambient token. The payload is
+ * the same ARM JSON `az resource show` was relaying, so the normalization below
+ * is untouched by the move.
  */
+import type { AzHttp } from "./op/activities/az-apply.js";
 import type { DeepNormalizationHooks, DeepObservationResult } from "@intentius/chant/lexicon";
 /**
  * Server-populated wherever they appear — matched on the final path segment,
@@ -76,6 +79,8 @@ export declare const AZURE_SERVICE_DEFAULTS: Record<string, Record<string, unkno
  */
 export declare const azureDeepNormalizationHooks: DeepNormalizationHooks;
 export interface AzureDeepObserveOptions {
+    /** Injectable transport, mirroring `azApply`'s — tests reach the reader with no network. */
+    http?: AzHttp;
     environment: string;
     entityNames: string[];
     entities: Map<string, {

package/dist/deep-observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAIH,OAAO,KAAK,EAGV,sBAAsB,EACtB,qBAAqB,EAGtB,MAAM,0BAA0B,CAAC;AAkDlC;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAKpD,CAAC;AAUH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI1E,CAAC;AAuCF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAiCzC,CAAC;AAIF,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAgEhC"}
+{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAGV,sBAAsB,EACtB,qBAAqB,EAGtB,MAAM,0BAA0B,CAAC;AAiDlC;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAKpD,CAAC;AAUH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI1E,CAAC;AAuCF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAiCzC,CAAC;AAIF,MAAM,WAAW,uBAAuB;IACtC,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAkEhC"}

package/dist/describe-resources.d.ts

@@ -1,10 +1,18 @@
 /**
- * Live introspection of an Azure resource group via the az CLI.
+ * Live introspection of an Azure resource group over ARM (#1212).
  *
- * For each declared Azure entity, runs:
- *   az resource show --resource-group <env> --name <name> --resource-type <type> -o json
+ * For each declared Azure entity, GETs
+ *   {endpoint}/subscriptions/{sub}/resourceGroups/{env}/providers/{type}/{name}
  *
- * and maps the response to a ResourceMetadata entry keyed by chant entity name
+ * on the applier's own transport (`./api/read-client.ts`, which is
+ * `az-apply.ts`'s client pointed at the read side) rather than shelling
+ * `az resource show`. The payload is the same ARM JSON either way — the CLI was
+ * only ever relaying it — so this is transport, not translation: no CLI to
+ * spawn, reads that run concurrently, failures carrying ARM's own error code,
+ * and an emulator override that reaches floci-az the same way every other
+ * lexicon's does.
+ *
+ * The response maps to a ResourceMetadata entry keyed by chant entity name
  * (using props.name from #39's entity-prop pass-through). The environment
  * argument is treated as the Azure resource group name.
  *
@@ -17,6 +25,7 @@
  * are holes for the same reason.
  */
 import type { ObservationResult, UnobservedReason } from "@intentius/chant/lexicon";
+import type { AzHttp } from "./op/activities/az-apply.js";
 /**
  * Top-level ARM type — i.e. exactly one `/` separating provider from kind.
  * Nested types like `Microsoft.Storage/storageAccounts/blobServices` need a
@@ -39,6 +48,19 @@ export declare function classifyAzFailure(err: unknown): {
     reason: UnobservedReason;
     detail: string;
 };
+/**
+ * Classify an ARM failure off its own error code (#1212).
+ *
+ * The CLI classifier above matched on prose because stderr was all it had.
+ * ARM sends `{ error: { code, message } }`, so the code is the signal and the
+ * message is only for the human — the same distinction the AWS read client
+ * makes. Kept beside `classifyAzFailure` rather than replacing it: the CLI
+ * path still exists for a signed read against real ARM.
+ */
+export declare function classifyArmFailure(err: unknown): {
+    reason: UnobservedReason;
+    detail: string;
+};
 export declare function describeResources(options: {
     environment: string;
     buildOutput: string;
@@ -47,5 +69,7 @@ export declare function describeResources(options: {
         entityType: string;
         props: Record<string, unknown>;
     }>;
+    /** Injectable transport, mirroring `azApply`'s — tests reach the reader with no network. */
+    http?: AzHttp;
 }): Promise<ObservationResult>;
 //# sourceMappingURL=describe-resources.d.ts.map

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAyBxH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAkC9H;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2E7B"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGxH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAUvD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAkC9H;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAmB7F;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+E7B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "a4aa3da45689da7b4702ca100a9aa2ff356a61483329179d5eb69648e185df01",
+    "manifest.json": "bc503f53d6bf2deade950968028c37335319c8868a0f7512e260d20f10dbfeed",
     "meta.json": "051fb4ee43f7de48a36f1abc59c8ff5207c3b75aa28f13db6440b9f5b0337605",
     "types/index.d.ts": "617a6de433bd92a126170a7f5ae903d6d7aa83fbb0b57169d3450b5a13e72e0d",
     "rules/hardcoded-location.ts": "a9b1d1cec93f2ca9c5206641f53fc9621cefcfd2c00b3ab89c194b30a75fa949",
@@ -33,5 +33,5 @@
     "skills/chant-azure-patterns.md": "1a3bacfac612826b77332d2692a59195638db9f1b5e8ea2eda7579621d25f603",
     "skills/chant-azure-aks.md": "2d4e0098c1a22b54ffadd410564d9df0f3a04cb4eb7c6261f20ae33106e7aca8"
   },
-  "composite": "ea9d89a3dd9d818fe6dbb3400c696232c2a74e6bf8af1c3af9296ea5fbb9e865"
+  "composite": "dff5b3422ce14b471818bb6b2799870cb3ce0d55d6caae6e0fc2164dce02830b"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "azure",
-  "version": "0.34.1",
+  "version": "0.37.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Azure",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-azure",
-  "version": "0.34.1",
+  "version": "0.37.0",
   "description": "Azure lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -74,7 +74,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.34.1",
+    "@intentius/chant": "^0.37.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/read-client.ts

@@ -0,0 +1,136 @@
+/**
+ * The native Azure read transport (#1212) — the read half of what
+ * `op/activities/az-apply.ts` already does for writes.
+ *
+ * Azure's observers shelled `az resource show`, once per declared entity,
+ * serially, and read the failure out of the CLI's stderr. The applier does
+ * not: `azApply` PUTs each resource at its ARM URL over `fetch`, honours an
+ * endpoint override, and is injectable for tests. Since `az resource show`
+ * returns the ARM JSON that endpoint would have returned anyway, this is
+ * transport only — the payload the readers normalize is unchanged, which is
+ * what made Azure the cheapest of the three observers to move.
+ *
+ * ## Signing
+ *
+ * Requests are unsigned, exactly like `azApply`'s. That is what makes the
+ * emulator lane work with no credential plumbing, and the reason this is
+ * scoped to floci-az rather than announced as a real-ARM read path: real ARM
+ * wants a bearer token. The `az` CLI path remains for a signed read until
+ * token acquisition lands here.
+ */
+
+import { type AzHttp } from "../op/activities/az-apply";
+
+/** Default ARM host, matching the applier's. */
+const DEFAULT_ENDPOINT = "https://management.azure.com";
+/** floci-az's fixed local subscription, matching the applier's. */
+const DEFAULT_SUBSCRIPTION = "00000000-0000-0000-0000-000000000001";
+/** Generic ARM resource read, adequate for every top-level type chant declares. */
+const DEFAULT_API_VERSION = "2021-04-01";
+
+export interface AzureReadClientOptions {
+  /** Endpoint override (floci-az `http://localhost:4577`). Omit for real ARM. */
+  endpoint?: string;
+  subscriptionId?: string;
+  /** Resource group the environment maps to. */
+  resourceGroup: string;
+  http?: AzHttp;
+  signal?: AbortSignal;
+}
+
+/** A failed read, carrying the status and ARM's own error code where it sent one. */
+export class AzureReadError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code?: string,
+  ) {
+    super(message);
+    this.name = "AzureReadError";
+  }
+}
+
+/** True when the read failed only because the resource is not there. */
+export function isNotFound(err: unknown): boolean {
+  return err instanceof AzureReadError && err.status === 404;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+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() };
+};
+
+/** The ARM URL for one resource in the group — the same shape the applier PUTs to. */
+export function armResourceReadUrl(
+  options: AzureReadClientOptions,
+  type: string,
+  name: string,
+  apiVersion = DEFAULT_API_VERSION,
+): string {
+  const base = (options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
+  const subscription = options.subscriptionId ?? DEFAULT_SUBSCRIPTION;
+  return `${base}/subscriptions/${subscription}/resourceGroups/${options.resourceGroup}/providers/${type}/${name}?api-version=${apiVersion}`;
+}
+
+/**
+ * ARM's error envelope is `{ error: { code, message } }`. Reading the code
+ * rather than the prose is the point of moving off the CLI: `ResourceNotFound`
+ * is a fact, "(ResourceNotFound) The Resource … was not found" is a sentence
+ * that changes between CLI versions.
+ */
+function readError(status: number, text: string): AzureReadError {
+  let code: string | undefined;
+  let message = `ARM read failed with HTTP ${status}`;
+  try {
+    const body: unknown = JSON.parse(text);
+    const error = isRecord(body) ? body.error : undefined;
+    if (isRecord(error)) {
+      if (typeof error.code === "string") code = error.code;
+      if (typeof error.message === "string") message = error.message;
+    }
+  } catch {
+    // A non-JSON body from a proxy or a gateway — the status is all there is.
+  }
+  return new AzureReadError(message, status, code);
+}
+
+/** One resource as ARM returns it. */
+export interface ArmResourceBody {
+  id?: string;
+  name?: string;
+  type?: string;
+  location?: string;
+  tags?: Record<string, string>;
+  properties?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/** GET one resource. Throws {@link AzureReadError}; 404 means absent, which callers check with {@link isNotFound}. */
+export async function getResource(
+  options: AzureReadClientOptions,
+  type: string,
+  name: string,
+  apiVersion?: string,
+): Promise<ArmResourceBody> {
+  const http = options.http ?? defaultHttp;
+  const url = armResourceReadUrl(options, type, name, apiVersion);
+  const res = await http("GET", url, undefined, options.signal);
+  if (res.status >= 300) throw readError(res.status, res.text);
+  try {
+    const body: unknown = JSON.parse(res.text);
+    if (!isRecord(body)) throw new AzureReadError(`unparseable ARM body for ${type}/${name}`, res.status);
+    return body as ArmResourceBody;
+  } catch (err) {
+    if (err instanceof AzureReadError) throw err;
+    throw new AzureReadError(`unparseable ARM body for ${type}/${name}`, res.status);
+  }
+}

package/src/codegen/docs.ts

@@ -72,6 +72,26 @@ const docsConfig: DocsConfig = {
   overview,
   outputFormat,
   serviceFromType,
+  // `lint-rules` below is the rules documentation; the generated `rules` table
+  // would duplicate it and land in no sidebar (#1312). aws, k8s, gitlab and
+  // github already suppress it for the same reason.
+  suppressPages: ["rules"],
+  // These pages are hand-written files under docs/src/content/docs/. The
+  // pipeline preserves pages it did not emit, but Starlight has no
+  // auto-discovery, so without an entry here they are reachable only by URL —
+  // which is what had happened to all ten of them.
+  sidebarExtra: [
+    { label: "Getting Started", slug: "getting-started" },
+    { label: "Resources", slug: "resources" },
+    { label: "Parameters & Outputs", slug: "parameters-outputs" },
+    { label: "Composites", slug: "composites" },
+    { label: "Linked Templates", slug: "linked-templates" },
+    { label: "Lint Rules", slug: "lint-rules" },
+    { label: "Importing ARM Templates", slug: "importing" },
+    { label: "Deploying to AKS", slug: "aks-kubernetes" },
+    { label: "Examples", slug: "examples" },
+    { label: "AI Skills", slug: "skills" },
+  ],
 };
 
 /**

package/src/deep-observe.test.ts

@@ -2,40 +2,51 @@
  * Azure deep observation (#1086) — the azure row of the deep-observe
  * contract (#1014).
  *
- * `node:child_process`'s `exec` is mocked, exactly like
- * describe-resources.test.ts — no ARM SDK, no ambient `az login` session,
- * nothing reaches a network.
+ * The transport is faked, exactly like describe-resources.test.ts (#1212) — no
+ * CLI, no ARM SDK, no ambient `az login` session, nothing reaches a network.
+ * `http` is injected where the reader is called directly, and `fetch` is
+ * stubbed where the plugin builds its own client.
  */
-import { describe, test, expect, vi, beforeEach } from "vitest";
-
-const execMock = vi.fn();
-vi.mock("node:child_process", async () => {
-  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
-  return {
-    ...actual,
-    exec: (cmd: string, cb: (err: Error | null, out: { stdout: string; stderr: string }) => void) => {
-      Promise.resolve(execMock(cmd)).then(
-        (out) => cb(null, out as { stdout: string; stderr: string }),
-        (err) => cb(err as Error, { stdout: "", stderr: "" }),
-      );
-    },
-  };
-});
+import { describe, test, expect, vi, afterEach } from "vitest";
+
+/** For the paths that go through the plugin, which builds its own transport. */
+const stubArmFetch = (response: { status: number; text: string }): void => {
+  vi.spyOn(globalThis, "fetch").mockImplementation((async () => ({
+    status: response.status,
+    text: () => Promise.resolve(response.text),
+  })) as unknown as typeof fetch);
+};
 
 const { azurePlugin } = await import("./plugin");
 const { observeResourcesDeepAzure, azureDeepNormalizationHooks } = await import("./deep-observe");
 const { deepDiffForLexicon } = await import("@intentius/chant/lifecycle/deep-observe");
 const { normalizeDeepObservation, normalizeDeepProperties } = await import("@intentius/chant/deep-observation");
 
-const ok = (body: Record<string, unknown>) => Promise.resolve({ stdout: JSON.stringify(body), stderr: "" });
-const fail = (stderr: string) => Promise.reject(Object.assign(new Error("az failed"), { stderr }));
+/** An ARM 200, in place of the CLI stdout this used to fake (#1212). */
+const ok = (body: Record<string, unknown>) => ({ status: 200, text: JSON.stringify(body) });
+/** ARM's error envelope — the code is the signal, not the prose. */
+const armError = (status: number, code: string, message = code) => ({
+  status,
+  text: JSON.stringify({ error: { code, message } }),
+});
+
+/** Routes by the resource name in the ARM URL, which is where it lives now. */
+function armFake(route: (name: string) => { status: number; text: string }) {
+  const urls: string[] = [];
+  const http = async (_method: string, url: string) => {
+    urls.push(url);
+    const name = decodeURIComponent(url.split("?")[0].split("/").pop() ?? "");
+    return route(name);
+  };
+  return { http, urls };
+}
 
 const entities = (
   record: Record<string, { entityType: string; props: Record<string, unknown> }>,
 ): Map<string, { entityType: string; props: Record<string, unknown> }> => new Map(Object.entries(record));
 
-beforeEach(() => {
-  execMock.mockReset();
+afterEach(() => {
+  vi.restoreAllMocks();
 });
 
 describe("the azure noise rules", () => {
@@ -126,11 +137,9 @@ describe("the azure noise rules", () => {
 });
 
 describe("observeResourcesDeepAzure", () => {
-  test("queries az resource show with rg + name + type and flattens properties.* onto the top level", async () => {
-    let receivedCmd = "";
-    execMock.mockImplementation((cmd: string) => {
-      receivedCmd = cmd;
-      return ok({
+  test("reads the resource over ARM and flattens properties.* onto the top level", async () => {
+    const fake = armFake(() =>
+      ok({
         id: "/subscriptions/sub/resourceGroups/prod-rg/providers/Microsoft.Storage/storageAccounts/mydata",
         name: "mydata",
         type: "Microsoft.Storage/storageAccounts",
@@ -139,21 +148,20 @@ describe("observeResourcesDeepAzure", () => {
         etag: "\"abc\"",
         systemData: { createdBy: "someone@example.com" },
         properties: { provisioningState: "Succeeded", minimumTlsVersion: "TLS1_2", allowBlobPublicAccess: false },
-      });
-    });
+      }),
+    );
 
     const result = normalizeDeepObservation(
       await observeResourcesDeepAzure({
         environment: "prod-rg",
         entityNames: ["dataAccount"],
         entities: entities({ dataAccount: { entityType: "Microsoft.Storage/storageAccounts", props: { name: "mydata" } } }),
+        http: fake.http,
       }),
     );
 
-    expect(receivedCmd).toContain("az resource show");
-    expect(receivedCmd).toContain("--resource-group prod-rg");
-    expect(receivedCmd).toContain("--name mydata");
-    expect(receivedCmd).toContain("--resource-type Microsoft.Storage/storageAccounts");
+    expect(fake.urls[0]).toContain("/resourceGroups/prod-rg/");
+    expect(fake.urls[0]).toContain("/providers/Microsoft.Storage/storageAccounts/mydata");
 
     // id/type/etag/systemData/provisioningState never reach the tree at all —
     // no declared tree yet, so this is what a one-sided read looks like.
@@ -165,24 +173,26 @@ describe("observeResourcesDeepAzure", () => {
   });
 
   test("a resource not found leaves the entity out — a confirmed absence", async () => {
-    execMock.mockImplementation(() => fail("ResourceNotFound: ..."));
+    const fake = armFake(() => armError(404, "ResourceNotFound", "not found"));
     const result = normalizeDeepObservation(
       await observeResourcesDeepAzure({
         environment: "prod-rg",
         entityNames: ["missing"],
         entities: entities({ missing: { entityType: "Microsoft.Storage/storageAccounts", props: { name: "missing" } } }),
+        http: fake.http,
       }),
     );
     expect(result).toEqual({ resources: {}, unobserved: {} });
   });
 
-  test("an expired az login is a hole, not an absence", async () => {
-    execMock.mockImplementation(() => fail("Please run 'az login' to setup account."));
+  test("a refused credential is a hole, not an absence", async () => {
+    const fake = armFake(() => armError(401, "AuthenticationFailed", "Authentication failed."));
     const result = normalizeDeepObservation(
       await observeResourcesDeepAzure({
         environment: "prod-rg",
         entityNames: ["acct"],
         entities: entities({ acct: { entityType: "Microsoft.Storage/storageAccounts", props: { name: "acct" } } }),
+        http: fake.http,
       }),
     );
     expect(result.resources).toEqual({});
@@ -190,40 +200,46 @@ describe("observeResourcesDeepAzure", () => {
   });
 
   test("a nested ARM type is unsupported-kind, never absent — az resource show is never called", async () => {
+    const fake = armFake(() => ok({}));
     const result = normalizeDeepObservation(
       await observeResourcesDeepAzure({
         environment: "prod-rg",
         entityNames: ["nested"],
         entities: entities({ nested: { entityType: "Microsoft.Storage/storageAccounts/blobServices", props: { name: "default" } } }),
+        http: fake.http,
       }),
     );
     expect(result.resources).toEqual({});
     expect(result.unobserved.nested.reason).toBe("unsupported-kind");
-    expect(execMock).not.toHaveBeenCalled();
+    expect(fake.urls).toEqual([]);
   });
 
   test("a non-ARM entity type is unsupported-kind — no ARM type to query", async () => {
+    const fake = armFake(() => ok({}));
     const result = normalizeDeepObservation(
       await observeResourcesDeepAzure({
         environment: "prod-rg",
         entityNames: ["x"],
         entities: entities({ x: { entityType: "AWS::S3::Bucket", props: { name: "x" } } }),
+        http: fake.http,
       }),
     );
     expect(result.unobserved.x.reason).toBe("unsupported-kind");
-    expect(execMock).not.toHaveBeenCalled();
+    expect(fake.urls).toEqual([]);
   });
 
   test("an entity with no name is a hole — nothing was queried", async () => {
+    const fake = armFake(() => ok({}));
     const result = normalizeDeepObservation(
       await observeResourcesDeepAzure({
         environment: "prod-rg",
         entityNames: ["broken"],
         entities: entities({ broken: { entityType: "Microsoft.Storage/storageAccounts", props: {} } }),
+        http: fake.http,
       }),
     );
     expect(result.unobserved.broken.reason).toBe("read-failed");
-    expect(execMock).not.toHaveBeenCalled();
+    expect(fake.urls).toEqual([]);
   });
 });
 
@@ -251,9 +267,12 @@ describe("end to end: declared + mutated live + baseline (#1086)", () => {
   });
 
   const wireMocks = (): void => {
-    execMock.mockImplementation((cmd: string) => {
-      if (cmd.includes("--name mydata")) {
-        return ok({
+    vi.spyOn(globalThis, "fetch").mockImplementation((async (url: string) => {
+      const name = decodeURIComponent(url.split("?")[0].split("/").pop() ?? "");
+      const respond = (r: { status: number; text: string }) =>
+        ({ status: r.status, text: () => Promise.resolve(r.text) });
+      if (name === "mydata") {
+        return respond(ok({
           id: "/subscriptions/sub/resourceGroups/prod/providers/Microsoft.Storage/storageAccounts/mydata",
           name: "mydata",
           location: "eastus",
@@ -269,10 +288,10 @@ describe("end to end: declared + mutated live + baseline (#1086)", () => {
             // GENUINE: somebody flipped this in the portal.
             allowBlobPublicAccess: true,
           },
-        });
+        }));
       }
-      if (cmd.includes("--name core-vnet")) {
-        return ok({
+      if (name === "core-vnet") {
+        return respond(ok({
           id: "/subscriptions/sub/resourceGroups/prod/providers/Microsoft.Network/virtualNetworks/core-vnet",
           name: "core-vnet",
           location: "eastus",
@@ -282,13 +301,13 @@ describe("end to end: declared + mutated live + baseline (#1086)", () => {
             // NOISE: same two prefixes, different order.
             addressSpace: { addressPrefixes: ["10.1.0.0/16", "10.0.0.0/16"] },
           },
-        });
+        }));
       }
-      if (cmd.includes("--name secure-acct")) {
-        return fail("Please run 'az login' to setup account.");
+      if (name === "secure-acct") {
+        return respond(armError(401, "AuthenticationFailed", "Authentication failed."));
       }
-      return fail("unexpected call");
-    });
+      return respond(armError(400, "BadRequest", `unexpected call for ${name}`));
+    }) as unknown as typeof fetch);
   };
 
   const baseline = {
@@ -331,9 +350,9 @@ describe("end to end: declared + mutated live + baseline (#1086)", () => {
         name: "blobServices",
         type: "Microsoft.Storage/storageAccounts/blobServices",
         reason: "unsupported-kind",
-        detail: "az resource show does not accept a nested ARM type; chant never queried this resource",
+        detail: "a nested ARM type needs a different read path; chant never queried this resource",
       },
-      { name: "secureAcct", type: "Microsoft.Storage/storageAccounts", reason: "no-credentials", detail: "Please run 'az login' to setup account." },
+      { name: "secureAcct", type: "Microsoft.Storage/storageAccounts", reason: "no-credentials", detail: "AuthenticationFailed: Authentication failed." },
     ]);
   });
 
@@ -358,15 +377,19 @@ describe("end to end: declared + mutated live + baseline (#1086)", () => {
   });
 
   test("a whole-lexicon failure is a hole for every declared entity, not a clean report", async () => {
-    execMock.mockImplementation(() => fail("Unable to locate credentials"));
+    stubArmFetch(armError(401, "AuthenticationFailed", "Authentication failed."));
     const result = await deepDiffForLexicon(azurePlugin, { environment: "prod", buildOutput: "", entities: declared });
     expect(result.drifted).toEqual([]);
-    // blobServices is still unsupported-kind — az resource show is never even
-    // called for it, so a broken CLI doesn't change its verdict.
+    // blobServices is still unsupported-kind — it is never addressed at all, so
+    // a refused transport doesn't change its verdict.
     expect(result.unobserved.map((u) => u.name).sort()).toEqual(["blobServices", "dataAccount", "secureAcct", "vnet"]);
     expect(result.unobserved.find((u) => u.name === "blobServices")?.reason).toBe("unsupported-kind");
+    // `no-credentials`, not the `read-failed` the CLI path reported: ARM sends
+    // `AuthenticationFailed` as a code, where the CLI's prose ("Unable to
+    // locate credentials") matched none of the patterns and fell through to the
+    // generic verdict. The code makes the credential case legible (#1212).
     expect(
-      result.unobserved.filter((u) => u.name !== "blobServices").every((u) => u.reason === "read-failed"),
+      result.unobserved.filter((u) => u.name !== "blobServices").every((u) => u.reason === "no-credentials"),
     ).toBe(true);
   });
 });

package/src/deep-observe.ts

@@ -42,12 +42,15 @@
  *
  * ## Nothing here talks to real Azure on its own terms
  *
- * `node:child_process` `exec`, exactly like the thin path — no ARM SDK, no
- * ambient token. Every test replaces `child_process.exec`.
+ * ARM over the applier's own transport (`./api/read-client.ts`), exactly like
+ * the thin path (#1212) — no CLI, no ARM SDK, no ambient token. The payload is
+ * the same ARM JSON `az resource show` was relaying, so the normalization below
+ * is untouched by the move.
  */
 
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
+import { boundedConcurrently } from "@intentius/chant/observation";
+import { getResource, isNotFound, type AzureReadClientOptions } from "./api/read-client";
+import type { AzHttp } from "./op/activities/az-apply";
 import type {
   DeepArrayElement,
   DeepNode,
@@ -57,9 +60,8 @@ import type {
   UnobservedEntity,
 } from "@intentius/chant/lexicon";
 import { deepObservation, normalizeDeepProperties } from "@intentius/chant/deep-observation";
-import { classifyAzFailure, isTopLevelType } from "./describe-resources";
+import { classifyArmFailure, isTopLevelType } from "./describe-resources";
 
-const execAsync = promisify(exec);
 
 /** The full `az resource show -o json` shape this reader reads (a superset of the thin path's `AzResourceShowResponse`). */
 interface ArmResourceShowResponse {
@@ -227,6 +229,8 @@ export const azureDeepNormalizationHooks: DeepNormalizationHooks = {
 // ── The reader ───────────────────────────────────────────────────────────────
 
 export interface AzureDeepObserveOptions {
+  /** Injectable transport, mirroring `azApply`'s — tests reach the reader with no network. */
+  http?: AzHttp;
   environment: string;
   entityNames: string[];
   entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
@@ -245,6 +249,14 @@ export async function observeResourcesDeepAzure(
 ): Promise<DeepObservationResult> {
   const resources: Record<string, DeepResourceObservation> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
+  const readable: Array<{ entityName: string; entityType: string; name: string }> = [];
+
+  const client: AzureReadClientOptions = {
+    resourceGroup: options.environment,
+    ...(process.env.AZURE_ENDPOINT_URL ? { endpoint: process.env.AZURE_ENDPOINT_URL } : {}),
+    ...(process.env.AZURE_SUBSCRIPTION_ID ? { subscriptionId: process.env.AZURE_SUBSCRIPTION_ID } : {}),
+    ...(options.http ? { http: options.http } : {}),
+  };
 
   for (const [entityName, { entityType, props }] of options.entities) {
     if (!entityType.startsWith("Microsoft.")) {
@@ -260,7 +272,7 @@ export async function observeResourcesDeepAzure(
       unobserved[entityName] = {
         type: entityType,
         reason: "unsupported-kind",
-        detail: "az resource show does not accept a nested ARM type; chant never queried this resource",
+        detail: "a nested ARM type needs a different read path; chant never queried this resource",
       };
       continue;
     }
@@ -275,17 +287,12 @@ export async function observeResourcesDeepAzure(
       continue;
     }
 
-    const cmd = [
-      "az", "resource", "show",
-      "--resource-group", options.environment,
-      "--name", name,
-      "--resource-type", entityType,
-      "-o", "json",
-    ].join(" ");
+    readable.push({ entityName, entityType, name });
+  }
 
+  await boundedConcurrently(readable, async ({ entityName, entityType, name }) => {
     try {
-      const { stdout } = await execAsync(cmd);
-      const obj: ArmResourceShowResponse = JSON.parse(stdout);
+      const obj = (await getResource(client, entityType, name)) as ArmResourceShowResponse;
       resources[entityName] = {
         type: entityType,
         physicalId: obj.id,
@@ -298,12 +305,11 @@ export async function observeResourcesDeepAzure(
     } catch (err) {
       // Not-found leaves the entity out (absence, same as the thin path).
       // Auth/binding/other failures are holes so they can't become creates.
-      const outcome = classifyAzFailure(err);
-      if (!outcome.absent) {
-        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
-      }
+      if (isNotFound(err)) return;
+      const outcome = classifyArmFailure(err);
+      unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
     }
-  }
+  });
 
   return deepObservation(resources, unobserved);
 }

package/src/describe-resources.test.ts

@@ -1,54 +1,53 @@
-import { describe, test, expect, vi, beforeEach } from "vitest";
-
-const execMock = vi.fn();
-vi.mock("node:child_process", async () => {
-  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
-  return { ...actual, exec: (cmd: string, cb: (err: Error | null, out: { stdout: string; stderr: string }) => void) => {
-    Promise.resolve(execMock(cmd)).then(
-      (out) => cb(null, out),
-      (err) => cb(err as Error, { stdout: "", stderr: "" }),
-    );
-  } };
-});
+import { describe, test, expect, vi } from "vitest";
 
 const { describeResources } = await import("./describe-resources");
 
+/** An ARM response, in place of the CLI stdout this used to fake (#1212). */
+const armOk = (body: unknown) => ({ status: 200, text: JSON.stringify(body) });
+/** ARM's error envelope: the code is the signal, the message is for the human. */
+const armError = (status: number, code: string, message: string) => ({
+  status,
+  text: JSON.stringify({ error: { code, message } }),
+});
+
+/** Records every ARM URL the reader asked for, so a test can assert the address. */
+function httpFake(respond: (url: string) => { status: number; text: string }) {
+  const urls: string[] = [];
+  const http = async (_method: string, url: string) => {
+    urls.push(url);
+    return respond(url);
+  };
+  return { http, urls };
+}
+
 function makeEntities(records: Array<{ name: string; entityType: string; props: Record<string, unknown> }>) {
   return new Map(records.map((r) => [r.name, { entityType: r.entityType, props: r.props }]));
 }
 
 describe("azure describeResources", () => {
-  beforeEach(() => {
-    execMock.mockReset();
-  });
-
   test("queries az resource show with rg + name + type and maps response", async () => {
-    let receivedCmd = "";
-    execMock.mockImplementation((cmd: string) => {
-      receivedCmd = cmd;
-      return {
-        stdout: JSON.stringify({
+    const fake = httpFake(() =>
+      armOk({
           id: "/subscriptions/sub/resourceGroups/prod-rg/providers/Microsoft.Storage/storageAccounts/mydata",
           name: "mydata",
           type: "Microsoft.Storage/storageAccounts",
           location: "eastus",
           properties: { provisioningState: "Succeeded" },
-          tags: { env: "prod" },
-        }),
-        stderr: "",
-      };
-    });
+        tags: { env: "prod" },
+      }),
+    );
 
     const entities = makeEntities([
       { name: "dataAccount", entityType: "Microsoft.Storage/storageAccounts", props: { name: "mydata" } },
     ]);
 
-    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["dataAccount"], entities });
+    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["dataAccount"], entities, http: fake.http });
 
-    expect(receivedCmd).toContain("az resource show");
-    expect(receivedCmd).toContain("--resource-group prod-rg");
-    expect(receivedCmd).toContain("--name mydata");
-    expect(receivedCmd).toContain("--resource-type Microsoft.Storage/storageAccounts");
+    // The resource group is the environment, and the type and name address the
+    // resource — the same URL shape the applier PUTs to.
+    expect(fake.urls[0]).toContain("/resourceGroups/prod-rg/");
+    expect(fake.urls[0]).toContain("/providers/Microsoft.Storage/storageAccounts/mydata");
+    expect(fake.urls[0]).toContain("api-version=");
 
     expect(result.resources["dataAccount"]).toMatchObject({
       type: "Microsoft.Storage/storageAccounts",
@@ -59,45 +58,42 @@ describe("azure describeResources", () => {
   });
 
   test("missing provisioningState falls back to PRESENT", async () => {
-    execMock.mockResolvedValue({
-      stdout: JSON.stringify({ id: "id", name: "x", type: "Microsoft.Network/virtualNetworks", location: "eastus", properties: {} }),
-      stderr: "",
-    });
+    const fake = httpFake(() =>
+      armOk({ id: "id", name: "x", type: "Microsoft.Network/virtualNetworks", location: "eastus", properties: {} }),
+    );
 
     const entities = makeEntities([
       { name: "vnet", entityType: "Microsoft.Network/virtualNetworks", props: { name: "x" } },
     ]);
 
-    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["vnet"], entities });
+    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["vnet"], entities, http: fake.http });
 
     expect(result.resources["vnet"].status).toBe("PRESENT");
   });
 
   test("az failure (resource not found) leaves entity out — a confirmed absence", async () => {
-    execMock.mockImplementation(() => { throw new Error("ResourceNotFound: ..."); });
+    const fake = httpFake(() => armError(404, "ResourceNotFound", "The Resource was not found."));
 
     const entities = makeEntities([
       { name: "missing", entityType: "Microsoft.Storage/storageAccounts", props: { name: "missing" } },
     ]);
 
-    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["missing"], entities });
+    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["missing"], entities, http: fake.http });
 
     expect(result.resources).toEqual({});
     expect(result.unobserved ?? {}).toEqual({});
   });
 
-  test("an expired az login is unobserved, not absent (#1089)", async () => {
-    execMock.mockImplementation(() => {
-      throw Object.assign(new Error("az failed"), {
-        stderr: "Please run 'az login' to setup account.",
-      });
-    });
+  test("a refused credential is unobserved, not absent (#1089)", async () => {
+    const fake = httpFake(() =>
+      armError(401, "AuthenticationFailed", "Authentication failed. The 'Authorization' header is missing."),
+    );
 
     const entities = makeEntities([
       { name: "acct", entityType: "Microsoft.Storage/storageAccounts", props: { name: "acct" } },
     ]);
 
-    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["acct"], entities });
+    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["acct"], entities, http: fake.http });
 
     expect(result.resources).toEqual({});
     expect(result.unobserved?.acct?.reason).toBe("no-credentials");
@@ -105,11 +101,12 @@ describe("azure describeResources", () => {
 
   test("nested-type entities are unobserved, not absent (#1089)", async () => {
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const fake = httpFake(() => armOk({}));
     const entities = makeEntities([
       { name: "nested", entityType: "Microsoft.Storage/storageAccounts/blobServices", props: { name: "x" } },
     ]);
 
-    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["nested"], entities });
+    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["nested"], entities, http: fake.http });
 
     expect(result.resources).toEqual({});
     expect(result.unobserved?.nested).toMatchObject({
@@ -117,31 +114,33 @@ describe("azure describeResources", () => {
       reason: "unsupported-kind",
     });
     expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("nested-type"));
-    expect(execMock).not.toHaveBeenCalled();
+    expect(fake.urls).toEqual([]);
     warnSpy.mockRestore();
   });
 
   test("non-Azure entity types are unobserved — no ARM type to query", async () => {
+    const fake = httpFake(() => armOk({}));
     const entities = makeEntities([
       { name: "x", entityType: "AWS::S3::Bucket", props: { name: "x" } },
     ]);
 
-    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["x"], entities });
+    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["x"], entities, http: fake.http });
 
     expect(result.resources).toEqual({});
     expect(result.unobserved?.x?.reason).toBe("unsupported-kind");
-    expect(execMock).not.toHaveBeenCalled();
+    expect(fake.urls).toEqual([]);
   });
 
   test("entity without name is unobserved — nothing was queried", async () => {
+    const fake = httpFake(() => armOk({}));
     const entities = makeEntities([
       { name: "broken", entityType: "Microsoft.Storage/storageAccounts", props: {} },
     ]);
 
-    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["broken"], entities });
+    const result = await describeResources({ environment: "prod-rg", buildOutput: "", entityNames: ["broken"], entities, http: fake.http });
 
     expect(result.resources).toEqual({});
     expect(result.unobserved?.broken?.reason).toBe("read-failed");
-    expect(execMock).not.toHaveBeenCalled();
+    expect(fake.urls).toEqual([]);
   });
 });

package/src/describe-resources.ts

@@ -1,10 +1,18 @@
 /**
- * Live introspection of an Azure resource group via the az CLI.
+ * Live introspection of an Azure resource group over ARM (#1212).
  *
- * For each declared Azure entity, runs:
- *   az resource show --resource-group <env> --name <name> --resource-type <type> -o json
+ * For each declared Azure entity, GETs
+ *   {endpoint}/subscriptions/{sub}/resourceGroups/{env}/providers/{type}/{name}
  *
- * and maps the response to a ResourceMetadata entry keyed by chant entity name
+ * on the applier's own transport (`./api/read-client.ts`, which is
+ * `az-apply.ts`'s client pointed at the read side) rather than shelling
+ * `az resource show`. The payload is the same ARM JSON either way — the CLI was
+ * only ever relaying it — so this is transport, not translation: no CLI to
+ * spawn, reads that run concurrently, failures carrying ARM's own error code,
+ * and an emulator override that reaches floci-az the same way every other
+ * lexicon's does.
+ *
+ * The response maps to a ResourceMetadata entry keyed by chant entity name
  * (using props.name from #39's entity-prop pass-through). The environment
  * argument is treated as the Azure resource group name.
  *
@@ -17,24 +25,10 @@
  * are holes for the same reason.
  */
 
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
 import type { ObservationResult, ResourceMetadata, UnobservedEntity, UnobservedReason } from "@intentius/chant/lexicon";
-import { observation } from "@intentius/chant/observation";
-
-const execAsync = promisify(exec);
-
-interface AzResourceShowResponse {
-  id?: string;
-  name?: string;
-  type?: string;
-  location?: string;
-  properties?: {
-    provisioningState?: string;
-    [k: string]: unknown;
-  };
-  tags?: Record<string, string>;
-}
+import { boundedConcurrently, observation } from "@intentius/chant/observation";
+import { AzureReadError, getResource, isNotFound, type AzureReadClientOptions } from "./api/read-client";
+import type { AzHttp } from "./op/activities/az-apply";
 
 function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
   const out: Record<string, unknown> = {};
@@ -99,19 +93,60 @@ export function classifyAzFailure(err: unknown): { absent: true } | { absent: fa
   return { absent: false, reason: "read-failed", detail };
 }
 
+/**
+ * Classify an ARM failure off its own error code (#1212).
+ *
+ * The CLI classifier above matched on prose because stderr was all it had.
+ * ARM sends `{ error: { code, message } }`, so the code is the signal and the
+ * message is only for the human — the same distinction the AWS read client
+ * makes. Kept beside `classifyAzFailure` rather than replacing it: the CLI
+ * path still exists for a signed read against real ARM.
+ */
+export function classifyArmFailure(err: unknown): { reason: UnobservedReason; detail: string } {
+  const code = err instanceof AzureReadError ? (err.code ?? "") : "";
+  const message = err instanceof Error ? err.message : String(err);
+  const detail = (code ? `${code}: ${message}` : message).slice(0, 200);
+  const both = `${code} ${message}`.toLowerCase();
+
+  if (
+    both.includes("authenticationfailed") ||
+    both.includes("authorizationfailed") ||
+    both.includes("expired") ||
+    both.includes("forbidden") ||
+    (err instanceof AzureReadError && (err.status === 401 || err.status === 403))
+  ) {
+    return { reason: "no-credentials", detail };
+  }
+  if (both.includes("subscriptionnotfound") || both.includes("resourcegroupnotfound")) {
+    return { reason: "no-binding", detail };
+  }
+  return { reason: "read-failed", detail };
+}
+
 export async function describeResources(options: {
   environment: string;
   buildOutput: string;
   entityNames: string[];
   entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  /** Injectable transport, mirroring `azApply`'s — tests reach the reader with no network. */
+  http?: AzHttp;
 }): Promise<ObservationResult> {
   const result: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
   const skippedNested: string[] = [];
+  const readable: Array<{ entityName: string; entityType: string; name: string }> = [];
+
+  // The environment is the resource group, as it has always been on this path.
+  const client: AzureReadClientOptions = {
+    resourceGroup: options.environment,
+    ...(process.env.AZURE_ENDPOINT_URL ? { endpoint: process.env.AZURE_ENDPOINT_URL } : {}),
+    ...(process.env.AZURE_SUBSCRIPTION_ID ? { subscriptionId: process.env.AZURE_SUBSCRIPTION_ID } : {}),
+    ...(options.http ? { http: options.http } : {}),
+  };
 
   for (const [entityName, { entityType, props }] of options.entities) {
     if (!entityType.startsWith("Microsoft.")) {
-      // Not an ARM resource type, so `az resource show` has nothing to ask for.
+      // Not an ARM resource type, so there is no ARM URL to GET.
       // Unobserved rather than skipped: a silent skip reads as absence (#1089).
       unobserved[entityName] = {
         type: entityType,
@@ -126,7 +161,7 @@ export async function describeResources(options: {
       unobserved[entityName] = {
         type: entityType,
         reason: "unsupported-kind",
-        detail: "az resource show does not accept a nested ARM type; chant never queried this resource",
+        detail: "a nested ARM type needs a different read path; chant never queried this resource",
       };
       continue;
     }
@@ -141,35 +176,30 @@ export async function describeResources(options: {
       continue;
     }
 
-    const cmd = [
-      "az", "resource", "show",
-      "--resource-group", options.environment,
-      "--name", name,
-      "--resource-type", entityType,
-      "-o", "json",
-    ].join(" ");
+    readable.push({ entityName, entityType, name });
+  }
 
+  // Concurrent, where the CLI path was one spawn after another (#1201/#1212).
+  await boundedConcurrently(readable, async ({ entityName, entityType, name }) => {
     try {
-      const { stdout } = await execAsync(cmd);
-      const obj: AzResourceShowResponse = JSON.parse(stdout);
+      const body = await getResource(client, entityType, name);
       result[entityName] = {
         type: entityType,
-        physicalId: obj.id,
-        status: obj.properties?.provisioningState ?? "PRESENT",
+        physicalId: body.id,
+        status: (body.properties?.provisioningState as string | undefined) ?? "PRESENT",
         attributes: pruneUndefined({
-          location: obj.location,
-          tags: obj.tags,
+          location: body.location,
+          tags: body.tags,
         }),
       };
     } catch (err) {
       // Not-found leaves the entity out (absence). Auth/binding/other failures
       // are recorded as holes so they can't become creates (#1089).
-      const outcome = classifyAzFailure(err);
-      if (!outcome.absent) {
-        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
-      }
+      if (isNotFound(err)) return;
+      const outcome = classifyArmFailure(err);
+      unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
     }
-  }
+  });
 
   if (skippedNested.length > 0) {
     // eslint-disable-next-line no-console

package/src/lifecycle-integration.test.ts

@@ -4,7 +4,7 @@
  * Drives the REAL azurePlugin through core's live-import driver and the
  * changeset path, with the `az` CLI edge mocked.
  */
-import { describe, test, expect, vi, beforeEach } from "vitest";
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import { mkdtempSync, rmSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -57,8 +57,17 @@ const resourceShow = {
   properties: { provisioningState: "Succeeded" },
 };
 
+/** The Azure reads speak ARM over `fetch` now (#1212), so that is the seam. */
+const stubArm = (respond: () => { status: number; text: string }): void => {
+  vi.spyOn(globalThis, "fetch").mockImplementation((async () => {
+    const r = respond();
+    return { status: r.status, text: () => Promise.resolve(r.text) };
+  }) as unknown as typeof fetch);
+};
+
 describe("azure lifecycle integration (#163)", () => {
   beforeEach(() => execMock.mockReset());
+  afterEach(() => vi.restoreAllMocks());
 
   test("live-import driver: real exportResources → IR → generated source", async () => {
     execMock.mockReturnValue({ stdout: JSON.stringify(liveTemplate), stderr: "" });
@@ -81,11 +90,7 @@ describe("azure lifecycle integration (#163)", () => {
   });
 
   test("changeset path: real describeResources → buildChangeSet verdicts", async () => {
-    execMock.mockImplementation((cmd?: string) =>
-      cmd?.includes("resource show")
-        ? { stdout: JSON.stringify(resourceShow), stderr: "" }
-        : new Error("unexpected"),
-    );
+    stubArm(() => ({ status: 200, text: JSON.stringify(resourceShow) }));
 
     const { resources: observedNow } = normalizeObservation(
       await azurePlugin.describeResources!({
@@ -122,12 +127,12 @@ describeObservationConformance({
   lexicon: "azure",
   scenarios: [
     {
-      name: "a nested ARM type az resource show cannot query",
+      name: "a nested ARM type the reader cannot address",
       declared: ["blobSvc", "gone"],
       expectUnobserved: ["blobSvc"],
       expectAbsent: ["gone"],
       run: () => {
-        execMock.mockImplementation(() => new Error("ResourceNotFound: gone"));
+        stubArm(() => ({ status: 404, text: JSON.stringify({ error: { code: "ResourceNotFound", message: "not found" } }) }));
         return azurePlugin.describeResources!({
           environment: "prod",
           buildOutput: "",
@@ -144,9 +149,10 @@ describeObservationConformance({
       declared: ["myStore"],
       expectUnobserved: ["myStore"],
       run: () => {
-        execMock.mockImplementation(() =>
-          Object.assign(new Error("az failed"), { stderr: "Please run 'az login' to setup account." }),
-        );
+        stubArm(() => ({
+          status: 401,
+          text: JSON.stringify({ error: { code: "AuthenticationFailed", message: "Authentication failed." } }),
+        }));
         return azurePlugin.describeResources!({
           environment: "prod",
           buildOutput: "",