<!-- ephemeral -->

# .NET Assist — Debug and SQL evidence

Generated SQL providers send structured execution metadata to the trusted
`IDiagnosticSqlLogSink`. Install `SafeSqlEvidenceSink` to retain a bounded,
value-free projection while still emitting the default operator-readable log.

```csharp
using System.Collections.Generic;
using System.IO;
using TeaQL.DataService;
using TeaQL.Runtime;

namespace Generated;

public sealed record SafeSqlEvidence(
    string Operation,
    string ParameterizedSql,
    int ParameterCount,
    long ElapsedMicros,
    int? ResultCount,
    long? AffectedRows,
    string ResultSummary);

public static class DebugEvidence
{
    public static IReadOnlyList<SafeSqlEvidence> Safe(SafeSqlEvidenceSink sink) => sink.Snapshot();
}

public sealed class SafeSqlEvidenceSink : IDiagnosticSqlLogSink
{
    private const int Capacity = 256;
    private readonly object gate = new();
    private readonly List<SafeSqlEvidence> entries = new();
    private readonly TextDiagnosticSqlLogSink text;

    public SafeSqlEvidenceSink(TextWriter? writer = null) => text = new(writer);

    public void Write(ExecutionMetadata metadata)
    {
        text.Write(metadata);
        var elapsed = metadata.EndedAt - metadata.StartedAt;
        var summary = metadata.ResultCount is not null
            ? $"{metadata.ResultCount} rows returned"
            : metadata.AffectedRows is not null ? $"{metadata.AffectedRows} rows affected" : "";
        var safe = new SafeSqlEvidence(
            metadata.Operation.ToString().ToLowerInvariant(),
            metadata.ParameterizedQuery ?? "",
            metadata.ParameterCount,
            (long)(elapsed.TotalMilliseconds * 1_000),
            metadata.ResultCount,
            metadata.AffectedRows is null ? null : checked((long)metadata.AffectedRows.Value),
            summary);
        lock (gate)
        {
            if (entries.Count == Capacity) entries.RemoveAt(0);
            entries.Add(safe);
        }
    }

    public IReadOnlyList<SafeSqlEvidence> Snapshot()
    {
        lock (gate) return entries.ToArray();
    }

    public void Clear()
    {
        lock (gate) entries.Clear();
    }
}
```

Every query still requires non-empty `Comment(...)` and `Purpose(...)`;
every mutation requires `AuditAs(...)`. Preserve not-found, checker,
optimistic-conflict, and provider failures rather than returning an empty
successful result.

Query and mutation logs and `TextDiagnosticSqlLogSink` are enabled by default.
Use `context.EnableQuerySqlLog()`, `context.DisableQuerySqlLog()`,
`context.EnableMutationSqlLog()`, and `context.DisableMutationSqlLog()`
independently. Call `sink.Clear()` when a diagnostic window starts. Each metadata entry retains a
typed multi-level trace, parameterized SQL, copy-paste `DebugQuery`, elapsed
time, result count, and affected rows. Comment, purpose, and audit reason are
provider-populated metadata; the current SQLite `DebugQuery` also embeds the
query comment. Passing `null` to `WithDiagnosticSqlLogSink` removes operator
output. Rendered SQL must never be exported as ordinary telemetry or returned
in an HTTP response.

---

## TeaQL seven-language assist contract

Apply the verified Rust semantic ceiling while using only the exact DOTNET 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.