Architecture
Principles
URUZ VM is being built with execution discipline, observability discipline, and canonical flow discipline. These principles are not aspirational. They are structural constraints that shape every decision.
Coordinator Owns Orchestration
Flow progression, retries, state transitions, and idempotent orchestration belong to the coordinator. The coordinator is the single authority for when and how flows advance. Contracts do not decide flow lifecycle. External systems do not push state. The coordinator pulls, validates, and progresses.
Contracts Stay Execution-Boundary Focused
Contracts are execution boundaries, state containers, event sources, and authority-enforced action surfaces. They should not become orchestration engines. Business logic that spans multiple actions or requires coordination does not belong on-chain.
Canonical Mapping First
Raw chain-native events are not the portable domain model. Canonical mapping is planned early and translation belongs in the adapter/mapping layer. Every flow has a canonical identifier that is deterministic and portable across chains.
Observability First
Event handles, health surfaces, metrics, and inspection views are designed from the start, not bolted on later. Every state transition is logged, timestamped, and queryable. Operators should never guess what happened.
Reconciliation Is Observational
Reconciliation compares surfaces and detects drift, but does not replace canonical truth. It reads state from multiple sources and reports mismatches. It never mutates. Reconciliation surfaces truth without forcing it.
Health Is Not Flow Truth
HTTP health, loop health, and actual flow state are separate concerns with separate surfaces. A healthy HTTP endpoint does not mean flows are progressing. A running loop does not mean individual flows are succeeding. These distinctions are visually and structurally separated.
Clear separation between execution and settlement.
URUZ VM maintains strict boundaries between where logic executes, where state settles, and where coordination happens. These boundaries are not suggestions.
Source Chain
URUZ Coordinator
Target Chain
All layers expose read-only inspection endpoints. Operators query state without modifying it.
Practical outcomes of architectural discipline.
These principles are not abstract ideals. They produce tangible operational benefits during development, deployment, and ongoing operation.
Safer Iteration
During devnet and localnet phases, clear boundaries allow rapid experimentation without cascading failures. Mistakes are contained.
Better Fault Recovery
Transient failures in one layer do not corrupt state in another. Retry logic is explicit. Recovery paths are predictable.
Cleaner Engine Swaps
Adapters and execution engines can be replaced without rewriting orchestration logic. The coordinator remains stable.
Clearer Operator Understanding
Operators know where to look. Health, loop health, and flow state are separate surfaces with separate semantics.
Less Accidental Coupling
Components that should be independent stay independent. Changes in one layer do not silently break another.