@intentius/chant-lexicon-azure 0.41.20 → 0.44.1

package/src/api/read-client.ts

@@ -114,6 +114,50 @@ export interface ArmResourceBody {
   [key: string]: unknown;
 }
 
+/**
+ * GET the resource-group's resource list — the enumeration half live export
+ * needs (#1214). Real ARM returns envelopes (id/name/type/location/tags);
+ * callers wanting the full body follow up with {@link getResourceById}.
+ */
+export async function listResources(options: AzureReadClientOptions): Promise<ArmResourceBody[]> {
+  const http = options.http ?? defaultHttp;
+  const base = (options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
+  const subscription = options.subscriptionId ?? DEFAULT_SUBSCRIPTION;
+  const url = `${base}/subscriptions/${subscription}/resourceGroups/${options.resourceGroup}/resources?api-version=${DEFAULT_API_VERSION}`;
+  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);
+    const value = isRecord(body) ? body.value : undefined;
+    if (!Array.isArray(value)) throw new AzureReadError("unparseable ARM resource list", res.status);
+    return value.filter(isRecord) as ArmResourceBody[];
+  } catch (err) {
+    if (err instanceof AzureReadError) throw err;
+    throw new AzureReadError("unparseable ARM resource list", res.status);
+  }
+}
+
+/** GET one resource by its full ARM id — the read for a list entry, nested types included. */
+export async function getResourceById(
+  options: AzureReadClientOptions,
+  id: string,
+  apiVersion = DEFAULT_API_VERSION,
+): Promise<ArmResourceBody> {
+  const http = options.http ?? defaultHttp;
+  const base = (options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
+  const url = `${base}${id}?api-version=${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 ${id}`, res.status);
+    return body as ArmResourceBody;
+  } catch (err) {
+    if (err instanceof AzureReadError) throw err;
+    throw new AzureReadError(`unparseable ARM body for ${id}`, res.status);
+  }
+}
+
 /** GET one resource. Throws {@link AzureReadError}; 404 means absent, which callers check with {@link isNotFound}. */
 export async function getResource(
   options: AzureReadClientOptions,

package/src/codegen/generate-lexicon.ts

@@ -25,6 +25,11 @@ export interface LexiconEntry {
   tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
   createOnly?: string[];
   writeOnly?: string[];
+  /**
+   * ARM deployment scopes the resource can be declared at (#1545).
+   * Absent means plain resource-group scope.
+   */
+  deployScopes?: string[];
 }
 
 /**
@@ -93,6 +98,7 @@ export function generateLexiconJSON(
         }),
         ...(r.resource.tagging && { tagging: r.resource.tagging }),
         ...(createOnly && { createOnly }),
+        ...(r.resource.deployScopes && { deployScopes: r.resource.deployScopes }),
       };
     },
     buildPropertyEntry: (resourceType, propertyType) => ({

package/src/codegen/naming.ts

@@ -45,6 +45,13 @@ const priorityNames: Record<string, string> = {
   "Microsoft.ManagedIdentity/userAssignedIdentities": "ManagedIdentity",
   "Microsoft.Authorization/roleAssignments": "RoleAssignment",
   "Microsoft.Authorization/roleDefinitions": "RoleDefinition",
+  "Microsoft.Authorization/policyDefinitions": "PolicyDefinition",
+  "Microsoft.Authorization/policyAssignments": "PolicyAssignment",
+  "Microsoft.Authorization/policySetDefinitions": "PolicySetDefinition",
+  "Microsoft.Authorization/policyExemptions": "PolicyExemption",
+  "Microsoft.Management/managementGroups": "ManagementGroup",
+  "Microsoft.Management/managementGroups_subscriptions": "ManagementGroupSubscription",
+  "Microsoft.Subscription/aliases": "SubscriptionAlias",
   "Microsoft.Insights/diagnosticSettings": "DiagnosticSetting",
   "Microsoft.Insights/components": "AppInsights",
   "Microsoft.OperationalInsights/workspaces": "LogAnalyticsWorkspace",

package/src/composites/index.ts

@@ -28,3 +28,10 @@ export { RedisCache } from "./redis-cache";
 export type { RedisCacheProps, RedisCacheResult } from "./redis-cache";
 export { PrivateEndpoint } from "./private-endpoint";
 export type { PrivateEndpointProps, PrivateEndpointResult } from "./private-endpoint";
+export { GovernanceFoundation, GovernanceBaseline, LocationRestriction, ActivityLogSink } from "./landing-zone";
+export type {
+  GovernanceFoundationProps, GovernanceFoundationResult,
+  GovernanceBaselineProps, GovernanceBaselineResult,
+  LocationRestrictionProps, LocationRestrictionResult,
+  ActivityLogSinkProps, ActivityLogSinkResult,
+} from "./landing-zone";

package/src/composites/landing-zone.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "vitest";
+import { expandComposite } from "@intentius/chant";
+import { ActivityLogSink, GovernanceBaseline, GovernanceFoundation, LocationRestriction } from "./landing-zone";
+import { ACTIVITY_LOG_TO_LOG_ANALYTICS_DEFINITION_ID } from "../governance";
+
+/** Helper to extract props from a Declarable member. */
+function p(member: unknown): Record<string, any> {
+  return (member as any).props;
+}
+
+describe("GovernanceFoundation (#791)", () => {
+  test("declares the foundation management groups and the subscription tenant policy", () => {
+    const lz = GovernanceFoundation({});
+    expect(Object.keys(lz.members)).toEqual([
+      "mgSecurity",
+      "mgInfrastructure",
+      "mgSandbox",
+      "mgWorkloads",
+      "subscriptionTenantPolicy",
+    ]);
+    expect(p(lz.mgSecurity).name).toBe("Security");
+    expect(p(lz.mgSecurity).displayName).toBe("Security");
+    expect(p(lz.mgSecurity).details).toBeUndefined();
+    expect(p(lz.subscriptionTenantPolicy)).toMatchObject({
+      name: "default",
+      blockSubscriptionsLeavingTenant: true,
+    });
+  });
+
+  test("parentId hangs the groups under an existing management group", () => {
+    const lz = GovernanceFoundation({ parentId: "acme-root" });
+    expect(p(lz.mgWorkloads).details).toEqual({
+      parent: { id: "/providers/Microsoft.Management/managementGroups/acme-root" },
+    });
+  });
+
+  test("blockSubscriptionsLeavingTenant can be relaxed", () => {
+    const lz = GovernanceFoundation({ blockSubscriptionsLeavingTenant: false });
+    expect(p(lz.subscriptionTenantPolicy).blockSubscriptionsLeavingTenant).toBe(false);
+  });
+
+  test("expandComposite produces prefixed logical names", () => {
+    const expanded = expandComposite("lz", GovernanceFoundation({}));
+    expect([...expanded.keys()]).toContain("lzMgSecurity");
+    expect([...expanded.keys()]).toContain("lzSubscriptionTenantPolicy");
+    expect(expanded.size).toBe(5);
+  });
+});
+
+describe("GovernanceBaseline (#791)", () => {
+  test("defines and assigns the two baseline policies", () => {
+    const gb = GovernanceBaseline({});
+    expect(Object.keys(gb.members)).toEqual([
+      "definitionDenyClassicResources",
+      "definitionDenyUnmanagedDisks",
+      "assignmentDenyClassicResources",
+      "assignmentDenyUnmanagedDisks",
+    ]);
+    const def = p(gb.definitionDenyClassicResources);
+    expect(def.name).toBe("deny-classic-resources");
+    expect(def.policyType).toBe("Custom");
+    expect(def.mode).toBe("All");
+    expect(def.policyRule).toMatchObject({ then: { effect: "deny" } });
+  });
+
+  test("assignments reference their definitions by managementGroupResourceId, under a distinct name", () => {
+    const gb = GovernanceBaseline({});
+    const assignment = p(gb.assignmentDenyClassicResources);
+    expect(assignment.name).toBe("deny-classic");
+    expect(assignment.policyDefinitionId).toBe(
+      "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', 'deny-classic-resources')]",
+    );
+    // Ordered after the definition — the serializer's dependsOn inference
+    // does not read managementGroupResourceId() expressions
+    expect((gb.assignmentDenyClassicResources as any).attributes).toEqual({ DependsOn: "deny-classic-resources" });
+  });
+});
+
+describe("LocationRestriction and ActivityLogSink (#791)", () => {
+  test("LocationRestriction defines and assigns the allowed-locations policy", () => {
+    const lr = LocationRestriction({ locations: ["westeurope"] });
+    const def = p(lr.definitionLocationRestriction);
+    expect(def.name).toBe("location-restriction");
+    expect(def.mode).toBe("Indexed");
+    expect(JSON.stringify(def.policyRule)).toContain("westeurope");
+    expect(p(lr.assignmentLocationRestriction).policyDefinitionId).toBe(
+      "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', 'location-restriction')]",
+    );
+  });
+
+  test("ActivityLogSink assigns the built-in DeployIfNotExists policy with a managed identity", () => {
+    const workspaceId =
+      "/subscriptions/00000000-0000-0000-0000-000000000001/resourceGroups/audit/providers/Microsoft.OperationalInsights/workspaces/org-audit";
+    const al = ActivityLogSink({ workspaceId, location: "westeurope" });
+    expect(p(al.assignmentActivityLogSink)).toMatchObject({
+      name: "activity-log-sink",
+      location: "westeurope",
+      identity: { type: "SystemAssigned" },
+      policyDefinitionId: ACTIVITY_LOG_TO_LOG_ANALYTICS_DEFINITION_ID,
+      parameters: { logAnalytics: { value: workspaceId } },
+    });
+  });
+});

package/src/composites/landing-zone.ts

@@ -0,0 +1,208 @@
+/**
+ * Landing-zone bootstrap composites (#791, epic #787 C1) — the Azure slice.
+ *
+ * Fixed-shape resources for greenfield creation of the recommended
+ * governance foundation. The evaluability rules (EVL002/004) require
+ * composites to declare a fixed set of resources, so these carry the
+ * foundation only; arbitrary management-group/subscription trees are
+ * authored as config with `landingZoneConfig()` (../governance.ts) and
+ * reconciled by the Azure cloud warden, and further groups/subscriptions
+ * are declared as ordinary resources.
+ *
+ * A single ARM template cannot mix deployment scopes (AZR030, #1545), so
+ * unlike the AWS/GCP slices the foundation splits per scope — each
+ * composite emits at exactly one scope and belongs in its own project:
+ *
+ *   // tenant-scope project (management groups + subscription tenant policy)
+ *   const lz = GovernanceFoundation({});
+ *   // management-group-scope project, deployed to the tenant root group —
+ *   // policy resources also deploy at subscription scope, so the project
+ *   // pins the scope explicitly
+ *   export const scope = deploymentScope("managementGroup");
+ *   const gb = GovernanceBaseline({});
+ *   const lr = LocationRestriction({ locations: ["westeurope"] });
+ *   const al = ActivityLogSink({ workspaceId: "/subscriptions/.../workspaces/audit", location: "westeurope" });
+ *
+ * There is no OrganizationRoot analog — the tenant and its root management
+ * group come from Entra ID, not the resource API, so greenfield and
+ * brownfield both start from the existing tenant.
+ */
+
+import { Composite } from "@intentius/chant";
+import {
+  ManagementGroup,
+  PolicyAssignment,
+  PolicyDefinition,
+  policies as SubscriptionTenantPolicy,
+} from "../generated";
+import {
+  ACTIVITY_LOG_TO_LOG_ANALYTICS_DEFINITION_ID,
+  DENY_CLASSIC_RESOURCES,
+  DENY_UNMANAGED_DISKS,
+  locationRestriction,
+  type PolicyConfig,
+} from "../governance";
+
+function policyDefinition(name: string, policy: PolicyConfig): InstanceType<typeof PolicyDefinition> {
+  return new PolicyDefinition({
+    name,
+    displayName: policy.displayName,
+    description: policy.description,
+    mode: policy.mode ?? "All",
+    policyType: "Custom",
+    ...(policy.parameters && { parameters: policy.parameters }),
+    policyRule: policy.policyRule,
+  });
+}
+
+/**
+ * The explicit DependsOn (by ARM name) orders the assignment after its
+ * definition — the serializer's inference only reads plain resourceId()
+ * expressions, not managementGroupResourceId(). Management-group assignment
+ * names are capped at 24 characters.
+ */
+function policyAssignment(
+  name: string,
+  definitionName: string,
+  policy: PolicyConfig,
+): InstanceType<typeof PolicyAssignment> {
+  return new PolicyAssignment(
+    {
+      name,
+      displayName: policy.displayName,
+      policyDefinitionId: `[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', '${definitionName}')]`,
+    },
+    { DependsOn: definitionName },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// GovernanceFoundation — the management-group hierarchy (tenant scope)
+// ---------------------------------------------------------------------------
+
+export interface GovernanceFoundationProps {
+  /** Management group the foundation hangs under. Default: the tenant root group. */
+  parentId?: string;
+  /** Block subscriptions from leaving the tenant (default true). */
+  blockSubscriptionsLeavingTenant?: boolean;
+}
+
+export type GovernanceFoundationResult = {
+  mgSecurity: InstanceType<typeof ManagementGroup>;
+  mgInfrastructure: InstanceType<typeof ManagementGroup>;
+  mgSandbox: InstanceType<typeof ManagementGroup>;
+  mgWorkloads: InstanceType<typeof ManagementGroup>;
+  subscriptionTenantPolicy: InstanceType<typeof SubscriptionTenantPolicy>;
+};
+
+/**
+ * Security / Infrastructure / Sandbox / Workloads management groups with
+ * subscriptions blocked from leaving the tenant — the same baseline
+ * `landingZoneConfig()` declares. Deploys at tenant scope.
+ */
+export const GovernanceFoundation = Composite<GovernanceFoundationProps, GovernanceFoundationResult>((props) => {
+  const group = (name: string): InstanceType<typeof ManagementGroup> =>
+    new ManagementGroup({
+      name,
+      displayName: name,
+      ...(props.parentId && {
+        details: { parent: { id: `/providers/Microsoft.Management/managementGroups/${props.parentId}` } },
+      }),
+    });
+
+  const subscriptionTenantPolicy = new SubscriptionTenantPolicy({
+    name: "default",
+    blockSubscriptionsLeavingTenant: props.blockSubscriptionsLeavingTenant ?? true,
+  });
+
+  return {
+    mgSecurity: group("Security"),
+    mgInfrastructure: group("Infrastructure"),
+    mgSandbox: group("Sandbox"),
+    mgWorkloads: group("Workloads"),
+    subscriptionTenantPolicy,
+  };
+}, "GovernanceFoundation");
+
+// ---------------------------------------------------------------------------
+// GovernanceBaseline — the baseline guardrails (management-group scope)
+// ---------------------------------------------------------------------------
+
+export type GovernanceBaselineProps = Record<string, never>;
+
+export type GovernanceBaselineResult = {
+  definitionDenyClassicResources: InstanceType<typeof PolicyDefinition>;
+  definitionDenyUnmanagedDisks: InstanceType<typeof PolicyDefinition>;
+  assignmentDenyClassicResources: InstanceType<typeof PolicyAssignment>;
+  assignmentDenyUnmanagedDisks: InstanceType<typeof PolicyAssignment>;
+};
+
+/**
+ * `deny-classic-resources` and `deny-unmanaged-disks` defined and assigned
+ * at the management group the project deploys to (the tenant root group for
+ * the `landingZoneConfig()` baseline). Custom policy definitions cannot
+ * deploy at tenant scope, which is why this is not part of
+ * GovernanceFoundation.
+ */
+export const GovernanceBaseline = Composite<GovernanceBaselineProps, GovernanceBaselineResult>(() => {
+  return {
+    definitionDenyClassicResources: policyDefinition("deny-classic-resources", DENY_CLASSIC_RESOURCES),
+    definitionDenyUnmanagedDisks: policyDefinition("deny-unmanaged-disks", DENY_UNMANAGED_DISKS),
+    assignmentDenyClassicResources: policyAssignment("deny-classic", "deny-classic-resources", DENY_CLASSIC_RESOURCES),
+    assignmentDenyUnmanagedDisks: policyAssignment("deny-unmanaged", "deny-unmanaged-disks", DENY_UNMANAGED_DISKS),
+  };
+}, "GovernanceBaseline");
+
+// ---------------------------------------------------------------------------
+// LocationRestriction — optional root guardrail (management-group scope)
+// ---------------------------------------------------------------------------
+
+export interface LocationRestrictionProps {
+  /** The only locations resources may be created in ("global" is always excepted). */
+  locations: string[];
+}
+
+export type LocationRestrictionResult = {
+  definitionLocationRestriction: InstanceType<typeof PolicyDefinition>;
+  assignmentLocationRestriction: InstanceType<typeof PolicyAssignment>;
+};
+
+export const LocationRestriction = Composite<LocationRestrictionProps, LocationRestrictionResult>((props) => {
+  const policy = locationRestriction(props.locations);
+  return {
+    definitionLocationRestriction: policyDefinition("location-restriction", policy),
+    assignmentLocationRestriction: policyAssignment("allowed-locations", "location-restriction", policy),
+  };
+}, "LocationRestriction");
+
+// ---------------------------------------------------------------------------
+// ActivityLogSink — the audit sink (management-group scope)
+// ---------------------------------------------------------------------------
+
+export interface ActivityLogSinkProps {
+  /** Resource id of the Log Analytics workspace activity logs flow into. */
+  workspaceId: string;
+  /** Region for the assignment's managed identity (DeployIfNotExists remediation). */
+  location: string;
+}
+
+export type ActivityLogSinkResult = {
+  assignmentActivityLogSink: InstanceType<typeof PolicyAssignment>;
+};
+
+/**
+ * Assigns the built-in DeployIfNotExists policy that streams every
+ * subscription's activity log into a Log Analytics workspace — current and
+ * future subscriptions under the management group alike.
+ */
+export const ActivityLogSink = Composite<ActivityLogSinkProps, ActivityLogSinkResult>((props) => {
+  const assignmentActivityLogSink = new PolicyAssignment({
+    name: "activity-log-sink",
+    location: props.location,
+    identity: { type: "SystemAssigned" },
+    displayName: "Stream activity logs to Log Analytics",
+    policyDefinitionId: ACTIVITY_LOG_TO_LOG_ANALYTICS_DEFINITION_ID,
+    parameters: { logAnalytics: { value: props.workspaceId } },
+  });
+  return { assignmentActivityLogSink };
+}, "ActivityLogSink");

package/src/deep-observe.test.ts

@@ -20,7 +20,7 @@ const stubArmFetch = (response: { status: number; text: string }): void => {
 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 { normalizeDeepObservation, normalizeDeepProperties, UNRESOLVED } = await import("@intentius/chant/deep-observation");
 
 /** 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) });
@@ -75,6 +75,173 @@ describe("the azure noise rules", () => {
     expect(out).toEqual({ securityRules: [{ name: "allow-ssh", priority: 100 }] });
   });
 
+  test("chant's own ownership marker is not drift — the azure edition of #1301", () => {
+    const live = {
+      name: "acct",
+      tags: {
+        "chant-managed-by": "chant",
+        "chant-stack": "cc-azure",
+        "chant-env": "local",
+        "managed-by": "chant",
+        team: "platform",
+      },
+    };
+    const out = normalizeDeepProperties(live, {
+      entityType: "Microsoft.Storage/storageAccounts",
+      side: "live",
+      hooks: azureDeepNormalizationHooks,
+      counterpartPaths: new Set(["name"]),
+    });
+    // The stamped marker subtracts; a genuinely foreign tag still surfaces.
+    expect(out).toEqual({ name: "acct", tags: { team: "platform" } });
+  });
+
+  test("a declared ownership tag is still compared, and a foreign managed-by is still drift", () => {
+    const declaredIt = normalizeDeepProperties(
+      { name: "acct", tags: { "chant-stack": "cc-azure" } },
+      {
+        entityType: "Microsoft.Storage/storageAccounts",
+        side: "live",
+        hooks: azureDeepNormalizationHooks,
+        counterpartPaths: new Set(["name", "tags.chant-stack"]),
+      },
+    );
+    expect(declaredIt).toEqual({ name: "acct", tags: { "chant-stack": "cc-azure" } });
+
+    const foreign = normalizeDeepProperties(
+      { name: "acct", tags: { "managed-by": "terraform" } },
+      {
+        entityType: "Microsoft.Storage/storageAccounts",
+        side: "live",
+        hooks: azureDeepNormalizationHooks,
+        counterpartPaths: new Set(["name"]),
+      },
+    );
+    expect(foreign).toEqual({ name: "acct", tags: { "managed-by": "terraform" } });
+  });
+
+  test("ARM's self-id on a nested child element subtracts; a declared element id is compared", () => {
+    const live = {
+      securityRules: [
+        {
+          name: "allow-https",
+          id: "/subscriptions/s/resourceGroups/rg/providers/Microsoft.Network/networkSecurityGroups/n/securityRules/allow-https",
+          properties: { priority: 100, provisioningState: "Succeeded" },
+        },
+      ],
+    };
+    const out = normalizeDeepProperties(live, {
+      entityType: "Microsoft.Network/networkSecurityGroups",
+      side: "live",
+      hooks: azureDeepNormalizationHooks,
+      counterpartPaths: new Set(["securityRules", "securityRules[]", "securityRules[].name", "securityRules[].properties", "securityRules[].properties.priority"]),
+    });
+    expect(out).toEqual({ securityRules: [{ name: "allow-https", properties: { priority: 100 } }] });
+
+    // A declared array of id-references (a storage account's virtualNetworkRules)
+    // has a counterpart, so the id is real content and stays.
+    const declaredRefs = normalizeDeepProperties(
+      { networkAcls: { virtualNetworkRules: [{ id: "/subscriptions/s/…/subnets/app" }] } },
+      {
+        entityType: "Microsoft.Storage/storageAccounts",
+        side: "live",
+        hooks: azureDeepNormalizationHooks,
+        counterpartPaths: new Set(["networkAcls.virtualNetworkRules[].id"]),
+      },
+    );
+    expect(declaredRefs).toEqual({ networkAcls: { virtualNetworkRules: [{ id: "/subscriptions/s/…/subnets/app" }] } });
+  });
+
+  test("a live location nobody declared is placement, not drift; a declared one is compared", () => {
+    const undeclared = normalizeDeepProperties(
+      { name: "subnet-1", location: "eastus", addressPrefix: "10.0.1.0/24" },
+      {
+        entityType: "Microsoft.Network/virtualNetworks_subnets",
+        side: "live",
+        hooks: azureDeepNormalizationHooks,
+        counterpartPaths: new Set(["name", "addressPrefix"]),
+      },
+    );
+    expect(undeclared).toEqual({ name: "subnet-1", addressPrefix: "10.0.1.0/24" });
+
+    const declared = normalizeDeepProperties(
+      { name: "acct", location: "westus" },
+      {
+        entityType: "Microsoft.Storage/storageAccounts",
+        side: "live",
+        hooks: azureDeepNormalizationHooks,
+        counterpartPaths: new Set(["name", "location"]),
+      },
+    );
+    expect(declared).toEqual({ name: "acct", location: "westus" });
+  });
+
+  test("a server-computed AKS surface nobody declared subtracts; a declared nodeResourceGroup is compared", () => {
+    const undeclared = normalizeDeepProperties(
+      {
+        name: "cc-aks",
+        kubernetesVersion: "1.31.0",
+        currentKubernetesVersion: "1.31.0",
+        fqdn: "floci-az-aks-1234:6443",
+        nodeResourceGroup: "MC_local_cc-aks_eastus",
+      },
+      {
+        entityType: "Microsoft.ContainerService/managedClusters",
+        side: "live",
+        hooks: azureDeepNormalizationHooks,
+        counterpartPaths: new Set(["name", "kubernetesVersion"]),
+      },
+    );
+    expect(undeclared).toEqual({ name: "cc-aks", kubernetesVersion: "1.31.0" });
+
+    const declared = normalizeDeepProperties(
+      { name: "cc-aks", nodeResourceGroup: "MC_custom" },
+      {
+        entityType: "Microsoft.ContainerService/managedClusters",
+        side: "live",
+        hooks: azureDeepNormalizationHooks,
+        counterpartPaths: new Set(["name", "nodeResourceGroup"]),
+      },
+    );
+    expect(declared).toEqual({ name: "cc-aks", nodeResourceGroup: "MC_custom" });
+  });
+
+  test("nested etags subtract wherever ARM stamps them", () => {
+    const out = normalizeDeepProperties(
+      { securityRules: [{ name: "r", etag: "W/\"1\"", properties: { priority: 100 } }] },
+      { entityType: "Microsoft.Network/networkSecurityGroups", side: "live", hooks: azureDeepNormalizationHooks },
+    );
+    expect(out).toEqual({ securityRules: [{ name: "r", properties: { priority: 100 } }] });
+  });
+
+  test("a declared ARM expression string is UNRESOLVED, never compared to its evaluated value", () => {
+    const declared = normalizeDeepProperties(
+      {
+        subnets: [
+          {
+            name: "subnet-1",
+            properties: {
+              addressPrefix: "10.0.1.0/24",
+              networkSecurityGroup: { id: "[resourceId('Microsoft.Network/networkSecurityGroups', 'x-nsg')]" },
+            },
+          },
+        ],
+        location: "eastus",
+      },
+      { entityType: "Microsoft.Network/virtualNetworks", side: "declared", hooks: azureDeepNormalizationHooks },
+    );
+    const subnet = (declared.subnets as Array<{ properties: { networkSecurityGroup: { id: string } } }>)[0];
+    expect(subnet.properties.networkSecurityGroup.id).toBe(UNRESOLVED);
+    expect(declared.location).toBe("eastus");
+
+    // An `[[`-escaped string is ARM's literal-`[` spelling, not an expression.
+    const escaped = normalizeDeepProperties(
+      { note: "[[not-an-expression]" },
+      { entityType: "Microsoft.Storage/storageAccounts", side: "declared", hooks: azureDeepNormalizationHooks },
+    );
+    expect(escaped.note).toBe("[[not-an-expression]");
+  });
+
   test("subtracts an empty tag map only where source declares no tags at all", () => {
     const declaredNothing = normalizeDeepProperties(
       { name: "acct", tags: {} },
@@ -172,6 +339,30 @@ describe("observeResourcesDeepAzure", () => {
     });
   });
 
+  test("a child resource's leaf name folds back to the declared vnet/subnet spelling", async () => {
+    // ARM answers a child GET with the leaf (`subnet-1`) while chant declares
+    // the nested name — the same identity, and the URL that returned 200 IS
+    // the declared name, so the two spellings must not diff.
+    const fake = armFake((leaf) =>
+      ok({
+        id: "/subscriptions/sub/resourceGroups/prod-rg/providers/Microsoft.Network/virtualNetworks/drift-vnet/subnets/subnet-1",
+        name: leaf,
+        properties: { addressPrefix: "10.0.1.0/24" },
+      }),
+    );
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAzure({
+        environment: "prod-rg",
+        entityNames: ["subnet1"],
+        entities: entities({
+          subnet1: { entityType: "Microsoft.Network/virtualNetworks_subnets", props: { name: "drift-vnet/subnet-1" } },
+        }),
+        http: fake.http,
+      }),
+    );
+    expect(result.resources.subnet1.properties.name).toBe("drift-vnet/subnet-1");
+  });
+
   test("a resource not found leaves the entity out — a confirmed absence", async () => {
     const fake = armFake(() => armError(404, "ResourceNotFound", "not found"));
     const result = normalizeDeepObservation(