AncientOS v3 Architecture
AncientOS v3 is the canonical application-platform architecture for AncientOS. It keeps the governed kernel from v1 and the visibility and explainability surfaces from v2, then adds Chen as the app-layer framework for workflow orchestration and domain implementation.
v3 exists because AncientOS now needs a repeatable way to add real applications without moving domain logic into the kernel. The system has enough governance, routing, records, visibility, and capability reasoning to support applications as first-class platform citizens. Chen provides that application layer while preserving the kernel boundary.
The v3 rule is:
Kernel governs -> Chen orchestrates -> Domains implement
Architectural Epochs
AncientOS v1
v1 established the governed kernel:
- governed kernel boundaries
- semantic routing
- kernel records
- transport neutrality
- initial Oracle, Rubick, and Lich foundations
v1 answered the question: how can Luna operate over a transport-neutral, governed substrate instead of being only a Discord bot?
AncientOS v2
v2 made the kernel visible and explainable:
- operational awareness
- Oracle visibility
- Beastmaster host awareness
- Rubick capability reasoning
- knowledge surfaces
- read-only cognition
- explainability
v2 answered the question: how can AncientOS explain what exists, what is known, what is degraded, and what authority is missing without silently executing?
AncientOS v3
v3 makes AncientOS an application platform:
- Chen application framework
- kernel governance retained as the authority boundary
- Chen workflow orchestration
- domain implementations behind Chen
- domain manifests under
docs/chen/domains/ - read-only domain registry discovery
- Oracle and Rubick application visibility
- Media Manager as the first active Chen domain
- external adapters such as Bitmagnet, Plex, qBittorrent, and Deluge
- Lich-gated mutation model for import, download, refresh, migration, and other authority-bearing actions
v3 answers the question: how can AncientOS add applications and domain workflows without turning the kernel into domain logic?
The architectural intent behind Chen's current evolution is captured in Chen Architectural Intent.
Layered Model
| Layer | Owns | Does not own |
|---|---|---|
| Luna | Conversation and interface surface | Kernel authority, domain truth, execution |
| Semantic Router | Intent classification and routing | Governance, approval, domain implementation |
| Kernel | Governance, routing, records, policy, audit, replay, universal platform capabilities | App goals, domain-specific logic, external service truth |
| Rubick | Capability registry, discovery, ontology, relationship visibility | Execution, approval, domain mutation |
| Oracle | Evidence, visibility, explanation, readiness rendering | Source of truth, execution, mutation |
| Lich | Approval and governance gate | Domain implementation, adapter execution |
| Beastmaster | Host and system awareness | Repository reasoning, approval, domain goals |
| Tinker | Governed execution machinery and provider lane | Approval authority, hidden mutation |
| Chen | Workflow orchestration and application framework | Kernel governance, audit/replay authority, policy enforcement |
| Domains | Subject-specific read models, planning, adapter coordination, workflow logic | Kernel primitives, approval authority |
| External adapters | Service-specific access to systems such as Bitmagnet, Plex, qBittorrent, Deluge, Home Assistant, finance APIs, publishing APIs, or knowledge stores | AncientOS authority, app identity, kernel truth |
Chen As Application Framework
Chen is the first AncientOS application framework. It is not merely the media app and not a kernel component. Chen coordinates capabilities, plans multi-step app/domain flows, and delegates to Rubick, Oracle, Lich, Tinker, and domain adapters.
Media Manager is the first active Chen domain. It remains at
app/media_manager as a compatibility module path. This is intentional:
AncientOS v3 declares the architecture before any large mechanical module
rename. A future app/chen or plugin/domain structure may be considered
later, but v3 does not require that refactor.
Domain Manifests And Registry
Chen domains should declare inert manifests under:
docs/chen/domains/
The manifest describes domain identity, compatibility module path, status, adapters, read-only capabilities, planning capabilities, future mutation-capable actions, required Lich approvals, Rubick evidence refs, Oracle visibility refs, external services, secret requirements, safety boundaries, and runbook references.
The domain registry reader discovers and validates these manifests for Rubick/Oracle visibility. It does not register runtime routes, invoke adapters, load secrets, approve work, execute actions, or mutate state.
Application Lifecycle
AncientOS v3 domains should follow this lifecycle:
Intent -> Planning -> Capability Discovery -> Evidence -> Approval -> Execution -> Verification -> Kernel Record
| Step | Meaning |
|---|---|
| Intent | Luna or another interface captures the operator request and the Semantic Router classifies it. |
| Planning | Chen builds a bounded plan or readiness preview without dispatching work. |
| Capability Discovery | Rubick identifies available capabilities, providers, dependencies, and gaps. |
| Evidence | Oracle and domain read models surface the evidence needed to judge readiness. |
| Approval | Lich gates any authority-bearing action. Read-only inspection and planning can proceed without mutation authority. |
| Execution | Tinker or another governed execution lane may act only after explicit approval and within scope. |
| Verification | Oracle, domain read models, adapters, and evidence receipts verify the result. |
| Kernel Record | The kernel records the governed outcome, evidence, audit path, and replayable state. |
Read-only inspection, planning, registry validation, and readiness reporting may stop before Approval. Mutation, import, download, refresh, migration, external dispatch, file movement, or service mutation must pass through Lich approval before execution.
Media Manager Domain
Media Manager is the first active Chen domain. Its current scope is read-only media readiness, brokered acquisition planning, and one bounded approved mutation:
- Bitmagnet health visibility
- Plex read-only identity, library section, count, and migration-inventory visibility
- qBittorrent read-only readiness
- Gluetun/VPN dependency modeling
- planning-only media request previews
- Acquisition Broker candidate discovery
- acquisition agents such as Bitmagnet metadata and legal demo/open-media fixtures
- future import/download/refresh/migration action modeling with Lich approval required
- approved paused qBittorrent dispatch
Bitmagnet, Plex, qBittorrent, legal/open fixture providers, Deluge, and similar services are external adapters or agents. They are not kernel concepts and do not become authority sources. Chen asks the broker who can satisfy a request; it does not hardcode where media comes from.
Migration Note
v2 applications should gradually become Chen domains when they represent subject-specific workflows rather than universal kernel services. This should happen by documentation, manifests, read-only registry visibility, tests, and compatibility paths first.
Do not rename existing modules merely to satisfy v3 terminology. Existing module paths, routes, service names, environment variables, and persisted artifacts remain compatibility surfaces until a separate mechanical migration is explicitly approved.
Non-Goals
AncientOS v3 does not add runtime app registration, automatic domain dispatch, hidden approval, secret loading, provider scraping, or piracy-specific providers. It allows explicit, bounded, approval-gated mutations when a domain has a reviewed packet and governed executor. It declares the platform architecture and the governed path future domains should follow.