S1a CLI reference

The S1a differenceS1a 的差異What S1a adds over S1 — the always-on physics mechanismsS1a 比 S1 多的 —— 恆開的物理機制

Each S1a mechanism restores a slice of physics the binary switch-level model cannot express, and they are armed unconditionally in every mode — --benchmark included, since S1a is a full engine, not a raw switch-level run. So S1a has its own golden checksums (full_palette, --extra-ram): 0x41244C26C45EDD32 @ 300k, 0xFA016F9CEA14029B @ 1M — distinct from S1's raw 0x794A43ABDF169ADA / 0x6D4CCBCE2E9CD599 because the mechanisms (the ALERead node-split especially) change internal node state. They simply run — there is no opt-out; the raw switch-level engine (S1's raw checksum) is the separate S1 fork. The mechanism set is unchanged from the AC 141/141 · 147 146/1 milestone (authoritative re-run pending). Two hand-written shims are also always-on, because no mechanism replaces them yet: OpenBus (last-transferred-byte replay — a behavioural ceiling) and DL (the $4016/$4017 input-data-latch φ2 transparency — deferred; its general form was unsound). See the shim ledger for the full RETIRED status.

每個 S1a 機制還原一片二值開關級模型表達不了的物理,而且在每個模式都無條件武裝 —— 含 --benchmark,因為 S1a 是完整引擎、不是 raw 開關級跑。所以 S1a 有自己的金 checksum(full_palette,--extra-ram):0x41244C26C45EDD32 @ 300k、0xFA016F9CEA14029B @ 1M —— 與 S1 的 raw 0x794A43ABDF169ADA / 0x6D4CCBCE2E9CD599 不同,因為機制(尤其 ALERead node-split)改了內部節點狀態。它們就是直接跑 —— 沒有關閉開關;raw 開關級引擎(S1 的 raw checksum)是獨立的 S1 fork。機制集合與 AC 141/141 · 147 146/1 里程碑相同(權威重跑待進行)。兩個手寫 shim 也恆開,因為還沒有機制能取代它們:OpenBus(最後傳輸位元組重放 —— 行為層天花板)與 DL($4016/$4017 輸入資料閂鎖 φ2 透明 —— 延後;它的通則形式不健全)。完整 RETIRED 狀態見 shim 總帳。

Always-on physics mechanisms (no env, no toggle)恆開的物理機制(無 env、無開關)

Every mechanism below runs unconditionally in test mode and needs no env var, and none disturb the golden checksum (they arm only in test mode). The whole set is gated on AC 141/141 + the 147-ROM regression. S1a is always the full engine — there is no off-switch; the raw switch-level engine is the separate S1 fork. The Replaces column names the physics each one covers.下面每個機制在 test 模式無條件執行、不需 env,且都不動金 checksum(只在 test 模式武裝)。整組以 AC 141/141 + 147 顆回歸為閘。S1a 永遠是完整引擎 —— 沒有關閉開關;raw 開關級引擎是獨立的 S1 fork。取代欄標出每個機制涵蓋的物理。

Always-on shims (no mechanism replaces them yet)恆開的 shim(還沒機制取代)

Experimental opt-ins (env-gated, default-OFF — not in the certified set)實驗性選用(env 控制、預設關 —— 不在認證組)

1 · Entry points1 · 入口Mode selectors執行模式(擇一) identical to S1 today今天與 S1 相同

2 · Simulation environment2 · 模擬環境How the chip is loaded and run晶片怎麼載入與跑 identical to S1 today今天與 S1 相同

3 · Verdict detection3 · 測試判定How a test-ROM result is read測試 ROM 結果怎麼判 identical to S1 today今天與 S1 相同

4 · Snapshot / resume · 5 · progress4 · 快照/續跑 · 5 · 進度Windowed regression & long-run telemetry窗口回歸與長跑遙測 identical to S1 today今天與 S1 相同

6 · Benchmark / perf6 · 效能量測Throughput knobs & profiling dumps吞吐旋鈕與剖析傾印 identical to S1 today今天與 S1 相同

7 · Shim CLI toggles7 · Shim CLI 開關The analog-race patch surface類比賽跑補丁面

8 · Diagnostic tools8 · 診斷工具Node & state inspection節點與狀態檢視

9 · Screen output9 · 畫面輸出Framebuffer dumpsframebuffer 傾印 identical to S1 today今天與 S1 相同

10 · Common recipes10 · 常用配方Copy-paste command lines可貼上的指令列

Golden checksum (full S1a engine, and the raw S1 core)黃金驗證(完整 S1a 引擎,與 raw S1 核心)

dotnet AprVisual.S1A.dll --benchmark AprVisualBenchMark/roms/full_palette.nes --bench-hc 300000 \
  --extra-ram --system-def-dir AprVisualBenchMark/data/system-def
# S1a engine (always full, no opt-out):  300k -> 0x41244C26C45EDD32   1M -> 0xFA016F9CEA14029B
# for the raw switch-level values (0x794A43ABDF169ADA / 0x6D4CCBCE2E9CD599), run the separate S1 fork

S1a mechanisms (they just run — no env)S1a 機制(直接跑 —— 無 env)

dotnet AprVisual.S1A.dll --test ...   # EVERY M1–M6 mechanism + ALERead mux ON, automatically (AC 141/141)
# there is no off-switch — S1a is always the full engine (for raw switch-level, run the separate S1 fork)

# Experimental opt-ins (default-OFF, not in the certified set):
M4_DL=1  dotnet AprVisual.S1A.dll --test ...      # add the experimental DL transparent row ($4016/$4017)
M2_CAP=1 dotnet AprVisual.S1A.dll --benchmark ... # physical-capacitance arbitration — CHANGES the checksum by design

The mechanisms are unconditional — there is no off-switch. PowerShell (for the opt-ins): $env:M4_DL=1; dotnet ….機制無條件執行 —— 沒有關閉開關。PowerShell(選用):$env:M4_DL=1; dotnet …。

AccuracyCoin flagship run (shared surface — same as S1)AccuracyCoin 掛牌跑(共用面 —— 與 S1 相同)

dotnet AprVisual.S1A.dll --test AprAccuracyCoinUnattended/AccuracyCoin.nes --ac-verdict --joypad \
  --reset-hold-extra 1 --pin 2 \
  --system-def-dir AprVisualBenchMark/data/system-def --max-frames 12000 \
  --snapshot-frames 10 --snapshot-dir out/snaps --progress-frames 600 --progress-dir out/prog
# S1a: every mechanism (M2 decay, ALERead mux, …) is already armed — no env prefix needed

11 · The 147-ROM test battery11 · 147 測試 ROM 實戰Four verdict paths, a controller, and a budget四種判定、手把、與預算 identical to S1 today今天與 S1 相同

Running the nes-test-roms battery is identical to S1 — the four verdict classes (blargg $6000 protocol, screen text, screen CRC), the controller simulation (--joypad + --input), and the budget/timeout flags are the same 71-flag surface. The full cookbook — one copy-paste command per verdict class, controller scripting, and the exit-code / detection=none notes — lives on the S1 page: S1 CLI §11 · The 147-ROM test battery. Just swap AprVisual.S1.dll → AprVisual.S1A.dll.跑 nes-test-roms 電池與 S1 完全相同 —— 四種判定(blargg $6000 協定、畫面文字、畫面 CRC)、手把模擬(--joypad + --input)、預算/timeout 旗標,都是同一組 71 旗標面。完整 cookbook(每種判定一行可貼上指令、手把腳本、exit code / detection=none 說明)在 S1 頁:S1 CLI §11 · 147 測試 ROM 實戰。只要把 AprVisual.S1.dll → AprVisual.S1A.dll。