ARVIS Architecture

Executive Summary

ARVIS is a runtime assurance kernel for LLM-based systems. The operating-system vocabulary used throughout this document (processes, syscalls, scheduler) describes how the kernel is built, not a claim that ARVIS schedules your workloads; GLOSSARY.md maps every term to its nearest standard concept.

It is not a model.

It is not a chatbot wrapper.

It is not merely an agent framework.

ARVIS is the runtime layer that governs:

how cognition is evaluated
when decisions are allowed
how execution is controlled
how results are replayed and audited

System View

Input
 ↓
Runtime Orchestration
 ↓
Cognitive Pipeline
 ↓
Decision Gate
 ↓
IR / Result View
 ↓
Controlled Execution
 ↓
Timeline / Replay / Audit

This means ARVIS separates:

thinking
deciding
acting
observing

Most systems mix all four.

Core Principle

A decision is not generated.
It is allowed to exist under constraints.

That single rule drives the architecture.

High-Level Layers

1. Public API Layer

Stable entrypoint:

from arvis import CognitiveOS

Main methods:

run(...)
run_ir(...)
replay_verified(...)
replay_recomposed(...)
inspect(...)
register_tool(...)

Purpose:

simple integration surface
stable contract
internal refactor freedom

2. Runtime Orchestration Layer

Primary role:

When and how cognition executes

Responsibilities:

process lifecycle
scheduling
execution order
budgets
multi-run orchestration
deterministic replay flow

Core concepts:

runtime state
process management
scheduling discipline

3. Cognitive Pipeline

Primary role:

How decisions are evaluated

The pipeline transforms input into governed decisions.

Typical stages include:

context ingestion
bundle construction
conflict analysis
control logic
projection checks
gate evaluation
confirmation logic
action intent generation

Important:

The pipeline decides semantics. The runtime decides execution order.

4. Decision Gate

This is where ARVIS becomes different.

The gate can:

allow
deny
abstain
request confirmation
escalate

It evaluates signals such as:

risk
uncertainty
stability
conflict pressure -structural constraints

Unsafe cognition stops here.

5. Result / IR Layer

Outputs become structured artifacts:

CognitiveResultView
deterministic summaries
portable IR
commitments
traces

This enables:

replay
audit
external integrations
long-term storage

6. Execution Layer

Only after decision validation.

Examples:

tool invocation
system actions
external connectors
side effects

Execution is downstream from cognition.

This separation is critical.

7. Observability Layer

ARVIS can expose:

traces
commitments
timelines
inspection summaries
replay verification

Production systems need visibility.

Architecture Diagram

            ┌───────────────────┐
            │   Public API      │
            │   CognitiveOS     │
            └─────────┬─────────┘
                      ↓
            ┌───────────────────┐
            │ Runtime Layer     │
            │ Scheduling / Flow │
            └─────────┬─────────┘
                      ↓
            ┌───────────────────┐
            │ Cognitive Pipeline│
            │ Reasoning Stages  │
            └─────────┬─────────┘
                      ↓
            ┌───────────────────┐
            │ Decision Gate     │
            └─────────┬─────────┘
                allow │ deny
                      ↓
            ┌───────────────────┐
            │ IR / Result View  │
            └─────────┬─────────┘
                      ↓
            ┌───────────────────┐
            │ Execution Layer   │
            └───────────────────┘

Why This Separation Matters

Cognition ≠ Execution

Many systems let generated text trigger actions directly.

ARVIS separates:

reasoning first
action second

Output ≠ Decision

A fluent answer is not proof of validity.

ARVIS validates decisions independently of language generation.

Memory ≠ Hidden State

Context can influence decisions, but under boundaries.

Audit ≠ Logs

Replayable commitments are stronger than plain logs.

Internal Domains

ARVIS is organized into explicit domains:

Runtime

Execution control and orchestration.

Pipeline

Decision semantics.

Memory

Governed context and continuity.

Tools

Authorized external capabilities.

IR

Portable decision contract.

Reflexive Layer

Safe self-observation and introspection.

Deterministic Replay

One of ARVIS’s strongest properties.

r1 = os.run("u1", payload)
r2 = os.replay_verified(
    r1.to_ir(),
    expected_global_commitment=r1.global_commitment,
)

Expected:

same commitment
same governed result

Use cases:

incident review
compliance checks
regression testing
simulation

Memory Architecture

Memory is treated as governed input.

Not uncontrolled prompt stuffing.

Memory can provide:

preferences
prior state
historical context
policy signals

But cognition remains rule-bound.

Tool Governance

Tools are external power.

ARVIS requires explicit control over capabilities such as:

email
payments
deletion
CRM writes
infrastructure actions

Tool usage can be denied even if reasoning requests it.

Governed effect transaction

ToolAuthorizationService
  → FrozenEffectPayload + AuthorizedEffectContext
  → ToolManager (confirmation + MINTED capability)
  → SyscallHandler (current/sealed context equality)
  → IntentOutboxService (receipt)
  → activation
  → EffectDispatcher
  → exact result binding

The orchestration entrypoints remain intentionally small. Security-sensitive state stays in private registries, and the extracted services are internal rather than public API. See docs/architecture/EFFECT_PATH.md.

The tool never observes the mutable cognitive pipeline context. Its exact authorized invocation contains a frozen business payload, immutable identity and provenance material, and the durable idempotency key. Host-owned clients, credentials and repositories are injected into the tool at construction.

For production integrations such as Veramem, ARVIS owns the governed authorization/outbox/capability/proof transaction. Veramem owns authentication, tenant resolution, the PostgreSQL audit sink, persistent confirmation and idempotency coordination, business services and distributed worker semantics.

Why This Is Better Than Standard AI Stacks

Most stacks optimize for:

speed of generation

ARVIS optimizes for:

quality of decisions
safety of execution
ability to verify

Example Lifecycle

Input

{
  "action": "wire_transfer",
  "risk": 0.91
}

Pipeline evaluates - risk high - sensitive action - human approval required

Result

Denied automatic execution
Escalated for confirmation

Trace available

Yes.

Production Benefits

Enterprises

safer automation
governed copilots
auditable actions

Finance

approval gates
replayable screening
controlled execution

Agents

bounded autonomy
safer tool usage
deterministic workflows

Regulated Systems

explainability
traceability
commitments

Design Philosophy

ARVIS treats cognition like compute infrastructure.

Just as operating systems brought order to hardware chaos, ARVIS aims to bring order to AI decision chaos.

In One Sentence

ARVIS is the architecture layer that separates reasoning, decision, and execution, then governs all three.