Component Model
Component Model
Section titled “Component Model”A sigMAX component is a contract-defined application unit served by the standardized runtime. Its execution placement follows the Core or Pro deployment model.
The component model defines what a component must expose so it can be generated, inspected, validated, and operated without guessing its internal implementation.
Component Responsibilities
Section titled “Component Responsibilities”A component should make its operational and application boundary explicit.
| Area | Responsibility |
|---|---|
| API surface | Expose the routes, methods, schemas, and generated OpenAPI description expected by the contract. |
| Runtime integration | Run through the standardized sigMAX runtime and only use allowed capabilities. |
| Discovery | Publish metadata that lets tools inspect what was generated. |
| Health | Provide a predictable health endpoint for local and orchestrated execution. |
| Documentation | Produce human-readable documentation for review and audit. |
| Evidence | Record generated files, endpoints, images, metadata, and validation output in the component agreement. |
Standard Surfaces
Section titled “Standard Surfaces”The exact surface can vary by component type, but a sigMAX component should keep the common inspection points stable.
| Surface | Purpose |
|---|---|
.well-known | Discovery metadata for tools and local inspection. |
openapi.yaml | API contract generated for exposed routes. |
healthz | Operational health check. |
metrics | Runtime or business metrics when the runtime configuration and component enable them. |
docs | Human-readable component documentation. |
| Component Agreement | Effective state used for validation and drift detection. |
Model Flow
Section titled “Model Flow”The component model sits between the application topology and the binary/runtime boundary.
The diagram follows a component from generated evidence through deployment and API testing. The selected executor depends on the edition: the containerized runtime in Core, or COS2000 inside a KubeVirt VM in Pro. It shows responsibilities, not container or VM allocation.
The green cylinder holds generated artifacts and the component agreement. Amber marks static checks; purple marks the executor. The API test report appears only after scenarios have actually run against the deployment. A static component agreement can therefore exist while runtime acceptance criteria are still pending.
Contract And Agreement
Section titled “Contract And Agreement”Contract · expected surface
- Identity and responsibility.
- Exposed routes and visibility.
- Expected OpenAPI output.
- Discovery, documentation and health endpoints.
- Allowed primitives and capabilities.
- Referenced binary contracts.
- Generated artifacts to record.
Agreement · produced surface
- Generated routes and OpenAPI file path.
- Discovered endpoints and metadata.
- Generated documentation and file hashes.
- Container image reference.
- WASM artifacts and binary agreements.
- Validation status and drift evidence.
Relation To The Runtime
Section titled “Relation To The Runtime”The runtime gives components a consistent execution boundary.
A component should not directly assume unrestricted host access. It should use the runtime capabilities allowed by its contract. This keeps the generated system inspectable and helps detect when a component accidentally exposes a route, imports a forbidden primitive, or depends on a capability that was not declared.
Drift Examples
Section titled “Drift Examples”Component drift can appear when:
- an endpoint exists in the generated OpenAPI file but not in the contract;
- a documented route is missing from the generated component;
- the component imports a binary that was not declared;
- health or discovery metadata is missing;
- a component exposes something publicly that was expected to remain internal;
- generated documentation no longer matches the effective surface.
Deployment Placement
Section titled “Deployment Placement”A component is a logical contract boundary; it does not imply one dedicated VM per component. Core uses Docker Compose with Host and Config on one host and WASM execution in a container, without dedicated execution isolation. Pro uses Kubernetes with the COS2000 executor in a KubeVirt VM. VM allocation and component placement belong to the deployment configuration.
Design Rules
Section titled “Design Rules”A good component model should be:
- autonomous enough to deploy and inspect locally;
- explicit about its API and runtime boundary;
- linked to binary contracts when executable WASM is involved;
- predictable in health, discovery, and documentation surfaces;
- strict enough to support drift detection;
- simple enough for Studio and local tooling to inspect.