# Log Schema Contract Test

**Task**: AZ-268_log_schema_contract_test
**Name**: Log Schema Contract Test
**Description**: A standalone test module that verifies every shared logger emission conforms to `log_record_schema` v1.0.0 — field names, field ordering, required keys, and the "INFO + DEBUG never reach FDR" invariant.
**Complexity**: 2 points
**Dependencies**: AZ-266_log_module, AZ-267_fdr_log_bridge
**Component**: shared.logging (cross-cutting; epic AZ-245 / E-CC-LOG)
**Tracker**: AZ-268
**Epic**: AZ-245 (E-CC-LOG)

### Document Dependencies

- `_docs/02_document/contracts/shared_logging/log_record_schema.md` — the contract this test verifies.

## Problem

The shared logging contract (v1.0.0) declares a strict 8-field set with mandated ordering. Without an automated test that parses raw emitted bytes and asserts the contract, formatter changes can silently drift the schema and break post-flight FDR analysis tools that depend on stable column ordering.

## Outcome

- A single test module under `tests/contract/log_schema.py` runs in unit-test scope, fails CI fast on any schema drift, and is the single authority that enforces the contract at code-review time.
- "DEBUG + INFO never reach FDR" is verified by a paired test case that wires a stub FDR queue and asserts zero records after a fixed batch of INFO/DEBUG calls.

## Scope

### Included

- One test file (`tests/contract/log_schema.py` per epic AZ-245 AC-4) with cases for every row in the contract's "Test Cases" table (valid-info-no-frame, valid-warn-with-frame, valid-error-with-exc, invalid-bad-level, invalid-multiline-msg, invalid-non-serialisable-kv, ordering-stable).
- A "DEBUG + INFO never reach FDR" case that uses a stub FDR queue.
- A pytest marker (`contract`) so CI can run contract tests as a discrete stage if desired.

### Excluded

- Integration-level "every component logs at least one record" tests — owned by per-component test specs in their own epics (Step 9 Decompose Tests).
- Performance microbenchmarks for the formatter — owned by the AZ-266 unit tests.

## Acceptance Criteria

**AC-1: Contract cases all pass**
Given the AZ-266 + AZ-267 implementations are complete
When `pytest tests/contract/log_schema.py` runs
Then all test cases listed in `_docs/02_document/contracts/shared_logging/log_record_schema.md § Test Cases` pass

**AC-2: Schema drift fails fast**
Given a hypothetical formatter change that re-orders the JSON keys
When `pytest tests/contract/log_schema.py` runs
Then the `ordering-stable` case fails with a diff showing actual vs. expected key order

**AC-3: FDR-suppression invariant verified**
Given a stub FDR queue wired into the bridge
When the test emits 100 INFO + 100 DEBUG records
Then the stub queue reports zero records received

**AC-4: Contract version pinned**
Given the test imports the contract version constant
When the contract is bumped to a new major version
Then the test fails until updated, preventing accidental coupling to an unreviewed contract change

## Non-Functional Requirements

**Reliability**
- The test never depends on real FDR I/O — only on the documented `enqueue` interface of the FDR producer client.

## Constraints

- Test file path is fixed at `tests/contract/log_schema.py` per epic AZ-245 AC-4 (allows the `traceability-matrix` reference to remain stable).
- Contract version constant must be sourced from a single location (the contract file or a generated constant) — never duplicated across the test and the formatter.
