# Engineering Standards

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

## Design

- 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.

## Changes

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.

## Failures

- 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.

## Dependencies

- 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.

## Testing

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.