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…
| 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 |