<!-- ephemeral -->

# TeaQL safe SQL execution evidence (TypeScript)

Attach a trusted evidence store to the server-created SQL client and project
only bounded fields before returning diagnostics to an application or Coding
Agent.

```typescript
import type { SQLExecutionMetadata, SQLExecutionOperation } from 'teaql-ts/sql/core';

export type SafeSQLExecutionEvidence = Readonly<{
  operation: SQLExecutionOperation;
  parameterizedSQL: string;
  parameterCount: number;
  elapsedMicros: number;
  resultCount?: number;
  affectedRows?: number;
  resultSummary: string;
}>;

export function safeSQLEvidence(
  entries: readonly SQLExecutionMetadata[],
): readonly SafeSQLExecutionEvidence[] {
  return entries.map(entry => Object.freeze({
    operation: entry.operation,
    parameterizedSQL: entry.parameterizedSQL,
    parameterCount: entry.parameters.length,
    elapsedMicros: entry.elapsedMicros,
    resultCount: entry.resultCount,
    affectedRows: entry.affectedRows,
    resultSummary: entry.resultSummary,
  }));
}
```

Create `SQLExecutionEvidenceStore`, attach it with
`client.setRuntimeTelemetrySink(store)`, and select `enableAll`, `enableSelect`,
`enableMutation`, or `disable`. Mode changes clear earlier entries. Raw
parameters, credentials, connection strings, and interpolated SQL remain inside
the trusted boundary and are intentionally absent above.

Query and mutation logs, including the text diagnostic sink, are enabled by default.
The default sink is `new TextDiagnosticSQLLogSink()` and may be
replaced with `client.setDiagnosticSQLLogSink(...)`. Disable the two operation
families independently with
`client.setQueryLoggingEnabled(false)` and
`client.setMutationLoggingEnabled(false)`; passing `undefined` to
`setDiagnosticSQLLogSink` removes operator output entirely. Each metadata entry
retains structured `comment`, `purpose`, `auditReason`, typed multi-level
`tracePath`, parameterized SQL, copy-paste `debugSQL`, elapsed time, result
count, and affected rows. Rendered SQL can contain secrets and must not be used
as ordinary telemetry.


---

## TeaQL seven-language assist contract

Apply the verified Rust semantic ceiling while using only the exact TYPESCRIPT 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, parameterized SQL summary,
  duration, row count, provider, and the runtime's native response when available.
- 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.