Agreements
Agreements
Section titled “Agreements”Agreements record the effective system state after generation, compilation, packaging or runtime preparation. They complement contracts, which describe what should exist.
What Agreements Record
Section titled “What Agreements Record”An agreement is evidence-oriented. It can contain or reference:
- generated files and their paths;
- compiled binaries and their hashes;
- container images and build metadata;
- routes and exposed endpoints that were actually produced;
- runtime configuration resolved from generation;
- component discovery metadata;
- binary imports, exports, and ABI checks;
- validation results and error messages;
- timestamps, generator versions, and reproducibility metadata;
- links between generated artifacts and the contracts they satisfy.
The agreement does not replace the generated artifact. It describes it, fingerprints it, and makes it comparable with the expected state.
Agreement Levels
Section titled “Agreement Levels”Agreements mirror the contract hierarchy.
| Level | Effective state recorded |
|---|---|
| Application Agreement | Generated topology, component list, exposed routes, dependencies, images, and deployment-level evidence. |
| Component Agreement | Produced component surface, local artifacts, OpenAPI output, health endpoints, documentation, and runtime metadata. |
| Binary Agreement | Compiled WASM artifact, hash, imports, exports, ABI conformance, memory expectations, and execution constraints. |
This mirroring matters because validation can happen at the right level. A binary can be rejected without rejecting the whole application model. A component can be inspected without re-running every generation step.
The cylinder represents the recorded evidence; the amber control represents its validation. In the current Studio implementation, creating an agreement leaves its validation status pending and links to a separate report. Read that report’s individual checks and evidence, rather than treating the existence of the agreement as a successful validation.
Binary checks verify current file hashes, contract and generation-trace references, declared imports, the entrypoint export and the absence of WASI. Component checks add routes, OpenAPI output, scenarios and binary-validation reports. Executed API test evidence is accepted only when it matches the current test script’s digest. Criteria without a mapped executable assertion remain pending.
Validation Role
Section titled “Validation Role”Agreements are useful because they can be compared with contracts.
The validation question is simple:
If the agreement satisfies the contract, the generated state can be accepted. If not, the system has drift, missing artifacts, invalid binary shape, unexpected exposure, or another mismatch that must be investigated.
Evidence Examples
Section titled “Evidence Examples”Agreements can capture evidence at different depths depending on the artifact:
| Artifact | Agreement evidence |
|---|---|
| Generated file | Path, content hash, generator version, source contract reference. |
| WASM binary | Binary hash, imports, exports, ABI layout, memory limits, validation result. |
| Component | Exposed routes, OpenAPI file, health endpoint, docs output, image reference. |
| Application | Edition, Host/Config placement, executor and image versions, internal dependencies, public exposure and observed deployment model. |
For Core, deployment evidence should show Docker Compose services on one host and execution in the container stack. For Pro, it should identify Kubernetes resources and the COS2000 VM managed by KubeVirt. A WASM import check is not evidence that a VM boundary exists.
Contracts And Agreements
Section titled “Contracts And Agreements”Contracts and agreements should be read together.
The contract alone is only intent. The agreement alone is only a snapshot. The pair gives sigMAX an auditable loop:
- Define the expected state.
- Generate or compile artifacts.
- Record the effective state.
- Compare expected and effective state.
- Decide: accept, reject or investigate drift.
Drift Detection
Section titled “Drift Detection”An agreement can reveal drift when the generated result does not match the contract.
Drift can be caused by:
- missing generated files;
- changed routes or unexpected exposure;
- a binary importing a primitive that was not allowed;
- a mismatched ABI layout;
- an image or artifact hash that differs from the recorded result;
- a runtime configuration that does not match the expected topology.
This is why agreements are not optional metadata. They are part of the trust boundary for generated systems.
Design Rules
Section titled “Design Rules”A good agreement should be:
- tied to a specific contract version;
- reproducible enough to compare later;
- explicit about artifact hashes;
- precise about generated endpoints and binaries;
- readable during review;
- stable enough to support audit and drift detection.
The agreement should not hide failures behind a generic success flag. It should preserve enough evidence to explain why a generated result was accepted or rejected.