Debugging and Governance Checklist

Use this checklist for an application release, a debugging guide change, or a runtime/provider upgrade. Record the runtime, provider, database, generated dependency versions, commit, command, and retained evidence for every checked item. An unchecked item is not implied support.

Evidence window

• The test starts from an empty SQL-evidence window.
• All, query-only, mutation-only, and disabled collection modes behave as documented.
• Switching modes cannot expose entries from the preceding mode.
• Safe evidence contains operation, parameterized SQL, parameter count, duration, counts, and a bounded summary.
• Safe evidence contains no raw binds, rendered SQL, credentials, connection strings, tenant IDs, actor IDs, or field values.
• Operator diagnostic output is access-controlled and removed or disabled after the test.
• Missing intent and provider failures remain errors rather than empty successful results.

Query, deep relations, Facets, and aggregates

• A bounded Query records non-empty comment and purpose.
• The typed trace identifies the outer Request, relation lineage, provider, and SQL operation.
• A deep selected relation can be distinguished from the outer Query in the trace.
• Repeated child traces are reviewed for N+1 behavior.
• Per-parent Top-N is executed by the exact provider plan, not in-memory slicing.
• Facet evidence records the outer filter, Facet name, child-domain predicate, include-all choice, and metric aliases.
• Include-all retains allowed zero-count buckets; matched-only removes them.
• Grouped aggregate aliases and result rows match the filtered population.
• Relation aggregates are attached to the correct parents.
• Counts are not incorrectly recomputed from a paged application list.

Mutation and audit

• Every save carries a non-empty business audit reason.
• Checker/Fix, request policy, provider mutation, and audit delivery are separately observable.
• Create, update, delete, and recover have the expected affected-row evidence.
• A stale version produces an optimistic-conflict failure.
• Raw row audit and masked application audit are tested as separate paths.
• Audit masking fields and maximum value length are verified with sensitive fixture data.
• Telemetry sampling cannot suppress the application audit sink.
• The chosen audit-sink failure policy is explicit and tested.

RuntimeTelemetry

• The no-op default changes no business result.
• Query, mutation, relation load, provider, cache, TFP, and audit operations use start/success/failure lifecycles where exercised.
• Error categories come from native types rather than raw messages.
• Exporter failure is fail-open and cannot change Query, save, audit, or readiness results.
• Telemetry excludes entity/user/tenant IDs, parameters, field values, audit reasons, request bodies, full URLs, and rendered SQL.
• W3C trace context is propagated through TFP metadata rather than business payload fields.
• The application owns bounded processors, exporter, sampling, flush, and shutdown.

Cache, lock, and cloud infrastructure

• Local-cache hit, miss, expiry, replacement, removal, concurrency, and cross-context process scope are tested.
• Cache keys contain every tenant/root, permission, locale, query-shape, namespace, and version input that affects the result.
• Audited create/update/delete/recover invalidates affected row, list, relation, Facet, and aggregate entries.
• Remote-cache provider presence and health are part of readiness when the cache is required.
• Remote-cache serialization failure and provider outage follow an explicit fail-open or fail-closed policy.
• Cache telemetry reports only operation, safe hit/miss outcome, duration, and error category; it excludes keys and values.
• Local-lock tests cover contention, same-owner renewal, wait timeout, lease expiry, non-owner release, and cleanup after failure.
• A multi-replica critical section uses Remote Lock rather than Local Lock.
• A required Remote Lock fails readiness when its provider is absent; optional no-op success is not treated as exclusion evidence.
• Redis release is owner-safe and atomic, or the adapter is explicitly qualified and not used as the sole critical guard.
• Idempotency records, database constraints, transactions, and optimistic locks remain in place where required.
• Nacos/Consul tests cover registration, healthy discovery where implemented, namespace/group/token handling, non-2xx responses, transport failure, and deregistration.
• Liveness is process-only; readiness reaches every required provider and returns out-of-service during shutdown.
• Graceful shutdown stops readiness, deregisters, drains work, flushes telemetry, and closes pools in a tested order.
• Tokens, credentials, configuration values, cache/lock keys, tenant IDs, and full service metadata are absent from logs and telemetry.
• Live-provider evidence is not inferred from an in-process HTTP protocol test.
• Unsupported infrastructure such as object storage, messaging, secrets, scheduling, and search is not presented as TeaQL runtime support.

Tenant and governance boundary

• The authoritative tenant comes from authentication or another trusted server identity.
• Missing tenant, request policy, provider, or schema dependency fails readiness.
• Recursive input validation rejects tenant, provider/data service, request policy, audit sink, hard limit, and pagination-governance overrides.
• Tenant A cannot read Tenant B through list, direct ID, relation, Facet, aggregate, or pagination paths.
• Tenant A cannot create, update, delete, or recover Tenant B data.
• A malicious business filter cannot broaden the trusted tenant constraint.
• Background jobs create an explicit service identity and tenant scope.
• TFP/federation requests cannot replace trusted local governance resources.
• The test accounts for the selected runtime's actual Request Policy hook coverage; application/provider guards cover any remaining mutation or TypeScript query boundary.

Documentation maintenance

• The language page names only APIs present in the current generated Debug and Runtime Customization Assist.
• Query/Facet/Aggregation examples link to the matching language data-operations page.
• Safe evidence, diagnostic SQL, telemetry, and audit are described as four distinct outputs.
• Provider execution evidence is not generalized into a support-lifetime promise.
• The conformance status record contains source revisions, verification commands, passes, gaps, and qualifications.
• npm run check:docs-contracts, the relevant script tests, and npm run build pass, or failures are recorded exactly.