Currency-War-SR/tools/gridfight-extract-node/README.md

# GridFight extractor (Node ESM)

Faithful port of the sibling extractor. Node 22+ and built-in modules only;
validated with Node 26.12.0. Native reader proofs require GNU `objdump`.
Linux installers use `flock`. XXH64 is implemented locally: no FFI, libxxhash,
npm install, metadata dumper, network fetch or game launch is required.

Run from the repository root:

```sh
node tools/gridfight-extract-node/extract.mjs \
  --client /path/to/client \
  --dump /path/to/config/dump.cs \
  --output /tmp/gridfight-core \
  --traits --season-id 2 \
  --evidence-dir /tmp/gridfight-core/evidence
node --test tools/gridfight-extract-node
```

The dump must contain `RPG.GameCore.Config.dll`; traits also need
`RPG.GameCore.Foundation.dll` and `RPG.GameCore.FixedMath.dll`. Use the matching
`config/dump.cs`, rather than assuming the top-level dump contains those rows.
Treat client files as read-only; place outputs and evidence outside the client.

`extract.mjs` retains `--language` (default `en`, choices `en cn cht jp kr de es
fr id pt ru th vi`), `--traits`, `--season-id`, and `--evidence-dir`. It publishes
roles, shop odds, traits/layers, season/divisions, offerings, schemas and
provenance with the same filenames and JSON contracts as the reference.
Season selection is explicit; it does not establish a live calendar.

Native mask tests and metadata establish field order. Every native indexed
collection must decode completely and re-encode to its exact original bytes.
Unknown types, absent/ambiguous assets, conflicting text and invalid references
fail. Required data documents publish only after the requested validations
succeed. Evidence may remain after failure. Each replacement is atomic; use a
staging directory for bundle-level installation. Large integers retain all 64
bits in JSON. Arrays, numeric dictionary ordering, indentation and Unicode
escaping retain the reference output representation.

Other entrypoints preserve their original flags (`.mjs` replaces `.py`):

| Entrypoint | Required flags | Optional flags/defaults |
|---|---|---|
| `stages.mjs` | `--client --dump --identity --output` | None |
| `items.mjs` | `--client --dump --identity --output` | None |
| `petpal.mjs` | `--client --dump --identity --output` | None |
| `rounds.mjs` | `--client --dump --literals --identity --output` | `--language en` |
| `trait_effects.mjs` | `--client` | `--output resources/grid_fight/trait_effects.json` |
| `trailblaze.mjs` | `--client` | `--output resources/grid_fight/trailblaze.json` |
| `jade.mjs` | `--client` | `--output resources/grid_fight/jade.json` |
| `equipment.mjs` | None | `--items`, `--catalog`, `--season 2`, `--output` |
| `portals.mjs` | None | `--items`, `--catalog`, `--season 2`, `--output`, `--augments` |
| `score.mjs` | None | `--catalog`, `--output` |
| `ui_names.mjs` | `--client --dump --resources --english --thai --output --evidence` | None |
| `native_slice.mjs` | `--client --dump --class --output` | Repeat `--class` |
| `audit_coverage.mjs` | `--dump --output` | `--source` defaults to repository root |
| `audit_battle_entry.mjs` | `--client --dump --assembly --roles --evidence` | None |
| `install_stages.mjs` | `--source --launcher --stage --report` | `--package stage` or `petpal` |
| `install_rounds.mjs` | `--server-root --launcher-root --stage` | None |
| `run_tests.mjs` | `--output` | `--zig zig` (requires 0.14.1 and cached protobuf) |

Default derived-table inputs and outputs remain repository-relative:
`resources/grid_fight/items.raw.json`, the matching basename's JSON, and
`protocol/evidence/cw-mechanics/catalog.json`. Portals also writes
`resources/grid_fight/augments.json`. Pass scratch output paths for comparison.

For example:

```sh
node tools/gridfight-extract-node/items.mjs \
  --client /path/to/client --dump /path/to/config/dump.cs \
  --identity /tmp/gridfight-core/provenance.json --output /tmp/gridfight-items
node tools/gridfight-extract-node/equipment.mjs \
  --items /tmp/gridfight-items/items.raw.json --season 2 \
  --catalog /path/to/matching/catalog.json --output /tmp/gridfight-equipment.json
```

`stages`, `items` and `petpal` consume the core extractor's identity manifest.
`rounds` consumes the client-table metadata identity (`client` and
`metadata_sha256`) and matching string literals. Its underscore raw filenames,
Supply `null`, and tagged DynamicValue contract intentionally differ from
`stages` (dot raw filenames, Supply `shop`, and `wire_tag`). Neither guesses
monster groups or tutorial selector meanings.

Installers retain identity/hash checks, a nonblocking runtime-refresh lock,
verified backups, atomic replacements, manifest refresh, protected-file checks
and rollback. They use a local Node port of the runtime verification helpers.
`install_rounds` stores its audit evidence in this new directory, preserving
the sibling reference directory. No installer was run against real resources;
installation was exercised only in disposable fixtures.

Full season-2 staging, including a fresh native catalog for equipment/score and a
file-by-file installed-data comparison:

```sh
node tools/gridfight-extract-node/stage_all.mjs \
  --client /path/to/client --dump /path/to/config/dump.cs \
  --literals /path/to/stringliterals.json \
  --english /path/to/active/en/TextMap.bytes \
  --thai /path/to/active/th/TextMap.bytes \
  --resources /path/to/server/resources \
  --baseline /path/to/server/resources/grid_fight \
  --output /tmp/cw-stage
```

The output must be outside the client and installed resources. All flags are
required; no derived entrypoint falls back to the older repository catalog in
this workflow. The active language blobs must match the client. Logs, native
proofs, CHANGES.md, comparison.json and a hashed bundle manifest accompany the
runtime JSON. Root rounds use the existing stages contract; the alternate
rounds extractor's distinct contract is retained under rounds-alternative/.
Server-authored node_profiles/orb_rewards are carried byte-identically, marked
as third-party observations rather than freshly extracted client data. Old
backup files are compared in the report but excluded from the runtime bundle.
AvatarConfig/AeonCatalog provide existing UI identity/name lookup hints; UI text
is resolved from the supplied client TextMaps. Staging does not install data.

Validation on OSBETAWin4.6.53, season 2:

- 51 tests pass, including native 4.6.53 dispatch mutation rejection, relocated
  4.6.51 layout, nested nulls, signed 64-bit limits, NaN payloads, dictionary
  doubles and the Phainon schema's stack-write regression.
- DynamicValue FromByteBinary resolves from metadata (4.6.53 RVA 0x1e745df0;
  4.6.51 RVA 0x1e58e120). Both use case offsets 0x85/0xc5/0x102/0x14f/0x18a/0x1cf
  and dispatch offset 0x2b0. Typed case operations and dispatch bindings must
  match before evidence is published. The wire layout is unchanged; both
  projection modes support null tag 6. Integer and float bytes stay lossless.
- Stages: all 14 tables, including 29,715 StageConfig rows, re-encode exactly.
  Fresh supplemental catalog: all 20 additional tables re-encode exactly,
  including all nine Phainon fields (stack addresses are excluded from native
  field candidates). Both stage and alternate-rounds extraction complete.
- 141 roles, 11 shop levels, 67 traits, 304 season-2 augments, 74 season-2 portals,
  147 season-2 equipment entries, 493 routes, 12 partners. Trial-avatar audit:
  5,200 rows re-encoded exactly and all 141 role identities verified.
- ui_names also exports item/augment/portal/trait hash maps for ID comparisons;
  the current run resolves 1,816 English and Thai texts.
- No client data, installed resources, reference Python code, archives or live
  processes are changed. No gameplay-correctness claim is made.

Use `node --test tools/gridfight-extract-node`. On hosts whose default test
isolation reports only a file-level result, add `--test-isolation=none` to see
all 51 individual results. Native proof fixtures are static objdump excerpts
from the matching beta DLL; method offsets come from config/dump.cs.