Guardrails API

Two endpoints run on the admin plane under /tt/api/v1, with the viewer role. Stored-content subjects additionally require explicit privileged content authorization. The generated typed contract is rendered at /api.

Method & path	Purpose
GET /tt/api/v1/guardrails/evidence	Retained execution coverage, findings and adjudication over the served window
POST /tt/api/v1/guardrails/simulate	Named embedded detector diagnostics or policy dry run; never live enforcement

GET /guardrails/evidence

$ curl -s http://127.0.0.1:9090/tt/api/v1/guardrails/evidence |
    jq '{coverage, suspension_rows, uninspected_rows, suspensions, adjudication, provenance}'

• coverage counts rows with receipts, complete and incomplete inspection, not-selected rows, legacy-unknown rows and actual external attempts. An old row without a versioned receipt stays unknown; no finding is not evidence of inspection.
• lineages[] groups observed findings by detector/version, with binding, phase, effect and confidence censuses. An empty lineage list says no findings were retained.
• configured[] is the live policy roster. fired: false means no observed fire in the window, not that a detector was healthy or completed. Compare it with execution coverage.
• suspensions[] is the per-reason census. suspension_rows counts affected rows; optional uninspected_rows remains absent when historical coverage cannot be established.
• adjudication carries observed true-positive and false-positive counts, denominators and optional detector/version splits. quality_sources is a separate quality-source report, not a replacement for those correctness counts. Traffic or fire volume supplies no ground truth.
• provenance describes the source, window and truncation. guarded_rows and engaged_rows are descriptive denominators, not proof of complete protection.

Guardrail evidence remains separate from routing promotion evidence. Guardrail findings cannot license routing promotion. Confidence intervals require a licensed calibration artifact; malformed envelopes are refused and counted rather than synthesized or averaged.

POST /guardrails/simulate

Name exactly one subject: content, req_id or dataset. A profile selects a current named profile; absence uses the deployment default. phase defaults to input and also accepts output. The key selector is recognized but per-key simulation is not implemented and is refused. Reading a stored request supplies content, not its historical key overrides.

$ curl -s -X POST http://127.0.0.1:9090/tt/api/v1/guardrails/simulate \
    -H 'Content-Type: application/json' \
    -d '{"operation_kind":"detector_diagnostics","content":"mail [email protected]","phase":"input"}'

operation_kind	Meaning
detector_diagnostics	Default for literal text; probes detectors on that text
policy_dry_run	Default for stored subjects; uses the serving extractor and sequential policy planner against the current selected profile

Every report carries mode: simulate and enforced: false. It includes operation_kind, generation, the selected profile/policy reference, case inspection states and execution records. Read coverage for total, selected, missing, unreadable, cap-excluded and truncated-body counts. max_cases cannot exceed the server cap of 200; excluded and unavailable cases stay disclosed.

cases[].fires[] reports candidate actions and admission decisions. An action label or action_implemented is not evidence of production transformation or delivery. Findings expose bounded safe metadata and spans, not submitted text or detector detail strings.

Only embedded detectors run; external detectors are explicitly skipped. Policy dry runs do not exercise external calls, stream framing, provider retries, re-identification or client delivery. Latency measures the selected operation on the available host; it is neither a production latency floor nor a concurrent-load prediction. Read notes[] for its scope.

Hot reload publishes the simulator with the runtime snapshot. A new operation uses the current generation; an in-flight operation retains its captured generation. Compare report generation and policy reference when checking reload behavior.

Access and unavailable results

Stored-content simulation requires the privileged content:read management permission and a successful audit append before reading stored content. An ordinary wildcard read grant is insufficient. This is a global management content scope: no per-record ownership or tenant isolation check is provided by this endpoint. The API does not read a local corpus directory; --corpus is a CLI-only subject.

An unwired feature returns 404 feature_absent. Evidence source failures and active-operation deadlines/cancellation return 503 evidence_unavailable; exhausted query capacity returns 429 rate_limited. A missing stored request returns 404 not_found; a dataset with no readable bodies returns 404 feature_absent. In a successful nonempty dataset report, missing or unreadable selected bodies remain explicit coverage gaps. Invalid requests and unsupported selectors return validation errors, including 422 validation_failed for rejected simulation policy. No partial report is returned as complete after active cancellation.