How it works
How Ordo works
Ordo moves decision-relevant meaning out of convention and into explicit domain structures. The method asks a simple sequence of questions: what can be true, what do we actually know, what authority exists, what legal change is available, what happened at the boundary, and what remains unresolved?
Prefer code to interpretation?
The C# walkthrough maps the concepts below into ordinary .NET types and functions, including examples grounded in the measured C# trial and explicit translations of the current Ordo 1.3 decision semantics.
A safe decision is constructed before it is selected.
The provider, model, or engineer operates inside a domain-defined choice space. It does not define that choice space.
- 1Semantically complete state viewThe domain projects the smallest authoritative view in which no omitted fact could change legality, evidence requirements, coverage, capability applicability, obligations, policy, or transition outcome.
- 2EvidenceTyped evidence identifies what was observed, where it came from, when it was observed, and what it depends on.
- 3Scoped coverageEach contract-defined scope is Complete, Partial, or Unknown. Required non-Complete coverage refuses the decision before provider execution.
- 4Capabilities and obligationsHost-established semantic authority is supplied as capabilities; unresolved required work remains explicit as obligations.
- 5Legal choice spacePolicy, guards, state, evidence, coverage, capabilities, and obligations determine which outcomes are actually legal.
- 6Compute, bounded decide, refuse, or escalateDeterministic work stays deterministic. Judgment happens only inside the legal choice space. Missing prerequisites do not force an answer.
- 7Result, requested effects, and auditThe result carries the state identity and decision facts forward; external work is requested as data and observations are recorded for later verification.
State is the semantic starting point
Mechanism
Closed states and state-specific data
A record occupies a named state from a closed set. Data meaningful only in one state is constructible only in that state. Exhaustiveness checking makes new states visible to every caller that must interpret them.
Consequence
Readers stop decoding combinations
Meaning no longer depends on everyone interpreting flags, nulls, status strings, and related fields in exactly the same way.
Decision view
Only the relevant authoritative state is projected
The view must be semantically complete for the contract. If an omitted authoritative fact could change legality, evidence requirements, coverage, capability applicability, obligations, policy, or transition outcome, the view is incomplete.
Evidence and coverage are separate concepts
Evidence
What observation or fact supports the decision?
Evidence carries identity, source, observation time, basis, and typed content. Derived evidence must form a closed, acyclic dependency set with every referenced input present.
Coverage
How completely did the observation method cover a named scope?
Coverage is Complete, Partial, or Unknown for a contract/domain-defined scope. Partial and Unknown are distinct, and neither can be promoted to Complete because a provider was confident or a call succeeded.
- 1Observation produces EvidenceEvidence carries identity, source, observation time, basis, and typed content. Derived evidence must have a closed, acyclic dependency set.
- 2Evidence supports a Coverage claimA ContextCoverageClaim names a contract/domain-defined scope and says Complete, Partial, or Unknown, citing Evidence as provenance.
- 3Contract declares required Complete scopesCompleteness is required only where the contract says it matters. Other scopes may legitimately remain Partial or Unknown.
- 4Coverage gate runs before provider executionMissing, Partial, or Unknown required coverage becomes InsufficientCoverage. Ordo does not ask the provider to reason through an unestablished context.
- 5Negative knowledge stays scopedA negative observation can support absence only when the method could detect the target and matching coverage is Complete.
- 6Decision proceeds with explicit knowledge limitsThe provider sees coverage as data. Confidence, quantity of context, successful execution, or absence of errors never upgrades coverage implicitly.
Coverage is not itself Evidence. A coverage claim cites Evidence as provenance. A contract may require Complete coverage for selected scopes, while allowing other scopes to remain Partial or Unknown.
Negative knowledge requires a complete search scope
"Not found" is not the same as "absent." Ordo keeps unavailable, not searched, not compared, unsupported, unknown, and absent separate. A negative observation can support absence only when the observation method could detect the target and the matching coverage scope is Complete.
Why this matters
Without scoped coverage, missing information can silently become a false fact. Ordo forces the system to say whether the thing is absent or whether the system simply failed to establish that it was present.
Legal transitions define the action space
Transitions
Change happens through named routes
Guards, invariants, policy, evidence requirements, capability requirements, and obligations determine whether the transition exists for the current state.
Capabilities
Authority is supplied, not invented
A Capability means the host has already established semantic authority needed for the action. It is not a credential and model output can never create one.
Obligations
Unresolved work can block the next transition
Obligations represent work the domain still requires. They remain part of the semantic state until satisfied rather than disappearing into operational notes.
- 1Current stateThe named state the entity is actually in — not a combination of flags a reader has to infer.
- 2Requested actionA named action, not an arbitrary field write.
- 3Capability checkIs this action one the current state permits at all? If not, the request is refused here.
- 4Evidence checkIs the basis for the transition present and valid?
- 5Policy checkDo the business rules covering this action hold for these particular values?
- 6Legal transitionOnly now does state change, and only to a state the model declares reachable from the current one.
- 7New state, obligations, effectsThe resulting state, what must still happen for the transition to be complete, and the external effects requested as data rather than performed in place.
External effects report what actually happened
Request
The semantic core requests the effect
Tier Two returns requested work as data. Tier Three coordinates it. Tier Four performs the database, network, browser, filesystem, provider, queue, clock, or other external work.
Interpretation
The domain interprets Succeeded, Failed, or Unknown
If an effect may have occurred but the result is unknown, Ordo does not collapse that into failure. It creates reconciliation work before later actions are allowed to depend on the uncertain result.
- 1Tier Two requests an effectThe semantic core describes the work as data. It does not perform the I/O.
- 2Tier Three coordinates the boundaryApplication code translates the request and hands it to the host without re-deciding the domain rule.
- 3Tier Four performs or observes the effectThe host returns what it can establish: Succeeded, Failed, or Unknown.
- 4Succeeded or Failed is interpreted normallyThe semantic core applies the domain meaning of the known result.
- 5Unknown creates a reconciliation obligationThe system preserves that the effect may or may not have happened. It does not pretend failure and blindly replay state-changing work.
- 6Tier Three / Four reconcile against realityThe external system is observed using the real contract. Retry is allowed early only when that contract proves retry safety.
- 7Tier Two interprets the reconciled factOnly after reality is re-established may later transitions that depend on the outcome proceed.
Retry before reconciliation is allowed only when the real external contract proves retry safety for that operation. Even then, reconciliation remains necessary before later work that requires knowing what actually occurred.
Semantic responsibility stays separate from infrastructure.
- 1Tier Four — Host / External EffectsDatabase, network, HTTP, browser, filesystem, clock, queues, provider SDKs, persistence and other external I/O. Reports Succeeded, Failed, or Unknown.
- 2Tier Three — Application / Projection / OrchestrationCoordinates use cases, projections, requested effects, and boundary translation without becoming a second semantic authority.
- 3Tier Two — State Transition / Domain ExecutionOwns decisions, guards, policy, invariants, evidence and capability requirements, legal transitions, obligations, and interpretation of effect results.
- 4Tier One — Semantic ModelOwns what can be true: domain values, closed alternatives, state-specific data, evidence, coverage, capabilities, obligations, and uncertainty.
The guardrail
Dependencies point toward the semantic core. Ordo may refine Tier One and Tier Two semantics, but it must never require the semantic core to import databases, HTTP, browser APIs, provider SDKs, persistence adapters, or ROS implementation dependencies.
Structural locality bounds the context needed for change
Mechanism
Route to semantic authority instead of exploring the repository
Semantic maps and feature ownership make state, transitions, contracts, effects, and tests deterministically discoverable. Navigation artifacts point to authority rather than restating it.
Consequence
The working context can stay bounded
Humans and agents can enter the feature through a small declared context and expand only when evidence shows the context is insufficient.
- 1Work item and acceptance criteriaThe requested change starts with explicit intent and conditions that can be checked.
- 2Semantic mapThe repository points to the semantic area and authority that own the decision.
- 3Declared feature contextState, transitions, contracts, effects, interfaces, and tests for the feature are locally discoverable.
- 4Mechanical feedback firstCompiler, architecture, contract, and structural checks expose required propagation before broad search.
- 5Expand only when evidence says context is insufficientSearch is an escalation mechanism, not the default navigation strategy.
- 6Heterogeneous verificationBehavioural, integration, and independent review cover failure classes the earlier mechanisms cannot.
- 7Record evidence and unresolved obligationsThe work leaves behind what ran, what was established, what remains open, and what the evidence does not prove.
Verification is heterogeneous on purpose
| Mechanism | Refuses | Cannot refuse |
|---|---|---|
| Type and exhaustiveness checking | Unrepresentable states, unhandled cases, signature drift | Code that type-checks and does the wrong thing |
| Architecture and dependency checks | Layering violations, inverted dependencies | Correct layering around incorrect behaviour |
| Contract and boundary checks | Representation collapse at a declared boundary | Boundaries nobody declared |
| Behavioural tests | Behaviour the author thought to assert | A check that passes for the wrong reason |
| Integration against a real boundary | Present-but-inert implementations, wire-format mismatches | Conditions the integration environment never produces |
| Independent adversarial review | Declared-but-unreachable outcomes, vacuous assertions | Anything the reviewer also fails to imagine |
Ordo is also an order of work.
State-directed architecture is not enough if the engineer or agent works around the mechanisms that make it useful.
- 1RequirementsNumbered, with acceptance criteria that can each be traced to a test.
- 2Semantic modelThe domain's states, and what each one means.
- 3State and legal transitionsWhich changes the model permits, and from where.
- 4Capabilities and obligationsWhat an actor may do next, and what is still owed.
- 5ImplementationWritten at the semantic authority first, then propagated outward.
- 6Mechanical verificationCompiler, architecture checks, contract checks — everything a machine can refuse without running the program.
- 7Heterogeneous verificationBehavioural tests, integration against real boundaries, adversarial review — mechanisms whose blind spots differ from each other's.
- 8EvidenceWhat ran, what it found, and what it does not establish, recorded durably.
Requirements are analyzed into semantic decisions. Work is routed through declared ownership. Mechanical feedback is used before broad repository search. Boundary changes require explicit evidence. Verification uses mechanisms with different failure sensitivities. Work stops when the declared obligations and acceptance conditions are satisfied, not when the code merely looks plausible.