OpenMaidEngine/docs/superpowers/specs/2026-07-07-scjump-decision-decode-design.md

# SCJUMP static decision-logic decode — design

**Date:** 2026-07-07
**Status:** approved (brainstorming) → ready for implementation plan
**Slice:** Phase B story-state layer, progression sub-slice (#2, following the globals registry).

---

## 1. Problem & goal

`SCJUMP.BIN` (29,790 instructions) is the game's **progression state machine** — it decides "what
comes next" in the story. Today it is an opaque blob. This slice **decodes its decision logic
faithfully into a readable, VM-verified progression graph**: for every decision site, the exact
`(chapter_mode, guarding conditions) → decision value` rule, extracted from the bytecode.

This is *decode*, not stub: every rule traces to specific instructions; nothing is invented. The VM
already executes SCJUMP correctly — this slice makes that logic **legible and verified**, it does not
change execution.

## 2. Non-goals (this slice)

- **Decision→scene resolution is deferred.** The decision value `0x62ccf` becomes an actual
  `SCxxxx.BIN` via the **native op `u00428010`** + array `0x5f0ed` — the resolution is compiled into
  `AGE.EXE`, not present in any script. We document this as the engine boundary (same bucket as the
  unsolved `call-script` dispatch, see `docs/name-resolution.md §1`) and stop there. No Frida / engine
  dump in this slice.
- **No VM changes** beyond, at most, a minimal headless-seed hook if `vm0.py` lacks one (used only by
  `--verify`; must not alter existing trace/sweep parity).
- Not decoding other flow scripts (FIELD/CAMP dispatch loops) — only SCJUMP's decision production.

## 3. Findings (verified against the bytecode, 2026-07-07)

- **Outputs:** SCJUMP writes exactly two globals, paired at every decision: `mov 0x0, 1`
  (decision-valid flag, always 1) and `mov 0x62ccf, <value>` (the decision). **1755 decision sites,
  847 distinct values, range 0..1693.** `0x62ccf` is our curated `scjump_decision_out`.
- **Top dispatch** switches on `0x3234` (`chapter_mode`): `eq(0x3234==N) ; jcc`. Chapter → block:
  `1→0x81, 2→0x9f, 3→0x1ded, 4→0x1e6d, 5→0x54c1, 6→0x93c4, 7→0x1e868, 8→0x2aa42, 9→0x2b8a3`.
- **Dominant decision inputs** (comparison-read): `0x4dfbc` (1609×), `0x2052e` (1223×), `0x152618`
  (530×) — the progression counters — plus story flags (`0xa63`, `0xa99`, `0x71b`, …).
- **Control flow is a pure DAG:** 1764 `jcc` + 1764 `jmp`, **0 back-edges** (1763 forward edges + 1765
  edges to the END jump `0x2f78d`). No loops → guarded DFS is bounded and safe.
- **jcc semantics** (`0xa0`, argc 3): `jcc(cond, A, B)` — `cond`≠0 → target `A`; `cond`==0 → target
  `B`; an operand `0xffffffff` = fall through to the next instruction. `cond` is a local holding a
  prior comparison result. Example (chapter-1 block entry):
  `ne(L1, 0x6d3, 1) ; jcc(L1, 0xffffffff, 0x9c) ; mov 0x0,1 ; mov 0x62ccf,0 ; jmp END` — decision 0 is
  emitted exactly when `0x6d3 != 1` (the fall-through branch, i.e. `L1` true).
- **Comparison ops** (result→arg0 local, operands arg1/arg2): `eq 0x5a, ne 0x5b, lt 0x5c, lte 0x5d,
  gr 0x5e, gre 0x5f`. **Logical combiners:** `and 0x56, or 0x57` (arg0=dest local, arg1/arg2=source
  locals). `mov 0x55` writes arg0.
- **The consumer is native:** FIELD/CAMP/scenes do `lookup-array(ptr, 0x5f0ed, 0x62ccf)` then
  `u00428010(ptr)` — decision→scene is a native handler. (`lookup-array` = `0x61`.)

## 4. Architecture — `tools/scjump_decode.py`

Static analyzer, reusing `sys4load` for decode and `paths` for location. Three stages.

### 4a. CFG build
Load SCJUMP; collect all jump/jcc code-target offsets (via `is_label_argument`) as block leaders;
split the instruction stream into basic blocks; build the successor graph. Assert acyclic (finding
§3). The END jump target (`0x2f78d`) is a terminal sink.

### 4b. Guarded DFS (the core)
Walk from entry (offset 0) carrying two path-local structures:
- a **guard stack** — the list of asserted condition-expressions along the current path;
- a **local→expression map** — updated whenever a compute op writes a local.

**Expression model** (`Expr`):
- `Cmp(global_addr, op, value)` — from a comparison op where one operand is a global (atype ∈
  {3,4,5,6,8}) and the other an immediate (atype 0). `op ∈ {==,!=,<,<=,>,>=}` from the opcode.
- `And(l, r)`, `Or(l, r)` — from `0x56`/`0x57` combining two locals (resolved via the local map).
- `Opaque(desc)` — any condition we cannot model faithfully (global-vs-global compare, arithmetic
  feeding a condition, an unresolved local). Represented, never silently dropped.

**Traversal:** at `cmp Ln, …` set `localmap[Ln] = Cmp(...)` (or `Opaque`); at `and/or Ln, La, Lb`
set `localmap[Ln] = And/Or(localmap[La], localmap[Lb])`. At `jcc(Lc, A, B)`:
- expr = `localmap.get(Lc, Opaque(Lc))`
- recurse to target `A` (or next instr if `A==0xffffffff`) with guard **`expr` asserted true**;
- recurse to target `B` (or next instr if `B==0xffffffff`) with guard **`Not(expr)`** asserted.

At `mov 0x62ccf, V` emit a decision `{guards: copy of stack, decision: V, site_offset}`. At the END
jump, return. DAG + no revisiting within a path → bounded (~1755 leaves).

**Guard negation** normalizes for readability: `Not(Cmp(g,==,v)) → Cmp(g,!=,v)`, `< ↔ >=`,
`<= ↔ >`, `> ↔ <=`, `>= ↔ <`; `Not(And/Or)` via De Morgan; `Not(Opaque)` kept as a negated-opaque
marker.

### 4c. Chapter attribution
The first guard on every path is `chapter_mode == N` (top dispatch). Tag each decision with that N.
Decisions whose path never asserts a `chapter_mode` equality (shouldn't occur) are tagged `null`.

## 5. Output

- **`build/scjump-decisions.json`** (generated, disposable — `build/` is gitignored): `meta` +
  `decisions[]`, each `{site_offset, chapter, decision_value, guards:[…]}`. Each guard is
  `{global:"0xADDR", name:<from registry or null>, op:"==", value:N}` for `Cmp`, or a nested
  `{and:[…]}`/`{or:[…]}`/`{not:…}`/`{opaque:"desc"}`. Also a `by_chapter` index and summary counts
  (sites, distinct decisions, opaque-guard count).
- **`build/scjump-decisions.md`** (generated, disposable): human table grouped by chapter — each rule
  as `chapter_mode==7 AND 0x6d3!=1 → decision 0`, globals rendered with their **globals.toml registry
  names** (loaded from `build/globals.json`; e.g. `0x3234`→`chapter_mode`).

The generated artifacts live in `build/`; the stable narrative lives in the canonical doc (§8).

## 6. Validation — VM cross-check (`--verify`)

Because the table is a decision function over a deterministic DAG, exactly one path is realized per
concrete state. Validate the decode by **witness synthesis + VM ground truth**:

1. For each decision, **synthesize a witness state** from its guards: collect the per-global
   constraints (equalities and `</<=/>/>=/!=` bounds) and pick a satisfying value per global (solve
   the conjunction; equality wins; inequalities → pick an in-range integer; `!=` → avoid the value).
   If a guard is `Opaque` or the per-global constraints are unsatisfiable by the simple solver, mark
   the decision **uncovered** and skip (reported, not failed).
2. **Run SCJUMP headlessly** with the witness as the initial global bank (via `vm0.py`; add a minimal
   seed hook if absent — must not change existing modes) and read the emitted `0x62ccf`.
3. **Assert** the emitted value equals the decision's value. Any mismatch = a mis-modeled condition →
   hard failure with the offending site.

`--verify` reports: covered/total decisions, and agreement (must be 100% on covered). Optionally also
seed a batch of random `(chapter, counters, flags)` states and check that the single table-predicted
decision (all guards concrete-true) matches the VM — a second, independent check. Coverage < 100% is
expected (opaque guards) and is a documented measure, not a failure.

## 7. Cross-link — name the progression counters

SCJUMP's dominant inputs are the story-progress state. As part of this slice, curate them into
`vm-map/globals.toml` (then `globals_build.py --build`): `0x4dfbc`, `0x2052e`, `0x152618` (and
`0xe6c5d`) as `progress_*` counters (`category = "counter"` or `story-flag` as fits, `source =
inference`, evidence = "top SCJUMP switch input"). This makes both the SCJUMP table and the wider
corpus more readable, and closes the loop with the registry built in the previous slice.

## 8. Docs & canonical map

- **New canonical doc `docs/scjump-progression.md`** (hand-authored, stable narrative): what SCJUMP is,
  the decode mechanism, the **native decision→scene boundary** (`u00428010` + `0x5f0ed`), how to read
  `build/scjump-decisions.{json,md}` and regenerate them, the `--verify` coverage/agreement summary,
  and cross-links to `name-resolution.md §1` (call-script) and `globals.toml`.
- **CLAUDE.md canonical-documents map** — add a row: `Progression / scene-sequencing logic (SCJUMP) →
  docs/scjump-progression.md`.
- **`docs/tools-reference.md`** — add `scjump_decode.py` (+ `test_scjump.py`).
- **`docs/name-resolution.md §1`** — add a back-reference: SCJUMP's *decision logic* is now decoded
  (`scjump-progression.md`); only the native decision→scene hop remains engine-level.
- Update the status memory (`himegari-port-status.md` + `MEMORY.md`).

## 9. Testing — `tools/test_scjump.py`

Standalone script (`check(cond,msg)` pattern, like `test_globals.py`):
- **CFG acyclic** — the built graph has no back-edge (regression-guards the DFS assumption).
- **Chapter dispatch** — extracted chapter→block map equals the known offsets (`1→0x81 … 9→0x2b8a3`).
- **Known decision** — the chapter-1 entry decision decodes to guards `{chapter_mode==1, 0x6d3!=1} →
  decision 0` (hand-traced anchor).
- **Totals** — decode yields 1755 decision sites (regression on the site count).
- **`--verify` sound** — witness cross-check runs on a bounded sample and reports 100% agreement on
  covered decisions (0 mismatches).

## 10. Implementation order (for the plan)

1. `scjump_decode.py`: load + CFG build + acyclic assert; `test_scjump.py` CFG/chapter tests.
2. Guarded DFS + Expr model + negation → in-memory decisions; known-decision + totals tests.
3. Emit `build/scjump-decisions.json` + `build/scjump-decisions.md` (registry-named); JSON shape test.
4. `--verify`: witness synthesis + headless SCJUMP run + agreement report; verify test.
5. Curate progression counters into `globals.toml`; rebuild registry.
6. Docs: `docs/scjump-progression.md`, CLAUDE.md map row, tools-reference, name-resolution back-ref;
   status memory.