feat(deploy): Terraform property-graph mode parity (issue #286, PR 4) (#291)

Match the bash deploy's schema-derived mode in the Terraform module so the two
surfaces expose the same artifact-mode contract.

- New variable property_graph (bool, default false). When true, the module sets
  BQAA_PROPERTY_GRAPH=property_graph.sql on the Cloud Run Job, so the #289
  runtime derives the ontology+binding (targeting the graph dataset via the #288
  enabler) instead of an explicit ontology/binding pair. The published image
  must be built with build_image.sh --property-graph (PR 3) so the placeholdered
  property_graph.sql + table_ddl.sql are staged.
- Plan-time precondition rejects property_graph=true + extraction_mode=
  compiled-only, mirroring the bash deploy's boundary rejection (derived mode
  stages no reference extractors).
- Explicit ontology/binding (compiled-extractor) path unchanged when
  property_graph=false. terraform.tfvars.example documents the new toggle.

terraform validate passes; terraform fmt clean. Tests: static assertions pin
the variable, the conditional BQAA_PROPERTY_GRAPH env wiring, and the
compiled-only precondition (so bash + TF can't drift), plus a terraform fmt
gate. 12 tests pass.

Next (PR 5): deploy README + Terraform README docs.

Author: caohy1988

examples/migration_v5/periodic_materialization/terraform/main.tf

@@ -66,6 +66,12 @@ locals {
     var.extraction_mode == "compiled-only" ? {
       BQAA_REFERENCE_EXTRACTORS_MODULE = "reference_extractor"
     } : {},
+    # Schema-derived mode (#286): tell the runtime to derive the spec from the
+    # staged ``property_graph.sql`` instead of the explicit ontology/binding
+    # pair. Mirrors the bash deploy's ``BQAA_PROPERTY_GRAPH`` wiring.
+    var.property_graph ? {
+      BQAA_PROPERTY_GRAPH = "property_graph.sql"
+    } : {},
   )
 }
 
@@ -268,6 +274,16 @@ resource "google_cloud_run_v2_job" "periodic" {
     }
   }
 
+  # Schema-derived mode has no reference extractors staged, so
+  # ``compiled-only`` would empty_extract at runtime. Reject the
+  # combination at plan time, mirroring the bash deploy's boundary check.
+  lifecycle {
+    precondition {
+      condition     = !(var.property_graph && var.extraction_mode == "compiled-only")
+      error_message = "property_graph = true (schema-derived mode) does not support extraction_mode = \"compiled-only\": no reference extractors are staged in derived mode. Use \"ai-fallback\", or the explicit ontology/binding path."
+    }
+  }
+
   # Allow IAM bindings on the runtime SA to settle before the
   # Cloud Run Job starts. Same race the bash deploy's
   # ``_retry_iam`` defends against — Terraform's dependency

examples/migration_v5/periodic_materialization/terraform/terraform.tfvars.example

@@ -15,6 +15,9 @@ image_uri         = "us-central1-docker.pkg.dev/your-project/bqaa/periodic-mater
 # Optional overrides (commented = use the default)
 # location              = "US"
 # job_name              = "bqaa-periodic-materialization"
+# property_graph        = false           # true → schema-derived mode (no ontology/binding);
+#                                         #        build the image with build_image.sh --property-graph;
+#                                         #        not compatible with extraction_mode = "compiled-only"
 # extraction_mode       = "ai-fallback"   # or "compiled-only"
 # max_retries           = 2
 # max_session_age_hours = 24              # null → orphan watchdog disabled

examples/migration_v5/periodic_materialization/terraform/variables.tf

@@ -74,6 +74,12 @@ variable "extraction_mode" {
   }
 }
 
+variable "property_graph" {
+  description = "Schema-derived mode (#286). When ``true``, the runtime derives the ontology + binding from a staged ``property_graph.sql`` + the table schemas instead of an explicit ``ontology.yaml`` / ``binding.yaml`` pair (the module sets ``BQAA_PROPERTY_GRAPH=property_graph.sql``). The published image must be built with ``build_image.sh --property-graph`` so the placeholdered (``$${PROJECT_ID}`` / ``$${DATASET}``) ``property_graph.sql`` + ``table_ddl.sql`` are staged. Use for rename-free graphs; not compatible with ``extraction_mode = \"compiled-only\"`` (no reference extractors are staged in derived mode). ``false`` (default) = explicit ontology + binding (the migration-v5 / compiled-extractor path)."
+  type        = bool
+  default     = false
+}
+
 variable "max_retries" {
   description = "Cloud Run Job retry count on failure. The orchestrator's session-level idempotency + append-only state table make additional retries safe. Default 2 matches the deploy script post-#183 (production posture: silently absorb transient BQ slot pressure / rate-limit noise instead of paging on-call)."
   type        = number

tests/test_terraform_property_graph_mode.py

@@ -0,0 +1,78 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Terraform property-graph parity: variable + env + guard wiring (issue #286).
+
+Static assertions on the HCL pin the same contract the bash deploy exposes (so
+the two surfaces don't drift), plus a ``terraform fmt`` gate when the binary is
+available (no provider download / network needed). Full ``terraform validate``
+is exercised locally during development; it needs provider init and is left out
+of CI to stay offline-safe.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
+
+_TF_DIR = (
+    Path(__file__).resolve().parents[1]
+    / "examples"
+    / "migration_v5"
+    / "periodic_materialization"
+    / "terraform"
+)
+_MAIN = (_TF_DIR / "main.tf").read_text()
+_VARS = (_TF_DIR / "variables.tf").read_text()
+_TFVARS = (_TF_DIR / "terraform.tfvars.example").read_text()
+
+
+def test_property_graph_variable_declared() -> None:
+  assert 'variable "property_graph"' in _VARS
+  assert "type        = bool" in _VARS
+
+
+def test_env_var_wired_conditionally() -> None:
+  # BQAA_PROPERTY_GRAPH is set only when var.property_graph is true.
+  assert "var.property_graph ?" in _MAIN
+  assert 'BQAA_PROPERTY_GRAPH = "property_graph.sql"' in _MAIN
+
+
+def test_compiled_only_precondition() -> None:
+  # Plan-time guard mirrors the bash deploy boundary rejection.
+  assert "precondition" in _MAIN
+  assert (
+      '!(var.property_graph && var.extraction_mode == "compiled-only")' in _MAIN
+  )
+
+
+def test_tfvars_example_documents_property_graph() -> None:
+  assert "property_graph" in _TFVARS
+
+
+@pytest.mark.skipif(
+    shutil.which("terraform") is None, reason="terraform binary not available"
+)
+def test_terraform_fmt_clean() -> None:
+  result = subprocess.run(
+      ["terraform", "fmt", "-check", "-recursive"],
+      cwd=str(_TF_DIR),
+      capture_output=True,
+      text=True,
+      timeout=60,
+  )
+  assert result.returncode == 0, f"terraform fmt would change:\n{result.stdout}"