AI Cells

AI Cells

Purpose

This page defines the AI Cell, the core resource unit in XAI OS.

Contents

• Definition
• Resource Contract
• Descriptor ABI
• Ownership Areas
• Lifecycle
• Telemetry

Definition

An AI Cell is a fixed-resource execution container for one app-local CPU-only AI agent or a tightly related group of workers.

An AI Cell is not a general process scheduler class. It is a resource contract with explicit ownership.

Resource Contract

Each AI Cell declares:

• CPU cores;
• memory arenas;
• model files and shared model-weight mappings;
• private KV/cache budget;
• NIC RX/TX queues;
• source-code index;
• build/test sandbox;
• Git workspace;
• telemetry counters;
• permissions and capabilities.

If the requested resources cannot be granted without violating another service contract, XAI OS should refuse startup.

Descriptor ABI

The QEMU AI Cell production contract uses the AIC1 version 1 descriptor ABI. This ABI is part of the QEMU release-candidate contract and must stay stable until a new descriptor version is explicitly introduced.

Descriptor fields:

• magic: AIC1 (0x41494331);
• version: 1;
• descriptor size: 112 bytes;
• cell id;
• core mask;
• model arena id;
• NIC queue id;
• Git workspace id;
• private KV/cache byte budget;
• source-index byte budget;
• build-output byte budget;
• log byte budget;
• bounded 32-byte name;
• checksum over the descriptor with the checksum field zeroed.

Required flags:

• CPU-only AI;
• fixed core ownership;
• shared model arena;
• private KV/cache;
• NIC queue ownership;
• Git workspace ownership.

Admission must reject malformed descriptors, missing required flags, missing model arenas, duplicate core leases, duplicate NIC queues, duplicate workspaces, and invalid workspace ids. Successful admission reserves memory through the PMM/VMM-backed arena path, binds the network queue, binds the workspace, and records the AI Cell lifecycle transition.

Ownership Areas

Core ownership means hot workers do not migrate by default.

Memory ownership means model arenas, KV/cache arenas, source indexes, build output, and network buffers are distinct and observable.

NIC queue ownership means app-agent traffic can stay on the intended core whenever hardware allows it.

Model-weight ownership means one physical read-only model copy can be mapped into many AI Cells while each agent keeps private KV/cache state.

Git/build/test ownership means code-changing agents work inside explicit workspaces and sandboxes.

Lifecycle

Example lifecycle:

DECLARED
  -> RESOURCES_GRANTED
  -> MODEL_MAPPED
  -> ARENAS_PREFAULTED
  -> WORKERS_PINNED
  -> READY
  -> RUNNING
  -> DRAINING
  -> STOPPED

After READY, the hot path should avoid scheduler migration, unexpected context switching, and page faults.

Manifest Example

[service]
name = "smart-app-agent"
binary = "/apps/smart-app-agent/bin/agent"

[cores]
network = "2"
inference = "3-6"
source_index = "7"
build_test = "8-11"
migration = "forbidden"

[memory]
model_arena = "shared"
kv_cache_arena = "private"
prefault = true
swap = false
post_ready_page_faults = "fail_cell"

[network]
ports = [8080]
rx_queues = "owned"
tx_queues = "owned"

[git]
repository = "/srv/apps/example"
worktree = "/srv/worktrees/example-agent"
allow_commit = true
allow_push = false
require_tests = true

Hot-Path Invariants

core_migrations = 0
involuntary_context_switches = 0
post_ready_page_faults = 0
timer_ticks_on_hot_cores = 0
interrupts_on_hot_cores = 0 unless declared

Fault Behavior

Fault handling depends on policy:

• hot-path page fault after READY: record counter, drain the cell, and fail the request unless explicitly allowed;
• invalid memory access: stop the cell and preserve crash telemetry;
• build/test failure: keep the patch in the worktree, mark it failed, do not deploy;
• Git conflict: stop before commit/push and require human or policy resolution;
• model arena fault: stop dependent cells or remap only through the control plane.

Patch, Rebuild, and Redeploy

An AI Cell may run source-index, patch, build, test, and deploy workers, but those workers should use declared cores and separate memory arenas. A successful patch flow creates a rollback point before hot reload or redeploy.

Stop and Restart

Stopping a cell drains network queues, stops hot workers, releases core leases, preserves logs and telemetry, and optionally keeps the Git worktree. Restarting requires resource validation again; no previous lease is assumed valid.

Telemetry

Minimum counters:

• core migration count;
• context switch count;
• post-warmup page fault count;
• RX/TX latency percentiles;
• model arena faults;
• memory bandwidth pressure;
• build/test resource usage;
• rollback count.

Related Pages

• Scheduler and Core Isolation
• Memory System
• Networking