Functional Overview

ArchitectOS (AOS) is a governance architecture for AI-assisted work. It defines how humans and language models collaborate on tasks while preserving accountability, auditability, and human authority.

This document describes what AOS does at a functional level. It does not cover installation, configuration, or implementation details.

The Core Loop

AOS implements a single operational loop:

Human prompt → Recall (evidence) → Plan → Execute → Log → Review

Every step in this loop produces artifacts. Every artifact has provenance. The Ledger records what happened, when, why, and under whose authority.

Key Components

The Ledger

The Ledger is an append-only log of all significant events. It records:

  • Commands issued and their results
  • Artifacts produced and their content hashes
  • Human approvals and rejections
  • Session state transitions

The Ledger is not metadata. It is a first-class output of the system. If an action is not in the Ledger, it did not happen within AOS governance.

Packs and Artifacts

A Pack is a versioned collection of related files, bound to a specific context (such as a ticket or task). Packs provide the evidence base for recall.

An Artifact is any file produced or consumed by the system. Artifacts are content-addressed: their identity is their hash. This makes them immutable and verifiable.

The Bridge

The Bridge is the execution substrate. It receives commands, enforces policy, executes permitted operations, and logs results. The Bridge does not make decisions; it carries them out.

In SAFE mode, the Bridge permits only local, reversible, non-destructive operations. Network access, privilege escalation, and unbounded execution are prohibited.

The Orchestration Layer

The orchestration layer coordinates multi-agent workflows. It manages session state, turn order, and evidence attachment. It does not execute commands directly; it delegates to the Bridge.

The orchestration layer enforces role separation. Agents that propose are not the same agents that review. Agents that review are not the same agents that execute.

Execution Modes

SAFE Mode

SAFE mode is the default and, in v0.1, the only permitted mode. SAFE is a contract, not a label.

SAFE mode guarantees:

  • No network access
  • No privilege escalation
  • No modification of files outside the workspace
  • No execution of arbitrary code without explicit boundaries
  • Explicit failure on policy violation (no silent degradation)

Violations produce POLICY_VIOLATION errors. There is no "try anyway" option.

Future Modes

Future versions may introduce additional modes (such as NET or UNBOUND) with expanded capabilities and correspondingly stricter oversight requirements. These modes are not part of the public product at this time.

The Recall System

Recall provides evidence to inform planning. It queries the Pack index and returns relevant artifacts based on metadata matching.

Recall is evidence, not authority. The system surfaces what it finds; humans decide what to trust.

In v0.1, recall operates on metadata only (tags, tickets, timestamps). Semantic search is deferred to future versions.

Session Structure

A session is a bounded unit of work. Each session has:

  • A unique identifier
  • A chat transcript (chat.raw.ndjson)
  • An evidence directory (recall bundles, excerpts)
  • An optional session-level ledger

Sessions live under a project. Projects do not share state. This isolation is enforced at the filesystem level.

Project Isolation

AOS supports multiple simultaneous projects on a single host. Each project is a quarantined universe containing:

  • Workspace state (sessions, logs, specs)
  • Pack index and metadata
  • A project-specific database
  • Optional repository working trees

Path confinement is enforced. Any attempt to access files outside the project workspace produces a POLICY_VIOLATION error.

What AOS Does Not Do

AOS does not:

  • Grant autonomous system access to agents
  • Treat model output as authoritative
  • Hide state, decisions, or mutations
  • Optimize for speed over comprehension
  • Permit silent failures or degraded modes

AOS is not a programming language, runtime environment, build system, workflow engine, or agent framework. It is a governance architecture that can be implemented atop any of these.

The Accountability Test

Every AOS system must be able to answer five questions about any action:

  1. What happened?
  2. Why did it happen?
  3. Who is responsible?
  4. What assumptions were made?
  5. What could have happened differently?

If the system cannot answer these questions, it is incomplete—regardless of how impressive its output may be.

Design Principles

Determinism Over Illusion

AOS uses probabilistic model output to generate plans that are validated using deterministic computing procedures. The models are not deterministic; the validation is.

Provenance Is First-Class

Every meaningful action is traceable: what model or tool acted, with what inputs, under what constraints, at whose request, producing which artifacts.

Friction Is a Feature

AOS intentionally resists "one-click magic." Deliberate pauses, confirmations, manifests, diffs, and checkpoints are protective mechanisms, not UX failures.

Explicit Failure Over Silent Success

When something goes wrong, the system says so. There are no best-effort modes, no partial successes dressed as wins, no silent swallowing of errors.

Current Status

AOS is in active development. The core architecture is frozen; implementation is ongoing.

The current milestone (FWV-Loop v0.1) targets a minimum integrated system supporting the full operational loop in SAFE mode, with metadata-only recall, multi-project isolation, and complete provenance logging.

This document will be updated as the system matures.