5.16 Review Corrections

This review fixes concrete inconsistencies in Lorenzo's interface proposal. It updates the contracts and their documentation; the services are still to be implemented. The review was checked on 2 November 2026.

5.16.1 What Changed and Why

Area	Correction	Why it matters
Client sync	Open and failed runs no longer require files or results they cannot have. Failed requests must include the details required in the response. Clients may read their own runs; enrolment retries return the original receipt.	An interrupted upload or a lost response must remain recoverable without invented data, duplicate accounts or broader permissions.
Raw files	Withdrawal is logical; physical erasure is separate. A known hash skips upload only for a verified, available object. Retrying does not restore a withdrawn file.	Preserve originals for audit and avoid claiming that missing bytes are already stored.
Shared types	Event times and observation values require the appropriate fields. Write identifiers are positive integers; read cutoffs also allow zero.	Reject contradictory payloads and make requests and responses agree on their types. This does not change the watermark algorithm.
Dataset exports	Reuse includes knowledge_clock as well as the data selection, cutoff, code, rules and anonymization.	Different definitions of what was known at a given time can produce different datasets.
Protobuf contracts	Complete the planned ai_model_platform rename. Optional fields distinguish an omitted override or export cutoff from an explicit zero.	Prevent incorrect ownership links and accidental default values.
External events	Clarify that the dead-letter attempt threshold is approximate; the 24-hour pause and 30-day failure access/redelivery need implementation.	Pub/Sub alone does not provide every behavior promised by the interface.
Generated documentation	Add a non-writing docs-interfaces --check, reject invalid sources and regenerate the affected pages.	Detect stale documentation without silently editing files during a check.

5.16.2 What Was Verified

• 28 regression tests, including valid and invalid payloads, relative OpenAPI references and non-writing generation checks.
• All 28 domain OpenAPI contracts validate; all 8 Protobuf files compile. Protobuf round-trip checks preserve explicit zero versus omission.
• Generated pages are current and the documentation builds in strict mode.
• Drive requirements 62, 71 and 72 are aligned; full Data regeneration changes only the three dataset pages. The existing AI Model Platform rename is also aligned in the source.

These checks cover contracts and documentation. They do not prove runtime authorization, database concurrency, cloud configuration or load capacity.

5.16.3 What Remains Open

A watermark is one possible approach to reproducible reads; its design is deferred.

Retry/reparse job membership, runtime integration tests, compatibility checks in CI and lossless handling of JSON int64 values remain separate work. The contracts retain their proposal status.