Yaoshi

v0.0.1 · direct UKI|--:--:-- UTC|01 — 09

Focused TUI · Offline Debian Installer

Yaoshi

One USB-writable image. Direct /EFI/BOOT/BOOTX64.EFI boot. First visible installer frame before full discovery, engine loading, payload verification, or destructive capability

Image ≤ 2048 MiBPayload seekable zstdIntegrity BLAKE3-256 Runtime tty1 TUI

Scroll · 9 Frames

Product Contract02 — 09

01 · Required chain

Yaoshi is not a live distro. It is a bounded installation chain from workspace to Console.

WorkspaceRootrun from repository root

Build imageone reported final_image

Check imagestatic + QEMU proof

USB bootdirect first-stage UKI

First framevisible before slow work

Confirm DiskIdexact target identity

Console TUIinstalled tty1 default

Fixed platform

Debian 13 · amd64 · UEFI

Distribution, architecture, firmware, partition model, filesystem model, output image format, and StateRoot layout are product constants.

Offline runtime

No package mirror during install

The installer consumes only embedded payload metadata, streams, chunk tables, integrity tables, and the deferred engine bundle.

Evidence first

Reports, gates, artifacts

report.json, gates.json, and artifacts.json define acceptance, not raw logs or pretty text.

First Stage · No Menu03 — 09

02 · Direct boot boundary

The default path is a small FirstStageInstallerUKI, not GRUB, systemd-boot, or a boot-manager menu.

UEFI REMOVABLE PATH/EFI/BOOT/BOOTX64.EFITTY1

FIRST FRAME CRITICAL PATHInstallerUI PID 1open tty1 · draw Booting frame · flush · emit first_frame_rendered · then spawn workers

UKI≤ 24 MiBtarget ≤ 16 MiB

IRInitrd ≤ 4 MiBzstd cpio · target ≤ 2 MiB

PIDStatic InstallerUIinput · TUI · bounded readers

Forbidden in first stage

The micro runtime has no destructive or general-purpose OS surface.

The engine bundle and payload streams stay outside the UKI/initrd. Engine loading starts only after the first visible frame has been flushed.

shell NOsystemd NOudev settle NOnetwork setup NOmkfs / parted NOpayload streams NOengine bundle NOboot menu NO

Payload · Footprint04 — 09

03 · Typed payload partition

The image carries a PayloadPartition: bounded discovery metadata, deferred engine, and chunk-verified streams.

PayloadHeaderYAOSHI_PAYLOADfixed binary identity · offsets · digests

DiscoveryIndexcanonical CBORearly source/target/stream descriptors

InstallerEngineBundlezstd cpio · BLAKE3loaded after first_frame_rendered

Streamsrootfs.pax.zst · esp.pax.zstseekable zstd · independent chunks · hash tree

Tableschunk · seek · integritybounded-memory install and real verification

01discoverheader + index

02verify enginecompressed + unpacked digest

03streamchunk progress

04verify targetitemized checks

05syncsuccess after durability

Final image≤ 2048 MiBhard build/check gate

Default regression≤ 1536 MiBquality evidence

ImageESP64 MiBexact partition size

Slack≤ 16 MiBno hidden padding

Rootfs stream≤ 1536 MiBcompressed bytes

ESP stream≤ 192 MiBcompressed bytes

Engine bundle≤ 96 MiBcompressed cpio

Metadata≤ 32 MiBheader, CBOR, tables

TuiVisualSystem05 — 10

04 · Focused screens

The installer renders one dominant state at a time: focused progress first, stale dashboard never.

YAOSHI INSTALLER · installing.focused-progresstarget: nvme-eui.002538B81234 · source locked

Installing rootfs.pax.zst

Candidate disk controls have left the default view. The selected target is immutable, compact, and non-focusable.

Progress48% · chunk 312 / 655

Throughput184 MiB/s

Verificationcompressed + uncompressed digest

DiagnosticsF12 / Ctrl+L

F12 DiagnosticsCtrl+L DiagnosticsEsc Return from diagnostics

TuiVisualSystem · Lifecycle06 — 10

04B · Screen contract

Information has a lifecycle. Controls appear only in the states that can still use them.

No dashboard drift

One dominant task

Each default state renders one focused work surface with only current-state information.

Information lifecycle

Old controls leave

Candidate tables appear in ChooseTarget only; Review shows exact DiskId confirmation; install/verify show no target switching.

Visual token set

Semantic roles

Accent, Focus, Selected, Warning, Error, Source, Target, Progress, and Diagnostic roles replace ad hoc colors.

Diagnostics

Structured first

Diagnostics show event history before bounded raw excerpts; default tty1 shows no raw logs and no OS prompt.

Runtime constraints

Dense data moves into state-specific surfaces.

The default screen remains sparse; secondary evidence is available through declared diagnostics instead of a persistent dashboard column.

Accent / Focusactive operation and keyboard locus

Selected / Targetimmutable chosen disk evidence

Progress / Sourcestream identity and chunk movement

Warning / Errorblocking recovery and diagnostics

no stale controlsno hidden target switchno raw log defaultno prompt fallback

Capability Boundary06 — 09

05 · Destructive writes

The UI can select. Discovery can read. Only a verified engine with a DestructivePermit can write.

Bootingfirst frame rendered and flushed

Discoveringread-only payload source + target candidates

PreparingEngineengine bundle verified after first frame

ChooseTargetdisk table, source excluded, NVMe preferred

Reviewexact DiskId input and source/target proof

Installingpartition, format, stream extract, sync

Verifyingitemized target verification

Done/Errorpreserved diagnostics, no tty1 fallback prompt

Permit

“No writable target handle exists until the selected DiskId is entered byte-for-byte in Review.”

candidate = ReadOnlyBlock
selected = TargetCandidate
confirmation = exact DiskId match
permit = DestructivePermit
engine = ConfirmedTargetDisk + payload manifest

no write before permitno target switch during installno empty verification

Installed System07 — 09

06 · Yaoshi Console

After install, Debian boots to Yaoshi Console on tty1. Rescue and remote access stay explicit.

YAOSHI CONSOLEkernel · uptime · primary network in headertty1

CPU12%load and usage

Memory38 GiBavailable of 48 GiB

Storage41%root ext4 usage

NetworkDHCPprimary link known

F12 DiagnosticsCtrl+L DiagnosticsAlt+F2 tty2 rescue

Access boundary

Root-only local operation.

No non-root human account is created. tty1 is not a prompt; tty2 is a direct root rescue surface. SSH is disabled unless public keys are configured.

tty1Yaoshi Console TUI · no OS prompt

tty2Alt+F2 direct root rescue · no getty

SSHroot public-key only when configured

Networksystemd-networkd DHCP + resolved DNS

Commands · Evidence08 — 09

07 · Local proof

Quality, build, and check are Rust-owned. Acceptance reads the immediate build report.

init

yaoshi.toml

Creates the optional config under StateRoot; missing, empty, and generated-comment config are equivalent.

build

final_image

Builds one USB image and publishes footprint evidence before a passed report.

check IMAGE

QEMU evidence

Runs static checks, installer VM, installed-system VM, visual captures, rescue, and optional SSH validation.

accept

exact artifact

Runs quality, workspace build, Yaoshi build, reads final_image, then checks that exact path.

workspace · commandshuman stdout · JSON authority

$cargo run --locked -p yaoshi -- init
Initialized: ./.yaoshi/yaoshi.toml
$cargo run --locked -p yaoshi -- build
… direct UKI · payload manifest · engine bundle · footprint gates · emit image …
Built: ./.yaoshi/images/yaoshi-YYYYMMDD-HHMMSS.img
$cargo run --locked -p yaoshi -- check ./.yaoshi/images/yaoshi-YYYYMMDD-HHMMSS.img
… static image checks · installer VM · installed VM · screenshots · terminal captures …
Report: ./.yaoshi/runs/check/run-UTC-*/report.json
$m accept
accepted: child-runs linked · same final_image checked

StateRoot · Finale09 — 09

08 · Evidence layout

All generated state lives under ./.yaoshi/

./.yaoshi/
├── yaoshi.toml                         // only user-editable product config
├── images/
│   └── yaoshi-*.img                    // D3 final YaoshiImage
├── runs/
│   ├── build/run-UTC-*/report.json
│   ├── check/run-UTC-*/report.json
│   ├── quality/run-UTC-*/report.json
│   └── accept/run-UTC-*/child-runs.json
├── latest/                              // convenience only
├── cache/v1/                            // never acceptance evidence
├── hardware-smoke/                     // release evidence
└── lock

Yaoshi

01 — 09

direct UKI · offline TUI

Yaoshi

A budget-bounded USB image that boots directly into Yaoshi Installer, shows the first frame before slow work, installs a chunked Debian payload, then starts Yaoshi Console.

≤ 2048 MiB final imageBOOTX64.EFI direct UKIDebian 13 trixie tty1 focused TUI

Contract02 — 09

01 · Chain

One workspace. One image. One checked install path.

buildfinal_image

checkQEMU proof

USB bootdirect UKI

first framebefore slow work

DiskIdexact confirm

payloadoffline install

Consoletty1 default

hardwarerelease smoke

no online installerno default boot menuno raw target imageno tty1 prompt

First Stage03 — 09

02 · BOOTX64.EFI

Small first stage. No boot manager menu.

UEFI/EFI/BOOT/BOOTX64.EFItty1

FIRST FRAMEInstallerUI PID 1draw · flush · emit event · then spawn bounded readers

UKI≤ 24 MiBtarget ≤ 16

IRinitrd ≤ 4 MiBtarget ≤ 2

NOshell / systemdno destructive tools

Payload04 — 09

03 · Typed partition

Bounded discovery. Chunked zstd streams. BLAKE3 verification.

HeaderPayloadHeaderoffsets · sizes · digests

IndexDiscoveryIndex CBORearly source and target facts

EngineInstallerEngineBundleverified after first frame

Streamsrootfs.pax.zst · esp.pax.zstseekable independent chunks

Tableschunk · seek · hashreal streaming verification

Footprint05 — 09

04 · Hard gates

Small image by construction, not by aspiration.

Final≤2048MiB

Default≤1536MiB

ImageESP64MiB exact

Slack≤16MiB

Rootfs≤1536MiB

ESP stream≤192MiB

Engine≤96MiB

Metadata≤32MiB

TUI Focus06 — 11

05 · Focused screen

Installing has one dominant surface; target controls are gone.

INSTALLING · focused-progresssource locked

Installing rootfs.pax.zst

Target: nvme-eui.002538B81234. Candidate disk controls have left the default view.

Progress48% · chunk 312 / 655

Throughput184 MiB/s

Verificationcompressed + uncompressed digest

DiagnosticsF12 / Ctrl+L

F12 diagnosticsCtrl+L diagnosticsEsc return

TUI Lifecycle07 — 11

05B · State model

Each state owns only the information it can act on.

Bootingcollapsed

ChooseTargetomitted

Reviewconfirmed

Installingfocused

Verifyingpending

Donepending

Preferred240×56

Fallbacks160×42 · 80×25

Coloransi16 roles + mono

CharsetUnicode + ASCII

no target switchno raw log wallno OS promptno full-screen flash

TUI Rules08 — 11

05C · Visual contract

Old controls leave. Diagnostics stay structured.

No dashboard drift

One dominant task

Default state shows only current-state information.

Info lifecycle

Old controls leave

ChooseTarget owns candidates; Review owns DiskId; install/verify show no switching.

Token set

Semantic roles

Accent, Focus, Selected, Warning, Error, Source, Target, Progress, Diagnostic.

Diagnostics

Structured first

Event history precedes bounded raw excerpts; tty1 never becomes a prompt.

Install07 — 09

06 · Permit

No write handle before exact DiskId confirmation.

Discoveryread-only workers

Enginedeferred and verified

Reviewbyte-for-byte DiskId input

PermitDestructivePermit issued

Installpartition · format · stream

Verifyitemized target checks

no target switchno empty verifyno tty1 promptno hidden write

Console08 — 09

07 · Installed system

tty1 is Yaoshi Console. tty2 is rescue.

CONSOLEkernel · uptimetty1

CPU12%usage

Memory38Gavailable

Storage41%root

NetworkDHCPprimary

Alt+F2 tty2F12 diagnostics

SSHdisabled unless public keys configured

Accessroot-only local operation

Evidence09 — 09

08 · Commands

report.json is the source of truth.

workspacelocked

$cargo run --locked -p yaoshi -- init
$cargo run --locked -p yaoshi -- build
direct UKI · payload · footprint gates · final_image
$cargo run --locked -p yaoshi -- check IMAGE
static · QEMU · screenshots · terminal captures
$m accept
passed: exact build artifact checked

./.yaoshi/
├── yaoshi.toml
├── images/yaoshi-*.img
├── runs/*/report.json
├── cache/v1/
├── hardware-smoke/
└── lock