@intentius/chant-lexicon-azure 0.124.39 → 0.124.41

package/src/components/arm-deploy.ts

@@ -0,0 +1,493 @@
+/**
+ * `arm-deploy`: the azure lexicon's apply step for components (#4273). It
+ * applies a built ARM template into one resource group through `azApply`
+ * (../op/activities/az-apply.ts), the same per-resource applier `ApplyOp`'s
+ * `arm` target and the floci-az lane use, so a component step, an Op and the
+ * emulator run share one code path.
+ *
+ * `plan` reads each template resource live with the read client
+ * (../api/read-client.ts) and compares it with the body `azApply` would PUT,
+ * normalized with the noise rules deep observation uses
+ * (../deep-observe.ts). A resource that is not there is a create, one whose
+ * claimed properties all match is a no-op, and one that differs is an update
+ * with each changed path before and after. With `prune: true`, each
+ * chant-owned resource in the group the template no longer declares is a
+ * delete, the set `pruneArmOrphans` would delete.
+ *
+ * ARM's PUT is a create-or-update with no preview, so the plan cannot ask
+ * Azure what would change the way `cfn-deploy` asks for a change set. What
+ * holds the apply to the approved plan is the digest: `run` plans again and
+ * applies only when it gets the approved one.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { Capability, CapabilityPlan, DeployContext, PlannedOutputs } from "@intentius/chant/components/capability";
+import type { ChangeSetAttribute, ChangeSetEntry, ChangeSetHole, ChangeSetPart } from "@intentius/chant/change-set";
+import { MASKED, UNRESOLVED, deepPathSet, flattenDeepProperties, normalizeDeepProperties } from "@intentius/chant/deep-observation";
+import { diffDeep } from "@intentius/chant/lifecycle/deep-diff";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+import { AzureReadError, getResource, isNotFound, listResources, type AzureReadClientOptions } from "../api/read-client";
+import { azureDeepNormalizationHooks, buildLiveProperties, type ArmResourceShowResponse } from "../deep-observe";
+import { classifyArmFailure } from "../describe-resources";
+import {
+  armDependencies,
+  azApply,
+  evalArm,
+  evalArmString,
+  isChantOwned,
+  orderArmResources,
+  rememberDeployed,
+  type ArmEvalCtx,
+  type ArmResource,
+  type AzHttp,
+  type AzNotPrunable,
+} from "../op/activities/az-apply";
+
+/** floci-az's local subscription, the applier's default too. */
+const DEFAULT_SUBSCRIPTION = "00000000-0000-0000-0000-000000000001";
+const DEFAULT_ENDPOINT = "https://management.azure.com";
+const DEFAULT_LOCATION = "eastus";
+
+export interface ArmDeployInput {
+  /** Path to the built ARM template (`deploymentTemplate.json`). */
+  template: string;
+  /** The resource group the template applies into. Default: the component's name. */
+  resourceGroup?: string;
+  /** Region for the group and for `resourceGroup().location`. Default: `eastus`. */
+  location?: string;
+  /** ARM endpoint. Default: `AZURE_ENDPOINT_URL`, else real Azure. */
+  endpoint?: string;
+  /** Subscription id. Default: `AZURE_SUBSCRIPTION_ID`, else floci-az's local subscription. */
+  subscriptionId?: string;
+  /** Delete chant-owned resources of the group the template no longer declares. Default: false. */
+  prune?: boolean;
+}
+
+export interface ArmDeployOutput {
+  applied: Array<{ type: string; name: string }>;
+  pruned: Array<{ type: string; name: string; deleted: boolean }>;
+  notPrunable: AzNotPrunable[];
+  /** The template's `outputs`, evaluated against the group once it applied. */
+  outputs: Record<string, unknown>;
+}
+
+/** What an `arm-deploy` plan hands `run` through `DeployContext.plans[resourceGroup]`. */
+export interface ArmDeployPlanArtifact {
+  kind: "arm-deploy-plan";
+  resourceGroup: string;
+  planDigest: string;
+}
+
+function isArmDeployPlanArtifact(value: unknown): value is ArmDeployPlanArtifact {
+  const v = value as Partial<ArmDeployPlanArtifact> | undefined;
+  return v?.kind === "arm-deploy-plan" && typeof v.resourceGroup === "string" && typeof v.planDigest === "string";
+}
+
+/**
+ * Thrown by `run` when planning again gives another digest than the approved
+ * plan: the group, the template or the endpoint moved since. Nothing is
+ * applied. `planMoved` is core's mark for a moved plan, so the command exits 3.
+ */
+export class ArmDeployPlanMovedError extends Error {
+  readonly planMoved = true;
+  constructor(
+    public readonly resourceGroup: string,
+    public readonly planned: string,
+    public readonly now: string,
+  ) {
+    super(
+      `arm-deploy "${resourceGroup}": refusing to apply. Planning again gives ${now}, the approved plan was ${planned}; ` +
+        `the resource group or its template changed since. Plan it again.`,
+    );
+    this.name = "ArmDeployPlanMovedError";
+  }
+}
+
+/** The settings a step resolves to, environment included. Read at call time so a test or an emulator lane can set them. */
+interface Target {
+  resourceGroup: string;
+  location: string;
+  endpoint: string;
+  subscriptionId: string;
+}
+
+function targetOf(ctx: DeployContext, input: ArmDeployInput): Target {
+  return {
+    resourceGroup: input.resourceGroup ?? ctx.component,
+    location: input.location ?? DEFAULT_LOCATION,
+    endpoint: (input.endpoint ?? process.env.AZURE_ENDPOINT_URL ?? DEFAULT_ENDPOINT).replace(/\/$/, ""),
+    subscriptionId: input.subscriptionId ?? process.env.AZURE_SUBSCRIPTION_ID ?? DEFAULT_SUBSCRIPTION,
+  };
+}
+
+function evalCtxOf(target: Target, http: AzHttp): ArmEvalCtx {
+  return {
+    subscriptionId: target.subscriptionId,
+    resourceGroup: target.resourceGroup,
+    location: target.location,
+    deployed: new Map(),
+    http,
+    base: target.endpoint,
+  };
+}
+
+function clientOf(target: Target, http: AzHttp): AzureReadClientOptions {
+  return { endpoint: target.endpoint, subscriptionId: target.subscriptionId, resourceGroup: target.resourceGroup, http };
+}
+
+interface ArmTemplate {
+  resources?: ArmResource[];
+  outputs?: Record<string, { type?: string; value?: unknown }>;
+}
+
+function readTemplate(path: string): ArmTemplate {
+  return JSON.parse(readFileSync(path, "utf8")) as ArmTemplate;
+}
+
+function templateDigest(path: string): string | null {
+  try {
+    return `sha256:${createHash("sha256").update(readFileSync(path)).digest("hex")}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A 404 that means the resource is not there, as opposed to one that means the
+ * subscription is not: ARM answers `SubscriptionNotFound` with a 404 too, and
+ * planning every resource as a create on that answer would be wrong. A missing
+ * resource group is absence, since `azApply` creates the group first.
+ */
+function isAbsent(err: unknown): boolean {
+  return isNotFound(err) && !(err instanceof AzureReadError && /^SubscriptionNotFound$/i.test(err.code ?? ""));
+}
+
+// ── The declared side ────────────────────────────────────────────────────────
+
+/** An expression that reads a resource's runtime state, which only an apply knows. */
+const RUNTIME_READ = /\b(reference|list[A-Za-z]*)\s*\(/;
+
+/**
+ * Evaluate one string the way `azApply` would, leaving an expression that
+ * reads runtime state (`reference()`, `listKeys()`) or uses a function the
+ * evaluator lacks as written. The noise rules read a bracket expression on
+ * the declared side as unresolved, so it is never compared, and the plan
+ * makes no `listKeys` call.
+ */
+async function evalStaticString(s: string, ctx: ArmEvalCtx): Promise<unknown> {
+  if (!(s.startsWith("[") && s.endsWith("]")) || s.startsWith("[[")) return evalArmString(s, ctx);
+  if (RUNTIME_READ.test(s)) return s;
+  try {
+    return await evalArmString(s, ctx);
+  } catch {
+    return s;
+  }
+}
+
+async function evalStatic(value: unknown, ctx: ArmEvalCtx): Promise<unknown> {
+  if (typeof value === "string") return evalStaticString(value, ctx);
+  if (Array.isArray(value)) return Promise.all(value.map((v) => evalStatic(v, ctx)));
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[String(await evalStaticString(k, ctx))] = await evalStatic(v, ctx);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * The fields `azApply` PUTs for a resource, in the flat shape deep
+ * observation reads a live resource into. The ownership tags `azApply` adds
+ * are left out: the noise rules drop them from the live side too.
+ */
+async function declaredTree(resource: ArmResource, name: string, ctx: ArmEvalCtx): Promise<Record<string, unknown>> {
+  const body: ArmResourceShowResponse = { name };
+  if (resource.location !== undefined) body.location = (await evalStatic(resource.location, ctx)) as string;
+  for (const field of ["sku", "kind", "identity", "tags", "zones", "plan", "properties"] as const) {
+    if (resource[field] !== undefined) (body as Record<string, unknown>)[field] = await evalStatic(resource[field], ctx);
+  }
+  return buildLiveProperties(body, name);
+}
+
+// ── The plan ─────────────────────────────────────────────────────────────────
+
+/** One template resource as the plan read it. */
+interface PlannedResource {
+  resource: ArmResource;
+  name: string;
+  action: "create" | "update" | "no-op" | "unread";
+}
+
+interface ArmPlanResult {
+  entries: ChangeSetEntry[];
+  holes: ChangeSetHole[];
+  resources: PlannedResource[];
+  /** The live bodies read, remembered for `reference()`. */
+  live: ArmEvalCtx;
+  template: ArmTemplate;
+}
+
+function attributeOf(path: string, before: unknown, after: unknown, hasBefore: boolean, hasAfter: boolean): ChangeSetAttribute {
+  if (before === MASKED || after === MASKED) return { path, sensitive: true };
+  if (after === UNRESOLVED) return { path, ...(hasBefore ? { before } : {}), unknown: true };
+  return { path, ...(hasBefore ? { before } : {}), ...(hasAfter ? { after } : {}) };
+}
+
+/** Read the group and compare it with the template. Pure apart from GETs. */
+async function readPlan(member: string, target: Target, input: ArmDeployInput, http: AzHttp): Promise<ArmPlanResult> {
+  const template = readTemplate(input.template);
+  const resources = template.resources ?? [];
+  const ctx = evalCtxOf(target, http);
+  const client = clientOf(target, http);
+  const entries: ChangeSetEntry[] = [];
+  const holes: ChangeSetHole[] = [];
+  const planned: PlannedResource[] = [];
+  const base = (type: string, name: string) => ({
+    member,
+    lexicon: "azure",
+    planner: "chant" as const,
+    address: `${type}/${name}`,
+    type,
+    name,
+  });
+
+  for (const resource of orderArmResources(resources)) {
+    const name = String(await evalStaticString(resource.name, ctx));
+    const address = `${resource.type}/${name}`;
+    if (name.startsWith("[")) {
+      holes.push({ address, type: resource.type, reason: "the resource's name reads runtime state; known only at apply" });
+      planned.push({ resource, name, action: "unread" });
+      continue;
+    }
+    const declaredRaw = await declaredTree(resource, name, ctx);
+    let live: ArmResourceShowResponse | undefined;
+    try {
+      live = (await getResource(client, resource.type, name, resource.apiVersion)) as ArmResourceShowResponse;
+    } catch (err) {
+      if (!isAbsent(err)) {
+        const failure = classifyArmFailure(err);
+        holes.push({ address, type: resource.type, reason: `${failure.reason}: ${failure.detail}` });
+        planned.push({ resource, name, action: "unread" });
+        continue;
+      }
+    }
+    const opts = { entityType: resource.type, hooks: azureDeepNormalizationHooks };
+
+    if (!live) {
+      const declared = normalizeDeepProperties(declaredRaw, { ...opts, side: "declared" });
+      const attributes = [...flattenDeepProperties(declared, { ...opts, side: "declared" })]
+        .map(([path, value]) => attributeOf(path, undefined, value, false, true))
+        .sort((a, b) => a.path.localeCompare(b.path));
+      entries.push({ ...base(resource.type, name), action: "create", attributes });
+      planned.push({ resource, name, action: "create" });
+      continue;
+    }
+
+    rememberDeployed(ctx, resource.type, name, live);
+    const liveRaw = buildLiveProperties(live, name);
+    const declared = normalizeDeepProperties(declaredRaw, { ...opts, side: "declared", counterpartPaths: deepPathSet(liveRaw) });
+    const liveTree = normalizeDeepProperties(liveRaw, { ...opts, side: "live", counterpartPaths: deepPathSet(declaredRaw) });
+    const diff = diffDeep({
+      declared: { [address]: { type: resource.type, properties: declared } },
+      live: { resources: { [address]: { type: resource.type, properties: liveTree } }, unobserved: {} },
+      hooks: azureDeepNormalizationHooks,
+    });
+    // A masked value ARM does not return (a password) is write-only, not a change.
+    const changes = (diff.drifted[0]?.changes ?? []).filter((c) => !(c.kind === "absent" && c.declared === MASKED));
+    const id = typeof live.id === "string" ? { id: live.id } : {};
+    if (changes.length === 0) {
+      entries.push({ ...base(resource.type, name), ...id, action: "no-op", attributes: [] });
+      planned.push({ resource, name, action: "no-op" });
+      continue;
+    }
+    const attributes = changes
+      .map((c) => attributeOf(c.path, c.live, c.declared, c.kind === "changed", true))
+      .sort((a, b) => a.path.localeCompare(b.path));
+    entries.push({ ...base(resource.type, name), ...id, action: "update", disruption: "in-place", attributes });
+    planned.push({ resource, name, action: "update" });
+  }
+
+  if (input.prune) {
+    // The set `pruneArmOrphans` deletes: chant-owned, of any type, and not declared by (type, name).
+    const keep = new Set(planned.map((p) => `${p.resource.type}\0${p.name}`));
+    try {
+      for (const item of await listResources(client)) {
+        if (typeof item.type !== "string" || typeof item.name !== "string") continue;
+        if (!isChantOwned(item.tags)) continue;
+        if (keep.has(`${item.type}\0${item.name}`)) continue;
+        entries.push({
+          ...base(item.type, item.name),
+          ...(typeof item.id === "string" ? { id: item.id } : {}),
+          action: "delete",
+          disruption: "destroy",
+          attributes: [],
+        });
+      }
+    } catch (err) {
+      if (!isAbsent(err)) {
+        const failure = classifyArmFailure(err);
+        holes.push({ address: target.resourceGroup, type: "Microsoft.Resources/resourceGroups", reason: `prune not read: ${failure.reason}: ${failure.detail}` });
+      }
+    }
+  }
+
+  entries.sort((a, b) => a.address.localeCompare(b.address));
+  holes.sort((a, b) => a.address.localeCompare(b.address));
+  return { entries, holes, resources: planned, live: ctx, template };
+}
+
+function armPlanDigest(ctx: DeployContext, target: Target, input: ArmDeployInput, unresolved: string[], plan?: Pick<ArmPlanResult, "entries" | "holes">): string {
+  return computePlanDigest("arm-deploy-plan", {
+    env: ctx.env,
+    ...target,
+    template: input.template,
+    templateDigest: templateDigest(input.template),
+    prune: input.prune ?? false,
+    unresolved,
+    ...(plan ? { entries: plan.entries, holes: plan.holes } : {}),
+  });
+}
+
+/** The template's outputs evaluated against `ctx`, leaving out each one that evaluates to nothing. */
+async function evaluateOutputs(
+  outputs: ArmTemplate["outputs"],
+  ctx: ArmEvalCtx,
+  only?: (name: string) => boolean,
+): Promise<{ known: Record<string, unknown>; unknown: string[] }> {
+  const known: Record<string, unknown> = {};
+  const unknown: string[] = [];
+  for (const [name, output] of Object.entries(outputs ?? {})) {
+    if (only && !only(name)) {
+      unknown.push(name);
+      continue;
+    }
+    let value: unknown;
+    try {
+      value = await evalArm(output?.value, ctx);
+    } catch {
+      value = undefined;
+    }
+    if (value === undefined) unknown.push(name);
+    else known[name] = value;
+  }
+  return { known, unknown: unknown.sort() };
+}
+
+/**
+ * What the plan says of the template's outputs: an output whose value reads
+ * only resources the plan leaves as they are is known from the live read.
+ * Every other one is known only after apply.
+ */
+async function plannedOutputs(plan: ArmPlanResult): Promise<PlannedOutputs> {
+  const names = new Set(plan.resources.map((r) => r.resource.name));
+  const changing = new Set(plan.resources.filter((r) => r.action !== "no-op").map((r) => r.resource.name));
+  return evaluateOutputs(plan.template.outputs, plan.live, (name) => {
+    const value = plan.template.outputs?.[name]?.value;
+    const reads = armDependencies({ type: "", apiVersion: "", name: "", properties: value }, names);
+    return reads.every((r) => !changing.has(r));
+  });
+}
+
+/** Read every template resource live and evaluate the template's outputs against them. */
+async function liveOutputs(target: Target, input: ArmDeployInput, http: AzHttp): Promise<Record<string, unknown>> {
+  const template = readTemplate(input.template);
+  if (Object.keys(template.outputs ?? {}).length === 0) return {};
+  const ctx = evalCtxOf(target, http);
+  const client = clientOf(target, http);
+  for (const resource of orderArmResources(template.resources ?? [])) {
+    const name = String(await evalStaticString(resource.name, ctx));
+    if (name.startsWith("[")) continue;
+    try {
+      rememberDeployed(ctx, resource.type, name, await getResource(client, resource.type, name, resource.apiVersion));
+    } catch (err) {
+      if (!isAbsent(err)) throw err;
+    }
+  }
+  return (await evaluateOutputs(template.outputs, ctx)).known;
+}
+
+async function planArmDeploy(http: AzHttp, ctx: DeployContext, input: ArmDeployInput): Promise<CapabilityPlan> {
+  const target = targetOf(ctx, input);
+  const member = target.resourceGroup;
+  const unresolved = [...(ctx.unresolvedInputs ?? [])].sort();
+  const memberOf = (planDigest: string, holes: ChangeSetHole[]): ChangeSetPart["member"] => ({
+    member,
+    lexicon: "azure",
+    planner: "chant",
+    status: "planned",
+    planDigest,
+    holes,
+  });
+
+  if (unresolved.length > 0) {
+    const planDigest = armPlanDigest(ctx, target, input, unresolved);
+    const hole = { address: member, type: "Microsoft.Resources/resourceGroups", reason: `inputs from ${unresolved.join(", ")}; re-checked on apply` };
+    return { member, planDigest, changeSet: { member: memberOf(planDigest, [hole]), entries: [] } };
+  }
+
+  const plan = await readPlan(member, target, input, http);
+  const planDigest = armPlanDigest(ctx, target, input, unresolved, plan);
+  const outputs = await plannedOutputs(plan);
+  // A plan with a hole hands `run` nothing to hold it to, as `cfn-deploy`'s does not.
+  const artifact: ArmDeployPlanArtifact | undefined = plan.holes.length === 0 ? { kind: "arm-deploy-plan", resourceGroup: member, planDigest } : undefined;
+  return {
+    member,
+    planDigest,
+    ...(artifact ? { artifact } : {}),
+    changeSet: { member: memberOf(planDigest, plan.holes), entries: plan.entries },
+    outputs,
+  };
+}
+
+/**
+ * The `arm-deploy` capability over an injectable HTTP transport (the
+ * `AzHttp` seam `azApply` and the read client share). Tests pass a fake;
+ * the default is `fetch`. There is no rollback: like `gcp-apply`, it mutates
+ * with no undo, so COMP003 has a component acknowledge the gap.
+ */
+export function createArmDeployCapability(options: { http?: AzHttp } = {}): Capability<ArmDeployInput, ArmDeployOutput> {
+  const http: AzHttp = options.http ?? (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() };
+  });
+  return {
+    kind: "arm-deploy",
+    rollbackPolicy: "needs-opt-out",
+    plan(ctx, input) {
+      return planArmDeploy(http, ctx, input);
+    },
+    outputs(ctx, input) {
+      return liveOutputs(targetOf(ctx, input), input, http);
+    },
+    async run(ctx, input) {
+      const target = targetOf(ctx, input);
+      const approved = ctx.plans?.[target.resourceGroup];
+      if (isArmDeployPlanArtifact(approved)) {
+        const now = await planArmDeploy(http, { env: ctx.env, component: ctx.component }, input);
+        if (now.planDigest !== approved.planDigest) throw new ArmDeployPlanMovedError(target.resourceGroup, approved.planDigest, now.planDigest);
+      }
+      const result = await azApply(
+        {
+          templatePath: input.template,
+          resourceGroup: target.resourceGroup,
+          location: target.location,
+          endpoint: target.endpoint,
+          subscriptionId: target.subscriptionId,
+          prune: input.prune ?? false,
+        },
+        undefined,
+        http,
+      );
+      return { ...result, outputs: await liveOutputs(target, input, http) };
+    },
+  };
+}
+
+/** The default `arm-deploy` capability, over `fetch`. */
+export const armDeployCapability: Capability<ArmDeployInput, ArmDeployOutput> = createArmDeployCapability();

package/src/components/capability-plugin.ts

@@ -0,0 +1,26 @@
+/**
+ * `azureCapabilityPlugin`: the azure lexicon's capability plugin (#4273). It
+ * contributes `arm-deploy` through core's `CapabilityPlugin` contract, so a
+ * project declaring `lexicons: ["azure"]` gets the verb registered when it
+ * runs components, the way the aws lexicon contributes `cfn-deploy`.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { armDeployCapability } from "./arm-deploy";
+
+export const AZURE_VERB_FAMILIES = {
+  apply: ["arm-deploy"],
+} as const;
+
+export const azureCapabilityPlugin: CapabilityPlugin = {
+  name: "azure",
+  get version(): string {
+    return ownPackageVersion(import.meta.url);
+  },
+  capabilities(): Array<Capability<never, unknown>> {
+    return [armDeployCapability as Capability<never, unknown>];
+  },
+  families(): Record<string, readonly string[]> {
+    return AZURE_VERB_FAMILIES;
+  },
+};

package/src/components/index.ts

@@ -0,0 +1,9 @@
+export { azureCapabilityPlugin, AZURE_VERB_FAMILIES } from "./capability-plugin";
+export {
+  armDeployCapability,
+  createArmDeployCapability,
+  ArmDeployPlanMovedError,
+  type ArmDeployInput,
+  type ArmDeployOutput,
+  type ArmDeployPlanArtifact,
+} from "./arm-deploy";

package/src/composites/composites.test.ts

@@ -777,6 +777,45 @@ describe("ContainerAppNetwork", () => {
     const { virtualNetwork } = ContainerAppNetwork({ name: "web", defaults: { virtualNetwork: { location: "westeurope" } } });
     expect(p(virtualNetwork).location).toBe("westeurope");
   });
+
+  type Inline = { name: string; properties: Record<string, unknown> };
+
+  test("defaults.subnet reaches the inline entry as well as the Subnet resource", () => {
+    const nsg = { id: "[resourceId('Microsoft.Network/networkSecurityGroups', 'web-nsg')]" };
+    const routeTable = { id: "[resourceId('Microsoft.Network/routeTables', 'web-rt')]" };
+    const { virtualNetwork, subnet } = ContainerAppNetwork({
+      name: "web",
+      defaults: { subnet: { networkSecurityGroup: nsg, routeTable } as any },
+    });
+    const inline = (p(virtualNetwork).subnets as Inline[])[0];
+    expect(p(subnet).networkSecurityGroup).toEqual(nsg);
+    expect(inline.properties.networkSecurityGroup).toEqual(nsg);
+    expect(inline.properties.routeTable).toEqual(routeTable);
+    const { name: _n, ...flat } = p(subnet);
+    expect(inline.properties).toEqual(flat);
+  });
+
+  test("defaults.virtualNetwork.subnets adds subnets after apps and keeps its delegation", () => {
+    const { virtualNetwork } = ContainerAppNetwork({
+      name: "web",
+      defaults: { virtualNetwork: { subnets: [{ name: "db", properties: { addressPrefix: "10.0.2.0/24" } }] } as any },
+    });
+    const subnets = p(virtualNetwork).subnets as Inline[];
+    expect(subnets.map((s) => s.name)).toEqual(["apps", "db"]);
+    const delegations = subnets[0].properties.delegations as Array<{ properties: { serviceName: string } }>;
+    expect(delegations[0].properties.serviceName).toBe("Microsoft.App/environments");
+  });
+
+  test("a caller's own apps entry in defaults.virtualNetwork.subnets is replaced by the merged one", () => {
+    const { virtualNetwork } = ContainerAppNetwork({
+      name: "web",
+      defaults: { virtualNetwork: { subnets: [{ name: "apps", properties: { addressPrefix: "10.9.0.0/23" } }] } as any },
+    });
+    const subnets = p(virtualNetwork).subnets as Inline[];
+    expect(subnets).toHaveLength(1);
+    expect(subnets[0].properties.addressPrefix).toBe("10.0.0.0/23");
+    expect(subnets[0].properties.delegations).toBeDefined();
+  });
 });
 
 // --- ContainerAppSite ---

package/src/composites/container-app.ts

@@ -65,25 +65,46 @@ export const ContainerAppNetwork = Composite((props: ContainerAppNetworkProps) =
   const vnetName = `${name}-vnet`;
   const delegations = [{ name: "apps", properties: { serviceName: "Microsoft.App/environments" } }];
 
+  const subnet = new Subnet(mergeDefaults({
+    name: `${vnetName}/apps`,
+    addressPrefix: subnetPrefix,
+    delegations,
+  }, defaults?.subnet), { apiVersion: "2023-05-01" });
+
   // The subnet is also listed inline, as VnetDefault does, so a later
-  // deployment of the VNet does not try to remove it.
+  // deployment of the VNet does not try to remove it. The inline entry is
+  // built from the Subnet resource's merged props, so `defaults.subnet`
+  // reaches both copies. The apps entry always comes first; a caller's
+  // `defaults.virtualNetwork.subnets` adds the other subnets after it, and
+  // an entry of theirs named "apps" is replaced by this one.
+  const { subnets: extraSubnets, ...vnetDefaults } = (defaults?.virtualNetwork ?? {}) as {
+    subnets?: Array<{ name?: string }>;
+  } & Record<string, unknown>;
   const virtualNetwork = new VirtualNetwork(mergeDefaults({
     name: vnetName,
     location,
     tags: mergedTags,
     addressSpace: { addressPrefixes: [addressSpace] },
-    subnets: [{ name: "apps", properties: { addressPrefix: subnetPrefix, delegations } }],
-  }, defaults?.virtualNetwork), { apiVersion: "2023-05-01" });
-
-  const subnet = new Subnet(mergeDefaults({
-    name: `${vnetName}/apps`,
-    addressPrefix: subnetPrefix,
-    delegations,
-  }, defaults?.subnet), { apiVersion: "2023-05-01" });
+    subnets: [
+      inlineSubnet("apps", subnetProps(subnet)),
+      ...(extraSubnets ?? []).filter((s) => s?.name !== "apps"),
+    ],
+  }, vnetDefaults), { apiVersion: "2023-05-01" });
 
   return { virtualNetwork, subnet };
 }, "ContainerAppNetwork");
 
+/** A Subnet resource's props, flat or under `properties`. */
+function subnetProps(subnet: InstanceType<typeof Subnet>): Record<string, unknown> {
+  return (subnet as unknown as { props: Record<string, unknown> }).props;
+}
+
+/** The VNet's inline entry for a subnet, from that Subnet resource's props. */
+function inlineSubnet(name: string, props: Record<string, unknown>) {
+  const { name: _name, id: _id, properties, ...flat } = props;
+  return { name, properties: { ...flat, ...(properties as Record<string, unknown> | undefined) } };
+}
+
 export interface ContainerAppSiteProps {
   /** Environment name; the workspace is `<name>-logs` and the identity `<name>-<app>`. */
   name: string;

package/src/deep-observe.ts

@@ -67,7 +67,7 @@ import { AZURE_TAG_OWNERSHIP_KEYS } from "./ownership";
 
 
 /** The full `az resource show -o json` shape this reader reads (a superset of the thin path's `AzResourceShowResponse`). */
-interface ArmResourceShowResponse {
+export interface ArmResourceShowResponse {
   id?: string;
   name?: string;
   type?: string;
@@ -96,7 +96,7 @@ interface ArmResourceShowResponse {
  * returned 200 is the declared name. The leaf is folded back to the declared
  * spelling; a name that is not the leaf of the query is kept as returned.
  */
-function buildLiveProperties(obj: ArmResourceShowResponse, queriedName?: string): Record<string, unknown> {
+export function buildLiveProperties(obj: ArmResourceShowResponse, queriedName?: string): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   if (obj.name !== undefined) {
     out.name =

package/src/index.ts

@@ -17,6 +17,9 @@ export { defaultTags, type TagEntry, type DefaultTags } from "./default-tags";
 export { deploymentScope, isDeploymentScope, type DeploymentScope, type DeployScope } from "./deploy-scopes";
 export { azureSerializer } from "./serializer";
 export { azurePlugin } from "./plugin";
+// Core's capability-plugin loader scans this package's exports and loads
+// `azureCapabilityPlugin` when a project's chant.config lists this lexicon (#4273).
+export { azureCapabilityPlugin } from "./components/capability-plugin";
 export { Parameter } from "./parameter";
 
 // Deep observation (#1086): the `az resource show` reader and the noise