# A1 — C# VM Core Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** A headless C# (.NET 8) reimplementation of the validated `vm0.py` AGE/SYS4 model that is per-scene trace-identical to the Python prototype and passes the RECOVER unit test.

**Architecture:** A `.NET 8` class library `Age.Engine` with four seam-namespaces — `Model` (version-neutral `Script` contract), `Vm` (execution core, depends only on `Model` + `Hosting`), `Sys4` (`.BIN` parser + cp932 codec + opcode-table loader), `Hosting` (`IHost` + headless `CaptureHost`) — plus a console `Age.Cli` and an `Age.Engine.Tests` xUnit project. Validated by a per-scene trace diff against `tools/vm0.py --trace`.

**Tech Stack:** C# / .NET 8, xUnit, `System.Text.Json`, `System.Text.Encoding.CodePages` (cp932). Python 3.11 for the `vm0.py --trace` reference.

## Global Constraints

- **Work on a feature branch** (e.g. `feat/a1-csharp-vm`); do not commit to `main`.
- Build: `dotnet build engine/AgeEngine.sln`. Test: `dotnet test engine/AgeEngine.sln` (or `--filter FullyQualifiedName~<Class>`).
- **Seam rule:** `Age.Engine.Vm` may reference only `Age.Engine.Model` and `Age.Engine.Hosting` — never `Age.Engine.Sys4`, never file I/O.
- All VM numeric values are `long`. `div`/`mod` use the Python-parity helpers `PyDiv`/`PyMod` (floor-div; divisor-sign mod). u32 operands load as **unsigned** into `long` (no sign-extension), matching vm0.
- Halt-reason strings must be **byte-identical** to vm0: `"exit"`, `"LOOP:line@0x{off:x}×{count}"` (× = U+00D7), `"STEP-LIMIT"`, `"ret-underflow"`, `"pc-out-of-range"`. Source files are UTF-8.
- Data prerequisites (resolved via `Paths`, repo-relative, like `tools/paths.py`): `build/opcodes.json` (run `tools/opcodes_build.py --build`), `../extracted/DATA1/*.BIN`, and — for the trace-diff — `build/vm0-trace.json` (produced by Task 5).
- Exact format facts (from `tools/sys4load.py`, `tools/vm0.py`): magic prefix `SYS4`, header 0x3C bytes = 8 magic + 13×u32 (F0–F12), body dwords from 0x3C; code section `[0..F8)`; instruction length `1 + 2*argc` dwords; `data_array_end` shrink stops code at the lowest referenced string(type-2)/array(op `0x64` arg index 1) offset; operand types `0=imm 2=string 3=g-int 4=g-float 5=g-string 6=g-ptr 9=l-int 10=l-float 11=l-string 12=l-ptr`; `jcc` sentinel `0xFFFFFFFF` = fallthrough; `ARRAY_OPCODE=0x64`; `EMIT_CAP=2`, `MAX_STEPS=2_000_000`.

---

## File Structure

```
engine/AgeEngine.sln
engine/Age.Engine/Age.Engine.csproj
engine/Age.Engine/Model/    Operand.cs Instruction.cs ScriptHeader.cs Script.cs OpcodeTable.cs
engine/Age.Engine/Sys4/     Paths.cs OpcodeTableJson.cs Sys4StringCodec.cs Sys4Loader.cs
engine/Age.Engine/Vm/       VmOptions.cs Frame.cs VirtualMachine.cs
engine/Age.Engine/Hosting/  IHost.cs CaptureHost.cs
engine/Age.Cli/Age.Cli.csproj  Program.cs
engine/Age.Engine.Tests/Age.Engine.Tests.csproj
   OpcodeTableTests.cs Sys4StringCodecTests.cs Sys4LoaderTests.cs RecoverTests.cs TraceDiffTests.cs
tools/vm0.py  (modify: add --trace)
.gitignore    (modify: ignore engine build output)
```

---

## Task 1: Solution scaffold + Model + OpcodeTable

**Files:** Create the solution, `Age.Engine/Model/*`, `Age.Engine/Sys4/Paths.cs`, `Age.Engine/Sys4/OpcodeTableJson.cs`; Test `Age.Engine.Tests/OpcodeTableTests.cs`; Modify `.gitignore`.

**Interfaces — Produces:**
- `Age.Engine.Model.Operand(int Type, long Value)` (readonly record struct)
- `Age.Engine.Model.Instruction(int Offset, int Opcode, IReadOnlyList<Operand> Args)`
- `Age.Engine.Model.ScriptHeader(int LocalInt1, int LocalFloats, int LocalStrings1, int LocalInt2, int Unknown, int LocalStrings2)`
- `Age.Engine.Model.Script { ScriptHeader Header; IReadOnlyList<Instruction> Instructions; IReadOnlyDictionary<int,int> IndexByOffset; IReadOnlyDictionary<int,string> Strings; string GetString(int) }`
- `Age.Engine.Model.OpcodeTable { bool TryGet(int,out string,out int); string Label(int); int Argc(int); int Count }`
- `Age.Engine.Sys4.OpcodeTableJson.Load(string path) -> OpcodeTable`
- `Age.Engine.Sys4.Paths { string Repo, Extracted, Data1, GameDir, Build, OpcodesJson; Dictionary<string,string> Scripts() }`

- [ ] **Step 1: Scaffold the solution**

```bash
cd "S:/Game Hacking/Eushully/Himegari/age-reimpl"
dotnet new sln -n AgeEngine -o engine
dotnet new classlib -n Age.Engine -o engine/Age.Engine -f net8.0
dotnet new console  -n Age.Cli    -o engine/Age.Cli    -f net8.0
dotnet new xunit    -n Age.Engine.Tests -o engine/Age.Engine.Tests -f net8.0
rm -f engine/Age.Engine/Class1.cs engine/Age.Engine.Tests/UnitTest1.cs
dotnet sln engine/AgeEngine.sln add engine/Age.Engine engine/Age.Cli engine/Age.Engine.Tests
dotnet add engine/Age.Cli reference engine/Age.Engine
dotnet add engine/Age.Engine.Tests reference engine/Age.Engine
dotnet add engine/Age.Engine package System.Text.Encoding.CodePages
```

- [ ] **Step 2: Ignore .NET build output** — append to `.gitignore`:

```
# .NET (engine/) build output
engine/**/bin/
engine/**/obj/
.vs/
```

- [ ] **Step 3: Write the failing test** — `engine/Age.Engine.Tests/OpcodeTableTests.cs`:

```csharp
using Age.Engine.Sys4;
using Xunit;

public class OpcodeTableTests
{
    [Fact]
    public void LoadsAll248FromJson()
    {
        var t = OpcodeTableJson.Load(Paths.OpcodesJson);
        Assert.Equal(248, t.Count);
        Assert.True(t.TryGet(0x55, out var label, out var argc));
        Assert.Equal("mov", label);
        Assert.Equal(2, argc);
        Assert.Equal("u0041BEB0", t.Label(0x90));
        Assert.Equal(7, t.Argc(0x90));
        Assert.Equal(-1, t.Argc(0x9999)); // absent -> -1
    }
}
```

- [ ] **Step 4: Run — expect FAIL (types missing / won't compile)**

```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~OpcodeTableTests
```
Expected: build error — `Paths`/`OpcodeTableJson` do not exist.

- [ ] **Step 5: Implement Model + Paths + OpcodeTableJson**

`engine/Age.Engine/Model/Operand.cs`:
```csharp
namespace Age.Engine.Model;
public readonly record struct Operand(int Type, long Value);
```
`engine/Age.Engine/Model/Instruction.cs`:
```csharp
namespace Age.Engine.Model;
public sealed record Instruction(int Offset, int Opcode, IReadOnlyList<Operand> Args);
```
`engine/Age.Engine/Model/ScriptHeader.cs`:
```csharp
namespace Age.Engine.Model;
public sealed record ScriptHeader(
    int LocalInt1, int LocalFloats, int LocalStrings1,
    int LocalInt2, int Unknown, int LocalStrings2);
```
`engine/Age.Engine/Model/Script.cs`:
```csharp
namespace Age.Engine.Model;
public sealed class Script
{
    public required ScriptHeader Header { get; init; }
    public required IReadOnlyList<Instruction> Instructions { get; init; }
    public required IReadOnlyDictionary<int, int> IndexByOffset { get; init; }
    public required IReadOnlyDictionary<int, string> Strings { get; init; }
    public string GetString(int offset) => Strings.TryGetValue(offset, out var s) ? s : "";
}
```
`engine/Age.Engine/Model/OpcodeTable.cs`:
```csharp
namespace Age.Engine.Model;
public sealed class OpcodeTable
{
    private readonly IReadOnlyDictionary<int, (string Label, int Argc)> _t;
    public OpcodeTable(IReadOnlyDictionary<int, (string, int)> t) => _t = t;
    public int Count => _t.Count;
    public bool TryGet(int op, out string label, out int argc)
    {
        if (_t.TryGetValue(op, out var e)) { label = e.Label; argc = e.Argc; return true; }
        label = ""; argc = -1; return false;
    }
    public string Label(int op) => _t.TryGetValue(op, out var e) ? e.Label : "";
    public int Argc(int op) => _t.TryGetValue(op, out var e) ? e.Argc : -1;
}
```
`engine/Age.Engine/Sys4/Paths.cs`:
```csharp
namespace Age.Engine.Sys4;
public static class Paths
{
    public static string Repo { get; } = FindRepo();
    public static string Workspace => Directory.GetParent(Repo)!.FullName;
    public static string Extracted => Path.Combine(Workspace, "extracted");
    public static string Data1 => Path.Combine(Extracted, "DATA1");
    public static string GameDir => Path.Combine(Workspace, "Himegari_Game");
    public static string Build => Path.Combine(Repo, "build");
    public static string OpcodesJson => Path.Combine(Build, "opcodes.json");

    private static string FindRepo()
    {
        var d = new DirectoryInfo(AppContext.BaseDirectory);
        while (d != null && d.Name != "age-reimpl") d = d.Parent;
        if (d == null) throw new DirectoryNotFoundException(
            "age-reimpl root not found above " + AppContext.BaseDirectory);
        return d.FullName;
    }

    /// name(UPPER).BIN -> path; game-dir loose overrides shadow extracted/DATA1 (mirrors paths.scripts()).
    public static Dictionary<string, string> Scripts()
    {
        var d = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        if (Directory.Exists(Data1))
            foreach (var p in Directory.EnumerateFiles(Data1, "*.BIN"))
                d[Path.GetFileName(p).ToUpperInvariant()] = p;
        if (Directory.Exists(GameDir))
            foreach (var p in Directory.EnumerateFiles(GameDir, "*.BIN"))
                d[Path.GetFileName(p).ToUpperInvariant()] = p;
        return d;
    }
}
```
`engine/Age.Engine/Sys4/OpcodeTableJson.cs`:
```csharp
using System.Text.Json;
using Age.Engine.Model;
namespace Age.Engine.Sys4;
public static class OpcodeTableJson
{
    public static OpcodeTable Load(string path)
    {
        using var doc = JsonDocument.Parse(File.ReadAllText(path));
        var dict = new Dictionary<int, (string, int)>();
        foreach (var e in doc.RootElement.GetProperty("opcodes").EnumerateArray())
        {
            int op = Convert.ToInt32(e.GetProperty("op").GetString(), 16);
            string label = e.GetProperty("label").GetString() ?? "";
            int argc = e.GetProperty("argc").GetInt32();
            dict[op] = (label, argc);
        }
        return new OpcodeTable(dict);
    }
}
```

- [ ] **Step 6: Run — expect PASS**

```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~OpcodeTableTests
```
Expected: 1 passed. (Prereq: `tools/opcodes_build.py --build` has produced `build/opcodes.json`.)

- [ ] **Step 7: Commit**
```bash
git add engine .gitignore
git commit -m "feat(a1): .NET 8 solution scaffold + Model + OpcodeTable loader"
```

---

## Task 2: SYS4 string codec

**Files:** Create `Age.Engine/Sys4/Sys4StringCodec.cs`; Test `Age.Engine.Tests/Sys4StringCodecTests.cs`.

**Interfaces — Produces:** `Sys4StringCodec.Decode(IReadOnlyList<uint> dwords, int start, int limit = 4096) -> (string? Text, int NDwords)` — XOR-`0xFFFFFFFF` per little-endian dword, cut at first NUL, strict cp932 validation (returns `(null,0)` when not a clean string), else decoded text + dword length including the NUL dword.

- [ ] **Step 1: Write the failing test** — `engine/Age.Engine.Tests/Sys4StringCodecTests.cs`:

```csharp
using Age.Engine.Sys4;
using Xunit;

public class Sys4StringCodecTests
{
    [Fact]
    public void DecodesXorFfCp932Ascii()
    {
        // "AB\0\0" little-endian = 0x00004241, stored XOR 0xFFFFFFFF
        uint[] dw = { 0x00004241u ^ 0xFFFFFFFFu };
        var (text, nd) = Sys4StringCodec.Decode(dw, 0);
        Assert.Equal("AB", text);
        Assert.Equal(1, nd);
    }

    [Fact]
    public void RejectsNonString()
    {
        // 0x00000000 XOR-decodes to 0xFFFFFFFF bytes (0xFF,0xFF,0xFF,0xFF) -> no NUL, invalid
        uint[] dw = { 0x00000000u };
        var (text, _) = Sys4StringCodec.Decode(dw, 0);
        Assert.Null(text);
    }
}
```

- [ ] **Step 2: Run — expect FAIL** (`Sys4StringCodec` missing)
```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~Sys4StringCodecTests
```

- [ ] **Step 3: Implement** — `engine/Age.Engine/Sys4/Sys4StringCodec.cs`:

```csharp
using System.Text;
namespace Age.Engine.Sys4;
public static class Sys4StringCodec
{
    static Sys4StringCodec() => Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
    private static readonly Encoding Cp932 = Encoding.GetEncoding(932);

    public static (string? Text, int NDwords) Decode(IReadOnlyList<uint> dwords, int start, int limit = 4096)
    {
        int n = dwords.Count, end = Math.Min(start + limit, n);
        var raw = new List<byte>();
        bool sawNul = false;
        for (int j = start; j < end; j++)
        {
            uint x = dwords[j] ^ 0xFFFFFFFFu;
            raw.Add((byte)(x & 0xFF)); raw.Add((byte)((x >> 8) & 0xFF));
            raw.Add((byte)((x >> 16) & 0xFF)); raw.Add((byte)((x >> 24) & 0xFF));
            if (raw[^1] == 0 || raw[^2] == 0 || raw[^3] == 0 || raw[^4] == 0) { sawNul = true; break; }
        }
        if (!sawNul) return (null, 0);
        int nul = raw.IndexOf(0);
        byte[] s = raw.GetRange(0, nul < 0 ? raw.Count : nul).ToArray();
        if (s.Length < 1) return ("", 1);
        int i = 0, chars = 0;
        while (i < s.Length)
        {
            byte b = s[i];
            if (b >= 0x20 && b <= 0x7E) { i++; chars++; }
            else if ((b >= 0x81 && b <= 0x9F) || (b >= 0xE0 && b <= 0xEA))
            {
                if (i + 1 < s.Length && s[i + 1] >= 0x40 && s[i + 1] <= 0xFC && s[i + 1] != 0x7F) { i += 2; chars++; }
                else return (null, 0);
            }
            else return (null, 0);
        }
        if (chars < 1) return (null, 0);
        string text;
        try { text = Cp932.GetString(s); } catch { return (null, 0); }
        return (text, (s.Length / 4) + 1);
    }
}
```

- [ ] **Step 4: Run — expect PASS**
```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~Sys4StringCodecTests
```

- [ ] **Step 5: Commit**
```bash
git add engine/Age.Engine/Sys4/Sys4StringCodec.cs engine/Age.Engine.Tests/Sys4StringCodecTests.cs
git commit -m "feat(a1): SYS4 XOR-FF cp932 string codec"
```

---

## Task 3: SYS4 container parser (`Sys4Loader`)

**Files:** Create `Age.Engine/Sys4/Sys4Loader.cs`; Test `Age.Engine.Tests/Sys4LoaderTests.cs`.

**Interfaces — Consumes:** `OpcodeTable`, `Sys4StringCodec`, `Script`. **Produces:** `Sys4Loader.Load(string path, OpcodeTable table) -> Script`; `Sys4Loader.Parse(byte[] data, OpcodeTable table, string name = "") -> Script`.

- [ ] **Step 1: Write the failing test** — `engine/Age.Engine.Tests/Sys4LoaderTests.cs`:

```csharp
using Age.Engine.Sys4;
using Xunit;

public class Sys4LoaderTests
{
    [Fact]
    public void ParsesMenuBinLikeSys4load()
    {
        var table = OpcodeTableJson.Load(Paths.OpcodesJson);
        var s = Sys4Loader.Load(Path.Combine(Paths.Data1, "MENU.BIN"), table);
        // header F0..F5 from `sys4load MENU.BIN --summary`
        Assert.Equal(0x17, s.Header.LocalInt1);
        Assert.Equal(1, s.Header.LocalFloats);
        Assert.Equal(1, s.Header.LocalStrings1);
        Assert.Equal(2, s.Header.LocalInt2);
        Assert.Equal(1, s.Header.Unknown);
        Assert.Equal(1, s.Header.LocalStrings2);
        Assert.Equal(148, s.Instructions.Count);   // sys4load: 148 instructions
        Assert.Equal(3, s.Strings.Count);           // sys4load: 3 inline strings
        // every instruction offset is indexed
        Assert.All(s.Instructions, ins => Assert.True(s.IndexByOffset.ContainsKey(ins.Offset)));
    }
}
```

- [ ] **Step 2: Run — expect FAIL** (`Sys4Loader` missing)
```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~Sys4LoaderTests
```

- [ ] **Step 3: Implement** — `engine/Age.Engine/Sys4/Sys4Loader.cs`:

```csharp
using Age.Engine.Model;
namespace Age.Engine.Sys4;
public static class Sys4Loader
{
    private const int HeaderSize = 0x3C, BodyOff = 0x3C, NumFields = 13, ArrayOpcode = 0x64;

    public static Script Load(string path, OpcodeTable table)
        => Parse(File.ReadAllBytes(path), table, Path.GetFileName(path));

    public static Script Parse(byte[] data, OpcodeTable table, string name = "")
    {
        if (data.Length < HeaderSize) throw new InvalidDataException($"{name}: too small");
        if (!(data[0] == (byte)'S' && data[1] == (byte)'Y' && data[2] == (byte)'S' && data[3] == (byte)'4'))
            throw new InvalidDataException($"{name}: bad magic");
        if (data.Length % 4 != 0) throw new InvalidDataException($"{name}: not dword-aligned");

        var fields = new int[NumFields];
        for (int k = 0; k < NumFields; k++) fields[k] = BitConverter.ToInt32(data, 8 + k * 4);
        int nbody = (data.Length - BodyOff) / 4;
        var dw = new uint[nbody];
        for (int k = 0; k < nbody; k++) dw[k] = BitConverter.ToUInt32(data, BodyOff + k * 4);

        var header = new ScriptHeader(fields[0], fields[1], fields[2], fields[3], fields[4], fields[5]);
        var (instrs, idxByOff, strings) = DecodeCode(dw, fields, nbody, table);
        return new Script { Header = header, Instructions = instrs, IndexByOffset = idxByOff, Strings = strings };
    }

    private static (List<Instruction>, Dictionary<int, int>, Dictionary<int, string>)
        DecodeCode(uint[] dw, int[] fields, int nbody, OpcodeTable table)
    {
        int codeEnd = fields[8];                       // F8; shrinks to first inline string/array offset
        var instrs = new List<Instruction>();
        var idx = new Dictionary<int, int>();
        var strings = new Dictionary<int, string>();
        int i = 0;
        while (i < codeEnd)
        {
            int op = (int)dw[i];
            int argc = table.Argc(op);
            if (argc < 0) { idx[i] = instrs.Count; instrs.Add(new Instruction(i, op, Array.Empty<Operand>())); break; }
            int baseI = i + 1;
            if (baseI + 2 * argc > codeEnd) { idx[i] = instrs.Count; instrs.Add(new Instruction(i, op, Array.Empty<Operand>())); break; }
            var args = new Operand[argc];
            for (int a = 0; a < argc; a++)
            {
                int atype = (int)dw[baseI + 2 * a];
                long aval = dw[baseI + 2 * a + 1];
                args[a] = new Operand(atype, aval);
                if (atype == 2 && aval >= 0 && aval < nbody)
                {
                    if (aval < codeEnd) codeEnd = (int)aval;
                    if (!strings.ContainsKey((int)aval))
                    {
                        var (text, _) = Sys4StringCodec.Decode(dw, (int)aval);
                        if (text != null) strings[(int)aval] = text;
                    }
                }
                else if (op == ArrayOpcode && a == 1 && aval >= 0 && aval < nbody)
                {
                    if (aval < codeEnd) codeEnd = (int)aval;
                }
            }
            idx[i] = instrs.Count;
            instrs.Add(new Instruction(i, op, args));
            i = baseI + 2 * argc;
        }
        return (instrs, idx, strings);
    }
}
```

- [ ] **Step 4: Run — expect PASS**
```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~Sys4LoaderTests
```
Expected: 1 passed (148 instructions, 3 strings, header matches). If instruction count differs, the `data_array_end` shrink or argc walk diverged — compare against `py -3.11 -X utf8 tools/sys4load.py ../extracted/DATA1/MENU.BIN --summary`.

- [ ] **Step 5: Commit**
```bash
git add engine/Age.Engine/Sys4/Sys4Loader.cs engine/Age.Engine.Tests/Sys4LoaderTests.cs
git commit -m "feat(a1): SYS4 container parser (header + code decode + data_array_end shrink)"
```

---

## Task 4: VM core + IHost/CaptureHost + RECOVER

**Files:** Create `Age.Engine/Hosting/IHost.cs`, `Age.Engine/Hosting/CaptureHost.cs`, `Age.Engine/Vm/VmOptions.cs`, `Age.Engine/Vm/Frame.cs`, `Age.Engine/Vm/VirtualMachine.cs`; Test `Age.Engine.Tests/RecoverTests.cs`.

**Interfaces — Consumes:** `Script`, `OpcodeTable`, `Sys4Loader`. **Produces:**
- `Age.Engine.Hosting.IHost { void ShowText(int,string); void CallScript(long); void OnStub(int); }`, `CaptureHost : IHost`
- `Age.Engine.Vm.VmOptions(int EmitCap = 2, long MaxSteps = 2_000_000)`
- `Age.Engine.Vm.VirtualMachine(Script, OpcodeTable, IHost, VmOptions? = null)` with public `Dictionary<int,long> Globals`, `Dictionary<int,string> GlobalStrings`, `List<(int Offset,string Text)> Emitted`, `string? HaltReason`, `long Steps`, and `void Run(int entryOffset = 0)`.

- [ ] **Step 1: Write the failing test** — `engine/Age.Engine.Tests/RecoverTests.cs`:

```csharp
using Age.Engine.Hosting;
using Age.Engine.Sys4;
using Age.Engine.Vm;
using Xunit;

public class RecoverTests
{
    private static long G(VirtualMachine vm, int k) => vm.Globals.TryGetValue(k, out var v) ? v : 0;

    [Fact]
    public void RecoverUnitTestPasses()
    {
        var table = OpcodeTableJson.Load(Paths.OpcodesJson);
        var script = Sys4Loader.Load(Path.Combine(Paths.Data1, "RECOVER.BIN"), table);
        var vm = new VirtualMachine(script, table, new CaptureHost());

        int unit = 0;
        vm.Globals[0x152616] = unit;
        int A = 0x4e11b, B = 0x4e085, C = 0x52383, E = 0x52f3b, F = 0x5295f, FL = 0xaacb4;
        for (int k = 0; k < 3; k++) vm.Globals[A + unit * 14 + (11 + k)] = 100 + k;
        vm.Globals[C + unit * 30 + 5] = 7; vm.Globals[FL + 5] = 1; vm.Globals[E + unit * 30 + 5] = 42;
        vm.Globals[C + unit * 30 + 6] = 0; vm.Globals[FL + 6] = 1; vm.Globals[E + unit * 30 + 6] = 99;
        vm.Globals[C + unit * 30 + 7] = 3; vm.Globals[FL + 7] = 0; vm.Globals[E + unit * 30 + 7] = 88;
        vm.Run();

        Assert.Equal(100, G(vm, B + unit * 3 + 0));
        Assert.Equal(101, G(vm, B + unit * 3 + 1));
        Assert.Equal(102, G(vm, B + unit * 3 + 2));
        Assert.Equal(42, G(vm, C + unit * 30 + 5));
        Assert.Equal(-1, G(vm, F + unit * 30 + 5));
        Assert.Equal(0, G(vm, C + unit * 30 + 6));
        Assert.Equal(3, G(vm, C + unit * 30 + 7));
    }
}
```

- [ ] **Step 2: Run — expect FAIL** (VM types missing)
```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~RecoverTests
```

- [ ] **Step 3: Implement hosting + VM**

`engine/Age.Engine/Hosting/IHost.cs`:
```csharp
namespace Age.Engine.Hosting;
public interface IHost
{
    void ShowText(int offset, string text);
    void CallScript(long id);
    void OnStub(int opcode);
}
```
`engine/Age.Engine/Hosting/CaptureHost.cs`:
```csharp
namespace Age.Engine.Hosting;
public sealed class CaptureHost : IHost
{
    public List<(int Offset, string Text)> Emitted { get; } = new();
    public int CallScriptCount { get; private set; }
    public Dictionary<int, int> Stubs { get; } = new();
    public void ShowText(int offset, string text) => Emitted.Add((offset, text));
    public void CallScript(long id) => CallScriptCount++;
    public void OnStub(int opcode) { Stubs.TryGetValue(opcode, out var c); Stubs[opcode] = c + 1; }
}
```
`engine/Age.Engine/Vm/VmOptions.cs`:
```csharp
namespace Age.Engine.Vm;
public sealed record VmOptions(int EmitCap = 2, long MaxSteps = 2_000_000);
```
`engine/Age.Engine/Vm/Frame.cs`:
```csharp
namespace Age.Engine.Vm;
public sealed class Frame
{
    public Dictionary<int, long> I = new();   // local-int
    public Dictionary<int, long> F = new();   // local-float (raw)
    public Dictionary<int, string> S = new(); // local-string
    public Dictionary<int, long> P = new();   // local-ptr (holds a global address)
}
```
`engine/Age.Engine/Vm/VirtualMachine.cs`:
```csharp
using Age.Engine.Hosting;
using Age.Engine.Model;
namespace Age.Engine.Vm;

public sealed class VirtualMachine
{
    private const long NoJump = 0xFFFFFFFF;
    private const int HALT = int.MinValue;
    private const int T_IMM = 0, T_STR = 2, T_GINT = 3, T_GFLOAT = 4, T_GSTR = 5, T_GPTR = 6,
                      T_LINT = 9, T_LFLOAT = 10, T_LSTR = 11, T_LPTR = 12;

    private readonly Script _s;
    private readonly OpcodeTable _t;
    private readonly IHost _host;
    private readonly VmOptions _o;
    private readonly Frame _fr = new();
    private readonly List<int> _callstack = new();
    private readonly Dictionary<int, int> _emitSeen = new();

    public Dictionary<int, long> Globals { get; } = new();
    public Dictionary<int, string> GlobalStrings { get; } = new();
    public List<(int Offset, string Text)> Emitted { get; } = new();
    public string? HaltReason { get; private set; }
    public long Steps { get; private set; }

    public VirtualMachine(Script s, OpcodeTable t, IHost host, VmOptions? o = null)
    { _s = s; _t = t; _host = host; _o = o ?? new VmOptions(); }

    private static long Gi(Dictionary<int, long> d, int k) => d.TryGetValue(k, out var v) ? v : 0;
    private static string Gs(Dictionary<int, string> d, int k) => d.TryGetValue(k, out var v) ? v : "";
    private static long PyDiv(long a, long b) { if (b == 0) return 0; long q = a / b, r = a % b; if (r != 0 && (r < 0) != (b < 0)) q--; return q; }
    private static long PyMod(long a, long b) { if (b == 0) return 0; long r = a % b; if (r != 0 && (r < 0) != (b < 0)) r += b; return r; }

    private static bool IsStr(Operand o) => o.Type == T_STR || o.Type == T_GSTR || o.Type == T_LSTR;

    private long Read(Operand op) => op.Type switch
    {
        T_IMM => op.Value,
        T_GINT or T_GFLOAT => Gi(Globals, (int)op.Value),
        T_GPTR => Gi(Globals, (int)Gi(Globals, (int)op.Value)),
        T_LINT => Gi(_fr.I, (int)op.Value),
        T_LFLOAT => Gi(_fr.F, (int)op.Value),
        T_LPTR => Gi(Globals, (int)Gi(_fr.P, (int)op.Value)),
        _ => op.Value,
    };

    private void Write(Operand op, long val)
    {
        switch (op.Type)
        {
            case T_GINT: case T_GFLOAT: Globals[(int)op.Value] = val; break;
            case T_GPTR: Globals[(int)Gi(Globals, (int)op.Value)] = val; break;
            case T_LINT: _fr.I[(int)op.Value] = val; break;
            case T_LFLOAT: _fr.F[(int)op.Value] = val; break;
            case T_LPTR: Globals[(int)Gi(_fr.P, (int)op.Value)] = val; break;
        }
    }

    private string ReadStr(Operand op) => op.Type switch
    {
        T_STR => _s.GetString((int)op.Value),
        T_GSTR => Gs(GlobalStrings, (int)op.Value),
        T_LSTR => Gs(_fr.S, (int)op.Value),
        _ => "",
    };

    private void WriteStr(Operand op, string val)
    {
        switch (op.Type)
        {
            case T_GSTR: GlobalStrings[(int)op.Value] = val; break;
            case T_LSTR: _fr.S[(int)op.Value] = val; break;
        }
    }

    private long BaseAddr(Operand op) => op.Type switch
    {
        T_IMM or T_GINT or T_GFLOAT or T_GSTR or T_GPTR => op.Value,
        T_LINT => Gi(_fr.I, (int)op.Value),
        T_LPTR => Gi(_fr.P, (int)op.Value),
        _ => op.Value,
    };

    private void LookupStore(Operand dst, long addr)
    {
        switch (dst.Type)
        {
            case T_LPTR: _fr.P[(int)dst.Value] = addr; break;
            case T_GPTR: Globals[(int)dst.Value] = addr; break;
            default: Write(dst, Gi(Globals, (int)addr)); break;
        }
    }

    public void Run(int entryOffset = 0)
    {
        int pc = _s.IndexByOffset.TryGetValue(entryOffset, out var idx) ? idx : 0;
        while (pc >= 0 && pc < _s.Instructions.Count)
        {
            if (Steps >= _o.MaxSteps) { HaltReason ??= "STEP-LIMIT"; return; }
            Steps++;
            int next = Step(_s.Instructions[pc], pc);
            if (next == HALT) return;
            pc = next;
        }
        HaltReason ??= "pc-out-of-range";
    }

    private int Step(Instruction ins, int pc)
    {
        int op = ins.Opcode;
        var a = ins.Args;
        switch (_t.Label(op))
        {
            case "add": Write(a[0], Read(a[1]) + Read(a[2])); return pc + 1;
            case "sub": Write(a[0], Read(a[1]) - Read(a[2])); return pc + 1;
            case "mul": Write(a[0], Read(a[1]) * Read(a[2])); return pc + 1;
            case "div": Write(a[0], PyDiv(Read(a[1]), Read(a[2]))); return pc + 1;
            case "mod": Write(a[0], PyMod(Read(a[1]), Read(a[2]))); return pc + 1;
            case "and": Write(a[0], Read(a[1]) & Read(a[2])); return pc + 1;
            case "or":  Write(a[0], Read(a[1]) | Read(a[2])); return pc + 1;
            case "sar": Write(a[0], Read(a[1]) >> (int)(Read(a[2]) & 31)); return pc + 1;
            case "shl": Write(a[0], Read(a[1]) << (int)(Read(a[2]) & 31)); return pc + 1;
            case "eq":  Write(a[0], Read(a[1]) == Read(a[2]) ? 1 : 0); return pc + 1;
            case "ne":  Write(a[0], Read(a[1]) != Read(a[2]) ? 1 : 0); return pc + 1;
            case "lt":  Write(a[0], Read(a[1]) <  Read(a[2]) ? 1 : 0); return pc + 1;
            case "lte": Write(a[0], Read(a[1]) <= Read(a[2]) ? 1 : 0); return pc + 1;
            case "gr":  Write(a[0], Read(a[1]) >  Read(a[2]) ? 1 : 0); return pc + 1;
            case "gre": Write(a[0], Read(a[1]) >= Read(a[2]) ? 1 : 0); return pc + 1;
            case "mov":
            case "set-string":
                if (IsStr(a[0]) || IsStr(a[1])) WriteStr(a[0], ReadStr(a[1]));
                else Write(a[0], Read(a[1]));
                return pc + 1;
            case "lookup-array":
                LookupStore(a[0], BaseAddr(a[1]) + Read(a[2])); return pc + 1;
            case "lookup-array-2d":
                LookupStore(a[0], BaseAddr(a[1]) + Read(a[2]) * Read(a[3]) + Read(a[4])); return pc + 1;
            case "bit-set": Write(a[0], Read(a[0]) | Read(a[1])); return pc + 1;
            case "bit-reset": Write(a[0], Read(a[0]) & ~Read(a[1])); return pc + 1;
            case "check-bit": Write(a[0], (Read(a[1]) >> (int)(Read(a[2]) & 31)) & 1); return pc + 1;
            case "copy-to-global": Write(a[0], Read(a[1])); return pc + 1;
            case "jmp": return _s.IndexByOffset.GetValueOrDefault((int)a[0].Value, pc + 1);
            case "call": _callstack.Add(pc + 1); return _s.IndexByOffset.GetValueOrDefault((int)a[0].Value, pc + 1);
            case "ret":
                if (_callstack.Count > 0) { int r = _callstack[^1]; _callstack.RemoveAt(_callstack.Count - 1); return r; }
                HaltReason = "ret-underflow"; return HALT;
            case "jcc":
            {
                long tgt = Read(a[0]) != 0 ? a[1].Value : a[2].Value;
                return tgt == NoJump ? pc + 1 : _s.IndexByOffset.GetValueOrDefault((int)tgt, pc + 1);
            }
            case "exit":
            case "exit-script": HaltReason = "exit"; return HALT;
            case "call-script": _host.CallScript(a.Count > 0 ? Read(a[0]) : 0); return pc + 1;
            case "show-text":
                foreach (var o in a)
                {
                    if (o.Type != T_STR) continue;
                    int off = (int)o.Value;
                    _emitSeen.TryGetValue(off, out var c); c++; _emitSeen[off] = c;
                    if (c > _o.EmitCap) { HaltReason = $"LOOP:line@0x{off:x}×{c}"; return HALT; }
                    string text = _s.GetString(off);
                    Emitted.Add((off, text));
                    _host.ShowText(off, text);
                }
                return pc + 1;
            case "end-text-line": case "wait-for-input": case "set-font":
            case "comment": case "display-furigana": case "dev_ukn":
                return pc + 1;
            default:
                _host.OnStub(op); return pc + 1;
        }
    }
}
```

- [ ] **Step 4: Run — expect PASS**
```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~RecoverTests
```
Expected: RECOVER passes (all 7 asserts). If a pointer/array assert fails, compare against `py -3.11 -X utf8 tools/vm0.py --test`.

- [ ] **Step 5: Commit**
```bash
git add engine/Age.Engine/Hosting engine/Age.Engine/Vm engine/Age.Engine.Tests/RecoverTests.cs
git commit -m "feat(a1): VM core (operands+pointer semantics, handlers, emit-cap) + RECOVER"
```

---

## Task 5: `Age.Cli` + `vm0.py --trace` + per-scene trace diff

**Files:** Modify `tools/vm0.py` (add `--trace`); Create `engine/Age.Cli/Program.cs`; Test `Age.Engine.Tests/TraceDiffTests.cs`.

**Interfaces — Consumes:** `Paths.Scripts()`, `Sys4Loader`, `OpcodeTableJson`, `VirtualMachine`, `CaptureHost`. **Produces (shared trace contract):** JSON object `{ "<SCENE>.BIN": { "offsets": [int...], "halt": "<reason>", "steps": int }, ... }` over the sorted set of names matching `^S[CP]\d{4}\.BIN$` from `Paths.Scripts()`. Both `vm0.py --trace <out>` and `Age.Cli trace <out>` emit exactly this.

- [ ] **Step 1: Write the failing test** — `engine/Age.Engine.Tests/TraceDiffTests.cs`:

```csharp
using System.Text.Json;
using System.Text.RegularExpressions;
using Age.Engine.Hosting;
using Age.Engine.Sys4;
using Age.Engine.Vm;
using Xunit;

public class TraceDiffTests
{
    private static readonly Regex Scene = new(@"^S[CP]\d{4}\.BIN$");

    [Fact]
    public void CsTraceMatchesVm0PerScene()
    {
        string refPath = Path.Combine(Paths.Build, "vm0-trace.json");
        Assert.True(File.Exists(refPath),
            "prerequisite: run `py -3.11 -X utf8 tools/vm0.py --trace build/vm0-trace.json`");

        using var doc = JsonDocument.Parse(File.ReadAllText(refPath));
        var expected = doc.RootElement;
        var table = OpcodeTableJson.Load(Paths.OpcodesJson);
        var scripts = Paths.Scripts();

        var mismatches = new List<string>();
        foreach (var name in scripts.Keys.Where(n => Scene.IsMatch(n)).OrderBy(n => n, StringComparer.Ordinal))
        {
            var script = Sys4Loader.Load(scripts[name], table);
            var vm = new VirtualMachine(script, table, new CaptureHost());
            vm.Run();
            var offsets = vm.Emitted.Select(e => e.Offset).ToArray();

            if (!expected.TryGetProperty(name, out var exp)) { mismatches.Add($"{name}: absent in vm0 trace"); continue; }
            var expOffsets = exp.GetProperty("offsets").EnumerateArray().Select(x => x.GetInt32()).ToArray();
            string expHalt = exp.GetProperty("halt").GetString() ?? "";
            long expSteps = exp.GetProperty("steps").GetInt64();

            if (!offsets.SequenceEqual(expOffsets))
                mismatches.Add($"{name}: offsets differ (cs {offsets.Length} vs vm0 {expOffsets.Length}; first diff at {FirstDiff(offsets, expOffsets)})");
            else if (vm.HaltReason != expHalt) mismatches.Add($"{name}: halt cs='{vm.HaltReason}' vs vm0='{expHalt}'");
            else if (vm.Steps != expSteps) mismatches.Add($"{name}: steps cs={vm.Steps} vs vm0={expSteps}");
        }
        Assert.True(mismatches.Count == 0, "scene mismatches:\n" + string.Join("\n", mismatches.Take(20)));
    }

    private static int FirstDiff(int[] a, int[] b)
    {
        int n = Math.Min(a.Length, b.Length);
        for (int i = 0; i < n; i++) if (a[i] != b[i]) return i;
        return n;
    }
}
```

- [ ] **Step 2: Add `--trace` to `tools/vm0.py`** — insert this function before `def main(` and a branch in `main`:

```python
def run_trace(out_path):
    """Dump per-scene emitted show-text offsets + halt + steps for the differential test."""
    oracle = load_oracle()
    scripts = paths.scripts()
    names = sorted(n for n in scripts if SCENE_RE.match(n))
    trace = {}
    for name in names:
        r = run_scene(name, scripts[name], oracle)
        vm = r["vm"]
        trace[name] = {"offsets": [off for off, _ in vm.text],
                       "halt": vm.halt_reason, "steps": vm.steps}
    Path(out_path).write_text(json.dumps(trace, ensure_ascii=False), encoding="utf-8")
    print(f"trace: {len(trace)} scenes -> {out_path}")
    return 0
```

In `main`, add the branch (after the `--sweep` branch):
```python
    if argv[0] == "--trace":
        return run_trace(argv[1])
```

- [ ] **Step 3: Generate the reference trace and confirm it matches the sweep**
```bash
cd "S:/Game Hacking/Eushully/Himegari/age-reimpl"
py -3.11 -X utf8 tools/vm0.py --trace build/vm0-trace.json
py -3.11 -X utf8 -c "import json; d=json.load(open('build/vm0-trace.json',encoding='utf-8')); print(len(d),'scenes')"
```
Expected: `trace: N scenes -> build/vm0-trace.json` and the count prints (≈297 SC/SP names).

- [ ] **Step 4: Run the C# test — expect FAIL** (Program/CLI not needed yet, but the test drives the C# VM directly)
```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~TraceDiffTests
```
Expected: FAIL only if a scene diverges — the message names the scene + first differing offset index. Investigate each divergence against `tools/vm0.py --scene <NAME>`; fix the VM/parser until the trace is identical. (If it passes first try, even better.)

- [ ] **Step 5: Implement the CLI** — `engine/Age.Cli/Program.cs`:

```csharp
using System.Text.Json;
using System.Text.RegularExpressions;
using Age.Engine.Hosting;
using Age.Engine.Sys4;
using Age.Engine.Vm;

var table = OpcodeTableJson.Load(Paths.OpcodesJson);

if (args.Length == 0) { Console.WriteLine("usage: run <file> | trace <out.json>"); return 1; }

if (args[0] == "run")
{
    var script = Sys4Loader.Load(args[1], table);
    var vm = new VirtualMachine(script, table, new CaptureHost());
    vm.Run();
    Console.WriteLine($"{Path.GetFileName(args[1])}: {vm.Steps} steps, {vm.Emitted.Count} show-text (halt: {vm.HaltReason})");
    foreach (var (off, text) in vm.Emitted.Take(20)) Console.WriteLine($"  [{off:x}] {text}");
    return 0;
}

if (args[0] == "trace")
{
    var scene = new Regex(@"^S[CP]\d{4}\.BIN$");
    var scripts = Paths.Scripts();
    var trace = new SortedDictionary<string, object>(StringComparer.Ordinal);
    foreach (var name in scripts.Keys.Where(n => scene.IsMatch(n)).OrderBy(n => n, StringComparer.Ordinal))
    {
        var vm = new VirtualMachine(Sys4Loader.Load(scripts[name], table), table, new CaptureHost());
        vm.Run();
        trace[name] = new { offsets = vm.Emitted.Select(e => e.Offset).ToArray(), halt = vm.HaltReason, steps = vm.Steps };
    }
    File.WriteAllText(args[1], JsonSerializer.Serialize(trace, new JsonSerializerOptions { Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping }));
    Console.WriteLine($"trace: {trace.Count} scenes -> {args[1]}");
    return 0;
}
Console.WriteLine("unknown command"); return 1;
```

- [ ] **Step 6: Run the C# test — expect PASS**, then cross-check the CLI trace
```bash
dotnet test engine/Age.Engine.Tests --filter FullyQualifiedName~TraceDiffTests
dotnet run --project engine/Age.Cli -- trace build/cs-trace.json
py -3.11 -X utf8 -c "import json;a=json.load(open('build/vm0-trace.json',encoding='utf-8'));b=json.load(open('build/cs-trace.json',encoding='utf-8'));print('identical' if a==b else 'DIFFER: '+str([k for k in a if a[k]!=b.get(k)][:5]))"
```
Expected: test passes; the Python cross-check prints `identical`.

- [ ] **Step 7: Full solution test + commit**
```bash
dotnet test engine/AgeEngine.sln
git add engine/Age.Cli/Program.cs engine/Age.Engine.Tests/TraceDiffTests.cs tools/vm0.py
git commit -m "feat(a1): CLI (run/trace) + vm0.py --trace + per-scene differential test (A1 green)"
```

---

## Self-Review

**Spec coverage:**
- Standalone .NET 8 solution (Task 1) ✓ · three seams + neutral `Script` contract (Model in Task 1, seam rule in Global Constraints, VM refs only Model+Hosting in Task 4) ✓ · SYS4 front-end parser+codec+opcode-table (Tasks 2–3, Task 1) ✓ · `IHost`/`CaptureHost` (Task 4) ✓ · faithful vm0 handlers incl. pointer semantics, emit-cap, halt reasons, PyDiv/PyMod (Task 4) ✓ · integer-parity + cp932 registration (Task 4, Task 2) ✓ · per-scene trace diff + RECOVER + parser/codec-parity tests (Tasks 3,4,5) ✓ · reads `build/opcodes.json` via `Paths` (Task 1) ✓ · `vm0.py --trace` addition (Task 5) ✓.
- Codec-parity note: the offset-only trace can't catch a decode bug; `Sys4LoaderTests` asserts `Strings.Count` and the ASCII codec test covers the codec — Japanese decode is exercised transitively (MENU strings) and by the trace run loading every scene without codec exceptions. (Acceptable; a byte-for-byte Japanese golden could be added if a divergence appears.)

**Placeholder scan:** none — every code step is complete; the only "investigate" is Task 5 Step 4, which is the differential-debugging loop (inherent) and points at `vm0.py --scene` for each named divergence.

**Type consistency:** `OpcodeTable`, `Script`, `Operand(Type,Value)`, `Instruction(Offset,Opcode,Args)`, `Sys4Loader.Load(path,table)`, `VirtualMachine(script,table,host,options?)` with `.Globals/.Emitted/.HaltReason/.Steps/.Run()`, `Paths.Scripts()/OpcodesJson/Build/Data1`, `IHost.ShowText/CallScript/OnStub` — used identically across Tasks 1→5. Trace JSON keys (`offsets`/`halt`/`steps`) match between `vm0.py --trace` (Task 5 Step 2) and both C# consumers (Task 5 Steps 1 & 5). Halt-reason format `LOOP:line@0x{off:x}×{count}` matches vm0's `{v:#x}` (0x-prefixed) exactly.