Public API, diagnostics, and versioning requirements
Defines stable public contracts, runtime-action and regression automation, compatibility policy, machine-readable diagnostics, capability discovery, and deprecation.
Section relationships
Depends on
Used by
| ID | Name | Priority | Requirement | Verification |
|---|---|---|---|---|
| API-001 | Native Rust API | MVP | BeforeMetal SHALL expose documented Rust APIs for project loading, compilation, execution, state queries, experiments, and results required by the reference workflow. | Test |
| API-002 | CLI coverage | MVP | Every MVP workflow SHALL be executable through a documented non-interactive command or configuration. | Test |
| API-003 | Stable identifiers | MVP | Public diagnostic codes, capability identifiers, metric identifiers, and persisted schema fields SHALL use stable names within their compatibility window. | Inspection |
| API-004 | Semantic versioning policy | MVP | Public crates, schemas, protocols, and extension APIs SHALL follow a documented versioning and compatibility policy. | Inspection |
| API-005 | Schema migration diagnostics | Beta | A migration SHALL report source version, target version, transformations, losses, warnings, and backup location. | Test |
| API-006 | Structured diagnostics | MVP | A diagnostic SHALL include stable code, severity, subsystem, message, responsible object or source location, context, and corrective guidance where known. | Test |
| API-007 | Machine-readable output | MVP | CLI diagnostics, compile reports, fidelity cards, and run summaries SHALL be available in a documented machine-readable form. | Test |
| API-008 | Structured logging | MVP | Logs SHALL include wall timestamp, virtual timestamp where applicable, severity, subsystem, run, world, entity, and message fields. | Test |
| API-009 | Metrics namespace | MVP | Built-in and extension metrics SHALL use versioned namespaced identifiers and declared units. | Inspection |
| API-010 | Read-only state query | MVP | Tools and metrics SHALL query committed state through read-only interfaces that do not depend on renderer state. | Test |
| API-011 | Deprecation policy | Beta | A supported public API or schema removal SHALL follow TBD-API-DEPRECATION and include migration guidance. | Inspection |
| API-012 | Capability discovery | MVP | APIs and adapters SHALL expose actual supported capabilities rather than requiring clients to infer them from version numbers. | Test |
| API-013 | Runtime-action request and receipt | Beta | Public APIs SHALL expose a versioned runtime-action request-and-receipt contract containing stable request identity, action type and version, origin and authorization context, world instance and target identities, requested virtual time or trigger, typed unit- and frame-aware payload, late, invalid, and failure policy, and accepted, rejected, applied, or failed disposition with structured diagnostics; the contract SHALL contain no backend-native handle. | Test |
| API-014 | Simulation regression CLI | Beta | BeforeMetal SHALL expose a non-interactive command for selecting and executing user-authored simulation regression cases, emitting the machine-readable regression result and distinct nonzero process statuses for assertion failure, execution error, and invalid configuration. | Test |
Change rationale (API-013, API-014): Runtime mutation needs one portable request-and-receipt boundary rather than direct access to backend state. API-002 guarantees CLI coverage only for MVP workflows and does not define automation semantics for Beta simulation tests; stable machine output and distinguishable failure statuses make the regression harness usable in user build systems without turning BeforeMetal's absent repository CI into product evidence.
Generated from the canonical specification. Edit section metadata or prose in docs/requirements.md; the website rebuilds this page and its relationships automatically.