# Current Design Authority

The current capOS design lives in reader-facing architecture, capability,
security, device, configuration, and status pages. Proposal documents remain
important design history, but they stop being the primary place to patch a
design after that design is implemented or accepted as the working baseline.

## Stable Homes

Use these homes for current behavior and accepted contracts:

| Area | Current-design home |
| --- | --- |
| Boot, manifest, init, processes, rings, IPC, session context, memory, scheduling | `docs/architecture/` |
| Capability model, authority accounting, ABI policy | `docs/capability-model.md`, `docs/authority-accounting-transfer-design.md`, `docs/abi-evolution-policy.md` |
| Operator configuration and CUE overlays | `docs/configuration.md` |
| DMA isolation, device authority, trusted inputs, panic surfaces | `docs/dma-isolation-design.md`, `docs/devices/`, `docs/trusted-build-inputs.md`, `docs/panic-surface-inventory.md` |
| Current status, roadmap, backlog, task lifecycle | `docs/status.md`, `docs/roadmap.md`, `docs/backlog/`, `docs/tasks/` |
| Proposal status and archival decision records | `docs/proposals/index.md` and individual files under `docs/proposals/` |

When a current-design home already exists, future implementation slices update
that page. When none exists and the proposal has become the working design,
create or extend a stable page in the nearest existing area instead of leaving
the proposal as the only current reference.

## Proposal Lifecycle

The proposal index classifies proposals with these roles:

- **Active design**: near-term design work still being changed before or during
  implementation. It may remain the primary working document while the design
  is not stable.
- **Accepted design**: selected direction. It can guide implementation, but any
  implemented subset needs a stable current-design page or an explicit pointer
  to the page that already owns the current contract.
- **Partially implemented**: some behavior is in tree. The proposal must
  distinguish present behavior from planned behavior, and current pages should
  describe the implemented subset.
- **Implemented**: the proposal is an archival decision record. Future changes
  update the stable current-design docs and code references first; the proposal
  changes only for archival status, links, or corrected history.
- **Superseded** or **Rejected**: historical records. They should point at the
  replacement or rejection rationale and must not be cited as current behavior.

## Initial Promotions

This repository already had stable homes for several implemented or accepted
designs. The initial promotion set makes the weakest current-authority links
explicit:

| Proposal or decision | Current-design authority | Disposition |
| --- | --- | --- |
| Session-Bound Invocation Context | `docs/architecture/session-context.md`, with endpoint transport details in `docs/architecture/ipc-endpoints.md` | Implemented proposal becomes archival history. |
| Error Handling | `docs/architecture/error-handling.md`, with ring transport details in `docs/architecture/capability-ring.md` | Implemented proposal becomes archival history. |
| System Configuration | `docs/configuration.md` and `docs/architecture/manifest-startup.md` | Implemented proposal stays as rationale and closeout history. |
| DMA Assurance Model | `docs/dma-isolation-design.md` | Accepted design remains grounded in the stable DMA design page. |
| SMP and Scheduler Evolution | `docs/architecture/threading.md` and `docs/architecture/scheduling.md` | Accepted design feeds current scheduler and threading contracts. |

Follow-up promotions should focus on proposals whose implemented slices are
large enough that readers still have to mine proposal text for current
behavior. Good candidates include storage/naming, installable system,
SystemInfo/System Manual, and userspace driver relocation once their current
contracts settle further.