AI Contract And Conformance Boundaries
Read this page when you need the current canonical answer for who owns AI behavior in Holon, where structured output is already required, and what minimum proof is expected before claims about AI-facing contract surfaces should be trusted.
Current-State Summary
Holon already has a bounded AI contract posture:
- the host authors the instruction contract,
- the runtime remains the authority for execution, approvals, evidence, and persisted truth,
- schema-bound outputs are required where downstream systems depend on them,
- unsupported breadth stays explicit in known issues instead of being implied by model narration.
This page is intentionally about current boundaries only. It does not claim a future fully integrated spec-based AI matrix beyond what the repo currently implements and documents.
Relationship Map
Canonical Rules
- Holon owns execution authority. Provider models do not become the execution authority by producing text or tool-call intent.
- The host chooses the instruction bundle, projected tool scope, routing, approval posture, and evidence requirements for the active lane.
- Provider replies are advisory until the host parses, validates, persists, and reconciles them with host-owned state.
- Runtime state, tool-call records, validations, durable events, and evidence outrank provider narration when the two disagree.
- Missing approvals, missing evidence, unsupported profile breadth, or invalid structured output must stay blocked or fail closed instead of widening capability.
Current Instruction Contract Floor
The current desktop live-model floor already includes a real instruction contract:
- desktop live chat builds a deterministic host-authored instruction bundle and passes it as the leading system message in
LiveChatRequest.messages, - the bundle states Holon host authority and anti-claiming rules,
- bounded retained session artifacts are included as host-authored context input rather than as execution proof,
- the desktop host may project only a narrow read-only built-in runtime-tool allowlist to provider tool calling when the current route supports it,
- one sequential bounded read-only
summary-scoutchild lane is the current desktop child-lane floor.
Current implementation detail and limitations for that floor are documented in Desktop Runtime Integration and Known Issues.
Structured Output Boundary
Holon already defines one clear rule: when downstream code, workflow state, approvals, or other agents depend on the result, the result must be structured and validated before acceptance.
Current boundary posture:
| Boundary | Current posture | Current gap |
|---|---|---|
| Workflow, frozen-tool, and other schema-bound machine outputs | Structured output is required and validated by holon-structured-output before acceptance | Coverage is bounded to the current implemented schema-bound lanes |
| Runtime tool results | Inputs, policy, execution, and declared outputs remain runtime-validated | Tool breadth remains intentionally narrow by profile |
| Desktop live-model outcome families | Host-authored instruction framing exists and host-owned outcome truth persists | Strict structured model-output enforcement for clarification, approval, unknown, blocked, or failure families is still missing in the live-model path |
The canonical structured-output definitions live in Tooling Taxonomy.
Current Implemented Profile Floor
Holon currently exposes only bounded AI-facing profiles in canon:
- Bounded desktop orchestration: host-authored instruction bundle, narrow provider tool loop, one sequential read-only child lane, and truthful durable events.
- Workflow execution: deterministic workflow artifact execution with schema-bound gates where implemented.
- Remote inspection: read-only continuity and inspection, not remote execution authority.
Broader autonomous execution, parallel child lanes, broad provider-managed orchestration, and unbounded model tool authority are not current canonical profiles.
Minimum Conformance Expectations
When one of these contract lanes changes, the minimum check should match the lane instead of falling back to narration:
| Lane | Current source of truth | Minimum validation | Expected evidence |
|---|---|---|---|
| Runtime protocol DTOs and schema fixtures | runtime/crates/holon-protocol plus fixture tests | cargo test -p holon-protocol --test schema_fixtures | Fixture parity or intentional fixture update |
| Desktop instruction-contract floor | Desktop host/runtime integration plus canonical docs | npm --prefix ./Frontend/HolonDesktop run test | Passing desktop host tests for request building, routing, events, and bounded instruction behavior |
| Workflow contract surface | Frontend/HolonClient workflow contract | npm --prefix ./Frontend/HolonClient run check:workflow-contract | Contract constant and root-shape proof |
| Contract-consumption proof | Frontend/HolonClient contract proof lane | npm --prefix ./Frontend/HolonClient run proof:elegy-contract-consumption -- <contracts-dir> when available | Compatibility matrix, pinned schema families, deterministic projection proof |
| Schema-bound structured-output lanes | holon-structured-output plus runtime tests | cargo test | Passing schema-gated workflow, tool, and AI-step validation behavior |
| Real desktop behavioral claims | Canonical desktop validation guide plus desktop test lane | npm --prefix ./Frontend/HolonDesktop run test:real-desktop | Artifacts under Frontend/HolonDesktop/tests/real-desktop/artifacts/ |
This is not yet a single machine-readable top-level conformance matrix. It is the current canonical statement of which proof lanes already exist and must be respected.
Current Known Gaps
- Desktop live-model clarification, approval, unknown, blocked, and failure families are not yet enforced through strict structured model outputs. See Known Issues.
- Desktop orchestration breadth remains bounded to one sequential read-only child lane and a narrow read-only tool loop. See Known Issues.
- A fuller profile-aware conformance matrix and stronger typed live-model outcome envelopes remain future work until implemented and validated.