Goal

Publish a Data Studio dashboard with tile-level parity to the Looker agent-analytics-block, using only the flat BigQuery views created by the ADK BigQuery Agent Analytics plugin.

Scope decision: no SDK implementation

This work must not add or change anything in the BigQuery Agent Analytics SDK:

• no SDK-managed BigQuery views;
• no bqaa dashboard-views CLI;
• no Python manager/client/export changes;
• no packaged SQL or SDK tests;
• no materialization command;
• no PR against SDK source code.

The SDK issue is only the tracking issue. The deliverables are the Data Studio report/template, its embedded BigQuery custom query, a parity manifest/checklist, screenshots, a hydration helper, and an operator runbook — all owned by the dedicated dashboard artifact repository selected in decision D3.

Source contracts

BQAA views are the semantic source of truth

Prerequisites:

• ADK Python 1.27.0 or later, where automatic view creation is supported.
• Automatic view creation enabled, with version-accurate configuration: on 1.27.0, BigQueryLoggerConfig(create_views=True) — the generated prefix is hardcoded to v and no view_prefix field exists; on 1.36.1 and 2.4.0, BigQueryLoggerConfig(create_views=True, view_prefix="v") with custom prefixes supported.
• The plugin projection must retain the fields needed by the dashboard. If content, attributes, or latency_ms projections are denied, BQAA can omit dependent derived columns from generated views and the report is not compatible.

Every generated view contains the common event columns:

timestamp, event_type, agent, session_id, invocation_id, user_id, trace_id, span_id, parent_span_id, status, error_message, and is_truncated.

The dashboard-specific fields already exist in:

Do not recreate, replace, or extend these views. BQAA owns them and can refresh them with CREATE OR REPLACE VIEW.

Pin a published ADK release

Dashboard v1 distinguishes two compatibility classes:

• parity-certification candidates — the three frozen profiles 1.27.0, 1.36.1, and 2.4.0 (primary target profile 2.4.0). Certification is a lifecycle, not a starting state: M0 marks a candidate's source/query contract validated once inventory, oracle, and query-fixture evidence passes; only M4 end-to-end dashboard parity promotes a candidate to parity-certified. The compatibility matrix records each profile's status, evidence commit, test date, and dashboard version.
• preflight-compatible — any other release from 1.27.0 onward where the required views, fields, and types exist and the query compiles. Preflight is a structural check only: it cannot detect a release that preserves names and types while changing a generated view's calculation, so the hydration helper must warn that such a profile's metric semantics are unverified. A release enters certification only through the lifecycle above.

How the helper classifies at hydration (INFORMATION_SCHEMA cannot identify the creating ADK release, so classification is provenance-based):

• with no declared profile, successful preflight means structurally compatible, release unknown — always emit the unverified-semantics warning;
• certified treatment requires an explicit --adk-profile: the helper compares the observed normalized inventory fingerprint (environment-specific identifiers normalized before hashing view definitions, so project/dataset substitution cannot cause false mismatches) against that profile's committed fingerprint and consults the committed compatibility matrix;
• it reports parity-certified only when the matrix entry has completed M4 evidence for the dashboard version;
• it never infers the installed release from structural similarity — a declared profile plus matching fingerprint is operator-supplied provenance checked against the contract;
• helper output records the declared profile, observed inventory hash, dashboard version, matrix status, and resulting classification.

Freeze contracts from the selected published release tags; do not build against google/adk-python main.

The canonical v1 CUSTOM_QUERY must be one static query whose referenced view names and columns exist in all three releases. INFORMATION_SCHEMA preflight can validate that contract, but it cannot make BigQuery ignore a missing UNION ALL branch. Consequently, 2.x-only workflow-event views are excluded from v1; future coverage requires a separately versioned query/template profile. No parity tile depends on those newer views.

The report version must record:

• minimum and tested ADK versions;
• expected view prefix;
• required view names and column types;
• the static view/column intersection used by the v1 all-events union and its explicit exclusion list;
• the per-release view-prefix capability: 1.27.0 fixed to v; 1.36.1 and 2.4.0 configurable — default v tested on all three, custom-prefix hydration tested only on 1.36.1 and 2.4.0;
• a compatibility check users can run against INFORMATION_SCHEMA.VIEWS and INFORMATION_SCHEMA.COLUMNS.

Reproducible release inventories

INFORMATION_SCHEMA describes a deployed dataset; it does not identify the ADK release that created it. M0 therefore captures inventories with one reusable capture tool run against three isolated fixture datasets created by ADK 1.27.0, 1.36.1, and 2.4.0, committing both expected and observed manifests.

Each snapshot records:

• ADK release and source commit/tag;
• project, dataset, location, and view prefix;
• view names and definitions;
• column names, order, and BigQuery types;
• the static v1 intersection and the explicit excluded-view/column list.

The capture tool accepts the dataset location explicitly and documents the required BigQuery metadata permissions (INFORMATION_SCHEMA.VIEWS).

Data architecture

BQAA creates one view per event type, but it does not create a single all-events view. The Looker block uses all events for Total Events and Events by Agent, so Data Studio needs an embedded BigQuery CUSTOM_QUERY data source that unions the generated views.

A single events data source is the initial hypothesis, subject to the frozen M0 listener decision. If M0 selects the additional-alias design (option 2 below), every added alias requires per-alias hydration by the helper, per-alias credential verification and schema testing, and cost attribution for the added query load; the architecture and parity definition must be updated after M0 with the selected behavior.

No persistent reporting object is created in the user's dashboard dataset (M0 provisions isolated fixture datasets, tables, and views in the test project only):

BQAA plugin
  |
  +-- v_llm_response -----------+
  +-- v_tool_completed ---------+
  +-- v_tool_error -------------+--> Data Studio CUSTOM_QUERY "events"
  +-- v_invocation_starting ----+       UNION ALL, common typed schema
  +-- v_agent_starting ---------+                 |
  +-- other generated v_* ------+                 v
  |                                      7 parity pages + Inspector
  +-- agent_events raw table
      not referenced by dashboard SQL

Embedded events custom query

The template data source aliases itself as events. Its SQL:

1. UNION ALLs the static core view set shared by the 1.27.0, 1.36.1, and 2.4.0 compatibility profiles.
2. Selects the common event columns from every branch.
3. Adds typed null placeholders so every branch has one stable schema.
4. Passes LLM fields only from v_llm_response.
5. Passes successful-tool fields only from v_tool_completed.
6. Passes error-tool fields only from v_tool_error.
7. Computes event_pk = CONCAT(trace_id, '|', span_id) and filtered LLM/tool/error keys for count-distinct measures.
8. Applies @DS_START_DATE and @DS_END_DATE inside the custom query so the partitioned source table can prune dates before aggregation (date semantics below).

Required source columns (validated by the preflight before hydration and reported by name when missing): the common event columns on every unioned view; on v_llm_response, the raw usage_metadata (JSON) needed by the token-precedence rule plus the content-derived token, latency, TTFT, and model-version columns; on the tool views, the tool name/origin/latency columns. A failure fixture must prove that a projected-out usage_metadata fails preflight by name rather than surfacing as a report-time query error.

Required stable output fields (the Looker Studio schema; the raw metadata object is not exposed):

• Common: timestamp, event_date = DATE(timestamp, 'UTC'), all common BQAA IDs, agent/user/status fields, event_pk.
• LLM: llm_response_pk, usage_prompt_tokens, usage_completion_tokens, usage_total_tokens, llm_total_ms, ttft_ms, model_version.
• Successful tool: tool_completed_pk, tool_completed_name, tool_completed_origin, tool_completed_total_ms.
• Tool error: tool_error_pk, tool_error_name, tool_error_origin, tool_error_total_ms.

The query reads only columns exposed by the generated views, but token fields must reproduce the pinned LookML precedence — otherwise four displayed tiles (Token Usage split by Agent, Top 5 users by tokens, token trend, Total Tokens) can disagree with the block and M4's exact-equality gate cannot hold. Read usage_metadata first and fall back to the content-derived column:

COALESCE(
  CAST(JSON_VALUE(usage_metadata, '$.total_token_count') AS INT64),
  usage_total_tokens
) AS usage_total_tokens

with the equivalent precedence for prompt and completion tokens. BQAA 1.27.0's v_llm_response exposes both the content-derived token columns and raw usage_metadata, so this needs no raw-table read and no BQAA view change. Fixtures must include metadata-only, content-only, and conflicting-value rows. For all other fields, BQAA view semantics win when they differ from the LookML derived table.

Repeated call keys: ADK logs streaming partial LLM_RESPONSE events under the same span as the final response, so multiple rows can share llm_response_pk (trace_id|span_id) even though the pinned LookML declares these keys one-to-one. M0 must freeze the dedup semantics for the count-distinct keys, token sums, and latency distributions (e.g. terminal-row-per-key vs raw-row aggregation), back it with streaming partial-plus-final fixtures sharing one trace/span, add duplicate-key audits for LLM and tool terminal events, and document a visible limitation if v1 parity is guaranteed only where the one-to-one key assumption holds.

Cached-token and cache-hit fields are not part of the canonical v1 query because 1.27.0 does not expose them. A later versioned query profile may add them as optional Inspector enrichment, but no parity tile or hydration check may require them in v1.

Date-boundary and timezone semantics (frozen for v1): Looker Studio passes @DS_START_DATE/@DS_END_DATE as YYYYMMDD strings, not typed dates. The query parses them, treats the selected end date as inclusive, and evaluates in UTC unless M0 demonstrates a parity reason for another fixed timezone. Canonical half-open predicate:

WHERE timestamp >= TIMESTAMP(PARSE_DATE('%Y%m%d', @DS_START_DATE), 'UTC')
  AND timestamp < TIMESTAMP(DATE_ADD(PARSE_DATE('%Y%m%d', @DS_END_DATE), INTERVAL 1 DAY), 'UTC')

The data source must have date-range parameters enabled; M0 proves both boundary correctness and partition pruning (custom-query parameters).

Known view-only limitation

Some BQAA event types, including the documented HITL completion events, exist only in the base agent_events table and have no generated view. A query that references generated views only cannot count those rows.

Therefore parity means:

• exact tile/layout parity, with filter parity per the frozen M0 listener decision (exact page-level parity, added aliases, or a documented global-control exception);
• exact metric parity over the parity oracle population: events exposed by the static v1 intersection — the 1.27.0 generated-view set, enumerated by the M0 inventory capture — under the frozen call_row_policy;
• known undercount in Total Events and Events by Agent from two distinct, separately asserted categories: (a) base-table-only event types that no generated-view profile exposes, and (b) generated views added after 1.27.0 that dashboard v1 intentionally excludes.

This limitation must appear in the report help text and setup guide. Removing it would require querying raw agent_events, which is outside the chosen scope.

The canonical v1 union also excludes generated event views that exist only in newer ADK profiles. This is an explicit compatibility choice, not dynamic discovery; adding one requires a versioned dashboard/query release.

Metric contract

The token and latency definitions above are provisional until M0 freezes call_row_policy (raw-row vs terminal-row-per-key aggregation for rows sharing trace_id|span_id); the frozen policy is recorded in the manifest and the definitions are finalized with it.

Do not add daily scalar percentile tables. Daily percentile values cannot be recombined into a correct percentile for an arbitrary report date range.

The LookML model defines 10 current/previous/change triplets, but the source dashboards display previous-period comparison on only 6 business scorecards: Total Tokens, Total Traces, Total Sessions, Total Calls, Total Users, and Total Errors. Implement those six with Data Studio's native Previous period comparison.

Report inventory

Pin the parity target to Looker block commit fe6423cc9775b6dc61f7f7047dd4424603ddb3a1.

The block contains 37 data tiles, not 36: 21 Usage and 16 Performance. It also contains 9 text/navigation elements (4 Usage, 5 Performance — corrected from the earlier estimate of 7 by M0 bootstrap evidence: tools/lookml_to_spec.py enumeration of the pinned LookML). Build one Data Studio page per source tab, plus an inspector page that is not included in the parity count.

Visual corrections from the original issue draft:

• Token Usage split by Agent is a bar, not a donut.
• Traces split by Agent is a bar, not a donut.
• Events by Agent is a bar.
• Tool Invocations is a bar grouped by tool, not a scorecard.

Filter contract:

• Usage tabs declare Date, Trace ID, Agent, User ID, and Span ID.
• Performance tabs declare the same plus Tool Name.
• Dashboard v1 preserves the pinned Looker behavior: Tool Name filters only Average Tool Latency. Implement this by grouping that control with that chart, encode the scope in the parity manifest, and create a linked v1.1 follow-up by M2 exit to evaluate applying it to all successful-tool charts.
• Tool Name is not the only scope exception. In the pinned Usage dashboard, User ID does not affect four tiles — Token Usage split by Agent, Top 5 users with most Tokens consumption, Top 5 users with most Traces, and Traces split by Agent (verified against the pinned LookML listener blocks). The manifest must record the complete control-to-chart listener matrix as explicit edges, plus each control's page/report-level placement.
• Data Studio controls affect all compatible charts on a page by default; grouping narrows a control's scope, but report-level components cannot be grouped with page-level components — which conflicts with persistent Inspector ID controls. M0 must spike the full listener matrix and, before M2, freeze one proven design: (1) exact page-level listener parity, accepting that control state may not follow the user to the Inspector; (2) additional embedded data-source aliases to isolate control scope; or (3) persistent global controls with a documented filter-parity exception.
• Cross-filter supported charts only. Scorecards cannot cross-filter.
• Trace Inspector uses ID controls and page navigation; control persistence across navigation is conditional on the frozen M0 listener design (report-level controls cannot be grouped with page-level components, so exact page-level parity may preclude persistent Inspector state). It does not claim to reproduce Looker's dynamic link: drill URLs.

Template hydration

Use one embedded BigQuery CUSTOM_QUERY data source named events (plus any aliases the frozen M0 listener decision adds — each hydrated, credential-verified, and schema-tested individually).

The canonical template's embedded SQL must be executable at template-construction time: Data Studio cannot discover fields or build the 37 charts over non-existent __PLACEHOLDER__ identifiers, and sqlReplace only rewrites strings when a generated URL is opened. The template therefore embeds real sentinel bindings — a real synthetic template project, a real fixture dataset, and a deliberately unique real view prefix — recorded in a committed binding manifest. The hydration helper replaces those exact sentinel strings with the user's values via ds.events.sqlReplace, sets billingProjectId, and keeps refreshFields=false after schema compatibility has been checked. The SQL artifact pipeline is explicit: events_v1.sql.tmpl (the reviewed logical query), template_bindings.yaml (the executable sentinel bindings), and the generated events_v1.template.sql (the exact SQL embedded in the canonical report). CI renders the generated file reproducibly and rejects drift; M0 approves the template and renderer, M1 embeds the generated result.

Example shape, URL-encoded in the published link:

https://datastudio.google.com/reporting/create?
  c.reportId=<TEMPLATE_ID>
  &ds.events.type=CUSTOM_QUERY
  &ds.events.billingProjectId=<BILLING_PROJECT>
  &ds.events.sqlReplace=<SENTINEL_PROJECT>,<PROJECT>,<SENTINEL_DATASET>,<DATASET>,<SENTINEL_PREFIX>,<PREFIX>
  &ds.events.refreshFields=false

The canonical template must record its owner/group, report ID, embedded data-source alias, tested ADK version, and rebuild procedure. Do not promise report JSON export; the Linking API copies/configures a report but is not a report-as-code export API.

Parity manifest

Maintain a source-controlled dashboard_spec.yaml in the dashboard-owning repository. It is executable, not a skeleton: the bootstrap version already contains 37 uniquely identified chart records derived from block commit fe6423c, ships with a schema, and is validated in CI. Each record contains:

• pinned Looker block source tile and source title;
• Data Studio page and chart type;
• dimensions, metrics (visible and hidden), filters, sort, limit, date default, comparison behavior, and interactions;
• normalized layout geometry (row, column, width, height) from the pinned LookML element;
• value formats and precision; stacking, axes, legends, labels, and sorting; series colors and chart styling;
• explicit control-to-chart listener edges and control placement (page-level vs report-level);
• expected fixture value or percentile tolerance;
• screenshot identifier plus comparison criteria.

The manifest also contains nine executable non_data_elements records — one per source text/navigation element (4 Usage, 5 Performance) — each with content, page, link target, geometry, and style. These are built in M2 and validated in M4 like any chart record.

Parity oracle

The pinned block repository contains no reference screenshots, and running it requires a Looker instance. v1 default: a checked-in, independently reviewed BigQuery SQL oracle — one query per data tile, derived from the pinned LookML measure/filter/join semantics — and the parity promise is semantic dashboard reproduction; rendered visual parity with a live Looker block is explicitly not established. Upgrade path: if a runnable Looker reference environment is available before M0 exit, freeze and record the instance/version and import permission, the BigQuery connection to the seeded fixture dataset, dialect/timezone/manifest-constant settings that affect compiled SQL, the compiled SQL and expected results for all 37 tiles, and seven fixed-viewport reference screenshots for the M4 visual sign-off — and the promise upgrades to validation against the running block.

The oracle is a first-class M0 artifact, not a concept: 37 versioned oracle queries mapped one-to-one to the chart IDs in dashboard_spec.yaml; deterministic expected result sets for each seeded scenario; an oracle runner with CI comparison supporting exact values and declared percentile tolerances; and coverage of tile filters, sorting, limits, current/previous periods, and the frozen call_row_policy.

Independence boundary: the oracle may query the BQAA-generated fixture views and independently translate the pinned LookML semantics, but it must not import or render events_v1.sql.tmpl, reuse the dashboard's calculated fields, or share the production transformation implementation — otherwise a translation defect can appear identically in the implementation and its expected results.

CI assertions (minimum):

• 37 data tiles: 21 Usage + 16 Performance;
• 7 source tabs/pages and 9 executable non_data_elements records;
• the complete control-to-chart listener matrix, including the four User ID exceptions on Usage;
• 6 previous-period business scorecards;
• 8 percentile scorecards;
• 14-day Usage and 7-day Performance date defaults;
• Tool Name grouped only with Average Tool Latency for v1;
• Trace Inspector excluded from the 37-tile parity count.

Layout/visual acceptance: pages declare fixed dimensions and a fixed screenshot viewport. On the SQL-oracle path, the pinned LookML plus dashboard_spec.yaml is the visual and structural specification — M2 screenshots are release-candidate evidence, not pre-existing references; in M4 they are manually verified directly against the manifest fields and pinned LookML, and only after sign-off are they promoted to versioned regression goldens (never compared against images produced by the implementation under test). On the Looker-environment path, block-rendered reference screenshots are compared directly. The v1 target is metric, interaction, and structural-layout parity plus that signed-off visual review — not pixel-exact rendering. A screenshot identifier alone is not an acceptance rule.

Work plan

M0 - Freeze BQAA compatibility and parity

Prerequisites — confirmed access before the spike starts:

• Three isolated ADK-version fixture datasets (1.27.0, 1.36.1, 2.4.0).
• A BigQuery billing project with metadata and query-job permissions.
• Looker Studio report/data-source edit access.
• A second Google identity for hydration testing.
• Budget to generate and query the 10M-event reference workload.
• Parity-oracle decision executed: the checked-in SQL oracle (v1 default), or — if Looker access exists — the frozen Looker reference environment per the Parity oracle section. Looker access is an additional external dependency only on the upgrade path.

Repository bootstrap PR — makes the work reviewable; does not close M0:

• Set the minimum/tested releases: 1.27.0 minimum, 2.4.0 primary, 1.36.1 secondary.
• Set the ownership model and select a dedicated dashboard artifact repository.
• Create the repository before publishing the first reviewable SQL/spec artifact and before M0 approval.
• One reusable inventory capture tool plus the three expected release-profile manifests.
• events_v1.sql.tmpl (reviewed logical query), template_bindings.yaml (sentinel bindings: template project, fixture dataset, unique view prefix), the renderer that generates events_v1.template.sql, and a separate preflight query — with CI asserting reproducible rendering and rejecting drift.
• Complete 37-chart dashboard_spec.yaml derived from block commit fe6423c, its schema, and automated CI validation.
• The parity oracle per its section: 37 versioned oracle queries (one-to-one with manifest chart IDs), deterministic expected result sets per seeded scenario, and the oracle runner with CI comparison — respecting the independence boundary.
• Synthetic 10M-event seed generator, representative query suite, benchmark runner, and written methodology.
• README, LICENSE, source attribution, CODEOWNERS, SECURITY guidance, CI, and query/template versioning conventions.

M0 evidence — only this closes M0:

• Final approved events_v1.sql.tmpl, renderer, template_bindings.yaml, generated events_v1.template.sql, and preflight query — M0's output is the production query contract; M1 does not rewrite it.
• Observed inventory diffs for all three candidate profiles against the expected manifests; frozen static v1 intersection plus base-table-only/newer-view exclusion list; committed normalized inventory fingerprints per profile.
• Spike results: percentile scorecards, native previous-period comparison, @DS_START_DATE/@DS_END_DATE boundary correctness and partition pruning, Linking API sqlReplace hydration, Tool Name grouped control, Inspector navigation.
• Control-scope spike: the complete control-to-chart listener matrix extracted from the pinned LookML, a Data Studio test of grouped vs page/report-level control behavior, and a frozen pre-M2 decision among the three documented listener designs.
• Frozen call_row_policy (raw-row vs terminal-row-per-key), recorded in the manifest and backed by streaming partial-plus-final fixtures and duplicate-key audits for LLM and tool terminal events; the metric-contract token/latency definitions are finalized with it.
• Query-level tests: three-candidate-profile compatibility (custom prefix only on 1.36.1/2.4.0), token-precedence fixtures (metadata-only, content-only, conflicting), and failure evidence — minimum version, missing view, missing projected column, projected-out usage_metadata failing preflight by name, custom prefix, empty dataset, permission denied, schema drift.
• Oracle evidence: every oracle query executes against each applicable frozen fixture profile; every manifest chart ID has exactly one oracle mapping; expected results recorded. This marks each candidate profile's source/query contract validated (full parity certification happens only at M4).
• Benchmark methodology applied and recorded: at least 20 cold runs per representative query shape; documented event mix and payload distribution; selected-column bytes; partitioning/clustering state; cache and BI Engine state; pricing model; and the page-job attribution window.
• The structural union gate measured in total_bytes_processed (≤3× a comparable date-pruned scan) with cache and BI Engine disabled — total_bytes_billed is billing-model-dependent and is reserved for the page/walk budgets; report total_slot_ms where capacity pricing applies.

Exit: the M0 approval gate reviews the bootstrap artifacts plus the evidence set above against the closed maintainer decisions.

M1 - Looker Studio data-source implementation

M0 owns the approved SQL, preflight, compatibility contract, and query-level tests. M1 is the Looker Studio implementation of that contract:

• Configure the BigQuery CUSTOM_QUERY connector with the generated events_v1.template.sql, the stable events alias, and date-range parameters enabled.
• Set field types and default aggregations; add calculated fields with names mapped to the LookML measures.
• Build the hydration helper (dashboard-repository tool, not an SDK command): accept project, dataset, billing project, location, and view prefix; validate strict BigQuery identifier formats; validate prefixes capability-first — preflight the requested prefixed views and, on failure, explain that configurable prefixes require ADK 1.36.1+, never claiming to have detected the installed release (an optional --adk-profile flag may make the explanation version-specific); classify certification per the provenance rule (declared --adk-profile + fingerprint match + matrix status; never structural inference) and record the classification evidence, warning whenever the dataset is preflight-compatible but not parity-certified; run the INFORMATION_SCHEMA preflight as the current user; confirm the static v1 field contract; URL-encode the sqlReplace pairs; print the final Linking API URL.
• Sentinel-binding tests: the embedded template SQL executes against the fixture dataset before replacement; every sentinel string occurs exactly where expected; replacement yields valid target SQL; no sentinel survives hydration.
• Validate the data source against the fixture metric oracle.

Exit: the events source works on all three candidate profiles (1.27.0, 1.36.1, 2.4.0) and returns the fixture metric oracle.

M2 - Data Studio report

• Build 7 parity pages and all 37 data tiles.
• Add the Trace Inspector page.
• Configure 14-day Usage and 7-day Performance defaults.
• Configure exact filters, top-5 sorting/limits, six previous-period comparisons, eight percentiles, and supported cross-filters.
• Implement the frozen listener design from M0: the full control-to-chart matrix including the four User ID exceptions, the Tool Name grouping, and the chosen Inspector-control behavior; link the v1.1 filter-scope follow-up.
• Apply the manifest's layout geometry and visual configuration (formats, stacking, axes, legends, colors) at the declared page dimensions.
• Build the nine non_data_elements from their manifest records.
• Capture canonical screenshots at the fixed viewport, plus empty/error states.

Exit: every chart record points to a working chart with its expected fixture result; every non_data_elements record passes content, link, and layout validation.

M3 - Release-candidate template and hydration

• Build the canonical template as a release candidate restricted to named QA identities, connected only to synthetic fixture data via the sentinel bindings.
• Generate the Linking API hydration link via the helper (sqlReplace; the URL intentionally omits ds.events.connector to invoke embedded-data-source update semantics — record this dependency explicitly).
• Test hydration from a second account, project, dataset, and custom view prefix (custom prefix on the 1.36.1/2.4.0 profiles only).
• Post-hydration credential gate: the Linking API creates the copy with the clicking user's credentials and its URL parameters cannot set the credential mode, so hydration alone proves nothing about credentials. Before any sharing, verify the hydrated data source is set to Viewer's Credentials and record evidence; document why Owner's Credentials is prohibited for shared copies (data credentials). Onboarding is two distinct steps: create the private copy, then pass the credential gate before sharing.
• Document BQAA configuration, required IAM, costs, compatibility checks, and troubleshooting.
• Document template ownership, versioning, rebuild, and rollback.
• Add a named backup Editor and dry-run ownership transfer plus embedded/reusable data-source claim or reconnection.

Exit: a working release-candidate template and helper-generated hydration link, validated end-to-end from a second identity. Onboarding is "run the validation command, open and save the generated private copy, then pass the Viewer's Credentials gate before sharing." No public sharing yet.

M4 - Parity, cost, and security QA

• Compare all 37 metrics against the parity oracle (the checked-in SQL oracle, or the frozen Looker reference environment if provisioned) on the same seeded data, over the static-intersection oracle population.
• Require exact equality for counts, distinct counts, sums, and averages over rows satisfying the LookML one-to-one key assumption; separately test the frozen call_row_policy behavior on repeated-key fixtures; document any intentional divergence from the Looker block as its own result. Use documented tolerance for approximate percentiles.
• Verify and document both expected undercount categories: base-table-only event types, and post-1.27.0 generated views excluded from v1.
• Inspect Data Studio-generated BigQuery jobs and record total_bytes_processed, total_bytes_billed, total_slot_ms, and p50/p95 chart latency per the M0 benchmark methodology (INFORMATION_SCHEMA.JOBS).
• Measure the defined page-refresh and seven-page-plus-Inspector cold-walk sequences against the 2 GB/page and 7.5 GB/walk bytes-billed budgets (explicitly on-demand reference project) and the 10-second p95/chart target.
• Test zero rows, null-heavy data, missing views, removed projected columns, permission denied, stale template schema, current/previous date boundaries, and custom prefixes.
• Review Owner vs Viewer credentials and exposure of trace IDs, user IDs, and errors; confirm tool arguments/results are not exposed (the canonical query intentionally does not select them).
• Manual visual sign-off: on the SQL-oracle path, verify the M2 release-candidate screenshots directly against the manifest fields and pinned LookML, then promote the approved screenshots to versioned regression goldens (no-rendered-visual-parity limitation documented); on the Looker-environment path, compare against the block-rendered reference screenshots.
• Promote each candidate profile that passes end-to-end dashboard parity to parity-certified in the compatibility matrix (status, evidence commit, test date, dashboard version).
• Keep the structural scan gate separate from acceleration: the ≤3× gate is measured in total_bytes_processed with cache and BI Engine disabled; BI Engine may then be evaluated separately for report latency with reservation cost reported. Querying raw agent_events or creating a materialized reporting object requires a separate scope decision.
• Public template sharing and canonical hydration-link publication happen only at M4 exit, after parity, cost, credential, and privacy approval.

Exit: parity checklist, cost envelope, security review, hydration test, and operating runbook are complete — only then is the template shared publicly.

Failure modes

Publication safety

Fixtures are synthetic only. Never commit production project IDs, credentials, service-account keys, trace/user identifiers, prompts, tool arguments/results, or error payloads. Benchmark raw results sanitize project and principal identifiers while retaining the job statistics the cost gate needs. The artifact repository ships matching .gitignore rules and CI secret scanning from the bootstrap PR onward.

Explicitly not in scope

• Any SDK code, CLI, API, package, SQL resource, or SDK documentation change.
• Any SDK-created or user-created persistent BigQuery reporting view/table.
• Reading raw agent_events from the dashboard.
• Session-duration facts, because BQAA does not generate a session rollup view and no parity tile uses them.
• Exact Looker dynamic drill-link behavior.
• Automatically incorporating future ADK views without a dashboard compatibility release.
• Materialization or daily percentile tables.

Closed maintainer decisions

The executable decision record is pinned in this issue comment; the execution-review refinements the full fresh-review fixes (token precedence, M0/M1 split, RC-before-publication, hydration helper, bytes-processed gate, oracle population, layout parity, wording), the second full-review fixes (executable sentinel bindings, version-accurate prefix support, listener-matrix design gate, repeated call-key semantics, non-data elements, visual sign-off, credential gate), the third-review propagation fixes (conditional single-source/Inspector/filter-parity promises, call_row_policy in the metric and M4 contracts, capability-first prefix validation, three-artifact SQL pipeline, support-horizon wording), the fourth-review fixes (SQL-oracle default with Looker upgrade path, preflight/parity compatibility classes), and the final-review fixes (oracle as M0 artifact with independence boundary, certification lifecycle, non-circular screenshot validation) are folded into the sections above:

1. Compatibility: 1.27.0 minimum; 2.4.0 primary; 1.36.1 and 1.27.0 compatibility checks; one static cross-version v1 query.
2. Ownership: managed team ownership with @caohy1988 as owner-of-record and a named backup before M3 publication; no shared credentials.
3. Artifacts: dedicated bigquery-agent-analytics-dashboard repository, required before M0 approval.
4. Tool Name: preserve one-chart scope in v1 through explicit control grouping; track the broader behavior for v1.1.
5. Performance: M0 structural union gate of ≤3× a comparable date-pruned scan, measured in total_bytes_processed with cache/BI Engine disabled; report targets of p95 ≤10 seconds/chart, ≤2 GB/page refresh, and ≤7.5 GB/full cold walk in bytes billed on an explicitly on-demand reference project.

References

• ADK BQAA generated views and schema
• Pinned Looker block
• BigQuery in Data Studio
• Data Studio Linking API, including CUSTOM_QUERY and sqlReplace
• Data Studio percentile function
• Data Studio cross-filtering
• Custom-query date parameters
• INFORMATION_SCHEMA.VIEWS
• Data Studio data credentials
• BigQuery INFORMATION_SCHEMA.JOBS
• ADK 1.27.0 generated-view source