<!-- ephemeral -->

# TeaQL Swift Runtime Customization

The application composition root owns the SQLite provider, request policy, trusted tenant and
App audit sink. Never deserialize these values from query, mutation or federation payloads.

```swift
import Foundation
import TeaQLCore
import TeaQLSQLite

public struct RuntimeComposition: Sendable {
  public let context: UserContext
  public let dataService: SQLiteDataService
  public let module: RuntimeModule
}

public enum RuntimeCustomizationError: Error, Equatable {
  case missingTrustedTenant
  case governanceOverride(String)
}

public func configuredRuntime(
  databasePath: String,
  module: RuntimeModule,
  requestPolicy: RequestPolicy,
  trustedTenant: String,
  appAuditSink: any AuditSink
) throws -> RuntimeComposition {
  guard !trustedTenant.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
    throw RuntimeCustomizationError.missingTrustedTenant
  }
  let service = try SQLiteDataService(path: databasePath)
  let context = UserContext(
    actor: "teaql-application",
    trustedTenant: trustedTenant,
    queryExecutor: service,
    mutationExecutor: service,
    requestPolicy: requestPolicy,
    auditSink: appAuditSink)
  return RuntimeComposition(context: context, dataService: service, module: module)
}

public func readiness(_ runtime: RuntimeComposition) async throws {
  guard let tenant = runtime.context.trustedTenant,
    !tenant.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
  else { throw RuntimeCustomizationError.missingTrustedTenant }
  try await runtime.context.ensureSchema(runtime.module)
}

private let governanceKeys: Set<String> = [
  "tenant", "trustedTenant", "provider", "dataService", "requestPolicy",
  "auditSink", "appAuditSink", "hardLimit", "continuousPage",
]

public func rejectGovernanceOverride(_ value: Any) throws {
  if let values = value as? [Any] {
    for nested in values { try rejectGovernanceOverride(nested) }
    return
  }
  guard let object = value as? [String: Any] else { return }
  for (key, nested) in object {
    if governanceKeys.contains(key) {
      throw RuntimeCustomizationError.governanceOverride(key)
    }
    try rejectGovernanceOverride(nested)
  }
}
```

Generated queries and audited mutations receive only `runtime.context`. Readiness must reach
the real provider/schema. Keep row audit inside the provider and App audit in the injected
`AuditSink`; federation payloads may carry allow-listed business predicates but no governance.

## Runtime telemetry

Observability is optional and application-owned. Import `TeaQLOpenTelemetry`,
construct `OpenTelemetryRuntimeTelemetry` from the application's tracer, meter
and logger, and pass it through the `runtimeTelemetry:` initializer argument of
`UserContext`, `FederalClient`, or `LocalCache` as applicable. Keep
`NoopRuntimeTelemetry()` when absent. The application owns bounded processors,
OTLP exporters, flush and shutdown; exporter failure must never change business
results. Telemetry setup does not call `ensureSchema`.
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 SWIFT 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.