# Architecture map

One is organized by semantic owner. This page is a reader's map; the linked
`AGENTS.md` files are the normative contracts.

## End-to-end flow

```text
Foundation -> Resources -> Authority -> Execution
                    \            \          \
                     +----------> Contracts  +-> {Communication, Data}
                                      |                    |
                                      +-> System IDL       v
                                                   Components
                                                       |
                                             {Composition, Experience}
                                                       |
                                                       v
Domain declarations and facts --------------------> Knowledge
Provider claims and catalog evidence -----------------+
                                                       v
                                                    Planning
                                                       |
                                                       v
                                            Build -> Deployment
                                                       |
                                  +--------------------+------------------+
                                  v                                       v
                               History                              Observability
```

Developer Interface orchestrates public APIs without owning their semantics.
This is semantic consumption and lowering flow, not a numeric crate hierarchy.

## System owners

| System | Owns |
| --- | --- |
| [Foundation](https://github.com/muijf/one/blob/main/systems/foundation/AGENTS.md) | target/host facts, values, identity, faults, time, events |
| [Resources](https://github.com/muijf/one/blob/main/systems/resources/AGENTS.md) | resource identity, lifecycle, ownership, cleanup, containment |
| [Authority](https://github.com/muijf/one/blob/main/systems/authority/AGENTS.md) | capabilities, effects, principals, policy, grants, trust |
| [Execution](https://github.com/muijf/one/blob/main/systems/execution/AGENTS.md) | tasks, cancellation, deadlines, timers, credits, channels |
| [Contracts](https://github.com/muijf/one/blob/main/systems/contracts/AGENTS.md) | domains, schemas, compatibility, mappings, profiles, projections |
| [System IDL](https://github.com/muijf/one/blob/main/systems/system-idl/AGENTS.md) | `.one`, System IDL, native One, parsing, source tooling |
| [Data](https://github.com/muijf/one/blob/main/systems/data/AGENTS.md) | state, storage, transactions, queries, physical data planning |
| [Communication](https://github.com/muijf/one/blob/main/systems/communication/AGENTS.md) | endpoints, calls, streams, messaging, transport mappings |
| [Components](https://github.com/muijf/one/blob/main/systems/components/AGENTS.md) | operations, services, jobs, workflows, placement |
| [Experience](https://github.com/muijf/one/blob/main/systems/experience/AGENTS.md) | places, intents, projections, interaction and surface contracts |
| [Composition](https://github.com/muijf/one/blob/main/systems/composition/AGENTS.md) | roots, selected semantics, reachability, binding intent |
| [Knowledge](https://github.com/muijf/one/blob/main/systems/knowledge/AGENTS.md) | semantic graph, D-IR, S-IR, provenance, explanations |
| [Planning](https://github.com/muijf/one/blob/main/systems/planning/AGENTS.md) | requirements, L-IR, P-IR, provider/topology selection |
| [Providers](https://github.com/muijf/one/blob/main/systems/providers/AGENTS.md) | ecosystem packages, catalogs, conformance, publisher trust |
| [Build](https://github.com/muijf/one/blob/main/systems/build/AGENTS.md) | A-IR, actions, artifacts, toolchains, provenance, signing |
| [Deployment](https://github.com/muijf/one/blob/main/systems/deployment/AGENTS.md) | DPL-IR, REC-IR, apply, placement, reconciliation |
| [History](https://github.com/muijf/one/blob/main/systems/history/AGENTS.md) | causal facts, effect journals, replay, compensation |
| [Observability](https://github.com/muijf/one/blob/main/systems/observability/AGENTS.md) | logs, metrics, traces, audits, lineage, budgets |
| [Developer Interface](https://github.com/muijf/one/blob/main/systems/developer-interface/AGENTS.md) | CLI, facade, tooling, inspection, automation |

## Composition laws

Across every system:

- every identity and contract has one owner;
- dependencies use public owned contracts;
- declarations, requirements, plans, artifacts, grants, and runtime authority
  remain distinct;
- optional edges are inert until selected for one root;
- generated projections are disposable;
- providers and adapters remain removable;
- unavailable behavior fails honestly;
- dependency cycles cause the smallest shared contract to move to the lowest
  valid owner.

Canonical root:
[repository architecture](https://github.com/muijf/one/blob/main/AGENTS.md).