The architecture is judged on three promises. Each row names the promise, the mechanism that keeps it, the ontology objects involved and the file that proves it exists. Open items are marked, never hidden.
| Promise | Mechanism | Objects | Backing |
|---|---|---|---|
| Services come back after a crash or reboot | podman restart policies + podman-restart.service (Linux) / launchd (Mac); console under systemd | ServiceRole, NativeConsole | appliance.yml, install.sh |
| A lifecycle mutation cannot half-complete | journaled CAS lifecycle.operation; generation volumes; roll-forward promotion; recovery of up:claimed | LifecycleOperation, VolumeSet | appliance/bin/kos |
| Data survives and moves | kos backup/restore with ownership kept; exact-count parity checks; the volumes are liftable | BackupSnapshot, VolumeSet | docs/guides/backup-restore.md, APPLE_TO_PODMAN_MACOS_MIGRATION.md |
| Schema changes are exact | migration ledger with checksums (kos_appliance_schema_baseline_migrations, kos_app_schema_migrations); refuses unknown rows | LifecycleOperation | appliance/migrate.py |
| A stuck run does not stall dispatch | dispatch lease expiry → watchdog auto-requeue; retry cap → CONSULT escalation; dead-run reclaim | DispatchLease, Handoff, TeamEvent | orchestrator.py, watchdog.py |
| A completion is not a claim | the reviewable return protocol + the evidence floor (harness "completed" with no evidence → partial) | CompletionHandback, EvidenceFloor | .agents/api/main.py |
| Memory stays fresh | work-product freshness by hash; retention tiers; ingest updates clear stale embeddings (KD-7) | WorkProduct, RetentionTier, Knowledge | run_agent.py, main.py |
| A green suite is not evidence | real-engine gate on a fresh host (kos-test) before any release | PackageChannel, HostFamily | THE_WAY §14, design 26 |
| Promise | Mechanism | Objects | Backing |
|---|---|---|---|
| One place configures the appliance | the control-volume contract; every consumer reads it, nothing is baked | Contract | bin/kos CONTRACT_KEYS |
| Who may act is data, not a guess | actor model + roles; designation (interactive / autonomous / deterministic); persona registry planned (E014) | Actor, Role, Agent | cortex_actors, app/domain/roles.py |
| Nothing dispatches by surprise | propose-mode parking; interactive holds announced once; auto_dispatch per agent; wave gating per epic | Handoff, DispatchLease, Epic | orchestrator.py |
| No one approves their own work | delegator ≠ worker on the return protocol; handbacks route to a visible reviewer | CompletionHandback | handback_recipient |
| Projects do not leak | cross-project isolation with a one-off CTO override that never cross-registers | Project, Handoff | cortex-handoff --cto-override |
| Spend and capability are gated | edition (structural) → entitlements (six gates) → Manifold key mint and spend reservations | Edition, Entitlement, Grant, SpendReservation | app/edition.py, app/license.py, Manifold |
| Provider credentials have one owner | OpenKai owns its store; KOS projects and tests it | KOSProjection, Provider | openkai_provider_config.py |
| The operator sees the raw truth | terminal-first: the PTY byte stream is the surface, never a reconstruction | Harness, NativeConsole | design 27, app/terminal_stream/ |
| Layer | Refuses | Objects | Backing |
|---|---|---|---|
| L1 hashed named tokens | any caller without a token; the legacy default token | Cortex API, Contract | admin_tokens, secrets.compare_digest |
| L2 Tailscale + TLS | LAN and internet exposure; services publish on loopback only | Appliance | tailscale serve, appliance.yml |
| L3 passwordless login + passkeys | password reuse and phishing; first admin only through the bootstrap token | Auth | app/auth.py |
| L4 mTLS (platform) | unauthenticated service-to-service calls on the hosted platform | cortex-service | docs/design/09-security-architecture.md |
| RLS substrate | cross-tenant reads on the platform; FORCE RLS everywhere | Organization, Project | rls_context.py |
| Process boundary | agent code escaping its sandbox (bwrap); the console running as root | HarnessInstall, NativeConsole | harness_runner.py, install.sh |
| Secret custody | secrets in code, in the browser, or in images | Contract | THE_WAY, bin/kos |
| Open work | SEC-04 per-user scoping of terminal routes · SEC-05 backup encryption · sandbox on Ubuntu (AppArmor) | — | tasklist C1–C4 |
| Concern | Mechanism | Backing source |
|---|---|---|
| Who runs the console | a dedicated non-root service user; systemd hardening on Linux | install.sh unit generation |
| Who runs agent code | harness child processes of the console user, sandboxed with bwrap where the distro permits unprivileged user namespaces (Fedora/RHEL: yes); interactive Leads are never sandboxed by designation | harness_runner.py _agent_full_access, _run_bwrap_probe |
| Where services listen | loopback-only published ports; nothing on the LAN; remote access through L2 (Tailscale + TLS) | appliance/appliance.yml 127.0.0.1: publishes |
| Where secrets live | the control volume contract (0600) and the console's runtime env; never the browser, never code | bin/kos contract, docs/CURRENT_ARCHITECTURE_AND_RELEASE.md |
| Data at rest | named volumes; backups carry the databases (encryption of backups is open work SEC-05) | kos backup |
| Provider credentials | OpenKai owns its store; KOS only projects and tests | app/openkai_provider_config.py |