S06.1 — Implement API schemas, stable errors, request IDs, and safe logging

Planning / historicaltaskdelivery

Historical

Planning material. It summarizes and links to the authoritative specification and the current measured state — it does not replace either, and it is not current engineering truth.

Migration identity#

Canonical identifier: S06.1 (GitHub issue type: subtask).
Legacy identifier: C06.1 (retained as old_identifier).
Parent epic: E06.
Milestone: M1 — IntentGuard Weekend MVP.

Objective#

Encode the interface contract with typed Pydantic models, deterministic validation/errors, request-ID behavior, and structured logs that omit raw text.

Rationale#

The public boundary must be testable, observable, and safe independently of predictor implementation.

Parent identifier#

E06.

Source task#

T-006.

Traceability#

Primary: T-006, NFR-004, NFR-005, AC-008. Secondary: FR-006, FR-007.

Prerequisites#

Request-ID, control-character, normalization, error-body, and tie-breaking decisions resolved from the interface contract.

Likely files#

src/intentguard/schemas.py, src/intentguard/api.py, src/intentguard/logging.py, tests/contract/test_api_contract.py, tests/unit/test_logging.py.

Implementation boundary#

HTTP/schema/logging boundary only; predictor may be injected for contract tests but is not strict serving evidence.

MUST scope#

Request/response fields, bounds, empty/control input handling, status codes, stable error shape, request-ID propagation/generation, structured sanitized logs.

Explicit non-goals#

Authentication, persistence, raw-text logging, batch schema, frontend, metrics service, or ticket adapter.

Acceptance criteria#

Valid/invalid payload tests match the contract; errors and IDs are deterministic under declared rules; captured logs contain metadata but not input text or secrets.

Validation commands#

uv run pytest tests/contract/test_api_contract.py tests/unit/test_logging.py -q.

Expected evidence#

Schema assertions, malformed-input matrix, request-ID cases, and sanitized log captures.

Fallback and status consequence#

A mock predictor is allowed for these tests, but schema/logging gaps make U06 Partial and fail strict MVP.

Stop condition#

Stop for unresolved contract ambiguity, sensitive log output, unstable errors, or framework defaults that violate the specification.

Definition of ready#

All boundary ambiguities are explicitly decided and test examples are enumerated.

Definition of done#

NFR-004, NFR-005, and AC-008 pass without depending on a trained model.

Labels#

type:subtask, priority:MUST, area:api

Estimate#

0.5 hour.