Drift Detection
Drift Detection
Section titled “Drift Detection”Drift detection checks whether generated artifacts still match the expected state declared by contracts.
In sigMAX, drift is not limited to source code changes. It can appear in routes, runtime capabilities, generated files, binaries, container metadata, exposed ports, documentation, or deployment topology.
What Can Drift
Section titled “What Can Drift”Drift can appear at several layers.
| Layer | Example drift |
|---|---|
| Application | A component is missing, an unexpected dependency appears, or a route is exposed differently than expected. |
| Component | The generated OpenAPI surface, health endpoint, docs, or runtime metadata no longer matches the component contract. |
| Binary | A WASM module imports an unauthorized primitive, exposes a different function, or has a mismatched ABI layout. |
| Runtime | A capability, endpoint, storage binding, or service invocation path differs from the declared contract. |
| Artifact | A file hash, image reference, or generated path differs from the recorded agreement. |
Detection Flow
Section titled “Detection Flow”Drift detection compares the contract with the agreement and produces a decision.
Comparison Areas
Section titled “Comparison Areas”The comparison should focus on boundaries that matter for correctness and safety:
- topology and component list;
- public and internal route exposure;
- API schemas and OpenAPI output;
- allowed runtime primitives;
- WASM imports, exports, and ABI layout;
- generated file paths and hashes;
- container images and metadata;
- runtime configuration and capabilities;
- documentation and discovery outputs.
The comparison does not need to treat every formatting change as drift. It should focus on differences that affect generated behavior, runtime safety, auditability, or reproducibility.
Drift Severity
Section titled “Drift Severity”Not every mismatch has the same impact.
| Severity | Meaning | Typical response |
|---|---|---|
| Informational | Non-behavioral metadata changed. | Record the difference or refresh the agreement. |
| Warning | Generated output changed in a way that should be reviewed. | Inspect the artifact and decide whether the contract or generator should change. |
| Blocking | Runtime behavior, exposure, ABI, or security boundary differs from the contract. | Reject the generated state until corrected. |
Response Options
Section titled “Response Options”When drift is detected, sigMAX should not hide the mismatch behind a successful generation message.
Possible responses include:
- regenerate from the same contract;
- revise the contract if the expected state was wrong or incomplete;
- fix the generator if it produced an invalid result;
- reject the binary or component agreement;
- open a review item for human inspection;
- preserve the drift evidence for audit.
Relation To Contracts And Agreements
Section titled “Relation To Contracts And Agreements”Contracts and agreements provide the two sides of drift detection.
The contract gives the expected state. The agreement gives the effective state. Drift detection compares both and determines whether the generated system can be accepted.
Design Rules
Section titled “Design Rules”Drift detection should be:
- deterministic where possible;
- strict on runtime and security boundaries;
- explicit about mismatches;
- tolerant only for differences that are known to be harmless;
- attached to the contract and agreement versions being compared;
- readable enough for a reviewer to understand what changed.
The goal is not to block every generated change. The goal is to prevent generated artifacts from silently escaping the contract that was supposed to govern them.