# Rust Assist — Debug and SQL evidence TeaQL captures structured SQL evidence on `UserContext`. Keep `sql` and `parameter_count` in application diagnostics; `debug_sql` and raw `params` may contain customer data and must remain inside a trusted, access-controlled test or operator boundary. ```rust use teaql_runtime::{SqlLogEntry, SqlLogOptions, SqlLogOperation, UserContext}; #[derive(Debug, Clone, PartialEq, Eq)] pub struct SafeSqlEvidence { pub operation: &'static str, pub parameterized_sql: String, pub parameter_count: usize, pub elapsed_micros: u128, pub result_count: Option, pub affected_rows: Option, pub result_summary: String, pub trace_chain: Vec, pub trace_path: Vec, } pub fn enable_all_sql_evidence(context: &mut UserContext) { context.set_sql_log_options(SqlLogOptions::all()); context.clear_sql_logs(); } pub fn enable_select_sql_evidence(context: &mut UserContext) { context.set_sql_log_options(SqlLogOptions::select_only()); context.clear_sql_logs(); } pub fn enable_mutation_sql_evidence(context: &mut UserContext) { context.set_sql_log_options(SqlLogOptions::mutation_only()); context.clear_sql_logs(); } pub fn disable_select_sql_evidence(context: &mut UserContext) { context.disable_select_sql_log(); context.clear_sql_logs(); } pub fn disable_mutation_sql_evidence(context: &mut UserContext) { context.disable_mutation_sql_log(); context.clear_sql_logs(); } pub fn disable_sql_evidence(context: &mut UserContext) { context.disable_sql_log(); } pub fn sql_evidence(context: &UserContext) -> Vec { context.sql_logs().iter().map(safe_sql_evidence).collect() } fn safe_sql_evidence(entry: &SqlLogEntry) -> SafeSqlEvidence { SafeSqlEvidence { operation: match entry.operation { SqlLogOperation::Select => "select", SqlLogOperation::Insert => "insert", SqlLogOperation::Update => "update", SqlLogOperation::Delete => "delete", SqlLogOperation::Recover => "recover", }, parameterized_sql: entry.sql.clone(), parameter_count: entry.params.len(), elapsed_micros: entry.elapsed.as_micros(), result_count: entry.result_count, affected_rows: entry.affected_rows, result_summary: entry.result_summary.clone(), trace_chain: entry.trace_chain.clone(), trace_path: entry.trace_path.clone(), } } ``` Every generated query must still carry non-empty `.comment(...)` and `.purpose(...)`; every mutation must carry `.audit_as(...)`. Classify not-found, validation/checker, optimistic-conflict, and provider errors rather than converting them into an empty successful result. Runtime log formatting accepts these environment values: - `TEAQL_SQL_LOG`: `_silent`, `_summary`, `_full`, `_full_with_payload`; - `TEAQL_SQL_LOG_TABLES`: comma-separated table focus; - `TEAQL_AUDIT_LOG`: the same four levels; - `TEAQL_AUDIT_LOG_ENTITIES`: comma-separated entity focus. Query and mutation SQL logging are both enabled on a new `UserContext`. `context.disable_select_sql_log()` and `context.disable_mutation_sql_log()` are independent switches; use `disable_sql_log()` only when both families must be silent. Each entry retains `comment`, `purpose`, `audit_reason`, the business `trace_chain` and the separate typed physical `trace_path`, parameterized SQL, copy-paste `debug_sql`, elapsed time, result count, and affected rows. Rendered values remain trusted operator output and `RuntimeTelemetry` must not export them. `trace_chain` follows actual Request parents (root purpose, root comment, native Q operation and nested query comment). `trace_path` records the physical request/relation/provider/SQL route. Neither is reconstructed from SQL or aliases. The entries returned by `sql_logs()` are already privacy-projected; copy those structured fields without adding a display-only business lineage. --- ## TeaQL seven-language assist contract Apply the verified Rust semantic ceiling while using only the exact RUST generated and runtime APIs. Discover APIs through the generated application AGENTS.md and progressive model-aware Assist. Do not inspect generated domain-library source. - Do not create plurals by appending `s` or `es`; use the centralized generated plural. - Human and non-human entities use different generated predicate vocabularies. Preserve forms such as “who are active” and “whose email is”; never infer them from English. - Configure filters, projection, paging, and other query options before `purpose(...)`. Comment may appear anywhere in the chain. Purpose enters the executable stage; execution requires both values, but comment does not have to immediately precede purpose. - Every execute/list/stream and every save accepts exactly one context argument: `UserContext`. Name that argument `context`, never `runtime`; data services and global policy are injected when the context is built. Reserve `runtime` for process-level runtime ownership, provider/pool setup, and module assembly. - Tenant, merchant, identity, permissions, request policy, purpose policy, hard limit, and continuous-page cursor policy come only from trusted context, never dynamic JSON or TFP. - If the required operation is absent after current entity/action and required field Assist, stop that path and report MISSING_ASSIST. Do not guess an API or search the generated library as a fallback. - Create each application-owned source file once. After its first compile attempt, repair only the smallest block identified by the exact compiler or test diagnostic. Preserve unrelated code; do not rewrite the complete file as an error-recovery loop. - Before a repair that would replace more than 25% of an existing application file, stop and report LARGE_REWRITE_REQUEST with the file, exact diagnostic, reason, and estimated scope. Initial creation and model-driven regeneration are not repairs. Capability: `debug`. - Capture purpose, comment, trace/correlation id, runtime-projected expanded masked SQL and its masking mode, duration, row count, provider and the native response. - Preserve the immutable row audit event and the customizable App Audit Sink as separate paths. Redact credentials, tokens, connection strings, and customer data. - Document only switches and hooks present in the selected runtime source. ## Standard OpenTelemetry module Use the optional standard module supplied by the selected TeaQL runtime. Match its version to the runtime dependency selected by the model and workspace; keep local source or internal Registry overrides during development. Do not upgrade to an unrelated public release just to enable telemetry. A runtime without this module reports `module_unavailable`; package installation alone does not enable export. On a supported backend, configure these trusted process variables before startup, never through a query, JSON or TFP payload: ```bash export TEAQL_TELEMETRY_ENABLED=true export TEAQL_TELEMETRY_SERVICE_NAME=payment-service export TEAQL_TELEMETRY_OTLP_ENDPOINT=http://localhost:4318 ``` Without enablement, startup reports `disabled` and all three activation variables; no SDK export resources are created. Enabled startup reports safe effective settings, full recording and masking. Invalid settings produce a fixed safe diagnostic, not a claim of successful export. Never print credentials or raw configuration values. The module automatically records supported Q, graph mutation and physical SQL operations as traces, logs and metrics. SQL is expanded with masked parameters; plaintext debugging never authorizes plaintext telemetry export. Full recording does not promise lossless delivery when bounded queues or exporters fail. Do not add per-method spans or replace the customer's global SDK providers. Keep schema reconciliation explicit. Run the generated ensure-schema and seed flow through the same configured runtime to observe startup settings and audited, idempotent seeding. Telemetry setup must not run ensure-schema implicitly. Flush and shut down the owned pipeline at application shutdown, not per query. Exporter failures do not change business results; durable business audit remains an independent path. ### Rust assembly Enable the `standard-telemetry` feature on the application's existing `teaql-runtime` dependency, preserving its selected version, registry or path. UserContext initialization selects the optional module automatically. Do not add SDK initialization to generated Q or entity methods. Set the three variables before launching the process.