<!-- ephemeral -->

# TeaQL Python Runtime Customization

The application lifespan owns the runtime module, provider, request policy, trusted tenant and
App audit sink. Never populate these resources from Pydantic/request or federation payloads.

```python
from __future__ import annotations

from collections.abc import Mapping, Sequence
from typing import Any

from teaql.runtime import RuntimeModule, UserContext


GOVERNANCE_KEYS = frozenset({
    "tenant", "trusted_tenant", "provider", "schema_provider", "data_service",
    "request_policy", "audit_sink", "app_audit_sink", "hard_limit", "continuous_page",
})


def configured_runtime(
    module: RuntimeModule,
    schema_provider: Any,
    request_policy: Any,
    trusted_tenant: str,
    app_audit_sink: Any,
) -> UserContext:
    if not trusted_tenant.strip():
        raise ValueError("a trusted tenant is required")
    return (
        module.into_context()
        .with_schema_provider(schema_provider)
        .with_request_policy(request_policy)
        .with_app_audit_event_sink(app_audit_sink)
        .insert_resource("trusted_tenant", trusted_tenant)
    )


async def readiness(context: UserContext) -> None:
    context.require_resource("request_policy")
    context.require_resource("schema_provider")
    context.require_resource("trusted_tenant")
    if not context.require_resource("trusted_tenant").strip():
        raise ValueError("a trusted tenant is required")
    await context.ensure_schema()


def reject_governance_override(value: Any) -> None:
    if isinstance(value, Mapping):
        for key, nested in value.items():
            if key in GOVERNANCE_KEYS:
                raise ValueError(f"untrusted governance override: {key}")
            reject_governance_override(nested)
    elif isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
        for nested in value:
            reject_governance_override(nested)
```

Generated query and audited mutation code receives only this context. `readiness` must reach the
real provider. Raw row audit remains module-owned and separate from masked App audit. Public DTOs
may contain allow-listed business fields, never the governance keys rejected above.

## Runtime telemetry

Observability is optional and application-owned. Construct
`teaql.runtime.opentelemetry.OpenTelemetryRuntimeTelemetry` from the
application's tracer and meter, then call
`context.with_runtime_telemetry(telemetry)`. Keep the no-op default when absent.
The application owns bounded SDK processors, OTLP exporters, `force_flush` and
shutdown; exporter failure must never change business results. Telemetry setup
does not call `ensure_schema`.
TeaQL derives `teaql.error.category` from the native error type. Sampling never
controls or replaces App Audit Sink delivery. Do not generate a Collector,
additional exporters, auto-discovery, or a telemetry configuration DSL.

---

## TeaQL seven-language assist contract

Apply the verified Rust semantic ceiling while using only the exact PYTHON 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: `runtime-custom`.

- Keep trusted dependencies and global runtime policy in UserContext initialization.
  Custom providers, policy hooks, and audit sinks must not add execute/save arguments.
- Preserve immutable row audit events and a separate customizable App Audit Sink.
  Include health, integration, and negative governance tests for every customization.