Covers conformance fixtures, adversarial cases, quality metrics, budgets, monitoring, fallback, and incident review for analytics query planning, so adopters can compile a natural-language analytics request into a validated metric query plan rather than mod...
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
For Analytics query planning, verify the contract under success, denial, failure, recovery, load, and drift so adopters can compile a natural-language analytics request into a validated metric query plan rather than model-authored SQL. The planner selects registered semantic operations; the trusted gateway alone compiles and executes database-specific queries. This is a reference contract: database products, numeric budgets, jurisdictions, retention, organizational defaults, and accountable owners remain explicit adoption choices.
Scope
- The Analytics query planning actors, inputs, outputs, states, versions, and externally visible outcomes needed to compile a natural-language analytics request into a validated metric query plan rather than model-authored SQL.
- The role-specific focus of this block: verify the contract under success, denial, failure, recovery, load, and drift, including primary, cached, asynchronous, export, support, and recovery paths where applicable.
- Adoption-specific configuration, ownership, rollout, evidence retention, and review responsibilities needed to use the contract safely.
Outside this block
- The planner selects registered semantic operations; the trusted gateway alone compiles and executes database-specific queries.
- Choosing a universal database, model, renderer, vendor, numeric threshold, retention period, timezone, jurisdiction, or service-level objective.
- Claiming that packaged scenarios ran against a downstream implementation or that this reference grants security, privacy, accessibility, analytical, or legal approval.
Contract
- Verification evidence for Analytics query planning must demonstrate this rule: The planner emits a closed structured schema containing metric IDs and approved operators; free-form SQL, expressions, table names, and column names are forbidden fields.
- Verification evidence for Analytics query planning must demonstrate this rule: Metric aliases, company names, and relative periods are resolved through tools and become canonical references before execution.
- Verification evidence for Analytics query planning must demonstrate this rule: Every dimension, filter, grain, comparison, and breakdown is checked against metric capabilities and caller policy before it enters the plan.
- Verification evidence for Analytics query planning must demonstrate this rule: The plan declares expected result shape, row and series limits, freshness need, precision mode, and cost class so the gateway can reject excessive work early.
- Verification evidence for Analytics query planning must demonstrate this rule: One user question may decompose into bounded independent metric calls whose dependencies and shared scope are explicit.
- Verification evidence for Analytics query planning must demonstrate this rule: The planner never treats a tool description, read-only annotation, user-supplied tenant identifier, or prior result handle as authorization evidence.
- Verification evidence for Analytics query planning must demonstrate this rule: A normalized plan has a stable digest used for caching, audit, reproducibility, and equality checks without persisting the original sensitive wording.
- Verification evidence for Analytics query planning must demonstrate this rule: Plan repair may change only fields identified by structured tool errors and cannot widen subject scope or swap the requested metric silently.
Implementation guidance
- Create paired positive and negative fixtures for each public operation, semantic rule, authorization boundary, and terminal state.
- Measure correctness, unsupported output, denial consistency, latency, resource use, and recovery by contract and implementation version.
- Inject dependency, policy, schema, freshness, cancellation, and audit failures before promoting the implementation beyond review.
- Keep human domain review for consequential interpretations and feed disagreements into versioned fixtures and rules.
Failure handling and safeguards
- For Analytics query planning, An unresolvable metric, subject, period, dimension, or comparison returns a clarification or unsupported request before database work begins.
- For Analytics query planning, A plan above query, cost, cardinality, or result-size budgets is narrowed with user-visible consequences or denied.
- For Analytics query planning, If multiple metrics match materially different meanings, the planner presents their plain descriptions rather than choosing from abbreviated IDs.
Verification and operations
- For the testing evidence of Analytics query planning, validate plans against a closed schema and fuzz all strings to prove that SQL fragments cannot become identifiers, filters, or expressions.
- For the testing evidence of Analytics query planning, compare normalized plans with gold fixtures for common questions, paraphrases, ambiguous periods, and multi-metric dashboards.
- For the testing evidence of Analytics query planning, verify that repair after every error class preserves caller scope, metric intent, plan budget, and prior approved assumptions.
Adoption assumptions
- The adopting product has authenticated identity, a versioned authorization policy, owned metric definitions, bounded telemetry, and a controlled path for change.
- Names and values in the example are fictional adoption fixtures, not universal defaults, production credentials, performance promises, or business targets.
- Referenced specifications constrain protocol, security, accessibility, or vendor behavior; the adopting team must confirm current applicability before promotion.
The executable-looking examples in this package are fixtures and acceptance contracts. Run the collection validator to check structure and metadata, then translate and execute the scenarios in the target repository before recording implementation evidence.
References
- NIST AI 600-1, Generative AI Profile (applies as of 2026-09-12)
- JSON Schema Core, Draft 2020-12
- Model Context Protocol 2026-07-28, Tools (applies as of 2026-09-12)