This page establishes baseline expectations for Soatrix-maintained software. Individual products may impose stronger requirements.

- Prefer explicit interfaces and dependency direction over cross-module reach-through.

- Keep stable identity separate from presentation/rendering identifiers.

- Validate external or authored input at the boundary before it enters runtime state.

- Prefer immutable published state where practical; publish replacements atomically rather than mutating a live registry piecemeal.

- Make compatibility claims explicit and testable. A version range is not equivalent to a validated exact-version matrix.

A change is ready to merge when its behavioural contract is understood, relevant tests are added or updated, and operations/documentation are changed where needed. Compatibility changes should include regression coverage at the boundary they introduce.

- Fail startup when continuing would publish corrupt or unsupported state.

- For reloadable systems, build and validate candidate state before replacing known-good state.

- Error messages should identify the invalid input or dependency chain rather than masking it with a generic failure.

- Pin or constrain dependencies deliberately.

- Isolate platform/version-specific APIs behind adapters when multiple runtime generations are supported.

- Avoid leaking implementation-specific APIs into common modules unless the common contract genuinely depends on them.

Use multiple layers where appropriate: unit tests for rules, integration tests for component boundaries, and real-runtime smoke tests for compatibility claims that mocks cannot establish.