# Architecture

## Document map

| Document | Role |
|---|---|
| [README.md](README.md) | Project overview, document layout, reading order, documentation checks |
| [docs/control-plane.md](docs/control-plane.md) | Reducer specification: state machines, transactions, failure handling, run termination, crash recovery |
| [docs/work-graph.md](docs/work-graph.md) | Hierarchical work graph, node contracts, decomposition, actions, scheduling |
| [docs/executors.md](docs/executors.md) | Executor selection, trust boundary, executor protocol, sandbox |
| [docs/integration-and-conflicts.md](docs/integration-and-conflicts.md) | Conflict model, integration ownership, repository semantics |
| [docs/budgets.md](docs/budgets.md) | Hierarchical budgets, accounting, no-overcommitment invariant |
| [docs/validation.md](docs/validation.md) | Evidence policy, acceptance binding, parent acceptance, independent evaluation |
| [docs/experiment.md](docs/experiment.md) | Conformance gate, experiment procedure, evaluation metrics |
| [docs/roadmap.md](docs/roadmap.md) | MVP boundary, implementation sequence, deferred questions |
| [docs/deferred.md](docs/deferred.md) | Alternatives, routing, evolving scope |
| [docs/glossary.md](docs/glossary.md) | Identifier catalogue: states, events, relations, conflicts, outcomes |
| [docs/event-catalogue.md](docs/event-catalogue.md) | Event definitions and payloads |
| [docs/tables/](docs/tables/) | Canonical table data (state machines, policy completeness, run outcomes, limits) rendered into the normative documents |

## Status

This document defines the architectural principles, execution semantics, trust boundaries, and unresolved implementation decisions for a practical autonomous project-development orchestrator.

It is a design baseline, not a claim that arbitrary projects can presently be developed autonomously and reliably.

## Purpose

The orchestrator coordinates recursive problem decomposition, parallel execution, multi-model reasoning, deterministic tools, integration, validation, and replanning.

Its objective is to make verified progress on an initially incomplete project description while:

- avoiding exhaustive speculative planning;
- exposing safe parallelism;
- supporting decomposition to arbitrary logical depth;
- limiting local complexity through bounded fan-out;
- selecting different models or tools for different tasks;
- minimising reasoning-model usage and token cost;
- keeping authoritative control outside reasoning components;
- preserving replayable evidence and provenance;
- preventing local task completion from being mistaken for project success.

## Core Principles

The architecture is specified normatively by the documents in the [Document map](#document-map). In summary:

- **Work graph**: each objective is a versioned node in a lazily expanded hierarchical work graph with typed relations.
  See [Work Graph](docs/work-graph.md).
- **Decomposition**: a node is decomposed only when expected gains outweigh coordination costs; acceptance requires
  complete mandatory coverage with an explicit integration path. See [Work Graph](docs/work-graph.md#decomposition).
- **Deterministic control plane**: the sole authority for event admission, ordering, mutation, scheduling, budgets,
  evidence policy, and state transitions. Replay is deterministic over the authoritative event stream. See
  [Control Plane](docs/control-plane.md).
- **Untrusted execution plane**: reasoning models, tools, and external services produce observations and proposals but
  never mutate authoritative state directly. See [Trust Boundary](docs/executors.md#trust-boundary).
- **Concurrency and conflicts**: actions run concurrently only when scopes, budgets, and conflict policies permit;
  blocking conflicts prevent acceptance transitions. See [Conflict Model](docs/integration-and-conflicts.md#conflict-model)
  and [Parallel scheduling](docs/work-graph.md#parallel-scheduling).
- **Alternatives**: exclusive alternatives execute only under explicit group policy. See [Alternatives](docs/deferred.md#alternatives).
- **Acceptance**: a node is accepted only when all mandatory children are satisfied, outputs are integrated, conflicts
  are resolved, and evidence appropriate to risk is applied. Acceptance is bound to versions. See
  [Validation and Acceptance](docs/validation.md).
- **Budgets**: hierarchical budgets enforce the no-overcommitment invariant; child consumption counts against every
  applicable ancestor. See [Hierarchical Budgets](docs/budgets.md).
- **Failure**: preserve all observations, artefacts, and accounting records; transition according to deterministic
  policy. Never infer parent acceptance from child completion. See [Failure and Replanning](docs/control-plane.md#failure-and-replanning).

## Architectural Model

The system consists of two fundamentally different planes.

### Deterministic control plane

The control plane is the sole authority for:

- authoritative event admission;
- event ordering;
- graph mutation;
- state transitions;
- readiness calculation;
- scheduling;
- permissions;
- resource allocation;
- budget reservation and accounting;
- retry and cancellation policy;
- alternative-selection policy;
- validation-policy application;
- acceptance transitions;
- artefact publication;
- invalidation;
- audit records;
- replay and recovery.

The control plane is deterministic with respect to:

- the same authoritative initial state;
- the same ordered event stream;
- the same recorded external observations;
- the same policy and schema versions.

It does not guarantee deterministic real-world outcomes.

### Untrusted execution plane

The execution plane contains:

- reasoning models;
- coding models;
- specialist models;
- local models;
- deterministic tools;
- external services;
- human approval interfaces;
- build and test systems;
- deployment systems.

Execution-plane components produce observations, proposals, artefacts, or evidence. They do not directly mutate
authoritative state.

## Safety Invariants

The initial system should enforce:

1. Reasoning components cannot mutate authoritative state.
2. Every authoritative mutation is event-backed and auditable.
3. Every mutation proposal carries expected versions for all authoritative entities it references; admitted events
      remain globally ordered facts.
4. Every accepted result is bound to concrete input and policy versions.
5. No action is dispatched without permission, scope isolation, capacity, and budget commitment.
6. For every budget and ancestor budget, actual consumption, active uncommitted reservations, active commitments, and
      protected reserves do not exceed the authorised limit.
7. Actual costs are recorded once and attributed through the ancestor path.
8. Protected validation and integration reserves cannot be silently consumed.
9. Alternative branches execute only under explicit group policy.
10. Shared production has an explicit integration and publication owner.
11. Blocking conflicts prevent affected acceptance transitions.
12. Results with freshness `STALE`, `INVALID`, or `REVALIDATION_REQUIRED` cannot satisfy dependencies.
13. Executor self-reported success is never sufficient evidence.
14. Child completion never implies parent acceptance.
15. Budget exhaustion, depth limits, and timeouts never imply success.
16. Replay does not silently re-execute non-deterministic or irreversible effects.
17. The reducer does not read wall clocks, live executor availability, live resource capacity, or external systems.
18. Scheduling, capacity changes, timer firings, dispatches, cancellations, and executor observations are event-backed.
19. Node, attempt, artefact, and freshness states are represented and transitioned independently.
20. Concurrent repository-writing attempts have deterministically disjoint write scopes.
21. Out-of-scope repository changes are rejected as `WRITE_CONFLICT`.
22. Root acceptance is evaluated against an oracle frozen before execution and independent from the generator.
23. A controller crash cannot publish or integrate an unrecorded executor side effect.
24. Repeated failure without a new diagnostic fingerprint, changed binding, changed strategy, or new evidence cannot
      retry indefinitely.

The invariants are enforced by:

| Invariant | Enforcing documents |
|---|---|
| 1–4 | [Event and proposal requirements](docs/control-plane.md#event-and-proposal-requirements), [Trust Boundary](docs/executors.md#trust-boundary) |
| 5 | [Control Plane](docs/control-plane.md#control-plane), [MVP no-overcommitment invariant](docs/budgets.md#mvp-no-overcommitment-invariant) |
| 6–8 | [MVP no-overcommitment invariant](docs/budgets.md#mvp-no-overcommitment-invariant), [Ancestor accounting](docs/budgets.md#ancestor-accounting) |
| 9 | [Alternatives](docs/deferred.md#alternatives) |
| 10 | [Production, Integration, and Ownership](docs/integration-and-conflicts.md#production-integration-and-ownership) |
| 11 | [Conflict Model](docs/integration-and-conflicts.md#conflict-model), [Parent Acceptance](docs/validation.md#parent-acceptance) |
| 12 | [Result freshness](docs/control-plane.md#result-freshness) |
| 13 | [Trust Boundary](docs/executors.md#trust-boundary), [Risk-sensitive and independent evidence](docs/validation.md#risk-sensitive-and-independent-evidence) |
| 14 | [Parent Acceptance](docs/validation.md#parent-acceptance) |
| 15 | [Executability and Decomposition Stopping](docs/work-graph.md#executability-and-decomposition-stopping), [Run termination and outcomes](docs/control-plane.md#run-termination-and-outcomes) |
| 16–18 | [Control Plane](docs/control-plane.md#control-plane), [Scheduling inputs and decisions](docs/work-graph.md#scheduling-inputs-and-decisions) |
| 19 | [State Machines](docs/control-plane.md#state-machines) |
| 20 | [Scheduling inputs and decisions](docs/work-graph.md#scheduling-inputs-and-decisions), [Deterministic decomposition acceptance](docs/work-graph.md#deterministic-decomposition-acceptance) |
| 21 | [Repository integration semantics](docs/integration-and-conflicts.md#repository-integration-semantics) |
| 22 | [Risk-sensitive and independent evidence](docs/validation.md#risk-sensitive-and-independent-evidence), [Experiment procedure](docs/experiment.md#experiment-procedure) |
| 23 | [Crash recovery](docs/control-plane.md#crash-recovery), [Executor sandbox](docs/executors.md#executor-sandbox) |
| 24 | [Repeated-failure rule](docs/control-plane.md#repeated-failure-rule) |

## Summary

The intended system is a recursively decomposing, lazily expanding, dependency-aware work orchestrator.

Its defining properties are:

- Hierarchy manages abstraction.
- Typed relations represent execution and semantic structure.
- Bounded fan-out manages local complexity.
- Lazy expansion delays unsupported detail.
- Dependencies manage ordering.
- Isolation and conflicts govern concurrency.
- Contracts govern delegation.
- Explicit owners govern integration and publication.
- Alternative groups govern choice.
- Hierarchical budgets govern resource consumption.
- Deterministic policy governs authority.
- Reasoning components handle bounded semantic uncertainty.
- Evidence governs acceptance.
- Versioning and provenance enable audit and replay.
- Parent validation governs composition.
- Failure evidence triggers retry, alternatives, or replanning.

The central trust rule is:

Reasoning components may propose, produce, and evaluate, but only the deterministic control plane may authorise, mutate,
schedule, account, publish, and accept.

The central decomposition rule is:

Decompose only when the expected improvement in executability, verifiability, failure isolation, risk containment,
context reduction, safe parallelism, reuse, information gain, or model or tool fit exceeds the expected
coordination and integration cost.

The central completion rule is:

Never infer parent acceptance from child completion. Integrate the child outputs and independently validate the parent
contract under the applicable versions and evidence policy.