test+docs: harden DDL-detection filter, soften DDL claims (#104)

Addresses three review findings on PR #108:

(1) Live test DDL-detection blind spot
The previous filter required the regressed CREATE OR REPLACE
PROPERTY GRAPH to target _PROJECT.<scratch_dataset>.<spec.name>.
But if skip_property_graph regressed, the compiler would actually
target _PROJECT._DATASET.<spec.name> (the orchestrator's
dataset_id argument is _DATASET in this test, used for extraction
of agent_events). The blind spot: a regression could fire DDL
that the test would not catch.

Fixed by replacing the fully-qualified-graph-ref filter with two
narrower constraints that catch the regression in either dataset:
  - graph name (spec.name) — present in the DDL string regardless
    of which dataset the compiler targets
  - sdk_feature='ontology-gql' label — only SDK-issued
    property-graph jobs carry this label per
    ontology_property_graph.py:465; the test's setup CREATE
    PROPERTY GRAPH (issued via direct SQL) does not, so it does
    not trip the assertion

(2) docs/ontology/ontology-build.md: document graph_ref limitation
Added a "Known limitation" section noting that
result["graph_ref"] reports the extraction dataset, not the
binding's target dataset, in split source/target setups. The
materialized base tables themselves still go to the binding's
target dataset per the resolved spec; only the reported string is
affected.

(3) docs/ontology/ontology-build.md: soften DDL-options wording
"additional indexes, dialect-specific options" was overreaching for
BigQuery property graphs; tightened to "custom labels or other
DDL details the SDK's compiler doesn't generate."

136/136 tests pass.

Author: caohy1988

docs/ontology/ontology-build.md

@@ -56,7 +56,7 @@ Without `--skip-property-graph`, the existing exit-1 behavior on graph-create fa
 ## When to use this
 
 - **You already manage `CREATE PROPERTY GRAPH` in Terraform / dbt / a SQL file.** The SDK's `CREATE OR REPLACE PROPERTY GRAPH` would clobber your DDL on every run.
-- **Your property graph definition uses options the SDK doesn't generate.** You hand-authored the graph DDL to express features (custom labels, additional indexes, dialect-specific options) the SDK's compiler doesn't emit.
+- **Your property graph definition uses DDL details the SDK compiler doesn't emit.** You hand-authored the graph DDL to express custom labels or other DDL details the SDK's compiler doesn't generate.
 - **You want to populate your tables on a different cadence than you redefine the graph.** The graph definition rarely changes; the data is refreshed continuously.
 
 For all other cases, leave the flag off and let the SDK manage the property graph end-to-end.
@@ -82,3 +82,7 @@ assert result["property_graph_created"] is False
 ```
 
 `skipped_reason` is only present when the phase was skipped; it is omitted when phase 5 ran (whether or not it succeeded).
+
+## Known limitation: `result["graph_ref"]` in split source/target setups
+
+`build_ontology_graph(...)` accepts a single `dataset_id` and uses it both for extraction (where `agent_events` lives) and for the `graph_ref` reported in the result dict (`{project_id}.{dataset_id}.{name}`). When `--skip-property-graph` is set and the caller's actual property graph lives in `binding.target.dataset` (different from the `dataset_id` used for extraction), `result["graph_ref"]` reports the **extraction dataset**, not the user-owned graph's dataset. The materialized base tables themselves still go to `binding.target.dataset` per the resolved spec — this only affects the reported `graph_ref` string. Tracked as a follow-up; not blocking for `--skip-property-graph` itself since the user already knows where their authored graph lives.

tests/test_integration_ontology_binding.py

@@ -431,19 +431,39 @@ def test_skip_property_graph_issues_no_create_graph_job(
     )
 
     # Step 4: assert no CREATE OR REPLACE PROPERTY GRAPH job ran for
-    # *this scratch dataset's graph* in the post-timestamp window.
-    # Filter by both the DDL keyword and the fully-qualified graph
-    # reference so the test does not false-fail on an unrelated
-    # CREATE OR REPLACE PROPERTY GRAPH issued by another developer
-    # or test running concurrently in the same project.
-    expected_graph_ref = f"{_PROJECT}.{scratch_dataset}.{spec.name}"
+    # *this test's graph* in the post-timestamp window.
+    #
+    # Filter design:
+    #   1. timestamp > the post-DDL baseline (closes the trap from
+    #      #107 cell 1.3 where the user's own setup CREATE PROPERTY
+    #      GRAPH would otherwise be caught).
+    #   2. DDL keyword.
+    #   3. graph name (spec.name) — the graph name is in the DDL
+    #      string regardless of which dataset the compiler would
+    #      target. If skip_property_graph regresses, the compiler
+    #      runs with dataset_id=_DATASET (the orchestrator's
+    #      argument), so the regressed DDL would target
+    #      _PROJECT._DATASET.<spec.name>, NOT
+    #      _PROJECT.<scratch_dataset>.<spec.name>. Filtering on the
+    #      graph name (rather than the fully-qualified ref) catches
+    #      the regression in either dataset.
+    #   4. sdk_feature='ontology-gql' label — only SDK-issued
+    #      property-graph jobs carry this label
+    #      (ontology_property_graph.py:465), so unrelated user-
+    #      authored CREATE PROPERTY GRAPH DDLs (including the test's
+    #      own setup job in step 1, which was not labeled this way)
+    #      do not trip the assertion.
     region_qual = f"`region-{_LOCATION.lower()}`"
     jobs_query = f"""
     SELECT job_id, query, creation_time
-    FROM {region_qual}.INFORMATION_SCHEMA.JOBS_BY_PROJECT
+    FROM {region_qual}.INFORMATION_SCHEMA.JOBS_BY_PROJECT AS j
     WHERE creation_time > @before
       AND UPPER(query) LIKE '%CREATE OR REPLACE PROPERTY GRAPH%'
-      AND query LIKE @graph_ref_pattern
+      AND query LIKE @graph_name_pattern
+      AND EXISTS (
+        SELECT 1 FROM UNNEST(j.labels) AS l
+        WHERE l.key = 'sdk_feature' AND l.value = 'ontology-gql'
+      )
     """
     job = client.query(
         jobs_query,
@@ -453,9 +473,9 @@ def test_skip_property_graph_issues_no_create_graph_job(
                     "before", "TIMESTAMP", before_skip_build_ts
                 ),
                 bigquery.ScalarQueryParameter(
-                    "graph_ref_pattern",
+                    "graph_name_pattern",
                     "STRING",
-                    f"%{expected_graph_ref}%",
+                    f"%{spec.name}%",
                 ),
             ]
         ),