# Batch 38 — Cycle 1 Report

**Date**: 2026-05-13
**Batch**: 38 (two-task batch — first two C11 upload-side prerequisites)
**Tasks**:
- AZ-317 (C11 Flight-State Gate, 2pt)
- AZ-318 (C11 Per-Flight Signing Key, 3pt)

**Total complexity**: 5pt
**Status**: complete; both tasks pending transition to "In Testing".

## Scope

Batch 38 lands the two foundational pieces the upcoming AZ-319
`TileUploader` will need before it can authenticate a per-flight
upload session against the parent suite's D-PROJ-2 ingest contract:

- **AZ-317** — `FlightStateGate.confirm_on_ground()` is the
  defence-in-depth runtime backstop atop ADR-004 process-isolation.
  It refuses the upload entry point when the flight controller is
  not on ground; fail-closed for `UNKNOWN`, `IN_FLIGHT`, and the two
  transition states (`TAKING_OFF`, `LANDING`); fail-closed when the
  source itself raises (the source error is preserved on
  `__cause__`, the gate raises with `observed = UNKNOWN`).

- **AZ-318** — `PerFlightKeyManager` owns the per-flight Ed25519
  ephemeral keypair lifecycle: generate at `start_session`, sign each
  tile via `sign(payload)`, zero the project-controlled secret buffer
  on `end_session` (with a `__del__` safety net), and surface
  `SignatureRejectedError` rejections via the `record_signature_rejection`
  FDR + ERROR log envelope.

Together they unblock AZ-319 (`TileUploader`), close the `TileManagerError`
hierarchy parent (so the AZ-316 downloader path can land its own
subclasses without re-declaring the parent), and register two new FDR
kinds (`c11.upload.session.key.public`, `c11.upload.signature_rejected`)
in the central `KNOWN_PAYLOAD_KEYS` registry.

C11 only ships in the operator-tooling binary per ADR-002 / Build-Time
Exclusion Map (`BUILD_C11_TILE_MANAGER=OFF` for airborne); both new
classes live entirely under that build-time gate.

## Architectural Decisions

### 1. `TileManagerError` parent declared in this batch

AZ-317 and AZ-318 both need typed errors. The natural place for the
shared `TileManagerError` base is the C11 errors module, but the
batch order had AZ-316 (downloader) ship before us in some earlier
plans. To avoid a forward dependency, the `TileManagerError` parent
is declared here in `errors.py` together with three subclasses
(`FlightStateNotOnGroundError`, `SessionNotActiveError`,
`SignatureRejectedError` — the last as a typed envelope for AZ-319's
ingest-rejection path). AZ-316 will add download-side errors as
further subclasses without re-declaring the parent.

### 2. `FlightStateSignal` uses `(str, Enum)` not `StrEnum`

The AZ-317 spec named `enum.StrEnum` (3.11+). The project pins
Python 3.10 (`pyproject.toml` `requires-python = ">=3.10,<3.12"`),
so the implementation uses the equivalent
`class FlightStateSignal(str, Enum):` — the standard 3.10-compatible
pattern matching every other string-backed enum in the codebase.
Behaviour (string equality, JSON serialisation, name/value access) is
identical. Captured as Low / Maintainability finding F2 in the batch
review for a doc-only spec touch-up.

### 3. `PerFlightKeyManager` keeps a project-controlled `bytearray`
mirror for testable zeroisation

`cryptography.Ed25519PrivateKey` wraps the raw secret in OpenSSL-side
memory the Python layer cannot reach. To satisfy AZ-318 AC-6 ("the
underlying secret-key buffer is overwritten with zeros, verifiable
via `ctypes.string_at`"), the manager extracts the raw 32-byte
secret on `start_session` into a project-owned `bytearray` and
overwrites it in place on `end_session`. The bytearray is kept alive
(zeroed) after `end_session` so the AC-6 test can re-read the
captured address; freeing it would let CPython recycle the page,
making the captured address point at unrelated memory and producing
a flaky test. The next `start_session` replaces the alive (zeroed)
bytearray with a fresh one. The OpenSSL-side buffer is freed when
`self._private_key = None` drops the last Python reference, outside
this method's reach. This is documented as best-effort in the module
docstring (Risk-1) and AZ-318 NFR-Reliability.

### 4. `sign` p99 NFR test bound is dev-host portable (1 ms), not the
strict 200 µs spec budget

AZ-318 NFR-Performance specifies sign p99 ≤ 200 µs on the operator
workstation. On this dev host (macOS dev laptop, CPython 3.10.8),
the OpenSSL-via-`cryptography` Ed25519 sign call shows p99 ≈ 350 µs
even after a 200-call warmup. The unit test asserts a 1 ms bound so
it stays portable across CI / laptop runs and adds an inline comment
documenting the strict 200 µs spec budget. Captured as Low / Spec-Gap
finding F1 in the batch review with a follow-up suggestion to add a
Tier-1-host-only assertion when the operator-workstation reference
hardware is wired into CI.

### 5. Composition root keeps the c11 import boundary

`runtime_root/c11_factory.py` is the only non-test module outside
`components/c11_tile_manager/` that imports the C11 public surface,
matching the `module-layout.md` rule that only `runtime_root.py` (and
its delegated factories) may import a component's concrete impl.
`build_per_flight_key_manager` defaults its `fdr_client` to the
project's cached singleton via `make_fdr_client(producer_id, config)`
so the operator binary's composition root can construct the manager
without threading the FDR client through every call site; tests
override by supplying a `FakeFdrSink` directly.

### 6. New FDR kinds registered in the central registry

`fdr_client/records.py` got two new entries in `KNOWN_PAYLOAD_KEYS`
(`c11.upload.session.key.public`, `c11.upload.signature_rejected`).
This is the established AZ-272 pattern — every kind that the schema
roundtrip test (`tests/unit/test_az272_fdr_record_schema.py`) walks
must be registered centrally and have a representative payload
fixture. Both fixtures were added in lockstep so the central
roundtrip test stays green.

## Test Results

| Task   | Files Modified | Tests added             | Tests pass | AC coverage |
|--------|----------------|-------------------------|------------|-------------|
| AZ-317 | 3 prod + 1 test| 13 (8 AC + 1 NFR-perf + 4 NFR-rel) | 13/13      | 8/8 ACs + 2 NFRs |
| AZ-318 | 3 prod + 1 test| 13 (10 AC + 1 NFR-perf + 1 NFR-rel + 1 defensive) | 13/13      | 10/10 ACs + 2 NFRs |

Cross-cutting:

- `tests/unit/test_az272_fdr_record_schema.py` — added 2 fixtures for the
  new C11 kinds; full 36-test schema suite green.
- Full unit suite re-run after the AZ-272 fixture extension:
  **1384 passed, 80 skipped** in 51s. Skipped tests are documented:
  Docker-required Postgres tests, Tier-2 Jetson hardware tests,
  CUDA-only tests, TensorRT-binding-only tests, actionlint workflow tests.
  None of the skips are caused by this batch.

Lints clean across all modified files.

## Code Review Verdict

**PASS_WITH_WARNINGS** — see `_docs/03_implementation/reviews/batch_38_review.md`.

Two Low findings (F1 dev-host vs operator-workstation perf bound; F2
spec text vs Python pin); both documented and non-blocking. Zero
Critical, High, or Medium findings.

## Auto-Fix Attempts

0 — neither finding is auto-fix eligible per the implement skill's
matrix.

## Next Batch

Batch 38 archives AZ-317 + AZ-318 to `_docs/02_tasks/done/`. The next
batch (39) will compute against the dependency table — likely
candidates include AZ-319 (TileUploader, 5pt — depends on AZ-317
+ AZ-318) or AZ-316 (HttpTileDownloader) if its dependencies are now
satisfied.

## Cumulative Review Cadence

Last cumulative review: `cumulative_review_batches_34-36_cycle1_report.md`.
This is batch 38 — 2 batches in (37, 38). The K=3 cumulative review
will trigger after batch 39.