# Architecture

Portable Agent OS has one canonical core and several projections. Host files, generated reports, and
an optional future control center are not alternate sources of truth.

## Components

| Component | Owns | Does not own |
| --- | --- | --- |
| Portable core | gateway, routing, goals, continuity, approvals, verification, provider interfaces | host credentials, personal state, host-specific hook implementation |
| Versioned contracts | bounded JSON shapes and capability states | runtime truth without a live probe |
| Host adapters | capability probes and deterministic instruction rendering | canonical private state or wider authority |
| Export compiler | allowlisted copying, privacy scan, manifest, hashes, preview/apply | discovery-based publication or blacklists |
| Lifecycle layer | managed files, manifests, locks, journals, backup, migration, recovery | deletion of unmanaged or drifted content |
| Private overlay | profile, memory, projects, sessions, runtime, evidence, secrets, backups | public source or distributable examples |
| Package layer | validation, provenance authorization, install and activation state | self-authorized rights or implicit permissions |
| Optional Operator Layer | shared execution policy, emergency controls, typed backups, managed replay/fork plans, read-only status | host key custody, private state, or execution authority |

## State flow

1. The operator supplies explicit command inputs.
2. Path and contract validators reject ambiguous, linked, out-of-root, oversized, or non-canonical
   inputs.
3. A capability probe or lifecycle inspection produces a hash-bound plan.
4. Preview exposes that plan without mutation.
5. Apply acquires the overlay lock, rechecks the plan, writes a transaction journal, and mutates only
   managed content.
6. Status, doctor, evidence, and host files project the resulting state.

## Public/private boundary

Public source contains code, schemas, synthetic examples, policies, and tests. The private overlay is
outside the repository and contains `profile`, `memory`, `projects`, `sessions`, `runtime`,
`evidence`, and `secrets`. Uninstall preserves the overlay by default.

The deterministic exporter starts from an allowlist. Unknown rights, private classes, unstable
reads, path escapes, and scanner findings block compilation. Generated evidence is not promoted into
source merely because it exists.

## Host degradation

Adapters report each capability as `supported`, `degraded`, `unsupported`, or `unknown`. Unknown is
not treated as supported. A missing optional hook produces a bounded reason and a safe next action;
it does not block unrelated file export. See [Host support](HOST_SUPPORT.md) for current evidence.

The normative design decision is [RFC-0001](../architecture/RFC-0001-portable-agent-os.md).
The optional operator boundary is documented in [Portable Operator Layer](OPERATOR_LAYER.md).