# Roots and composition

A One project may contain many applications and deployables, but each root is
planned as an isolated product. Only explicit semantic edges determine what it
can contain.

## A root defines the boundary

Roots identify independently built and governed units such as:

- a server or worker;
- a browser, mobile, desktop, or device application;
- a command-line tool;
- a migration or scheduled job;
- a plugin or portable computation;
- a provider or control-plane workload.

Every root gets its own semantic, implementation, provider, schema, codec,
artifact, resource, permission, secret, and Build closure.

```mermaid
flowchart TD
    project[One project]
    project --> browser[Browser root\npublic schemas + HTTPS client]
    project --> api[API root\nservice + database + ingress]
    project --> worker[Worker root\nqueue + activities]
    project --> operator[Operator root\ninspection + scoped control]
```

The browser cannot inherit server credentials. The worker cannot gain an
operator grant. A debug artifact cannot enter a production root. Workspace
membership, installed providers, package-manager features, and generated
files never create reachability.

## Composition is explicit

An edge may reference a schema, call an operation, bind state, launch a child,
emit an event, require a capability, select a mapping, or expose an endpoint.
Each edge retains its source and owner.

Knowledge normalizes declarations into a typed semantic graph. Planning walks
that graph to a fixed point for one root, activates only explicitly selected
optional contributions, and records an inclusion proof for every result.

## Topology follows semantics

Topology planning decides where component edges cross task, process, machine,
region, trust, or provider boundaries. Closure is recomputed at every boundary.

For example, moving a local call across regions adds remote identity,
serialization, encryption, authorization, deadlines, retry and idempotency
rules, discovery, routing, observations, and network cost. If those
requirements cannot be satisfied together, planning returns a minimal typed
conflict instead of weakening the contract.

## Runtime choice stays inside the release envelope

A released application may offer bounded runtime or tenant choices when every
candidate artifact, provider, capability, grant, resource, cost, and switching
rule is already inside its immutable plan. Runtime binding can select an exact
instance or an admitted member of that envelope.

Choosing something that needs new code, authority, resources, data movement,
or cost approval produces a new plan and release. Customer requests never
turn into ambient provider discovery or permission to run the One CLI in the
request path.

## Explain every inclusion

For any artifact, permission, route, sidecar, storage volume, provider,
generated client, or cloud resource, One can explain:

```text
included because the selected provider implements RemoteCallTransport
selected because CarrierGateway is placed in another region
required because OrderApi calls CarrierGateway
source: system.one:42:19
policy: production.carrier_gateway = eu-west
alternatives: rejected with exact reasons and comparative costs
```

`WhatWouldRemove` finds the smallest source, placement, or policy changes that
cut every inclusion path without mutating the system.

See the closure in practice in
[Build a multi-tenant platform](/one/examples/multi-tenant-platform) and
[Ship and inspect a release](/one/examples/release).

Canonical owners:
[Composition](https://github.com/muijf/one/blob/main/systems/composition/AGENTS.md),
[Knowledge](https://github.com/muijf/one/blob/main/systems/knowledge/AGENTS.md),
and [Planning](https://github.com/muijf/one/blob/main/systems/planning/AGENTS.md).

Next: [add implementations](/one/authoring/implementations).