Monorepo for Aesthetic.Computer
aesthetic.computer
papers: add PDF hit tracking, update OG meta, bump vscode extension to 1.267.1
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+1463
-5
+421
reports/ac-native-boot-speed-optimization.md
+421
reports/ac-native-boot-speed-optimization.md
···
1
+
# AC Native OS Boot Speed Optimization Report
2
+
3
+
Analysis of the full boot path from kernel handoff to running JS piece, with concrete proposals for reducing the ~9-second typical boot time.
4
+
5
+
Source files analyzed:
6
+
- `fedac/native/initramfs/init`
7
+
- `fedac/native/src/ac-native.c` (main boot sequence, `try_mount_log`, `draw_startup_fade`, `draw_boot_status`, `load_boot_visual_config`)
8
+
- `fedac/native/src/audio.c` (`audio_init`)
9
+
- `fedac/native/src/wifi.c` (`wifi_init`)
10
+
- `fedac/native/src/tts.c` (`tts_init`, `tts_precache`)
11
+
- `fedac/native/src/input.c` (`input_init`)
12
+
- `fedac/native/kernel/config-minimal`
13
+
14
+
---
15
+
16
+
## 1. Current Boot Timeline
17
+
18
+
Typical boot from kernel to piece running: **~9 seconds** (when audio hardware cooperates). Measured by the `boot_start`/`boot_end` monotonic clock in `main()` (ac-native.c:1774, 2101-2105).
19
+
20
+
| Phase | Location | Duration | Blocking? | Notes |
21
+
|---|---|---|---|---|
22
+
| Kernel decompress + hw init | kernel/BIOS | ~1-2s | Yes | LZ4 initramfs, built-in driver probe |
23
+
| Init script | `initramfs/init` | ~1-2s | Yes | mounts, zram, dmesg dump (1s sleep) |
24
+
| PID 1 setup + DRI wait | ac-native.c:1778-1802 | 0-1s | Yes | Polls `/dev/dri/card0` every 10ms for 1s |
25
+
| Display init (DRM) | ac-native.c:1860 | <100ms | Yes | Opens card, finds CRTC, creates dumb buffers |
26
+
| Framebuffer + font init | ac-native.c:1883-1888 | <10ms | Yes | Software render context |
27
+
| **USB mount wait** | ac-native.c:266-273 | **0-2s** | **Yes** | Polls `/dev/sda1` every 20ms for 2s |
28
+
| Config load | ac-native.c:542-620 | <1ms | Yes | File read + JSON parse |
29
+
| **Audio init** | audio.c:616-928 | **0-18s** | **Yes** | Sound card poll + ALSA retries (see below) |
30
+
| TTS init | tts.c:125-158 | ~50ms | Yes | Flite voice registration |
31
+
| **TTS precache** | tts.c:204-222 | **~500ms-1s** | **Yes** | 41 Flite renders (a-z, 0-9, 5 keys) |
32
+
| Boot beep | audio.c:1407-1413 | ~200ms | Yes | Two-tone E5/B5 with 80ms gap |
33
+
| **Boot animation** | ac-native.c:1288-1700 | **0-5s** | **Skippable** | 300 frames at 60fps, key-skippable after 1s |
34
+
| Input init | input.c:315+ | <100ms | Yes | evdev scan + hidraw |
35
+
| **WiFi init** | wifi.c:653-758 | **0-3s** | **Yes** | Interface poll every 100ms for 3s |
36
+
| WiFi autoconnect | wifi.c (after init) | ~async | Partly | Starts connection, returns |
37
+
| JS init | js-bindings.c:1637+ | ~100-200ms | Yes | QuickJS context + API registration |
38
+
| Config re-read + piece resolve | ac-native.c:2016-2077 | <10ms | Yes | |
39
+
| Piece load + boot() | ac-native.c:2080-2144 | ~100ms | Yes | Module eval + boot() call |
40
+
| TTS wait + melody | ac-native.c:2128-2134 | **~700ms** | **Yes** | 300ms TTS drain + 400ms melody ring-out |
41
+
42
+
### Audio Init Breakdown (the big variable)
43
+
44
+
Audio initialization at `audio.c:616-928` has two stacked wait loops:
45
+
46
+
**Loop 1 -- Sound card detection** (audio.c:665-670):
47
+
- Polls for `/dev/snd/pcmC{0,1,2}D0p` every 20ms
48
+
- 400 iterations = **8 seconds max**
49
+
- On fast boots with working HDA: exits in <500ms
50
+
- On slow codec probe: hits full 8s timeout
51
+
52
+
**Loop 2 -- ALSA device open** (audio.c:722-743):
53
+
- 5 retry attempts, each trying 11 device names
54
+
- 2-second `usleep()` between retries
55
+
- **10 seconds additional worst case** (5 retries x 2s)
56
+
57
+
**Worst case total: 8s + 10s = 18 seconds for audio alone.**
58
+
59
+
Typical case (hardware ready quickly): <1s.
60
+
61
+
---
62
+
63
+
## 2. Polling vs. Event-Driven Detection
64
+
65
+
The current code uses busy-polling for all hardware detection. Every poll loop wastes CPU cycles spinning on `usleep()` and `access()` calls, and more importantly, it cannot react faster than its poll interval.
66
+
67
+
### 2.1 Current Polling Inventory
68
+
69
+
| Subsystem | File | What it polls | Interval | Max wait | Location |
70
+
|---|---|---|---|---|---|
71
+
| Sound card | audio.c | `/dev/snd/pcmC*D0p` | 20ms | 8s | Line 665-670 |
72
+
| USB block device | ac-native.c | `/dev/sda1`, `/dev/sdb1` | 20ms | 2s | Line 270-273 |
73
+
| WiFi interface | wifi.c | `detect_iface()` via sysfs | 100ms | 3s | Line 736-743 |
74
+
| DRI device | ac-native.c | `/dev/dri/card0`, `/dev/fb0` | 10ms | 1s | Line 246 (PID 1 path) |
75
+
76
+
### 2.2 Proposed Alternatives
77
+
78
+
**inotify on `/dev/snd/`** (for audio card detection):
79
+
- Create an `inotify` watch on `/dev/snd/` with `IN_CREATE` mask.
80
+
- Block on `read()` with a timeout (via `poll()` or `select()` with 8s timeout).
81
+
- When a `pcmC*D0p` node appears, immediately break out.
82
+
- Reacts within milliseconds of device node creation instead of up to 20ms poll granularity.
83
+
- Implementation: ~30 lines of C replacing the 6-line poll loop.
84
+
85
+
```c
86
+
// Pseudocode
87
+
int ifd = inotify_init1(IN_NONBLOCK);
88
+
inotify_add_watch(ifd, "/dev/snd", IN_CREATE);
89
+
struct pollfd pfd = { .fd = ifd, .events = POLLIN };
90
+
while (!card_found) {
91
+
// Check if already present
92
+
if (access("/dev/snd/pcmC0D0p", F_OK) == 0) { card_found = 1; break; }
93
+
int ret = poll(&pfd, 1, 8000); // 8s timeout
94
+
if (ret > 0) { /* read events, check name */ }
95
+
else break; // timeout
96
+
}
97
+
close(ifd);
98
+
```
99
+
100
+
**inotify on `/dev/` for USB block devices**:
101
+
- Same pattern as above, watching `/dev/` for `IN_CREATE` events matching `sd[a-d]1`.
102
+
- Replaces the 2s poll in `try_mount_log()`.
103
+
104
+
**Netlink socket for WiFi interface detection**:
105
+
- Open a `NETLINK_ROUTE` socket, subscribe to `RTNLGRP_LINK` group.
106
+
- Listen for `RTM_NEWLINK` messages with `ifi_flags` containing `IFF_UP`.
107
+
- Eliminates the 3s poll loop in `wifi_init()` and reacts to interface creation instantly.
108
+
- More complex (~80 lines) but the canonical Linux approach. Already used by NetworkManager, iwd, etc.
109
+
110
+
**Why not udev?**
111
+
- AC Native OS runs no udevd (no service manager at all). Starting udevd would add its own startup cost.
112
+
- A minimal `libudev` monitor is possible without udevd (it reads the same netlink/inotify events), but adds a library dependency.
113
+
- The inotify/netlink approaches above are lower-level but dependency-free, which matches the system's philosophy.
114
+
115
+
---
116
+
117
+
## 3. Parallelization Opportunities
118
+
119
+
Currently, every boot phase in `main()` is fully sequential. The execution order is:
120
+
121
+
```
122
+
try_mount_log() -> load_boot_visual_config() -> audio_init() -> tts_init() ->
123
+
tts_precache() -> boot_beep -> draw_startup_fade() [5s animation] ->
124
+
input_init() -> wifi_init() -> wifi_autoconnect() -> js_init() -> piece load
125
+
```
126
+
127
+
Several of these have no data dependencies on each other.
128
+
129
+
### 3.1 Dependency Graph
130
+
131
+
```
132
+
display_init
133
+
|
134
+
framebuffer + font
135
+
|
136
+
+----------+----------+
137
+
| | |
138
+
try_mount_log (parallel) (parallel)
139
+
|
140
+
load_config
141
+
|
142
+
+---------+---------+
143
+
| | |
144
+
audio_init wifi_init input_init <-- all independent of each other
145
+
|
146
+
tts_init
147
+
|
148
+
tts_precache
149
+
|
150
+
boot_animation <-- needs: display, audio (for beep), tts (for greeting)
151
+
|
152
+
js_init <-- needs: graph, input, audio, wifi, tts
153
+
|
154
+
piece_load
155
+
```
156
+
157
+
### 3.2 Concrete Parallelization Plan
158
+
159
+
**Phase A: Start audio + wifi + input concurrently**
160
+
161
+
These three subsystems have zero shared state during init:
162
+
- `audio_init()` touches ALSA devices only
163
+
- `wifi_init()` touches wireless sysfs/netlink only
164
+
- `input_init()` touches evdev/hidraw only
165
+
166
+
Spawn threads for audio and wifi, run input on the main thread (it is fast):
167
+
168
+
```c
169
+
pthread_t audio_thread, wifi_thread;
170
+
pthread_create(&audio_thread, NULL, audio_init_threaded, NULL);
171
+
if (!wifi_disabled) pthread_create(&wifi_thread, NULL, wifi_init_threaded, NULL);
172
+
input = input_init(display->width, display->height, pixel_scale);
173
+
pthread_join(&audio_thread, (void**)&audio);
174
+
if (!wifi_disabled) pthread_join(&wifi_thread, (void**)&wifi);
175
+
```
176
+
177
+
**Estimated savings: 2-3 seconds typical** (wifi 3s wait runs during audio 8s wait instead of after).
178
+
179
+
**Phase B: Overlap boot animation with hardware waits**
180
+
181
+
The boot animation (`draw_startup_fade`, 5 seconds) is currently run *after* audio/TTS init. But the animation only needs:
182
+
- Display (already initialized)
183
+
- Audio (for boot beep at start, TTS greeting at frame 10)
184
+
185
+
Strategy: start the animation immediately after display init. Audio can still be initializing in a background thread. The boot beep and TTS greeting are delayed until audio is ready (a simple flag check per frame).
186
+
187
+
```c
188
+
// Start audio init in background
189
+
pthread_create(&audio_thread, NULL, audio_init_threaded, NULL);
190
+
// Start animation immediately
191
+
// Inside animation loop: if (audio_ready && !beep_played) { audio_boot_beep(); beep_played=1; }
192
+
```
193
+
194
+
**Estimated savings: up to 5 seconds** -- the animation runs *during* audio init instead of after, and the 5s animation cost is fully overlapped.
195
+
196
+
**Phase C: Defer TTS precache to after piece starts**
197
+
198
+
`tts_precache()` renders 41 utterances (~500ms-1s). This only matters when the user starts typing, which happens well after boot. Defer it to a background thread launched after `js_call_boot()`.
199
+
200
+
```c
201
+
js_call_boot(rt);
202
+
// Precache TTS in background -- user won't type for several seconds
203
+
pthread_create(&tts_precache_thread, NULL, (void*)tts_precache, tts);
204
+
```
205
+
206
+
**Estimated savings: ~500ms-1s.**
207
+
208
+
**Phase D: Move JS init earlier**
209
+
210
+
`js_init()` has no dependency on wifi or input -- it only needs the `ACGraph` pointer (and NULL is acceptable for input/audio/wifi, which can be set after). The QuickJS runtime creation and API registration could be done in parallel with hardware waits.
211
+
212
+
However, `js_init()` currently takes the pointers at creation time. Refactoring to allow late-binding of subsystem pointers would require changes to `js-bindings.c`. Lower priority.
213
+
214
+
---
215
+
216
+
## 4. Specific Optimizations
217
+
218
+
### Optimization 1: Replace audio polling with inotify
219
+
220
+
**Current cost:** Up to 8s polling at 20ms intervals (400 iterations).
221
+
**Proposed:** inotify watch on `/dev/snd/` with `IN_CREATE`, blocking `poll()` with 8s timeout.
222
+
**Expected savings:** Reacts within ~1ms of device node creation instead of up to 20ms. On fast boots where the card appears at 200ms, saves no time. On slow boots where it appears at 7.5s, saves ~20ms max. The real win is cleaner code and less CPU wake-up churn.
223
+
**Risk:** Low. inotify is a stable Linux API (since 2.6.13). Fallback: if inotify_init fails, fall back to current poll loop.
224
+
**Estimated time savings:** 0-20ms typical (marginal), but enables Phase B parallelization cleanly.
225
+
226
+
### Optimization 2: Smarter ALSA retry strategy
227
+
228
+
**Current cost:** 5 retries x 2s sleep = up to 10s additional on top of 8s card wait.
229
+
**Problem:** The 2s sleep between retries is a fixed delay. If the codec probes 100ms after the last attempt, we waste 1.9s.
230
+
231
+
**Proposed approach -- inotify + exponential backoff:**
232
+
1. After the card wait loop finds a PCM device node, do NOT sleep-retry on `snd_pcm_open()` failure.
233
+
2. Instead, use inotify on `/dev/snd/` to detect NEW device nodes appearing (codec re-probe creates additional nodes).
234
+
3. When a new node appears, immediately retry all devices.
235
+
4. If no new nodes appear within 500ms, try again with exponential backoff: 200ms, 400ms, 800ms, 1600ms (4 retries, 3s total instead of 10s).
236
+
237
+
**Alternative -- probe via sysfs:**
238
+
Before trying `snd_pcm_open()`, check `/proc/asound/card0/codec#0` for a `Codec:` line. If present, the codec is probed. If not, wait for it via inotify on `/proc/asound/card0/`.
239
+
240
+
**Estimated time savings:** 0-7s on pathological hardware. Reduces worst-case audio init from 18s to ~11s (8s card wait + 3s smarter retry).
241
+
**Risk:** Medium. ALSA timing edge cases vary by hardware. Must keep the fallback timeout.
242
+
243
+
### Optimization 3: Parallelize audio + wifi + boot animation
244
+
245
+
**Current cost:** Sequential: audio (0-18s) + animation (5s) + wifi (3s) = up to 26s serial.
246
+
**Proposed:** Run audio_init and wifi_init in background threads while the boot animation plays on the main thread. See Section 3.2, Phases A and B.
247
+
248
+
**Estimated time savings:** 3-8s typical.
249
+
- WiFi 3s overlapped with audio: saves 3s.
250
+
- Animation 5s overlapped with audio: saves up to 5s.
251
+
- Total overlap with audio: audio takes 0-18s, animation+wifi take 5-8s. If audio finishes in <5s (typical), the animation is the gating factor. If audio takes >5s (rare), audio is the gating factor but we saved the animation's 5s by running it concurrently.
252
+
253
+
**Risk:** Medium. `audio_init()` writes to `audio->pcm`, `audio->audio_status`, etc. The boot animation currently reads `audio` only for `audio_boot_beep()` and TTS. These calls would need to be guarded with an `audio_ready` flag or atomic. `wifi_init()` is already self-contained (returns an opaque struct) and safe to thread.
254
+
255
+
### Optimization 4: Defer TTS precache
256
+
257
+
**Current cost:** ~500ms-1s blocking on main thread before animation starts.
258
+
**Proposed:** Move `tts_precache()` to a background thread launched after `js_call_boot()`.
259
+
**Estimated time savings:** 500ms-1s.
260
+
**Risk:** Low. The only consumer of cached TTS is `tts_speak_cached()`, called on keypress. If a keypress arrives before precache finishes, the cache entry will be NULL and `tts_speak_cached()` already handles this (falls back to nothing). Could add a fallback to `tts_speak()` (live render) for uncached entries during the precache window.
261
+
262
+
### Optimization 5: Eliminate init script dmesg dump sleep
263
+
264
+
**Current cost:** 1 second (`sleep 1` at init:69).
265
+
**Problem:** The init script does `cat /dev/kmsg > /mnt/dmesg.log &` then `sleep 1; kill $PID`. This is a debugging aid that costs 1 second on every boot.
266
+
**Proposed:** Two options:
267
+
1. Remove entirely and rely on ac-native's USB log (which already captures kernel messages).
268
+
2. Replace with a bounded read: `timeout 0.2 cat /dev/kmsg > /mnt/dmesg.log 2>/dev/null` (busybox `timeout` if available, or just skip).
269
+
3. Move to background: let ac-native copy `/dev/kmsg` to USB asynchronously after boot completes.
270
+
271
+
**Estimated time savings:** 1s.
272
+
**Risk:** Low. Loss of kernel boot log on USB is acceptable since ac-native logs diagnostic info anyway.
273
+
274
+
### Optimization 6: Reduce boot animation to 3 seconds
275
+
276
+
**Current cost:** 300 frames at 60fps = 5 seconds.
277
+
**Observation:** The animation was designed for 3s (`180 frames` in the comment at line 1381) but was extended to 5s (`total_frames = 300` at line 1384) to accommodate TTS greeting. If TTS greeting runs in a background thread (it already does -- `tts_speak` is async), and we overlap the animation with hardware init (Optimization 3), the extra 2s are unnecessary padding.
278
+
**Proposed:** Reduce `total_frames` back to 180 (3 seconds). Or better: make the animation end when all hardware init threads join, with a 3s minimum.
279
+
**Estimated time savings:** 0-2s (only saves time when animation is the gating factor).
280
+
**Risk:** Low. TTS greeting may get cut short if it exceeds 3s, but the melody at the end serves as the "ready" signal anyway.
281
+
282
+
### Optimization 7: Kernel config -- skip unnecessary subsystem probes
283
+
284
+
**Current state:** All audio (HDA, SOF) and WiFi (iwlwifi) drivers are built-in (`=y`), not modules. This means they probe at kernel boot time, which is correct for fast startup -- no `modprobe` overhead.
285
+
286
+
**Potential wins:**
287
+
- `CONFIG_SND_HDA_CODEC_HDMI` is already disabled, good.
288
+
- Ensure only needed HDA codecs are enabled. Currently only `CONFIG_SND_HDA_CODEC_REALTEK=y` and `CONFIG_SND_HDA_GENERIC=y`. This is already well-tuned.
289
+
- Consider disabling `CONFIG_SND_PROC_FS=y` and `CONFIG_SND_VERBOSE_PROCFS=y` -- saves a few ms of procfs setup. But useful for debugging; probably not worth it.
290
+
- `CONFIG_SND_CTL_LED=y` can be disabled if no LED indicators are needed -- tiny savings.
291
+
292
+
**Estimated time savings:** <100ms. The kernel config is already lean for the target hardware.
293
+
**Risk:** Very low for cosmetic changes. Disabling needed codecs would break audio.
294
+
295
+
### Optimization 8: Initramfs compression -- uncompressed for NVMe
296
+
297
+
**Current state:** LZ4 compression (`CONFIG_INITRAMFS_COMPRESSION_LZ4=y`).
298
+
**Analysis:** LZ4 is already the fastest decompression option Linux supports. On NVMe (>3 GB/s read), decompression CPU cost may actually exceed the I/O savings from smaller size. However:
299
+
- The initramfs contains firmware blobs, the ac-native binary, Flite voice data, pieces, and shared libraries -- likely 50-150MB uncompressed.
300
+
- LZ4 decompresses at ~4 GB/s on modern CPUs, so a 100MB initramfs decompresses in ~25ms.
301
+
- Uncompressed would save those 25ms but increase read time from NVMe by ~20ms (assuming 2:1 compression ratio, 50MB extra at 3 GB/s).
302
+
- Net difference: essentially zero.
303
+
304
+
For USB boot (USB 3.0 at ~400 MB/s), LZ4 is clearly better -- the smaller size saves more I/O time than the decompression costs.
305
+
306
+
**Estimated time savings:** ~0ms (LZ4 is already optimal).
307
+
**Risk:** Switching to uncompressed increases kernel image size, which matters for EFI partition space and OTA upload time.
308
+
309
+
### Optimization 9: Eliminate post-boot delays
310
+
311
+
**Current cost:** After piece loads, there are explicit waits:
312
+
- `usleep(300000)` -- 300ms TTS ring buffer drain (ac-native.c:2131)
313
+
- `usleep(400000)` -- 400ms melody ring-out (ac-native.c:2134)
314
+
315
+
**Proposed:** The ring buffer drain and melody can continue playing after `js_call_boot()`. The audio thread is independent. Move `js_call_boot()` before the melody/drain wait:
316
+
317
+
```c
318
+
// Current:
319
+
tts_wait(); usleep(300000);
320
+
audio_ready_melody(); usleep(400000);
321
+
audio_prewarm();
322
+
js_call_boot();
323
+
324
+
// Proposed:
325
+
audio_prewarm();
326
+
js_call_boot(); // piece starts running immediately
327
+
tts_wait(); // TTS finishes in background (audio thread handles playback)
328
+
audio_ready_melody(); // plays over the already-running piece
329
+
```
330
+
331
+
**Estimated time savings:** 700ms.
332
+
**Risk:** Low. The piece's first `paint()` frame will render while the melody is still playing, which is fine -- it creates a seamless transition. The `audio_prewarm()` must happen before boot to avoid first-note latency, but it is nearly instant (50ms at 0.001 volume).
333
+
334
+
### Optimization 10: USB mount -- skip poll when block device already exists
335
+
336
+
**Current cost:** `try_mount_log()` always waits up to 2s, even when booted from NVMe where `/dev/sda1` may never appear.
337
+
**Proposed:** Check once. If no USB block device exists and we detect NVMe (`/dev/nvme0n1p1`), skip the 2s wait and go directly to NVMe mount.
338
+
339
+
```c
340
+
// Quick check -- is a block device already present?
341
+
int found_quick = (access("/dev/sda1", F_OK) == 0 || access("/dev/sdb1", F_OK) == 0);
342
+
if (!found_quick && access("/dev/nvme0n1p1", F_OK) == 0) {
343
+
// NVMe boot, USB probably won't appear. Mount NVMe ESP directly.
344
+
goto mount_phase;
345
+
}
346
+
// Only poll if nothing found and no NVMe fallback
347
+
for (int w = 0; w < 100; w++) { ... }
348
+
```
349
+
350
+
**Estimated time savings:** 0-2s (saves the full 2s on NVMe-installed boots where no USB is plugged in).
351
+
**Risk:** Low. If a USB drive is being slow to enumerate on an NVMe system, we miss it -- but we still mount NVMe ESP for config.json, which is the critical need.
352
+
353
+
---
354
+
355
+
## 5. Combined Impact Estimate
356
+
357
+
| Optimization | Time Saved (typical) | Time Saved (worst case) | Risk |
358
+
|---|---|---|---|
359
+
| 1. inotify for audio detection | ~0ms | ~20ms | Low |
360
+
| 2. Smarter ALSA retry | ~0ms | ~7s | Medium |
361
+
| 3. Parallel audio + wifi + animation | **3-5s** | **8s** | Medium |
362
+
| 4. Defer TTS precache | **500ms-1s** | **1s** | Low |
363
+
| 5. Eliminate init dmesg sleep | **1s** | **1s** | Low |
364
+
| 6. Shorter boot animation | **0-2s** | **2s** | Low |
365
+
| 7. Kernel config tuning | <100ms | <100ms | Very low |
366
+
| 8. Initramfs compression | ~0ms | ~0ms | N/A |
367
+
| 9. Eliminate post-boot delays | **700ms** | **700ms** | Low |
368
+
| 10. Skip USB poll on NVMe | **0-2s** | **2s** | Low |
369
+
370
+
### Projected Boot Times
371
+
372
+
**Current typical:** ~9s (kernel to piece running)
373
+
374
+
**After low-risk optimizations (4, 5, 6, 9, 10):**
375
+
- Savings: ~1s (init dmesg) + ~700ms (post-boot delays) + ~750ms (TTS precache) + ~1s (shorter animation, NVMe skip) = **~3.5s**
376
+
- **Projected: ~5.5s**
377
+
378
+
**After all optimizations including parallelization (1-10):**
379
+
- Audio, WiFi, and animation all run concurrently. The gating factor becomes `max(audio_init, 3s_animation)`.
380
+
- Typical audio init: <1s. Animation: 3s. WiFi: overlapped.
381
+
- **Projected: ~3-4s** (kernel to piece running)
382
+
383
+
**Worst-case (bad audio hardware):**
384
+
- Current: ~27s (18s audio + 5s animation + 3s wifi + 1s init)
385
+
- After: ~13s (11s audio with smarter retry, overlapped with everything else)
386
+
387
+
---
388
+
389
+
## 6. Implementation Priority
390
+
391
+
Recommended implementation order, balancing impact vs. effort:
392
+
393
+
1. **Eliminate init dmesg sleep** (5 min, saves 1s) -- change `sleep 1` to `sleep 0.1` or remove entirely
394
+
2. **Eliminate post-boot delays** (10 min, saves 700ms) -- reorder `js_call_boot()` before melody
395
+
3. **Defer TTS precache** (15 min, saves ~750ms) -- spawn background thread after boot
396
+
4. **Skip USB poll on NVMe** (20 min, saves 0-2s) -- quick-check before poll loop
397
+
5. **Shorten animation to 3s** (5 min, saves 0-2s) -- change `total_frames = 300` to `180`
398
+
6. **Parallel audio + wifi init** (2 hours, saves 3-5s) -- thread spawning + ready flags
399
+
7. **Overlap animation with audio init** (4 hours, saves additional 0-3s) -- requires animation to handle audio-not-ready state
400
+
8. **inotify for device detection** (2 hours, saves marginal) -- cleaner code, enables further async work
401
+
9. **Smarter ALSA retry** (3 hours, saves 0-7s worst case) -- inotify + exponential backoff
402
+
403
+
Items 1-5 are low-risk, high-value, and can be done independently in an afternoon. Items 6-9 require more careful testing across hardware variants.
404
+
405
+
---
406
+
407
+
## 7. Risk Assessment Summary
408
+
409
+
| Risk Level | Optimizations | Gotchas |
410
+
|---|---|---|
411
+
| **Very Low** | 7 (kernel config), 8 (compression) | Negligible impact; don't bother unless chasing <100ms |
412
+
| **Low** | 4 (defer TTS), 5 (init sleep), 6 (shorter anim), 9 (post-boot delays), 10 (NVMe skip) | TTS precache race: keypress before cache ready (already handled by NULL check). NVMe skip: misses slow USB enumeration (acceptable). |
413
+
| **Medium** | 1 (inotify audio), 2 (smarter retry), 3 (parallel init), overlap animation | Thread safety: `audio_init()` return value must be visible to main thread (use `pthread_join` or atomic flag). WiFi thread must not conflict with audio's sysfs reads. Boot animation must handle `audio == NULL` during early frames. ALSA retry timing: some codecs need the full 2s between probes; shorter retry could miss a working window. |
414
+
| **High** | Removing the 8s card wait entirely | Some hardware genuinely takes 5-7s for HDA codec probe. Removing the timeout would break those machines. Always keep a generous maximum. |
415
+
416
+
### Hardware-Specific Concerns
417
+
418
+
- **ThinkPad HDA codecs** (Realtek ALC257): Known to have variable probe times. The 5-retry ALSA loop was added specifically for machines where the codec appears in `/dev/snd/` but `snd_pcm_open()` fails for another 2-4 seconds.
419
+
- **SOF audio** (Intel Sound Open Firmware): Not currently targeted but present in firmware bundles. If future hardware needs SOF, its probe time is typically longer (3-5s for DSP firmware load).
420
+
- **USB audio**: If an external USB audio device is the primary output, the 8s wait for PCM nodes may be insufficient (USB enumeration + audio class driver). This is an edge case.
421
+
- **NVMe vs. USB boot**: NVMe boots are faster for everything except situations where config.json is on USB. The USB poll skip (Optimization 10) must not break USB-only boots.
+521
reports/ac-native-init-analysis.md
+521
reports/ac-native-init-analysis.md
···
1
+
# AC Native OS — Initialization Analysis
2
+
3
+
Internal technical analysis of the full boot path from EFI firmware to running JS piece.
4
+
5
+
Source files analyzed:
6
+
- `fedac/native/initramfs/init` (81 lines)
7
+
- `fedac/native/src/ac-native.c` (~2300+ lines, focus on `main()` and boot functions)
8
+
- `fedac/native/src/audio.c` (1497 lines)
9
+
- `fedac/native/scripts/build-and-flash.sh` (956 lines)
10
+
- `fedac/native/ac-os` (build orchestrator)
11
+
- `fedac/native/Makefile`
12
+
13
+
---
14
+
15
+
## 1. EFI Boot
16
+
17
+
The system boots via UEFI from a GPT-partitioned drive with a single EFI System Partition (ESP), FAT32-formatted, labeled `AC-NATIVE`.
18
+
19
+
**Partition layout** (build-and-flash.sh:876-879):
20
+
```
21
+
label: gpt
22
+
type=C12A7328-F81F-11D2-BA4B-00A0C93EC93B, size=512M
23
+
```
24
+
25
+
**Boot chain**: The kernel (`vmlinuz`) is a standard Linux bzImage with the initramfs CPIO archive (LZ4-compressed) embedded directly via `CONFIG_INITRAMFS_SOURCE`. This means the kernel and initramfs are a single file.
26
+
27
+
Two boot layouts are supported:
28
+
1. **Direct EFI stub** — `EFI/BOOT/BOOTX64.EFI` is the kernel itself (default for USB flash).
29
+
2. **Splash chainloader** — If `fedac/native/bootloader/splash.efi` exists, it is placed at `BOOTX64.EFI` and the kernel goes to `EFI/BOOT/KERNEL.EFI`. The splash EFI displays a logo while the kernel loads (build-and-flash.sh:900-908).
30
+
3. **systemd-boot layout** — Detected during install-to-disk: kernel at `EFI/Linux/vmlinuz-ac-native` with separate loader configs.
31
+
32
+
The kernel version defaults to 6.14.2 (build-and-flash.sh:36). It is compiled with Intel WiFi firmware (`iwlwifi-*`) built in via `CONFIG_EXTRA_FIRMWARE`, i915 GPU drivers, HDA audio, and all necessary subsystems for the target ThinkPad-class hardware.
33
+
34
+
---
35
+
36
+
## 2. Init Script (`/init` — PID 1)
37
+
38
+
The init script is a minimal POSIX shell script (`#!/bin/sh`) that runs as PID 1 inside the initramfs. It never uses systemd, udev, or any service manager.
39
+
40
+
### Filesystem Mounts (lines 4-13)
41
+
42
+
Mounts are performed in order with error suppression:
43
+
44
+
| Mount Point | Type | Notes |
45
+
|---|---|---|
46
+
| `/proc` | proc | |
47
+
| `/sys` | sysfs | |
48
+
| `/dev` | devtmpfs | Kernel-populated device nodes |
49
+
| `/dev/pts` | devpts | PTY support (ptmxmode=0666) |
50
+
| `/dev/shm` | tmpfs | Shared memory |
51
+
| `/tmp` | tmpfs | Temporary storage |
52
+
| `/run` | tmpfs | Runtime data |
53
+
| `/sys/kernel/tracing` | tracefs | Performance tracing |
54
+
| `/sys/kernel/debug` | debugfs | Debug interfaces |
55
+
56
+
### Credential Restoration (lines 15-34)
57
+
58
+
The build system bakes Claude Code credentials into the initramfs at `/claude-creds.json` and `/claude-state.json`. Because `/tmp` is mounted as tmpfs (hiding the initramfs's own `/tmp`), the init script copies these from the initramfs root:
59
+
60
+
- `/claude-creds.json` -> `/tmp/.claude/.credentials.json`
61
+
- `/claude-state.json` -> `/tmp/.claude.json`
62
+
- Seeds `/tmp/.claude/settings.json` with default permissions (all tools allowed, `installMethod: "native"`, auto-updates off)
63
+
- Copies `/device-claude.md` -> `/tmp/ac/CLAUDE.md` (working dir for Claude Code sessions)
64
+
65
+
### Logging (line 37)
66
+
67
+
An `ilog()` function writes to `/tmp/ac-init.log` (tmpfs). This log is later copied to USB by `ac-native`'s `try_mount_log()` for post-mortem debugging.
68
+
69
+
### zram Swap (line 42)
70
+
71
+
Creates 1GB compressed RAM swap via zram:
72
+
```
73
+
modprobe zram && echo 1G > /sys/block/zram0/disksize && mkswap /dev/zram0 && swapon /dev/zram0
74
+
```
75
+
76
+
This effectively doubles usable memory for Firefox/GTK browser sessions.
77
+
78
+
### Networking (line 45)
79
+
80
+
Brings up loopback interface (`ip link set lo up`) for localhost connections (needed for Claude OAuth callback server).
81
+
82
+
### Environment (lines 47-51)
83
+
84
+
Sets `PATH`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `SSL_CERT_DIR` for curl/OpenSSL trust in the initramfs environment.
85
+
86
+
### System Setup (lines 53-59)
87
+
88
+
- Creates minimal `/etc/group` and `/etc/passwd` (root only) for seatd compatibility.
89
+
- Sets all CPU cores to `performance` governor.
90
+
91
+
### Kernel Log Dump (lines 62-77)
92
+
93
+
Before launching ac-native, the init script attempts to dump kernel boot logs to USB for debugging:
94
+
- Scans `/dev/sda1`, `/dev/sdb1`, `/dev/sdc1` for block devices
95
+
- Mounts the first available one at `/mnt`
96
+
- Reads `/dev/kmsg` (non-blocking, 1-second read window) and writes to `/mnt/dmesg.log`
97
+
- Copies `/tmp/ac-init.log` to `/mnt/init.log`
98
+
99
+
### Exec (line 80)
100
+
101
+
```sh
102
+
exec /ac-native /piece.mjs
103
+
```
104
+
105
+
The init script replaces itself with the ac-native binary (PID 1 preserved). The default piece is `/piece.mjs` (baked into initramfs at build time, defaults to `prompt.mjs`).
106
+
107
+
---
108
+
109
+
## 3. ac-native Main Boot Sequence
110
+
111
+
The `main()` function begins at line 1773 of `ac-native.c`. The binary records a monotonic clock timestamp at entry (`boot_start`) and reports total boot time at the end.
112
+
113
+
### 3.1 PID 1 Detection and Filesystem Setup (lines 1777-1802)
114
+
115
+
Two code paths based on PID:
116
+
117
+
**PID 1 (direct DRM boot — no cage):**
118
+
- Calls `mount_minimal_fs()` (line 217) which mounts proc, sysfs, devtmpfs, devpts, shm
119
+
- Creates 1GB zram swap (again — safe if already done by init, skips silently)
120
+
- Brings up loopback
121
+
- **Waits up to 1 second** for `/dev/dri/card0` or `/dev/fb0` to appear (line 246, 100 iterations x 10ms)
122
+
- Sets all CPUs to performance governor
123
+
124
+
**Non-PID-1 (under cage compositor):**
125
+
- Filesystems already mounted by init/parent
126
+
- Opens `cage-child.log` on USB or falls back to tmpfs
127
+
128
+
Both paths set `PATH` and SSL environment variables.
129
+
130
+
### 3.2 Signal Handling (lines 1804-1814)
131
+
132
+
- `SIGINT`, `SIGTERM` -> graceful shutdown (`running = 0`)
133
+
- `SIGUSR1` -> DRM master release (for browser handoff)
134
+
- `SIGUSR2` -> reboot request
135
+
- `SIGSEGV`, `SIGBUS`, `SIGABRT`, `SIGFPE` -> crash report to `/mnt/crash.json` with machine ID and timestamp, then re-raise
136
+
137
+
### 3.3 Display Initialization (lines 1834-1880)
138
+
139
+
Two display backends, selected at runtime:
140
+
141
+
**Wayland path** (when `WAYLAND_DISPLAY` env var is set — running under cage):
142
+
- Calls `wayland_display_init()` which connects to the cage compositor
143
+
- Creates a minimal `ACDisplay` struct with width/height from Wayland surface
144
+
- On failure: exits with code 1 (cage will restart or fall through to DRM)
145
+
146
+
**DRM path** (direct framebuffer — default for PID 1 boot):
147
+
- Calls `drm_init()` which opens `/dev/dri/card0`, finds a connected CRTC, and sets up double-buffered dumb buffers
148
+
- Fatal if no display found — powers off after 5 seconds if PID 1
149
+
150
+
**Framebuffer creation** (line 1869):
151
+
- Software framebuffer at 1/3 display resolution: `fb_create(display->width / 3, display->height / 3)`
152
+
- Default `pixel_scale = 3` (3x nearest-neighbor upscale on present)
153
+
154
+
### 3.4 Graphics and Font Init (lines 1883-1888)
155
+
156
+
- `graph_init()` — software rendering context bound to framebuffer
157
+
- `font_init()` — loads built-in bitmap font
158
+
- Creates separate cursor overlay framebuffer (prevents KidLisp effects from smearing cursor)
159
+
160
+
### 3.5 USB/Disk Mount and Log Setup (line 1894)
161
+
162
+
`try_mount_log()` (defined at line 266):
163
+
164
+
1. **Waits up to 2 seconds** for USB block devices (`/dev/sda1`, `/dev/sdb1`) to appear (100 iterations x 20ms)
165
+
2. **Two-pass mount strategy:**
166
+
- Pass 0: Try removable devices first (USB install source)
167
+
- Pass 1: Fall back to internal ESP (for disk-installed boots)
168
+
3. Scans: `sda1, sdb1, sdc1, sdd1, nvme0n1p1, nvme1n1p1`
169
+
4. Mounts as VFAT at `/mnt`
170
+
5. Opens `/mnt/ac-native.log` in append mode
171
+
6. Dumps init log (`/tmp/ac-init.log`) and cage stderr to `/mnt/init.log`
172
+
7. Logs all available block devices with removable status
173
+
174
+
### 3.6 Config Loading (line 1897)
175
+
176
+
`load_boot_visual_config()` (defined at line 542):
177
+
178
+
Reads `/mnt/config.json` (USB/HD) or falls back to `/default-config.json` (baked in initramfs).
179
+
180
+
Extracts:
181
+
- **`handle`** — sets `AC_HANDLE` env var, generates time-of-day greeting as boot title (e.g., "good morning @jeffrey")
182
+
- **`colors`** — per-character RGB colors for the boot title text, from the `handle-colors` API
183
+
- **`wifi`** — boolean, defaults to true; when false, sets `wifi_disabled = 1`
184
+
- **`claudeCreds`** — JSON object written to `/tmp/.claude/.credentials.json`
185
+
- **`claudeState`** — JSON object written to `/tmp/.claude.json`
186
+
- **`voice`** — "off" disables keystroke TTS
187
+
188
+
The config supports an `AC_IDENTITY_BLOCK_V1` header line (used by `ac-usb` flash tool).
189
+
190
+
### 3.7 Audio Init (line 1900)
191
+
192
+
`audio_init()` (defined at audio.c:616):
193
+
194
+
This is the most timing-sensitive subsystem. The function:
195
+
196
+
1. **Allocates state** — `ACAudio` struct with defaults: BPM 120, sample rate 192kHz (default target), reverb buffers, 10-second sample buffer at 48kHz, TTS ring buffer (5 seconds at output rate).
197
+
198
+
2. **Seeds default sample** — Generates a 550ms synthesized one-shot (240Hz with wobble and exponential decay) so sample-mode is playable before first mic recording (audio.c:587-614).
199
+
200
+
3. **Waits for sound card** — Polls for `/dev/snd/pcmC{0,1,2}D0p` for up to **8 seconds** (400 iterations x 20ms) at audio.c:665-670. This is the critical wait for HDA codec probe completion.
201
+
202
+
4. **Diagnostics** — On timeout, distinguishes between:
203
+
- HDA controller present but codec not probed (`/dev/snd/controlC0` exists but no PCM device)
204
+
- No hardware at all
205
+
Dumps `/proc/asound/cards` and `/dev/snd/` contents to `/mnt/ac-audio.log`.
206
+
207
+
5. **ALSA device open** — Tries 11 device names with **5 retry attempts** (2-second sleep between retries, audio.c:722-743):
208
+
```
209
+
hw:0,0 hw:1,0 hw:0,1 hw:1,1 hw:0,2 hw:0,3 hw:1,2 hw:1,3
210
+
plughw:0,0 plughw:1,0 default
211
+
```
212
+
Total worst case: 5 attempts x 2s sleep = 10 additional seconds on top of the 8s card wait.
213
+
214
+
6. **ALSA configuration** (audio.c:755-801):
215
+
- Format: S16_LE interleaved, 2 channels
216
+
- Rate: Requests 192kHz (AUDIO_SAMPLE_RATE), accepts whatever the hardware provides via `set_rate_near`
217
+
- Period size: `AUDIO_PERIOD_SIZE` (negotiated)
218
+
- Buffer: 6 periods for underrun tolerance
219
+
- Logs actual vs. requested rate (common mismatch on some codecs)
220
+
221
+
7. **Mixer setup** (audio.c:809-875):
222
+
- Opens ALSA mixer for the detected card
223
+
- Unmutes **every** playback switch found
224
+
- Sets **all** playback volumes to maximum
225
+
- Enables all capture switches and sets capture volume to 90% of max
226
+
- Attempts HDA codec verb injection for ALC257 (Speaker node 0x14, HP Out node 0x21)
227
+
228
+
8. **HDMI audio** (audio.c:882-920) — Best-effort secondary output:
229
+
- Tries: `hdmi:0,0` through `hdmi:1,1`, `plughw:0,3`, `plughw:0,7`, `plughw:0,8`, `plughw:1,3`, `plughw:1,7`
230
+
- Opens non-blocking, 48kHz, 512-frame period
231
+
- Calculates downsample ratio from primary rate
232
+
233
+
9. **Audio thread** (audio.c:924) — Starts the real-time audio thread at SCHED_FIFO priority 50.
234
+
235
+
**Audio is treated as optional** — if no ALSA device is found after all retries, `audio->pcm` is NULL and the struct is returned with a status message. The rest of the system continues without sound.
236
+
237
+
### 3.8 TTS Init and Precache (lines 1901, 1928-1929)
238
+
239
+
In DRM boot path only:
240
+
241
+
- `tts_init(audio)` (tts.c:125) — Initializes Flite with two voices:
242
+
- `cmu_us_slt` (female, primary)
243
+
- `cmu_us_kal` (male, secondary)
244
+
- Both set to 0.9x duration stretch (slightly faster speech)
245
+
- Starts a background TTS thread
246
+
247
+
- `tts_precache(tts)` (tts.c:204) — Pre-renders all lowercase letters (a-z) and digits (0-9) as cached TTS waveforms. This eliminates latency on keystroke speech during typing.
248
+
249
+
### 3.9 Boot Beep (line 1927)
250
+
251
+
`audio_boot_beep(audio)` (audio.c:1407-1413):
252
+
- Two-tone "doo-dah": E5 (660Hz, 120ms) then B5 (990Hz, 150ms) with 80ms gap
253
+
- Stereo-panned slightly left then right
254
+
255
+
### 3.10 Boot Animation — Startup Fade (line 1937)
256
+
257
+
`draw_startup_fade()` (defined at line 1288):
258
+
259
+
**300 frames at 60fps = 5-second animation.**
260
+
261
+
1. **Immediate solid frame** — White (daytime 7am-6pm LA time) or black (nighttime) to hide kernel console text.
262
+
2. **Version check** — Compares `AC_GIT_HASH-AC_BUILD_TS` against `/mnt/booted-version`. Marks as "FRESH" if different. Appends to `/mnt/boot-history.log`.
263
+
3. **Machine ID** — Reads `/mnt/.machine-id` or generates `notepat-XXXXXXXX` (random hex from `/dev/urandom`).
264
+
4. **TTS greeting** (frame 10) — Speaks time-of-day greeting with handle name and build name: "good morning jeffrey. enjoy Los Angeles! fuzzy-meadow."
265
+
5. **Visual elements:**
266
+
- Fade from solid color to time-of-day themed background (cream/warm white for day, deep blue/sunset purple for night)
267
+
- Centered title with per-character handle colors (animated pulse)
268
+
- Version panel (top-right): build name, git hash, build timestamp, "FRESH" badge
269
+
- "enjoy Los Angeles!" subtitle (appears after frame 130)
270
+
- Auth badges (bottom-left): pixel-art crab (Claude token present) and octocat (GitHub PAT present)
271
+
- Shrinking time bar at bottom
272
+
- "W: install to disk" hint (only when booting from removable USB)
273
+
6. **Input handling** — Opens all `/dev/input/event*` devices non-blocking:
274
+
- First 60 frames (1 second): all key presses are drained/ignored
275
+
- After frame 60: `W` key triggers install-to-disk flow, any other key skips animation
276
+
277
+
### 3.11 Input Init (line 1944)
278
+
279
+
`input_init()` (input.c:315):
280
+
281
+
- Scans all `/dev/input/event*` devices
282
+
- Opens each with `O_RDONLY | O_NONBLOCK | O_CLOEXEC`
283
+
- Checks event bits: accepts devices with EV_KEY, EV_ABS, EV_REL, or EV_SW
284
+
- Detects tablet mode (EV_SW + SW_TABLET_MODE) with sysfs fallback for ThinkPad ACPI
285
+
- Identifies NuPhy keyboards by vendor ID — marks them for hidraw analog handling instead of evdev
286
+
- Calls `hidraw_scan()` for analog keyboard support via HID raw protocol
287
+
288
+
### 3.12 Install-to-Disk Flow (lines 1967-1981)
289
+
290
+
Triggered only when user pressed `W` during boot animation and confirmed with `Y`:
291
+
292
+
`auto_install_to_hd()` (line 713):
293
+
1. Identifies source (removable USB with kernel at `EFI/BOOT/BOOTX64.EFI`)
294
+
2. Finds target non-removable block device (NVMe or SATA)
295
+
3. Creates GPT with EFI System Partition via `sfdisk`
296
+
4. Formats FAT32, copies kernel and config.json
297
+
5. Supports both direct EFI stub and systemd-boot layouts
298
+
6. Displays animated progress during install
299
+
7. On success: prompts reboot (with TTS "rebooting", shutdown sound, 600ms delay)
300
+
301
+
### 3.13 WiFi Init (line 1987)
302
+
303
+
`wifi_init()` (wifi.c:653):
304
+
305
+
1. Checks for `iw` binary existence
306
+
2. Logs diagnostic info: network interfaces, firmware files, kernel wireless messages from `/dev/kmsg`, PCI device enumeration
307
+
3. **Waits up to 3 seconds** for wireless interface (30 attempts x 100ms)
308
+
4. If found, stores interface name (e.g., `wlan0`)
309
+
5. `wifi_autoconnect()` called immediately after — connects to saved/preset network
310
+
311
+
WiFi is skipped entirely if `wifi_disabled` is set from config.json.
312
+
313
+
### 3.14 Secondary HDMI Display (lines 1997-2000)
314
+
315
+
`drm_init_secondary()` — attempts to find a second connected DRM output for HDMI mirroring/extension.
316
+
317
+
### 3.15 JS Runtime Init (line 2004)
318
+
319
+
`js_init()` (js-bindings.c:1637):
320
+
321
+
1. Allocates `ACRuntime` struct with pointers to all subsystems (graph, input, audio, wifi, tts)
322
+
2. Creates WebSocket and UDP client handles
323
+
3. Initializes 3D camera
324
+
4. Creates QuickJS-ng runtime and context
325
+
5. Registers `Form` and `Painting` JS classes
326
+
6. Sets up module loader (`JS_SetModuleLoaderFunc`)
327
+
7. Registers the full native API surface:
328
+
- **Graphics chain API**: box, line, circle, plot, write, scroll, blur, zoom, contrast, spin, qr, form, ink
329
+
- **Top-level graphics**: wipe, ink, line, box, circle, qr, plot, write, scroll, blur, zoom, contrast, spin
330
+
- **console**: log, warn, error
331
+
- **performance**: now()
332
+
8. Evaluates init JS code (Button, Box classes)
333
+
9. Evaluates browser API stubs for KidLisp compatibility
334
+
335
+
### 3.16 Config Application to Runtime (lines 2016-2077)
336
+
337
+
After JS init, re-reads `/mnt/config.json` to populate runtime fields:
338
+
- `rt->handle` and `rt->piece` (boot piece override)
339
+
- Voice config ("off" disables keystroke TTS)
340
+
- Claude token -> `/claude-token`
341
+
- GitHub PAT -> `/github-pat`
342
+
- Piece aliases: "claude" and "cc" resolve to "terminal" with param "claude"
343
+
- Resolves piece path: `/pieces/{name}.mjs`
344
+
345
+
### 3.17 Piece Load and Boot (lines 2080-2144)
346
+
347
+
1. `js_load_piece(rt, piece_path)` — Evaluates the `.mjs` file, extracts `boot`, `paint`, `act`, `sim`, `leave`, `beat` function references
348
+
2. Logs boot time: `"Booted in %.1fms"` (line 2105)
349
+
3. Logs subsystem status: audio, backlight, input devices, NuPhy analog status, JS function availability
350
+
4. Waits for TTS to finish greeting + 300ms drain + plays ready melody (C5-E5-G5 ascending triad) + 400ms ring-out
351
+
5. `audio_prewarm()` — plays near-silent 440Hz note (50ms, 0.001 volume) to fill ALSA buffers
352
+
6. Drains queued input events from boot animation
353
+
7. `js_call_boot(rt)` — Calls the piece's `boot()` function
354
+
8. `perf_init()` — Initializes performance logger (30-second CSV chunks to `/mnt/perf/`)
355
+
356
+
### 3.18 DRM-to-Cage Transition (lines 2149-2280)
357
+
358
+
After boot completes in DRM mode (compiled with `USE_WAYLAND`), the system attempts to transition to a Wayland session for browser popup support:
359
+
360
+
1. Destroys audio (cage child will re-open ALSA)
361
+
2. Releases DRM master
362
+
3. **Forks:**
363
+
- **Child**: Sets env vars (`WLR_RENDERER=pixman`, `WLR_BACKENDS=drm`), creates XDG runtime dir, starts `seatd -g root`, waits up to 3s for `/run/seatd.sock`, then `execlp("cage", "cage", "-s", "--", "/ac-native", "/piece.mjs")`
364
+
- **Parent**: Waits for cage to exit, copies cage stderr to USB log
365
+
366
+
This means ac-native boots twice: once in DRM for fast startup, then re-execs under cage for full Wayland capabilities.
367
+
368
+
---
369
+
370
+
## 4. Timing
371
+
372
+
Based on log data and code analysis, approximate timing from kernel handoff:
373
+
374
+
| Phase | Duration | Cumulative | Notes |
375
+
|---|---|---|---|
376
+
| Kernel + initramfs decompress | ~1-2s | ~1-2s | LZ4 decompression, driver probe |
377
+
| Init script (mounts, zram, dmesg dump) | ~1-2s | ~2-4s | dmesg dump takes ~1s (sleep 1) |
378
+
| Display wait | 0-1s | ~2-5s | Up to 1s for /dev/dri/card0 |
379
+
| USB mount + log setup | 0-2s | ~2-7s | Up to 2s waiting for USB block devs |
380
+
| Config load | <1ms | — | Simple file read + JSON parse |
381
+
| Audio init | 0-18s | ~2-25s | **Highly variable** — see Known Issues |
382
+
| TTS init + precache | ~0.5-1s | — | 36 Flite renders (a-z, 0-9) |
383
+
| Boot animation | 0-5s | — | Skippable with any keypress |
384
+
| Input init | <100ms | — | evdev + hidraw scan |
385
+
| WiFi init | 0-3s | — | Interface detection wait |
386
+
| JS init + piece load | ~100-200ms | — | QuickJS context + module eval |
387
+
| **Total (typical, audio found quickly)** | | **~9s** | From kernel to piece running |
388
+
389
+
The `ac_log` at line 2105 reports `"Booted in %.1fms"` measuring from `main()` entry to piece load completion. With well-behaved audio hardware (card appears quickly, first ALSA device opens on attempt 0), total time from kernel to playable piece is approximately 9 seconds.
390
+
391
+
---
392
+
393
+
## 5. Known Issues
394
+
395
+
### 5.1 ALSA Race Condition (HDA Codec Probe Timing)
396
+
397
+
**The primary boot-time variability comes from audio initialization.**
398
+
399
+
On fast NVMe boots, the HDA codec may not be fully probed when ac-native first tries to open ALSA. The code handles this with a two-layer retry:
400
+
401
+
1. **Card wait loop** (audio.c:665-670): Polls for `/dev/snd/pcmC{0,1,2}D0p` for 8 seconds. If timeout occurs and `/dev/snd/controlC0` exists, it means the HDA controller initialized but the codec hasn't finished probing — this is logged as `"HDA ctrl ok, codec not probed"`.
402
+
403
+
2. **ALSA device open retries** (audio.c:722-743): Even after a PCM device node appears, `snd_pcm_open()` can fail if the codec isn't fully ready. The code retries 5 times with 2-second intervals across 11 different device names.
404
+
405
+
**Worst case**: 8s card wait + 5 retries x 2s = 18 seconds for audio init alone. On machines where audio hardware is ready quickly, this completes in under 1 second.
406
+
407
+
The diagnostic output is written to `/mnt/ac-audio.log` (separate from the main log) with full `/proc/asound/cards` and `/dev/snd/` directory listings.
408
+
409
+
### 5.2 Missing Shared Libraries
410
+
411
+
The build system uses dynamic linking by default (gcc, not musl-gcc). This means all shared libraries must be correctly bundled into the initramfs. The build script (build-and-flash.sh) handles this with:
412
+
413
+
1. Per-binary `ldd` scanning for direct dependencies
414
+
2. A two-pass transitive dependency resolver (lines 740-769) that scans all ELF files in the initramfs and copies missing `.so` files
415
+
416
+
Historical issues:
417
+
- Libraries missed by single-pass `ldd` (transitive deps of deps)
418
+
- Unversioned `.so` symlinks needed for `dlopen()` but not created
419
+
- Mesa GPU stack requiring `libexpat`, `libffi`, `libxkbcommon` that aren't direct deps of ac-native
420
+
421
+
The build now generates an initramfs manifest (`build/initramfs-manifest.txt`, copied into the image as `/manifest.txt`) for build parity verification.
422
+
423
+
### 5.3 Firmware Requirements
424
+
425
+
Required firmware blobs (bundled in initramfs at `/lib/firmware/`):
426
+
427
+
| Firmware | Purpose |
428
+
|---|---|
429
+
| `iwlwifi-9260-th-b0-jf-b0-*.ucode` | Intel WiFi 9260 |
430
+
| `iwlwifi-cc-a0-*.ucode` | Intel WiFi AX200 |
431
+
| `iwlwifi-QuZ-a0-hr-b0-*.ucode` | Intel WiFi AX201 |
432
+
| `iwlwifi-QuZ-a0-jf-b0-*.ucode` | Intel WiFi AX201 (variant) |
433
+
| `regulatory.db` + `.p7s` | Wireless regulatory database |
434
+
| `i915/*` | Intel GPU display firmware (all generations) |
435
+
| `intel/sof/*`, `intel/sof-ipc4/*` | Intel SOF audio firmware |
436
+
| `intel/sof-tplg/*`, `intel/sof-ipc4-tplg/*` | SOF audio topology |
437
+
438
+
The kernel config also embeds a subset of WiFi firmware via `CONFIG_EXTRA_FIRMWARE` for early availability before the initramfs mounts firmware. The build script decompresses `.xz` and `.zst` compressed firmware from the host system.
439
+
440
+
### 5.4 Wayland/Cage Transition Complexity
441
+
442
+
The DRM-to-cage transition (Section 3.18) is inherently fragile:
443
+
- Audio must be destroyed and re-opened by the cage child
444
+
- DRM master must be released before cage can take it
445
+
- seatd must start successfully within 3 seconds
446
+
- The ac-native binary effectively boots twice (DRM then Wayland)
447
+
- If cage fails, the parent logs the error but the system stays on the DRM frame (no automatic fallback to DRM-only mode with continued operation)
448
+
449
+
### 5.5 Clock Accuracy
450
+
451
+
Time-of-day greetings and themed backgrounds depend on `get_la_hour()` which computes LA time. Since the system has no RTC battery on some hardware and NTP hasn't run yet at boot, the kernel time may be epoch (1970). The code accepts this gracefully — it just shows the wrong greeting.
452
+
453
+
---
454
+
455
+
## 6. Build Pipeline
456
+
457
+
### Local builds (`ac-os build`)
458
+
459
+
Orchestrated by `fedac/native/ac-os`:
460
+
461
+
1. **Binary build** (`build_binary()`):
462
+
- Runs `make CC=gcc` (or musl-gcc if available with linux/input.h)
463
+
- Passes `BUILD_TS` env var for timestamp embedding
464
+
- **Verifies** the binary contains the current git hash via `strings` check
465
+
- Builds BPF trace tools if Makefile exists
466
+
467
+
2. **Initramfs build** (`build_initramfs()`):
468
+
- Runs `build-and-flash.sh --skip-kernel --skip-binary` under sudo
469
+
- **KidLisp bundling** done as user (npx unavailable under sudo): `npx esbuild` bundles `kidlisp.mjs` as IIFE
470
+
- Copies fresh binary into initramfs
471
+
- **Claude Code native binary**: copies from `~/.local/share/claude/versions/` (latest), bakes OAuth token from `~/.claude/.credentials.json`, bakes GitHub PAT from `gh auth token`
472
+
- Bakes credentials into initramfs root files
473
+
474
+
3. **Kernel build**: Runs `build-and-flash.sh` for kernel compilation with embedded initramfs
475
+
476
+
### Makefile version stamps (Makefile:10-15)
477
+
478
+
```makefile
479
+
GIT_HASH := $(shell git rev-parse --short HEAD)
480
+
BUILD_TS := $(shell date -u '+%Y-%m-%dT%H:%M')
481
+
BUILD_NAME := $(shell scripts/build-name.sh --bump)
482
+
```
483
+
484
+
These are compiled into the binary via `-DAC_GIT_HASH`, `-DAC_BUILD_TS`, `-DAC_BUILD_NAME` and used for:
485
+
- Boot screen version panel
486
+
- TTS greeting (build name spoken aloud)
487
+
- `/mnt/booted-version` comparison for "FRESH" detection
488
+
- `/mnt/boot-history.log` entries
489
+
490
+
**Critical note** (Makefile:123 comment): Make's dependency tracking doesn't detect changes to `AC_BUILD_NAME` or `AC_GIT_HASH` because they're not source file changes. The Makefile forces a rebuild of the main object file to prevent stale version strings.
491
+
492
+
### Oven builds vs. local builds
493
+
494
+
The primary differences:
495
+
496
+
| Aspect | Local (`ac-os`) | Oven (CI/Docker) |
497
+
|---|---|---|
498
+
| Compiler | gcc (dynamic) or musl-gcc (static) | gcc (dynamic) |
499
+
| Claude binary | From `~/.local/share/claude/versions/` | Downloaded from GCS (`claude-code-releases`) |
500
+
| Claude credentials | From `~/.claude/.credentials.json` | Baked by `ac-usb flash` injection |
501
+
| GitHub PAT | From `gh auth token` | Baked by flash injection |
502
+
| KidLisp bundle | `npx esbuild` (user space) | Not available under sudo |
503
+
| Firmware | Host `/lib/firmware/` (all generations) | Host `/lib/firmware/` (Docker image) |
504
+
| i915 blobs | All from `/lib/firmware/i915/` | All from Docker image |
505
+
| SOF audio | All from host | All from Docker image |
506
+
| Manifest | Generated and embedded | Generated and embedded |
507
+
| Build name | `scripts/build-name.sh --bump` | Same (increments per build) |
508
+
509
+
Both produce the same artifact structure: a single `vmlinuz` with embedded LZ4 initramfs CPIO. The build parity is verified via the initramfs manifest file.
510
+
511
+
### Flash pipeline
512
+
513
+
`ac-os flash` extends the build with USB write:
514
+
1. Full rebuild (binary + initramfs + kernel)
515
+
2. GPT partition table with 512MB ESP
516
+
3. FAT32 format labeled `AC-NATIVE`
517
+
4. Kernel copied to `EFI/BOOT/BOOTX64.EFI` (or splash chainloader + `KERNEL.EFI`)
518
+
5. `config.json` with handle + colors from `handle-colors` API
519
+
6. Credentials injected (Claude token, GitHub PAT, Claude settings)
520
+
521
+
`ac-os upload` always rebuilds first (kernel embeds git hash at compile time), then uploads to OTA release endpoint.
+418
reports/ac-native-size-analysis.md
+418
reports/ac-native-size-analysis.md
···
1
+
# AC Native OS Size Analysis
2
+
3
+
**Date:** 2026-03-19
4
+
**Build:** native-notepat-latest (kernel 6.14.2)
5
+
**Source:** Live data from `oven.aesthetic.computer:/opt/oven/native-cache/`
6
+
7
+
---
8
+
9
+
## 1. Size Summary
10
+
11
+
| Metric | Size |
12
+
|--------|------|
13
+
| **vmlinuz (compressed, shipped)** | **271 MB** (284,120,064 bytes) |
14
+
| Initramfs uncompressed (cpio) | 781 MB |
15
+
| Initramfs compressed (cpio.lz4) | 306 MB (320,097,197 bytes) |
16
+
| Initramfs root (on disk) | 783 MB |
17
+
| Kernel overhead (vmlinuz - initramfs) | ~-35 MB (kernel re-compresses with gzip) |
18
+
| vmlinux (uncompressed ELF) | 357 MB |
19
+
| Manifest entries | 1,893 files |
20
+
21
+
**Compression pipeline:** The initramfs is first compressed with LZ4 (781 MB -> 306 MB, 2.55x ratio). The kernel then wraps everything with gzip (`CONFIG_KERNEL_GZIP=y`), yielding a final vmlinuz of 271 MB. The effective compression ratio from initramfs root to vmlinuz is **2.89x**.
22
+
23
+
---
24
+
25
+
## 2. Component Breakdown
26
+
27
+
### 2.1 Top-Level Directory Sizes
28
+
29
+
| Directory | Size | % of 783 MB |
30
+
|-----------|------|-------------|
31
+
| `bin/` | 234 MB | 29.9% |
32
+
| `lib/` (firmware + x86_64 libs) | 275 MB | 35.1% |
33
+
| `lib64/` (shared libraries + DRI) | 263 MB | 33.6% |
34
+
| `usr/` (ALSA, XKB, sbin) | 8.4 MB | 1.1% |
35
+
| `pieces/` | 616 KB | 0.1% |
36
+
| `etc/` | 684 KB | 0.1% |
37
+
| Other (dev, proc, sys, scripts, sbin, var) | <100 KB | ~0% |
38
+
39
+
**Critical finding:** `lib/x86_64-linux-gnu/` and `lib64/` contain **214 MB of duplicated libraries** (same files, different inodes -- not hardlinks or symlinks). This is the single largest waste.
40
+
41
+
### 2.2 Detailed Component Breakdown
42
+
43
+
#### Core Binary
44
+
45
+
| Component | Size | Notes |
46
+
|-----------|------|-------|
47
+
| `ac-native` | 1.3 MB | The AC piece runner (dynamically linked, C + QuickJS) |
48
+
49
+
#### Claude Code
50
+
51
+
| Component | Size | Notes |
52
+
|-----------|------|-------|
53
+
| `bin/claude` | **226 MB** | Bun SEA binary, **not stripped**, 1,061 symbols exposed |
54
+
55
+
This single file accounts for **28.9%** of the uncompressed initramfs and is the #1 largest item.
56
+
57
+
#### JavaScript Runtime
58
+
59
+
| Component | Size | Notes |
60
+
|-----------|------|-------|
61
+
| `pieces/` (34 .mjs files) | 616 KB | clock.mjs (284K) is largest |
62
+
| `jslib/` | 4 KB | KidLisp bundle (empty -- bundled by ac-os step) |
63
+
64
+
#### Shared Libraries (lib64/) -- Top 15
65
+
66
+
| Library | Size | Purpose | Duplicate in lib/x86_64? |
67
+
|---------|------|---------|--------------------------|
68
+
| libLLVM.so.20.1 | **137 MB** | LLVM backend for Mesa gallium | YES (137 MB) |
69
+
| libgallium-25.2.8.so | **42 MB** | Mesa gallium GPU driver (iris/i915/swrast) | No (lib64 only) |
70
+
| libicudata.so.74 | **30 MB** | ICU Unicode data tables | YES (30 MB) |
71
+
| libcrypto.so.3 | 5.1 MB | OpenSSL crypto | YES |
72
+
| libflite_cmu_us_slt.so.1 | 4.0 MB | Flite TTS female voice (slt) | YES |
73
+
| libflite_cmu_us_slt.so.2.2 | 4.0 MB | Same voice, version duplicate in lib64 | No |
74
+
| libstdc++.so.6 | 2.5 MB | C++ standard library | YES |
75
+
| libicuuc.so.74 | 2.1 MB | ICU Unicode common | YES |
76
+
| libc.so.6 | 2.1 MB | glibc | YES |
77
+
| libgnutls.so.30 | 2.0 MB | GnuTLS | YES |
78
+
| libxml2.so.2 | 1.9 MB | XML parser | YES |
79
+
| libunistring.so.5 | 1.7 MB | Unicode string handling | YES |
80
+
| libp11-kit.so.0 | 1.7 MB | PKCS#11 module loader | YES |
81
+
| libflite_cmu_us_kal.so.1 | 1.4 MB | Flite TTS male voice (kal) | YES |
82
+
| libglib-2.0.so.0 | 1.3 MB | GLib | YES |
83
+
84
+
Total files: 121 shared libraries in lib64/ (50 are symlinks).
85
+
86
+
#### Library Duplication Detail
87
+
88
+
The build script copies libs to `lib64/` for most binaries, but `ac-native` libs go to `lib/x86_64-linux-gnu/` (via canonical path resolution). The result is two full copies:
89
+
90
+
| Path | Size | Role |
91
+
|------|------|------|
92
+
| `lib64/` | 263 MB | Used by claude, cage, busybox, git, curl, etc. |
93
+
| `lib/x86_64-linux-gnu/` | 217 MB | Used by ac-native (canonical Debian paths) |
94
+
| **Overlap** | **214 MB** | Same content, different inodes |
95
+
96
+
#### Firmware
97
+
98
+
| Category | Size | Files | Notes |
99
+
|----------|------|-------|-------|
100
+
| **i915 GPU** | **27 MB** | 128 blobs | All Intel GPU generations |
101
+
| **Intel SOF audio** | **31 MB** | ~180+ files | 4 directories (sof, sof-ipc4, sof-tplg, sof-ipc4-tplg) |
102
+
| WiFi (iwlwifi) | 2.0 MB | 4 ucodes | 9260, AX200, AX201 |
103
+
| Regulatory DB | 12 KB | 2 files | |
104
+
| **Total firmware** | **59 MB** | ~314 files | |
105
+
106
+
**i915 by generation:**
107
+
108
+
| Generation | Size | Blobs | Target hardware |
109
+
|------------|------|-------|-----------------|
110
+
| tgl (Tiger Lake) | 4.3 MB | 15 | 11th gen |
111
+
| icl (Ice Lake) | 3.0 MB | 10 | 10th gen |
112
+
| dg1/dg2 (Arc) | 4.6 MB | 16 | Discrete GPU |
113
+
| skl (Skylake) | 2.0 MB | 17 | 6th gen |
114
+
| kbl (Kaby Lake) | 1.9 MB | 13 | 7th/8th gen |
115
+
| bxt (Broxton) | 1.9 MB | 13 | Atom |
116
+
| ehl (Elkhart Lake) | 2.1 MB | 6 | Embedded |
117
+
| mtl (Meteor Lake) | 2.1 MB | 5 | 14th gen (current target) |
118
+
| adlp (Alder Lake) | 1.7 MB | 10 | 12th gen |
119
+
| glk (Gemini Lake) | 1.6 MB | 9 | Atom |
120
+
| cml (Comet Lake) | 1.2 MB | 6 | 10th gen |
121
+
| Other (rkl, cnl, xe3lpd, xe2lpd, bmg, adls) | <0.3 MB | 6 | Various |
122
+
123
+
**Intel SOF audio breakdown:**
124
+
125
+
| Directory | Size | Notes |
126
+
|-----------|------|-------|
127
+
| sof-tplg/ (legacy topologies) | 9.7 MB | Old IPC format |
128
+
| sof-ipc4/ (new firmware) | 7.7 MB | 11 platform dirs |
129
+
| sof/ (legacy firmware) | 6.7 MB | Old IPC format |
130
+
| sof-ipc4-tplg/ (new topologies) | 6.4 MB | 129 topology files |
131
+
132
+
SOF IPC4 platforms: adl, adl-n, adl-s, arl, arl-s, lnl, mtl, rpl, rpl-s, tgl, tgl-h
133
+
134
+
#### Mesa GPU Stack
135
+
136
+
| Component | Size | Notes |
137
+
|-----------|------|-------|
138
+
| libLLVM.so.20.1 | 137 MB | JIT compiler for gallium shaders |
139
+
| libgallium-25.2.8.so | 42 MB | Monolithic driver (iris + i915 + swrast) |
140
+
| lib64/dri/ (driver stubs) | 120 KB | 1 real file + 4 symlinks |
141
+
| EGL/GBM/GLES libs | ~2 MB | Symlinks into lib64/ |
142
+
| **Total Mesa (deduplicated)** | **~181 MB** | libLLVM + gallium + supporting libs |
143
+
144
+
**Dependency chain:** `dri/iris_dri.so` -> `libdril_dri.so` -> `libgallium` -> `libLLVM.so.20.1` -> `libicudata.so.74`
145
+
146
+
#### System Tools
147
+
148
+
| Binary | Size | Notes |
149
+
|--------|------|-------|
150
+
| busybox | 2.1 MB | 45+ applet symlinks (sh, find, cp, mv, etc.) |
151
+
| git | 3.9 MB | For Claude Code git operations |
152
+
| awk (gawk) | 724 KB | GNU awk |
153
+
| ip | 756 KB | Network config |
154
+
| ac-trace | 412 KB | BPF/ftrace diagnostic tool |
155
+
| iw | 308 KB | WiFi scanner |
156
+
| curl | 292 KB | HTTP client |
157
+
| grep | 184 KB | Pattern search |
158
+
| dropbear | 165 KB | SSH daemon |
159
+
| sed | 112 KB | Stream editor |
160
+
| sfdisk | 108 KB | Partition tool (USB flash) |
161
+
| cage | 64 KB | Wayland kiosk compositor |
162
+
| seatd | 48 KB | Seat daemon for wlroots |
163
+
| mkfs.vfat | 52 KB | FAT32 formatter |
164
+
| dropbearkey | 47 KB | SSH key generator |
165
+
| jq | 32 KB | JSON processor |
166
+
| Other (head, cut, sleep, etc.) | ~200 KB | Small coreutils |
167
+
168
+
#### Flite TTS
169
+
170
+
| Component | Size | Copies | Notes |
171
+
|-----------|------|--------|-------|
172
+
| libflite_cmu_us_slt (female voice) | 4.0 MB | 3 copies (lib64 .so.1, .so.2.2, lib/x86_64) | **12 MB total** |
173
+
| libflite_cmu_us_kal (male voice) | 1.4 MB | 3 copies | **4.2 MB total** |
174
+
| libflite_cmulex (lexicon) | 600 KB | 3 copies | 1.8 MB total |
175
+
| libflite.so (core) | 228 KB | 3 copies | 684 KB total |
176
+
| libflite_usenglish.so | 168 KB | 3 copies | 504 KB total |
177
+
| **Total Flite (all copies)** | | | **~19 MB** |
178
+
179
+
The .so.1 and .so.2.2 files in lib64/ are also duplicates (different inodes, same content).
180
+
181
+
#### Audio Config
182
+
183
+
| Component | Size | Notes |
184
+
|-----------|------|-------|
185
+
| ALSA ucm2/ | 2.4 MB | Use Case Manager configs |
186
+
| ALSA topology/ | 364 KB | |
187
+
| ALSA cards/ | 272 KB | |
188
+
| ALSA pcm/ + ctl/ + conf | ~90 KB | |
189
+
| **Total ALSA** | **3.1 MB** | |
190
+
191
+
#### XKB Keyboard Data
192
+
193
+
| Component | Size | Notes |
194
+
|-----------|------|-------|
195
+
| symbols/ | 2.5 MB | All keyboard layouts worldwide |
196
+
| rules/ | 804 KB | Layout selection rules |
197
+
| geometry/ | 404 KB | Physical keyboard geometry |
198
+
| keycodes/ | 148 KB | |
199
+
| compat/ + types/ | 152 KB | |
200
+
| **Total XKB** | **4.0 MB** | |
201
+
202
+
#### Other
203
+
204
+
| Component | Size | Notes |
205
+
|-----------|------|-------|
206
+
| CA certificates | 444 KB | /etc/pki/ |
207
+
| SSL certs (duplicate CA) | 224 KB | /etc/ssl/ |
208
+
| init script | 2.9 KB | Boot script |
209
+
| scripts/ | 4 KB | upload-log.sh |
210
+
| dhclient-script | 4 KB | |
211
+
| git-credential-ac | 4 KB | PAT helper |
212
+
213
+
---
214
+
215
+
## 3. Shrink Opportunities
216
+
217
+
### 3.1 Library Deduplication (lib64/ vs lib/x86_64-linux-gnu/)
218
+
219
+
**Current waste: 214 MB of exact duplicates**
220
+
221
+
The build script (`build-and-flash.sh`) copies libs in two ways:
222
+
1. Per-binary `ldd` copies go to `lib64/`
223
+
2. ac-native's canonical-path copy goes to `lib/x86_64-linux-gnu/`
224
+
225
+
**Fix:** Replace `lib/x86_64-linux-gnu/` with a symlink to `lib64/` (or vice versa). The transitive dependency resolver (lines 740-769 of build-and-flash.sh) already copies everything to lib64/, so the x86_64-linux-gnu directory can be a symlink.
226
+
227
+
**Estimated savings:** 214 MB uncompressed, ~84 MB compressed
228
+
**Difficulty:** Low (single line change in build script)
229
+
**Risk:** Low (just a symlink, all paths still resolve)
230
+
231
+
### 3.2 Flite TTS Version Duplicates in lib64/
232
+
233
+
Both `.so.1` and `.so.2.2` exist as separate files with identical content (different inodes).
234
+
235
+
**Fix:** Make `.so.1` a symlink to `.so.2.2` (or vice versa).
236
+
237
+
**Estimated savings:** 6.4 MB (slt 4.0 MB + kal 1.4 MB + cmulex 600 KB + core 228 KB + usenglish 168 KB)
238
+
**Difficulty:** Low
239
+
**Risk:** Low
240
+
241
+
### 3.3 Claude Code Binary (226 MB)
242
+
243
+
The binary is a Bun Single Executable Application (SEA). It is **not stripped** (1,061 symbols, `file` reports "not stripped"). However, the build script contains a warning: "Do NOT strip -- Claude Code is a Bun SEA binary and stripping destroys the embedded JS blob."
244
+
245
+
**Options:**
246
+
1. **UPX compression:** UPX can compress ELF binaries ~50-70%. The binary would self-extract at startup (adds ~1-2 seconds boot time). UPX is not currently installed on the oven. Bun SEA binaries may or may not survive UPX -- needs testing.
247
+
- **Potential savings:** 100-150 MB
248
+
- **Difficulty:** Medium (needs testing)
249
+
- **Risk:** Medium (may break Bun SEA resource extraction)
250
+
251
+
2. **Lazy load from USB:** Instead of embedding Claude in the initramfs, keep it on the FAT32 USB partition and mount + exec at runtime. The initramfs would ship without Claude, loading it on demand.
252
+
- **Potential savings:** 226 MB from initramfs (but still on USB)
253
+
- **Difficulty:** Medium (requires init script changes + mount logic)
254
+
- **Risk:** Low (USB is always present at boot)
255
+
256
+
3. **Download on first use:** Only fetch the Claude binary when the user first invokes it (requires network).
257
+
- **Potential savings:** 226 MB
258
+
- **Difficulty:** Medium
259
+
- **Risk:** High (requires network, slow first launch)
260
+
261
+
4. **Wait for smaller Claude builds:** Anthropic may release a more compact Claude Code binary in the future.
262
+
263
+
### 3.4 libLLVM.so.20.1 (137 MB)
264
+
265
+
This is the LLVM JIT compiler, required by Mesa gallium for shader compilation. The dependency chain is: `iris_dri.so` -> `libgallium` -> `libLLVM`.
266
+
267
+
**Options:**
268
+
1. **Build Mesa without LLVM:** Mesa can be built with `-Dllvm=disabled`. This removes software shader compilation (swrast) and some gallium optimizations, but the Intel iris driver can still work using Intel's proprietary shader compiler path (i965 backend, not gallium). However, the Ubuntu-shipped Mesa packages always include LLVM.
269
+
- **Potential savings:** 137 MB (+ 30 MB libicudata which is only needed by libLLVM)
270
+
- **Difficulty:** High (custom Mesa build required)
271
+
- **Risk:** Medium (may degrade GPU performance or break some features)
272
+
273
+
2. **Strip LLVM:** The shipped libLLVM may contain debug sections or unnecessary targets. A custom LLVM build targeting only x86_64 backend would be significantly smaller (~30-50 MB).
274
+
- **Potential savings:** 90-110 MB
275
+
- **Difficulty:** High
276
+
- **Risk:** Low (if built correctly)
277
+
278
+
3. **Use i965 DRI driver instead of iris/gallium:** For older Intel hardware, the classic i965 driver doesn't need LLVM. But for modern Intel (Gen 12+), iris is required.
279
+
- Not recommended for current target hardware.
280
+
281
+
### 3.5 libicudata.so.74 (30 MB)
282
+
283
+
ICU Unicode data tables. Only loaded by libLLVM (which loads it via libxml2 -> libicuuc -> libicudata). Nothing else in the initramfs directly needs ICU.
284
+
285
+
**Fix:** Eliminating LLVM (3.4 above) would also eliminate ICU.
286
+
287
+
**Estimated savings:** 30 MB
288
+
**Difficulty:** Tied to LLVM removal
289
+
**Risk:** Same as LLVM removal
290
+
291
+
### 3.6 i915 GPU Firmware (27 MB, 128 blobs)
292
+
293
+
The build copies **all** i915 generations from the host. If AC Native OS only targets specific hardware (e.g., Meteor Lake laptops), most can be removed.
294
+
295
+
**Minimum set for Meteor Lake + Alder Lake:**
296
+
- mtl (5 blobs, 2.1 MB) -- 14th gen
297
+
- adlp (10 blobs, 1.7 MB) -- 12th gen
298
+
- tgl (15 blobs, 4.3 MB) -- 11th gen (backwards compat)
299
+
300
+
**Everything else removable:** skl, kbl, bxt, glk, icl, cml, ehl, dg1, dg2, rkl, cnl, xe3lpd, xe2lpd, bmg, adls
301
+
302
+
**Estimated savings:** ~19 MB (keep ~8 MB for mtl+adlp+tgl)
303
+
**Difficulty:** Low (filter in build-and-flash.sh line 369-383)
304
+
**Risk:** Medium (breaks support for older Intel hardware)
305
+
306
+
### 3.7 Intel SOF Audio Firmware (31 MB)
307
+
308
+
The build copies ALL SOF firmware (legacy IPC + IPC4, all platforms, all topologies).
309
+
310
+
**Options:**
311
+
1. **Remove legacy SOF (sof/ + sof-tplg/):** Modern Intel uses IPC4. Legacy is for pre-TGL.
312
+
- **Savings:** 16.4 MB
313
+
- **Risk:** Breaks audio on pre-Tiger Lake hardware
314
+
315
+
2. **Trim IPC4 topologies:** 129 topology files, most for specific codec combinations. The device likely only needs the HDA-generic topologies + its specific codec.
316
+
- **Savings:** ~4-5 MB
317
+
- **Risk:** Medium (need to identify correct topology)
318
+
319
+
3. **Trim IPC4 platforms:** Keep only mtl + arl (current targets), remove adl/tgl/rpl variants.
320
+
- **Savings:** ~4 MB
321
+
- **Risk:** Medium
322
+
323
+
**Total potential SOF savings:** ~20-25 MB
324
+
**Difficulty:** Medium (requires knowing exact target hardware)
325
+
326
+
### 3.8 Flite TTS Voice Models
327
+
328
+
Two voices are bundled: slt (female, 4.0 MB) and kal (male, 1.4 MB).
329
+
330
+
**Options:**
331
+
1. **Keep only one voice:** Remove kal (male) if unused.
332
+
- **Savings:** ~1.4 MB (plus duplicates = ~4.2 MB)
333
+
- **Difficulty:** Low
334
+
- **Risk:** Low
335
+
336
+
2. **Use kal only (smaller):** kal is 1.4 MB vs slt at 4.0 MB.
337
+
- **Savings:** ~2.6 MB (plus duplicates)
338
+
- **Difficulty:** Low
339
+
- **Risk:** Low (lower voice quality)
340
+
341
+
### 3.9 XKB Keyboard Data (4.0 MB)
342
+
343
+
The `symbols/` directory (2.5 MB) contains layouts for every language/country.
344
+
345
+
**Fix:** Keep only `us`, `gb`, and `inet` (for media keys). Remove all other layouts.
346
+
347
+
**Estimated savings:** ~2-3 MB
348
+
**Difficulty:** Low
349
+
**Risk:** Low (US keyboard is the primary target)
350
+
351
+
### 3.10 Git Binary (3.9 MB)
352
+
353
+
Git is bundled for Claude Code's git operations on-device.
354
+
355
+
**Options:**
356
+
1. **Keep it:** Claude Code is significantly more capable with git. At 3.9 MB, it's not a major contributor.
357
+
2. **Lazy-load from USB partition:** Similar to Claude binary lazy-loading.
358
+
359
+
**Recommendation:** Keep. The 3.9 MB is worth the capability.
360
+
361
+
### 3.11 Compression Algorithm
362
+
363
+
Currently: LZ4 for initramfs, gzip for kernel wrapping.
364
+
365
+
| Algorithm | Compress ratio | Decompress speed | Boot impact |
366
+
|-----------|---------------|------------------|-------------|
367
+
| LZ4 (current) | 2.55x | ~4 GB/s | Fastest boot |
368
+
| zstd | ~3.0-3.5x | ~1.5 GB/s | +100-200ms |
369
+
| xz/lzma | ~3.5-4.0x | ~200 MB/s | +1-3s |
370
+
371
+
The kernel already supports `CONFIG_RD_ZSTD=y`. Switching initramfs to zstd would save ~30-60 MB in vmlinuz at the cost of slightly slower boot.
372
+
373
+
For the kernel wrapper, switching from gzip to zstd (`CONFIG_KERNEL_ZSTD=y`) would save another ~10-20 MB.
374
+
375
+
**Total compression savings (zstd):** ~40-80 MB in final vmlinuz
376
+
**Difficulty:** Low (kernel config change)
377
+
**Risk:** Low (adds ~200-400ms boot time)
378
+
379
+
### 3.12 ALSA UCM2 Config (2.4 MB)
380
+
381
+
The UCM2 directory contains Use Case Manager configs for many different sound cards.
382
+
383
+
**Fix:** Keep only the configs for the target hardware's codec.
384
+
385
+
**Estimated savings:** ~2 MB
386
+
**Difficulty:** Medium (need to identify correct configs)
387
+
**Risk:** Low
388
+
389
+
---
390
+
391
+
## 4. Recommended Reductions (Prioritized)
392
+
393
+
| # | Change | Savings (uncompressed) | Est. vmlinuz savings | Difficulty | Risk |
394
+
|---|--------|----------------------|---------------------|------------|------|
395
+
| 1 | **Deduplicate lib/x86_64 -> lib64 symlink** | **214 MB** | **~84 MB** | Low | Low |
396
+
| 2 | **Remove legacy SOF firmware (sof/ + sof-tplg/)** | **16.4 MB** | ~6 MB | Low | Medium |
397
+
| 3 | **Trim i915 to target generations only** | **19 MB** | ~7 MB | Low | Medium |
398
+
| 4 | **Fix Flite .so.1/.so.2.2 duplicates (symlinks)** | **6.4 MB** | ~2 MB | Low | Low |
399
+
| 5 | **Switch to zstd compression** | 0 (compression only) | **~40-80 MB** | Low | Low |
400
+
| 6 | **Trim XKB to US layout only** | **3 MB** | ~1 MB | Low | Low |
401
+
| 7 | **Trim SOF IPC4 topologies + platforms** | **8 MB** | ~3 MB | Medium | Medium |
402
+
| 8 | **Lazy-load Claude from USB partition** | **226 MB** | **~89 MB** | Medium | Low |
403
+
| 9 | **Build Mesa without LLVM (custom package)** | **167 MB** | **~65 MB** | High | Medium |
404
+
| 10 | **UPX-compress Claude binary** | **~130 MB** | **~51 MB** | Medium | Medium |
405
+
| 11 | **Remove second TTS voice (kal)** | **4.2 MB** | ~1.5 MB | Low | Low |
406
+
| 12 | **Trim ALSA UCM2 configs** | **2 MB** | ~1 MB | Medium | Low |
407
+
408
+
### Quick Wins (items 1-6): ~259 MB uncompressed, ~140-180 MB vmlinuz savings
409
+
410
+
Applying just the top 6 low-difficulty changes would reduce the vmlinuz from **271 MB** to approximately **~90-130 MB**.
411
+
412
+
### Full Optimization (items 1-12): ~796 MB uncompressed savings
413
+
414
+
With all changes including LLVM removal and Claude lazy-loading, the vmlinuz could theoretically reach **~50-80 MB**.
415
+
416
+
### Fastest Single Fix
417
+
418
+
**Item #1 alone** (lib deduplication) saves 214 MB uncompressed / ~84 MB compressed. It requires changing approximately one line in `build-and-flash.sh` to create a symlink instead of a separate directory. This should be done immediately -- it's free savings from a build bug.
+10
system/netlify.toml
+10
system/netlify.toml
···
295
295
external_node_modules = ["mongodb", "mongodb-connection-string-url"]
296
296
included_env_vars = ["CONTEXT", "MONGODB_CONNECTION_STRING", "MONGODB_NAME"]
297
297
298
+
[functions.paper-hit]
299
+
# Track paper PDF views/downloads
300
+
included_files = ["backend/**/*.mjs"]
301
+
external_node_modules = ["mongodb", "mongodb-connection-string-url"]
302
+
included_env_vars = ["MONGODB_CONNECTION_STRING", "MONGODB_NAME"]
303
+
298
304
[functions.keep-confirm]
299
305
# Confirm client-side wallet mints and update MongoDB
300
306
included_files = ["backend/**/*.mjs"]
···
1866
1872
[[redirects]]
1867
1873
from = "/api/boot-log"
1868
1874
to = "/.netlify/functions/boot-log"
1875
+
status = 200
1876
+
[[redirects]]
1877
+
from = "/api/paper-hit"
1878
+
to = "/.netlify/functions/paper-hit"
1869
1879
status = 200
1870
1880
[[redirects]]
1871
1881
from = "/api/kidlisp-log"
+71
system/netlify/functions/paper-hit.mjs
+71
system/netlify/functions/paper-hit.mjs
···
1
+
// paper-hit.mjs - Track paper PDF views/downloads
2
+
// POST /api/paper-hit { paper, format, lang }
3
+
// GET /api/paper-hit → aggregate counts
4
+
5
+
import { connect } from "../../backend/database.mjs";
6
+
import { respond } from "../../backend/http.mjs";
7
+
8
+
export async function handler(event) {
9
+
if (event.httpMethod === "OPTIONS") return respond(204, "");
10
+
11
+
const database = await connect();
12
+
const hits = database.db.collection("paper-hits");
13
+
14
+
try {
15
+
if (event.httpMethod === "GET") {
16
+
const pipeline = [
17
+
{
18
+
$group: {
19
+
_id: { paper: "$paper", format: "$format" },
20
+
count: { $sum: 1 },
21
+
lastHit: { $max: "$createdAt" },
22
+
},
23
+
},
24
+
{ $sort: { count: -1 } },
25
+
];
26
+
const stats = await hits.aggregate(pipeline).toArray();
27
+
await database.disconnect();
28
+
return respond(200, { stats });
29
+
}
30
+
31
+
if (event.httpMethod !== "POST") {
32
+
await database.disconnect();
33
+
return respond(405, { error: "Method not allowed" });
34
+
}
35
+
36
+
let body;
37
+
try {
38
+
body = JSON.parse(event.body || "{}");
39
+
} catch {
40
+
await database.disconnect();
41
+
return respond(400, { error: "Invalid JSON" });
42
+
}
43
+
44
+
const { paper, format = "pdf", lang = "en" } = body || {};
45
+
if (!paper) {
46
+
await database.disconnect();
47
+
return respond(400, { error: "Missing paper" });
48
+
}
49
+
50
+
const headers = event.headers || {};
51
+
await hits.insertOne({
52
+
paper,
53
+
format,
54
+
lang,
55
+
createdAt: new Date(),
56
+
ip:
57
+
headers["x-nf-client-connection-ip"] ||
58
+
headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
59
+
null,
60
+
country: headers["x-country"] || headers["x-nf-country-code"] || null,
61
+
referer: headers["referer"] || headers["referrer"] || null,
62
+
ua: headers["user-agent"] || null,
63
+
});
64
+
65
+
await database.disconnect();
66
+
return respond(200, { ok: true });
67
+
} catch (err) {
68
+
try { await database.disconnect(); } catch {}
69
+
return respond(500, { error: err.message || "Failed to log hit" });
70
+
}
71
+
}
+18
-1
system/public/papers.aesthetic.computer/index.html
+18
-1
system/public/papers.aesthetic.computer/index.html
···
6
6
<title>papers · Aesthetic Computer</title>
7
7
<meta name="description" content="Academic papers on Aesthetic Computer and KidLisp.">
8
8
<meta property="og:title" content="papers — Aesthetic.Computer" />
9
-
<meta property="og:description" content="18 papers by Jeffrey Alan Scudder on creative computing, KidLisp, and Aesthetic Computer." />
9
+
<meta property="og:description" content="Papers by @jeffrey on creative computing, KidLisp, and Aesthetic Computer." />
10
10
<meta property="og:image" content="https://papers.aesthetic.computer/papers-og.jpg" />
11
11
<meta property="og:image:width" content="1200" />
12
12
<meta property="og:image:height" content="630" />
···
833
833
if (e.target.closest('a')) return;
834
834
const link = p.querySelector('.title a');
835
835
if (link) link.click();
836
+
});
837
+
});
838
+
839
+
// Track paper PDF views/downloads
840
+
function trackHit(paper, format) {
841
+
const lang = currentLang || 'en';
842
+
navigator.sendBeacon(
843
+
'https://aesthetic.computer/api/paper-hit',
844
+
JSON.stringify({ paper, format, lang })
845
+
);
846
+
}
847
+
document.querySelectorAll('.p').forEach(p => {
848
+
const id = p.dataset.paperId;
849
+
if (!id) return;
850
+
p.querySelectorAll('a[href$=".pdf"], a[href*=".pdf?"]').forEach(a => {
851
+
const fmt = a.href.includes('-cards') ? 'cards' : 'pdf';
852
+
a.addEventListener('click', () => trackHit(id, fmt));
836
853
});
837
854
});
838
855
+1
-1
system/public/sitemap.html
+1
-1
system/public/sitemap.html
···
953
953
<span class="section-title">papers.aesthetic.computer</span>
954
954
<span class="section-count">Research</span>
955
955
</summary>
956
-
<div class="section-desc">Academic papers portal. Four publications (arXiv preprints + JOSS summaries) on Aesthetic Computer and KidLisp by Jeffrey Alan Scudder, March 2026. Dark/light theme toggle.</div>
956
+
<div class="section-desc">Academic papers portal by @jeffrey. arXiv preprints, JOSS summaries, and ELS proceedings on Aesthetic Computer and KidLisp. Multi-language support, dark/light theme, PDF hit tracking.</div>
957
957
<div class="routes single-col">
958
958
<div class="route full-url">papers.aesthetic.computer/ — Papers index with PDF downloads</div>
959
959
</div>
+2
-2
vscode-extension/package-lock.json
+2
-2
vscode-extension/package-lock.json
···
1
1
{
2
2
"name": "aesthetic-computer-code",
3
-
"version": "1.267.0",
3
+
"version": "1.267.1",
4
4
"lockfileVersion": 3,
5
5
"requires": true,
6
6
"packages": {
7
7
"": {
8
8
"name": "aesthetic-computer-code",
9
-
"version": "1.267.0",
9
+
"version": "1.267.1",
10
10
"license": "None",
11
11
"dependencies": {
12
12
"acorn": "^8.15.0",
+1
-1
vscode-extension/package.json
+1
-1
vscode-extension/package.json
···
4
4
"displayName": "Aesthetic Computer",
5
5
"icon": "resources/icon.png",
6
6
"author": "Jeffrey Alan Scudder",
7
-
"version": "1.267.0",
7
+
"version": "1.267.1",
8
8
"description": "Code, run, and publish your pieces. Includes Aesthetic Computer themes and KidLisp syntax highlighting.",
9
9
"engines": {
10
10
"vscode": "^1.105.0"