Aethera/render_3D/third_party/datoviz/spec/README.md

Spec Index

This directory contains normative design material for v0.4 contracts and features, including some surfaces that now have partial implementations.

Use spec/ for contracts that should drive implementation and tests. Do not use it for execution planning or broad architecture essays.

Authority Map

• architecture/: cross-cutting source-module layers, scene split direction, and external dependency policy.
• api/: cross-module public API conventions for naming, structs, bindings, and release review.
• bindings/: raw generated Python ctypes binding architecture, generation policy, and validation rules.
• build/: component-target, packaging, install/export, and package-consumer build contracts.
• data/: data-submodule layout, manifest/provenance rules, and scientific showcase-dataset policy.
• docs/: v0.4 documentation architecture, example coverage, gallery site, and AI-friendly authoring rules.
• drp2/: backend-agnostic rendering protocol contract, schemas, fixtures, DVZR replay, and native-runtime pressure rules.
• examples/: executable example taxonomy, generated example-page contract, gallery selection, and scientific showcase policy.
• release/: release readiness, RC process, communication/blog assets, and gallery outreach policy.
• scene/: scene-layer requirements, consumer-side object model, retained object semantics, and implementation boundary notes.
• testing/: test-runner scheduling, skip, fixture, and validation policy.

AI-facing usage policy starts in docs/AI_DOCUMENTATION.md. Scene/app defaults, copy-safe examples, diagnostic shape, and Python scope then route to scene/api/, scene/examples/, scene/validation/, api/, and bindings/ respectively. Cross-cutting module placement questions route to architecture/; protocol replay questions route to drp2/.

Rules

1. If violating a statement should fail implementation work or conformance tests, it belongs in spec/.
2. If a document is primarily about sequencing, backlog, or what to do next, it belongs in agents/.
3. If a document is primarily explanatory, comparative, or tutorial-like, it belongs in docs/.
4. Keep top-level spec/ limited to this index and intentionally global policy; put owned material in the nearest topic directory.
5. Avoid speculative API sketches in spec/ unless they are directly needed to validate the written contract.

Validation

Spec-owned executable checks should be runnable from the repository root.

Current entrypoint:

just spec-check

At the moment this validates the DRP2 fixture corpus and the DRP2 fixture-runner tests. Scene spec changes that alter implemented behavior should also run the narrowest relevant just test scene filter, because the scene spec now has multiple active source slices.