infraweaver 0.1.0

package/src/mcp/terraform/oscal.ts

@@ -0,0 +1,283 @@
+/**
+ * Strict OSCAL Assessment Results emitter (the buyer-gated follow-up to the
+ * Infraweaver-native evidence bundle in [[evidence]]).
+ *
+ * The native bundle is Infraweaver's own schema; this renders the SAME assessment as
+ * NIST **OSCAL 1.1.2 Assessment Results** JSON, so a buyer whose GRC tooling
+ * imports OSCAL (compliance-trestle / C2P / Auditree) can ingest it directly. It
+ * is INDICATIVE (crosswalk-derived, no formal assessment plan) and honest: every
+ * open concern becomes a `not-satisfied` finding against the control objective it
+ * touches — we never synthesise a `satisfied` we can't code-verify.
+ *
+ * Determinism: UUIDs are name-based (a sha256 of stable seeds, formatted as a v5
+ * UUID), so the same inputs + `generatedAt` always produce byte-identical output —
+ * matching the pure stance of the evidence builder, and keeping diffs meaningful.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { type } from "arktype";
+import { OSCAL_FILE, PRODUCT_NAME } from "#app/brand";
+import {
+  type AssessmentScorecard,
+  runAssessmentPipeline,
+} from "#app/mcp/assess";
+import type { CrosswalkReport } from "#app/mcp/crosswalk";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import type { EvidenceSubject } from "#app/mcp/terraform/evidence";
+import type { Severity } from "#app/mcp/terraform/types";
+import { log } from "#app/utils/cli";
+import { githubContext } from "#app/utils/env";
+import packageJson from "#package.json" with { type: "json" };
+
+export const OSCAL_VERSION = "1.1.2" as const;
+
+const INDICATIVE_REMARK =
+  "Indicative, crosswalk-derived assessment from a deterministic starter rule-pack — " +
+  "NOT a formal OSCAL assessment against an authored assessment plan. Statuses are " +
+  "code-verified only; absence of a finding is not proof of compliance.";
+
+interface OscalProp {
+  name: string;
+  value: string;
+  ns?: string;
+}
+
+interface OscalObservation {
+  uuid: string;
+  title: string;
+  description: string;
+  methods: string[];
+  collected: string;
+  "relevant-evidence"?: { description: string }[];
+}
+
+interface OscalFinding {
+  uuid: string;
+  title: string;
+  description: string;
+  target: {
+    type: "objective-id";
+    "target-id": string;
+    status: { state: "satisfied" | "not-satisfied"; reason?: string };
+  };
+  "related-observations"?: { "observation-uuid": string }[];
+  props?: OscalProp[];
+}
+
+export interface OscalAssessmentResults {
+  "assessment-results": {
+    uuid: string;
+    metadata: {
+      title: string;
+      "last-modified": string;
+      version: string;
+      "oscal-version": typeof OSCAL_VERSION;
+      props: OscalProp[];
+      remarks: string;
+    };
+    "import-ap": { href: string; remarks: string };
+    results: Array<{
+      uuid: string;
+      title: string;
+      description: string;
+      start: string;
+      "reviewed-controls": {
+        "control-selections": Array<{
+          "include-controls"?: { "control-id": string }[];
+          "include-all"?: Record<string, never>;
+        }>;
+      };
+      observations: OscalObservation[];
+      findings: OscalFinding[];
+    }>;
+  };
+}
+
+const NS = "https://infraweaver.dev/ns/oscal";
+
+/** name-based (v5-shaped) UUID from a seed, so output is reproducible.
+ * Shared with the CycloneDX VEX emitter ([[vex]]) — both artefacts keep the
+ * pure/deterministic stance of the evidence builder. */
+export function deterministicUuid(seed: string): string {
+  const hex = createHash("sha256")
+    .update(seed)
+    .digest("hex")
+    .slice(0, 32)
+    .split("");
+  hex[12] = "5"; // version 5 (name-based)
+  hex[16] = ((Number.parseInt(hex[16] ?? "0", 16) & 0x3) | 0x8).toString(16); // RFC 4122 variant
+  const u = hex.join("");
+  return `${u.slice(0, 8)}-${u.slice(8, 12)}-${u.slice(12, 16)}-${u.slice(16, 20)}-${u.slice(20, 32)}`;
+}
+
+function subjectLabel(s: EvidenceSubject): string {
+  return s.repo ? `${s.repo}${s.ref ? `@${s.ref}` : ""}` : s.scanned_dir;
+}
+
+/**
+ * Build a strict OSCAL 1.1.2 Assessment Results document from an assessment's
+ * scorecard + crosswalk. Pure (clock/identity passed in). Each crosswalk entry
+ * (an open concern) yields one observation and one `not-satisfied` finding per
+ * control objective it maps to; the finding's verification status + severity ride
+ * as props so an OSCAL consumer keeps the five-status nuance.
+ */
+export function buildOscalAssessmentResults(args: {
+  scorecard: AssessmentScorecard;
+  crosswalk: CrosswalkReport;
+  subject: EvidenceSubject;
+  generatedAt: string;
+  version?: string;
+}): OscalAssessmentResults {
+  const { scorecard, crosswalk, subject, generatedAt } = args;
+  const label = subjectLabel(subject);
+  const seed = `${subject.commit ?? subject.scanned_dir}|${generatedAt}`;
+
+  const observations: OscalObservation[] = [];
+  const findings: OscalFinding[] = [];
+  const controlIds = new Set<string>();
+
+  for (const e of crosswalk.entries) {
+    const obsUuid = deterministicUuid(`obs|${seed}|${e.concern_id}`);
+    observations.push({
+      uuid: obsUuid,
+      title: `${e.rule_id} (${e.concern_id})`,
+      description: `Scanner finding ${e.rule_id} mapped via the indicative crosswalk.`,
+      methods: ["TEST"], // automated scanner evidence
+      collected: generatedAt,
+    });
+    for (const c of e.controls) {
+      controlIds.add(c.control);
+      findings.push({
+        uuid: deterministicUuid(
+          `finding|${seed}|${e.concern_id}|${c.framework}|${c.control}`,
+        ),
+        title: `${c.control} — ${c.title}`,
+        description: `${e.rule_id} indicates control "${c.title}" (${c.framework}) is not satisfied.`,
+        target: {
+          type: "objective-id",
+          "target-id": c.control,
+          status: { state: "not-satisfied", reason: e.status },
+        },
+        "related-observations": [{ "observation-uuid": obsUuid }],
+        props: [
+          { name: "verification-status", value: e.status, ns: NS },
+          { name: "framework", value: c.framework, ns: NS },
+        ],
+      });
+    }
+  }
+
+  const includeControls = [...controlIds]
+    .sort()
+    .map((id) => ({ "control-id": id }));
+
+  return {
+    "assessment-results": {
+      uuid: deterministicUuid(`ar|${seed}`),
+      metadata: {
+        title: `${PRODUCT_NAME} indicative compliance assessment — ${label}`,
+        "last-modified": generatedAt,
+        version: args.version ?? packageJson.version,
+        "oscal-version": OSCAL_VERSION,
+        props: [
+          { name: "marking", value: "indicative", ns: NS },
+          { name: "posture", value: scorecard.posture, ns: NS },
+        ],
+        remarks: INDICATIVE_REMARK,
+      },
+      "import-ap": {
+        // No formal assessment plan exists; OSCAL requires import-ap, so we point
+        // at a self-describing URN and explain the indicative basis in remarks.
+        href: "urn:infraweaver:indicative-assessment-plan",
+        remarks: INDICATIVE_REMARK,
+      },
+      results: [
+        {
+          uuid: deterministicUuid(`result|${seed}`),
+          title: "Indicative assessment result",
+          description: INDICATIVE_REMARK,
+          start: generatedAt,
+          "reviewed-controls": {
+            "control-selections": [
+              includeControls.length > 0
+                ? { "include-controls": includeControls }
+                : { "include-all": {} },
+            ],
+          },
+          observations,
+          findings,
+        },
+      ],
+    },
+  };
+}
+
+export const DEFAULT_OSCAL_PATH = `compliance/${OSCAL_FILE}`;
+
+export const TerraformEmitOscalParams = type({
+  "output_path?": type.string.describe(
+    `where to write the OSCAL Assessment Results (default: ./${DEFAULT_OSCAL_PATH}). Commit it so the compliance/ path is the auditable, GRC-importable trail.`,
+  ),
+  "severity_threshold?": type(
+    "'critical' | 'high' | 'medium' | 'low' | 'info'",
+  ).describe(
+    "minimum severity to include (default: the run's configured threshold, else low).",
+  ),
+});
+
+export function TerraformEmitOscalTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_emit_oscal",
+    description:
+      "Emit the read-only assessment as strict NIST OSCAL 1.1.2 ASSESSMENT RESULTS JSON (default " +
+      `\`${DEFAULT_OSCAL_PATH}\`) — the same indicative crosswalk assessment as ` +
+      "`terraform_emit_evidence`, but in the format a GRC tool that imports OSCAL (compliance-trestle / C2P / " +
+      "Auditree) ingests directly. Every open concern becomes a `not-satisfied` finding against the control " +
+      "objective it touches, with its five-status verdict carried as a prop; UUIDs are deterministic so " +
+      "re-runs diff cleanly. It NEVER modifies Terraform or opens a PR, and is INDICATIVE (crosswalk-derived, " +
+      "no formal assessment plan) — never an audit verdict and never a satisfied it can't code-verify. Use " +
+      "this only when a buyer's GRC tooling actually consumes OSCAL; otherwise `terraform_emit_evidence` is lighter.",
+    parameters: TerraformEmitOscalParams,
+    execute: execute(async ({ output_path, severity_threshold }) => {
+      const configured = ctx.payload.severityThreshold as Severity | undefined;
+      const threshold: Severity = severity_threshold ?? configured ?? "low";
+      const { cwd, scorecard, crosswalk } = runAssessmentPipeline(
+        ctx,
+        threshold,
+      );
+
+      // SECURITY: confine the agent-supplied path to the workspace (same guard as
+      // terraform_emit_evidence / terraform_emit_sarif).
+      const target = resolveWithinCwd(cwd, output_path ?? DEFAULT_OSCAL_PATH);
+      const gh = githubContext();
+      const doc = buildOscalAssessmentResults({
+        scorecard,
+        crosswalk,
+        subject: {
+          scanned_dir: cwd,
+          repo: gh.repository,
+          ref: gh.refName,
+          commit: gh.sha,
+        },
+        generatedAt: new Date().toISOString(),
+      });
+      // the default compliance/ dir may not exist yet on a first run.
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, `${JSON.stringify(doc, null, 2)}\n`);
+      const result = doc["assessment-results"].results[0];
+      const findings = result?.findings.length ?? 0;
+      log.info(
+        `» terraform_emit_oscal: ${scorecard.posture} — ${findings} OSCAL finding(s) → ${target}`,
+      );
+      return toolOk({
+        output_path: target,
+        posture: scorecard.posture,
+        findings,
+        oscal_version: OSCAL_VERSION,
+      });
+    }),
+  });
+}

package/src/mcp/terraform/packs/azurerm-3-4.ts

@@ -0,0 +1,382 @@
+import type { TransformEntry, TransformPack } from "#app/mcp/terraform/transformPacks";
+
+/**
+ * azurerm 3.x → 4.0.
+ *
+ * Transcribed from HashiCorp's own v4.0 upgrade guide (cited below). Everything
+ * here is a documented upstream breaking change — nothing is inferred from the
+ * schema or guessed from a naming pattern, even where v4's renames are visibly
+ * systematic (`enable_x` → `x_enabled`). Guessing the rest of that family would
+ * be indistinguishable, to a reader, from the entries that were actually
+ * verified, and an entry nobody checked is exactly the kind of confident-wrong
+ * claim this product exists to refuse.
+ *
+ * ⚠️ NOT EXHAUSTIVE. v4 removed ~70 resources and changed arguments on well over
+ * a hundred. This pack carries the ones most likely to appear in real Terraform
+ * and, above all, the ones whose migration MOVES STATE — because those are the
+ * ones where getting it wrong destroys data rather than failing a build. For
+ * completeness, `terraform_validate`'s `unknown_arguments` reads the installed
+ * v4 schema and will name every argument this table missed.
+ */
+
+const SOURCE =
+  "https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/4.0-upgrade-guide";
+
+/** `azurerm_<old>` → `azurerm_<new>` where the whole resource TYPE changed.
+ *
+ *  Every one of these is `manual_import`. A `moved {}` block cannot carry state
+ *  between two different resource types — it moves an address, not a schema — so
+ *  the only correct path is `terraform state rm` + `terraform import` against the
+ *  new type. Ship this as a config edit alone and the apply destroys the live
+ *  database and creates an empty one. */
+const REMOVED_RESOURCES: [from: string, to: string | null][] = [
+  ["azurerm_sql_server", "azurerm_mssql_server"],
+  ["azurerm_sql_database", "azurerm_mssql_database"],
+  ["azurerm_sql_firewall_rule", "azurerm_mssql_firewall_rule"],
+  ["azurerm_sql_failover_group", "azurerm_mssql_failover_group"],
+  ["azurerm_sql_virtual_network_rule", "azurerm_mssql_virtual_network_rule"],
+  ["azurerm_sql_managed_instance", "azurerm_mssql_managed_instance"],
+  ["azurerm_sql_managed_database", "azurerm_mssql_managed_database"],
+  ["azurerm_mysql_server", "azurerm_mysql_flexible_server"],
+  ["azurerm_mysql_database", "azurerm_mysql_flexible_database"],
+  ["azurerm_mysql_configuration", "azurerm_mysql_flexible_server_configuration"],
+  ["azurerm_mysql_firewall_rule", "azurerm_mysql_flexible_server_firewall_rule"],
+  ["azurerm_mariadb_server", "azurerm_mysql_flexible_server"],
+  ["azurerm_mariadb_database", "azurerm_mysql_flexible_database"],
+  ["azurerm_mariadb_configuration", "azurerm_mysql_flexible_server_configuration"],
+  ["azurerm_mariadb_firewall_rule", "azurerm_mysql_flexible_server_firewall_rule"],
+  ["azurerm_template_deployment", "azurerm_resource_group_template_deployment"],
+  [
+    "azurerm_monitor_action_rule_action_group",
+    "azurerm_monitor_alert_processing_rule_action_group",
+  ],
+  ["azurerm_monitor_action_rule_suppression", "azurerm_monitor_alert_processing_rule_suppression"],
+  // Removed outright — the guide names no replacement resource, so neither do we.
+  ["azurerm_monitor_log_profile", null],
+];
+
+/** Straight top-level argument renames: same meaning, same value, new name. */
+const ARGUMENT_RENAMES: [resource: string, from: string, to: string][] = [
+  ["azurerm_storage_account", "enable_https_traffic_only", "https_traffic_only_enabled"],
+  ["azurerm_network_interface", "enable_accelerated_networking", "accelerated_networking_enabled"],
+  ["azurerm_network_interface", "enable_ip_forwarding", "ip_forwarding_enabled"],
+  ["azurerm_redis_cache", "enable_non_ssl_port", "non_ssl_port_enabled"],
+  ["azurerm_kubernetes_cluster", "automatic_channel_upgrade", "automatic_upgrade_channel"],
+  ["azurerm_kubernetes_cluster", "node_os_channel_upgrade", "node_os_upgrade_channel"],
+  ["azurerm_kubernetes_cluster_node_pool", "enable_auto_scaling", "auto_scaling_enabled"],
+  ["azurerm_kubernetes_cluster_node_pool", "enable_node_public_ip", "node_public_ip_enabled"],
+  ["azurerm_kubernetes_cluster_node_pool", "enable_host_encryption", "host_encryption_enabled"],
+  [
+    "azurerm_cosmosdb_account",
+    "enable_multiple_write_locations",
+    "multiple_write_locations_enabled",
+  ],
+  ["azurerm_cosmosdb_account", "enable_free_tier", "free_tier_enabled"],
+  ["azurerm_cosmosdb_account", "enable_automatic_failover", "automatic_failover_enabled"],
+  ["azurerm_servicebus_queue", "enable_batched_operations", "batched_operations_enabled"],
+  ["azurerm_servicebus_queue", "enable_express", "express_enabled"],
+  ["azurerm_servicebus_queue", "enable_partitioning", "partitioning_enabled"],
+  ["azurerm_servicebus_topic", "enable_batched_operations", "batched_operations_enabled"],
+  ["azurerm_servicebus_topic", "enable_express", "express_enabled"],
+  ["azurerm_servicebus_topic", "enable_partitioning", "partitioning_enabled"],
+  ["azurerm_servicebus_subscription", "enable_batched_operations", "batched_operations_enabled"],
+  ["azurerm_managed_application", "parameters", "parameter_values"],
+  ["azurerm_sentinel_automation_rule", "condition", "condition_json"],
+  [
+    "azurerm_machine_learning_workspace",
+    "public_access_behind_virtual_network_enabled",
+    "public_network_access_enabled",
+  ],
+];
+
+/** Renames inside a nested block. The parser sees top-level argument names only,
+ *  so these can never be `confirmed` — they are reported as leads to check by
+ *  hand, which is why they are kept separate rather than mixed in above.
+ *
+ *  ⚠️ Filing a nested argument as top-level makes the entry DEAD, not merely
+ *  imprecise: the matcher tests membership of the depth-0 name list, which a
+ *  nested argument never appears in. `network_interface.is_primary` was written
+ *  as bare `is_primary` in the first cut and could never have fired. */
+const NESTED_RENAMES: [resource: string, from: string, to: string][] = [
+  [
+    "azurerm_kubernetes_cluster",
+    "default_node_pool.enable_auto_scaling",
+    "default_node_pool.auto_scaling_enabled",
+  ],
+  [
+    "azurerm_kubernetes_cluster",
+    "default_node_pool.enable_node_public_ip",
+    "default_node_pool.node_public_ip_enabled",
+  ],
+  [
+    "azurerm_kubernetes_cluster",
+    "default_node_pool.enable_host_encryption",
+    "default_node_pool.host_encryption_enabled",
+  ],
+  [
+    "azurerm_redis_cache",
+    "redis_configuration.enable_authentication",
+    "redis_configuration.authentication_enabled",
+  ],
+];
+
+/** Arguments removed from inside a nested block. Same depth-0 caveat as above. */
+const NESTED_REMOVED: [resource: string, arg: string][] = [
+  ["azurerm_site_recovery_replicated_vm", "network_interface.is_primary"],
+];
+
+/**
+ * Arguments deleted with no replacement — the fix is to remove the line.
+ *
+ * ⚠️ Everything here must be a genuine deletion. An argument that was removed
+ * *in favour of* another one belongs above as a rename with a `value_change`:
+ * telling someone to delete `soap_pass_through` rather than write
+ * `api_type = "soap"` silently converts their SOAP API to HTTP. Two entries in
+ * the first cut of this pack were misfiled that way.
+ *
+ * ⚠️ Nothing COMPUTED belongs here either. `azurerm_cosmosdb_account.connection_strings`
+ * was removed in v4, but it is a read-only attribute — it never appears as an
+ * argument in a `resource` block, so an entry for it can never match. It would
+ * have looked like coverage of a real breakage (`…account.x.connection_strings[0]`
+ * in an expression elsewhere) while detecting nothing.
+ */
+const REMOVED_ARGUMENTS: [resource: string, arg: string][] = [
+  ["azurerm_kubernetes_cluster", "enable_pod_security_policy"],
+  ["azurerm_kubernetes_cluster", "custom_ca_trust_enabled"],
+  ["azurerm_kubernetes_cluster", "message_of_the_day"],
+  ["azurerm_kubernetes_cluster_node_pool", "custom_ca_trust_enabled"],
+  ["azurerm_kubernetes_cluster_node_pool", "message_of_the_day"],
+  ["azurerm_storage_share_directory", "storage_account_name"],
+  ["azurerm_storage_table_entity", "storage_account_name"],
+  ["azurerm_dev_test_lab", "storage_type"],
+  ["azurerm_machine_learning_compute_instance", "location"],
+];
+
+/** Arguments that became REQUIRED in v4 — absent, `plan` fails. */
+const NEWLY_REQUIRED: [resource: string, arg: string][] = [
+  ["azurerm_virtual_network_gateway_connection", "shared_key"],
+  ["azurerm_dashboard_grafana", "grafana_major_version"],
+  ["azurerm_monitor_activity_log_alert", "location"],
+];
+
+function entry(e: TransformEntry): TransformEntry {
+  return e;
+}
+
+const ENTRIES: TransformEntry[] = [
+  // ── provider block ──────────────────────────────────────────────────────
+  entry({
+    id: "azurerm.3-4.provider-subscription-id",
+    kind: "provider_setting",
+    resource_type: null,
+    from: "(implicit subscription)",
+    to: "subscription_id",
+    state_move: "auto",
+    forces_replacement: false,
+    note: "v4 requires `subscription_id` in the provider block (or ARM_SUBSCRIPTION_ID in the environment). Prefer the environment variable in CI so a subscription id is not committed.",
+  }),
+  entry({
+    id: "azurerm.3-4.provider-registrations",
+    kind: "provider_setting",
+    resource_type: null,
+    from: "skip_provider_registration",
+    to: "resource_provider_registrations",
+    state_move: "auto",
+    forces_replacement: false,
+    value_change:
+      'not a boolean any more — it takes a MODE: `core`, `extended`, `all`, `none` or `legacy`. `skip_provider_registration = true` becomes `resource_provider_registrations = "none"`.',
+    note: "Replace the boolean with the equivalent registration mode; `resource_providers_to_register` can name extra RPs alongside it.",
+  }),
+
+  // ── whole-resource replacements (state must be moved by hand) ───────────
+  ...REMOVED_RESOURCES.map(([from, to]) =>
+    entry({
+      id: `azurerm.3-4.resource.${from}`,
+      kind: to ? "resource_renamed" : "resource_removed",
+      resource_type: from,
+      from,
+      to,
+      state_move: "manual_import",
+      forces_replacement: true,
+      note: to
+        ? `\`${from}\` was removed in v4. Migrate to \`${to}\`: the schemas differ, so this is \`terraform state rm\` + \`terraform import\`, NOT a rename and NOT a \`moved {}\` block.`
+        : `\`${from}\` was removed in v4 with no replacement resource. The configuration has to be deleted and the capability re-provisioned another way.`,
+    }),
+  ),
+
+  // ── argument renames ────────────────────────────────────────────────────
+  ...ARGUMENT_RENAMES.map(([resource, from, to]) =>
+    entry({
+      id: `azurerm.3-4.arg.${resource}.${from}`,
+      kind: "argument_renamed",
+      resource_type: resource,
+      from,
+      to,
+      state_move: "auto",
+      forces_replacement: false,
+      note: `Renamed in v4: \`${from}\` → \`${to}\`. Same meaning and same value — a plan after the edit should show no change.`,
+    }),
+  ),
+  ...NESTED_RENAMES.map(([resource, from, to]) =>
+    entry({
+      id: `azurerm.3-4.arg.${resource}.${from}`,
+      kind: "argument_renamed",
+      resource_type: resource,
+      from,
+      to,
+      state_move: "auto",
+      forces_replacement: false,
+      note: `Renamed in v4, INSIDE a nested block: \`${from}\` → \`${to}\`. Open the block and check — the scanner only sees top-level argument names, so it cannot confirm this one for you.`,
+    }),
+  ),
+
+  // ── the ones that are NOT pure renames ──────────────────────────────────
+  entry({
+    id: "azurerm.3-4.arg.azurerm_route_table.disable_bgp_route_propagation",
+    kind: "argument_renamed",
+    resource_type: "azurerm_route_table",
+    from: "disable_bgp_route_propagation",
+    to: "bgp_route_propagation_enabled",
+    state_move: "auto",
+    forces_replacement: false,
+    value_change:
+      "⚠️ THE BOOLEAN IS INVERTED. `disable_bgp_route_propagation = true` becomes `bgp_route_propagation_enabled = false`. Copying the value across silently reverses route propagation on a live network, and nothing — validate, plan shape, or any scanner — will flag it.",
+    note: "Rename AND negate. Treat every occurrence as a value change, not a rename.",
+  }),
+  // ⚠️ THE SUBNET FAMILY. Both of these read as boring boolean renames and are
+  // neither. v3's `enforce_*` pair used INVERTED polarity (`true` = *disable*
+  // the policy); v4's replacements are positive, and one of them is a string.
+  // Carrying the value across breaks Private Link on a live subnet with a green
+  // validate, a green plan shape and no scanner finding — the same trap as the
+  // route-table entry below, which the first cut of this pack caught while
+  // missing these two.
+  entry({
+    id: "azurerm.3-4.arg.azurerm_subnet.enforce_private_link_service_network_policies",
+    kind: "argument_renamed",
+    resource_type: "azurerm_subnet",
+    from: "enforce_private_link_service_network_policies",
+    to: "private_link_service_network_policies_enabled",
+    state_move: "auto",
+    forces_replacement: false,
+    value_change:
+      "⚠️ THE BOOLEAN IS INVERTED. In v3, `enforce_… = true` DISABLED the policy; in v4, `private_link_service_network_policies_enabled = true` ENABLES it. `true` must become `false` and vice versa. A subnet hosting a Private Link Service needs the policy disabled — copy the value across unchanged and you enable it, and the service stops working.",
+    note: "Rename AND negate. Note the defaults also flipped (v3 `false`, v4 `true`), so an omitted argument does not mean the same thing either.",
+  }),
+  entry({
+    id: "azurerm.3-4.arg.azurerm_subnet.enforce_private_link_endpoint_network_policies",
+    kind: "argument_renamed",
+    resource_type: "azurerm_subnet",
+    from: "enforce_private_link_endpoint_network_policies",
+    to: "private_endpoint_network_policies",
+    state_move: "auto",
+    forces_replacement: false,
+    value_change:
+      '⚠️ NOT A DELETION AND NOT A BOOLEAN. It becomes a STRING: `"Enabled"` / `"Disabled"`. v3\'s inverted polarity applies, so `enforce_… = false` (policies enforced) becomes `private_endpoint_network_policies = "Enabled"`, and `= true` becomes `"Disabled"`. ⚠️ v4 DEFAULTS this to `"Disabled"` — simply dropping the line silently stops NSGs and route tables applying to every private endpoint in that subnet.',
+    note: "Removed in favour of `private_endpoint_network_policies`. Always write the replacement explicitly; never delete the line and rely on the default.",
+  }),
+  entry({
+    id: "azurerm.3-4.arg.azurerm_api_management_api.soap_pass_through",
+    kind: "argument_renamed",
+    resource_type: "azurerm_api_management_api",
+    from: "soap_pass_through",
+    to: "api_type",
+    state_move: "auto",
+    forces_replacement: false,
+    value_change:
+      '`soap_pass_through = true` becomes `api_type = "soap"`; `false` becomes `api_type = "http"` (also v4\'s default). Deleting the line instead converts a SOAP-fronted API to HTTP.',
+    note: "Removed in favour of the `api_type` property — a replacement, not a deletion.",
+  }),
+  entry({
+    id: "azurerm.3-4.arg.azurerm_cosmosdb_sql_container.partition_key_path",
+    kind: "argument_renamed",
+    resource_type: "azurerm_cosmosdb_sql_container",
+    from: "partition_key_path",
+    to: "partition_key_paths",
+    state_move: "auto",
+    forces_replacement: true,
+    value_change: 'the type changed from a string to a list — wrap the existing value: `["/id"]`.',
+    note: "Changing a container's partition key forces replacement of the container, which loses its data. Confirm the plan before shipping.",
+  }),
+  entry({
+    id: "azurerm.3-4.arg.azurerm_container_group.network_profile_id",
+    kind: "argument_renamed",
+    resource_type: "azurerm_container_group",
+    from: "network_profile_id",
+    to: "subnet_ids",
+    state_move: "auto",
+    forces_replacement: true,
+    value_change:
+      "a network-profile id is not a subnet id — supply the subnet id(s) the profile referenced.",
+    note: "Network profiles were retired; the container group now takes subnet ids directly.",
+  }),
+  entry({
+    id: "azurerm.3-4.arg.azurerm_storage_share_directory.share_name",
+    kind: "argument_renamed",
+    resource_type: "azurerm_storage_share_directory",
+    from: "share_name",
+    to: "storage_share_id",
+    state_move: "auto",
+    forces_replacement: true,
+    value_change: "a name is not an id — reference the share resource's `id` attribute.",
+    note: "Also drop `storage_account_name`; the share id carries it.",
+  }),
+  entry({
+    id: "azurerm.3-4.arg.azurerm_storage_table_entity.table_name",
+    kind: "argument_renamed",
+    resource_type: "azurerm_storage_table_entity",
+    from: "table_name",
+    to: "storage_table_id",
+    state_move: "auto",
+    forces_replacement: true,
+    value_change: "a name is not an id — reference the table resource's `id` attribute.",
+    note: "Also drop `storage_account_name`; the table id carries it.",
+  }),
+
+  // ── deletions and new requirements ──────────────────────────────────────
+  ...REMOVED_ARGUMENTS.map(([resource, arg]) =>
+    entry({
+      id: `azurerm.3-4.removed.${resource}.${arg}`,
+      kind: "argument_removed",
+      resource_type: resource,
+      from: arg,
+      to: null,
+      state_move: "auto",
+      forces_replacement: false,
+      note: `\`${arg}\` was removed from \`${resource}\` in v4 — delete the line.`,
+    }),
+  ),
+  ...NESTED_REMOVED.map(([resource, arg]) =>
+    entry({
+      id: `azurerm.3-4.removed.${resource}.${arg}`,
+      kind: "argument_removed",
+      resource_type: resource,
+      from: arg,
+      to: null,
+      state_move: "auto",
+      forces_replacement: false,
+      note: `\`${arg}\` was removed from \`${resource}\` in v4 — delete the line. It lives INSIDE a nested block, so the scanner cannot confirm it for you; open the block and check.`,
+    }),
+  ),
+  ...NEWLY_REQUIRED.map(([resource, arg]) =>
+    entry({
+      id: `azurerm.3-4.required.${resource}.${arg}`,
+      kind: "argument_required",
+      resource_type: resource,
+      from: arg,
+      to: arg,
+      state_move: "auto",
+      forces_replacement: false,
+      note: `\`${arg}\` is REQUIRED on \`${resource}\` in v4. Add it before planning, or the plan fails.`,
+    }),
+  ),
+];
+
+export const AZURERM_3_TO_4: TransformPack = {
+  provider: "azurerm",
+  from_major: 3,
+  to_major: 4,
+  version: "2026.07",
+  source: SOURCE,
+  exhaustive: false,
+  entries: ENTRIES,
+};