Filesystem and Storage

Filesystem and Storage

Purpose

This page describes the minimal storage plan for XAI OS.

Contents

• Storage Layout
• QEMU First
• System Image
• Mutable Filesystem Slice
• App Data and Worktrees
• Rollback

Storage Layout

The initial storage plan includes:

• boot partition;
• system image;
• app data;
• repository worktrees;
• build artifacts;
• logs and telemetry;
• rollback snapshots.

Keep these domains separate:

Domain	Purpose	Isolation rule
Boot partition	UEFI loader and early kernel payload	Read-only after boot where possible
System image	Kernel, userspace, runtime services	Signed update path
Model files	CPU-only AI weights and metadata	Read-only mappings into model arenas
Source repos	Application Git repositories	Access controlled per embedded app agent
Worktrees	Agent-specific patch workspace	One worktree per agent/session
Build output	Compiler and test artifacts	Never mixed with source or model arenas
Logs	Audit, boot, test, benchmark output	Scrub secrets before persistence

QEMU First

QEMU uses VirtIO block first. The current prototype uses a versioned read-only filesystem header stored in the VirtIO test image. The header records block size, data offset, image size, entry flags, manifest index, and per-file content hashes. The kernel rejects bad metadata, duplicate paths, hash mismatches, and config manifests that point at a missing or non-executable service.

The full-OS track now also has a mutable filesystem slice in a separate VirtIO block sector range. It is intentionally separate from the read-only boot filesystem and the single-sector persistence record.

Area	Sector range	Purpose
Read-only boot filesystem	starts at sector 1	/init, /bin/service-manager, config, service descriptor
Persistence records	sector 3000	boot/service/workspace/sandbox/update snapshot records
Mutable filesystem metadata	sectors 3072-3087	checksum-protected mutable filesystem metadata
Mutable filesystem journal	sectors 3088-3089	pending transaction header and replay payload
Mutable filesystem data	starts at sector 3090	allocator-backed file blocks and rollback snapshots

Mutable Filesystem Slice

The QEMU mutable filesystem implementation provides:

• explicit read-write mount policy;
• checksum-protected metadata;
• directory records and parent path validation;
• paths under /state, /config, and /logs;
• allocator-backed data blocks instead of fixed one-sector file slots;
• multi-sector files;
• create/update/read/delete operations;
• per-file rollback snapshot sectors;
• crash-consistency journal replay for pending file writes;
• service, workspace, and update state records;
• commit and rollback self-tests;
• telemetry for mounts, formats, boot loads, files, directories, writes, reads, deletes, commits, rollbacks, replays, journal writes, allocations, frees, multi-sector files, state records, rejects, and checksum errors.

This is still a QEMU filesystem contract, not a full POSIX filesystem. Later work can add a larger persistent state area, richer directory APIs, hardware-specific storage tuning, and user-facing filesystem syscalls.

System Image

The system image should be reproducible and generated from scripts. Build artifacts belong in build/, out/, or another ignored output directory.

App Data and Worktrees

Each app agent should use explicit worktrees and build output directories. Build artifacts should not contaminate source trees.

Rollback

Snapshot and rollback are required before code-changing agents can safely modify running services.

Patch failure behavior:

• failed build/test keeps the worktree for review and does not commit;
• failed deploy rolls back to the previous known-good service image;
• Git conflict blocks commit/push until resolved;
• storage error drains the affected AI Cell and preserves logs.

Hardware Direction

NVMe is the first real storage target after VirtIO. Queue ownership and NUMA locality matter for Intel Xeon.

Related Pages

• App Agents
• Security Model
• Driver Model
• Project Tracker