#!/usr/bin/env python3
"""Decode engine-visible channel state words into named fields, and diff captures.

During GR bring-up the answer often hides in a handful of 32-bit words inside
the INSTANCE block, the RAMFC chunk and context-buffer headers: one bit turns
"nothing happens" into an engine that runs or refuses.  Raw hex hides that;
this tool turns a captured dump into a named field table and makes two
captures differ field-by-field.

Schemas:

* ``greeneye-state-decode/1``    -- the decoded report produced by ``decode``.
* ``greeneye-state-diff/1``      -- the word/field diff produced by ``diff``.
* ``greeneye-server-snapshot/1`` -- an input snapshot emitted elsewhere::

      {"schema": "greeneye-server-snapshot/1", "source": "...",
       "chunks": [{"label": "INSTANCE", "base": "0x0",
                   "words": ["0x...", "..."]}]}

  (one hex string or integer per 32-bit word; accepted exactly).
* ``greeneye-state-map/1``       -- an optional field map (``--map``), see below.

Input formats (auto-detected per ``--input``):

(a) text lines ``LABEL[OFFSET]=VALUE`` -- label case-insensitive, offset and
    value hex (``0x..``, letters, or leading-zero padded) or decimal; every
    other line is ignored;
(b) a dump row with a bracketed chunk offset and words, e.g.
    ``... INSTANCE[0040]: 00100000 00030000 ...`` -- this is the shape live
    ladder traces print (8 words per row; any count accepted);
(c) plain hexdump rows ``00000000: 000002d2 00000000 ...`` named with
    ``--label``/``--base``;
(d) raw little-endian u32 words (``--bin``, or auto-detected when a text parse
    finds nothing and the bytes are control-heavy and 4-byte aligned);
(e) the snapshot JSON above;
(f) aggregate state groups -- one ``GROUP: key=value ...`` group per line,
    e.g. ``stage: primed=1 kicked=1 tx_seq_num=106``; the token right after
    the group colon must itself be a ``key=value`` token, and a line may
    carry several ``|``-separated groups (``rm_call_userd: userd=sysmem
    (host-writable) | rm_call_pdb: vaBase=0x100000 ...``).  Each group
    becomes a chunk named ``PHYS_<group>`` whose fields are the kv pairs:
    values are kept as integers when the module's number convention parses
    them (``0x..``, bare hex letters, leading-zero hex, decimal, signed),
    everything else stays a raw string (``variant=V6``, ``userd=sysmem``),
    and each group's raw text is preserved on the chunk.  Aggregate chunks
    carry no words, so the map does not apply to them; the diff compares
    their kvs and classifies every row as ``added`` / ``removed`` /
    ``changed``.

Offsets inside a chunk are byte offsets relative to the chunk start (all
inputs above are u32 word dumps, so offsets are multiples of 4).  ``base`` is
the engine-visible address of chunk-relative offset 0: it is recorded as
provenance and for the diff, but it does not shift map lookup.

Additive evolution (2026-10, aggregate inputs; no key renamed or removed):
aggregate chunks add ``group`` / ``kv_count`` / ``raw`` chunk keys, kv fields
add ``kind: "kv"`` / ``index`` (duplicate-key occurrence) / ``numeric``, diff
chunks and ``summary`` add ``fields_added`` / ``fields_removed`` /
``fields_changed``, and every ``changed_fields`` row now carries ``status``
(``added`` / ``removed`` / ``changed``).

Bundled map (deliberately small; extend or override it from a map file, never
by guessing here).  Provenance is live bring-up observation (2026-10 GSP
ladder runs):

* ``INSTANCE`` 0x010: magic ``0xface``.
* ``INSTANCE`` 0x048: GPFIFO VA, observed as ``0x100000``.
* ``RAMFC`` 0x048: ``RAMFC_TARGET`` -- bits 16/17 ``ENG_CTX_VALID`` /
  ``CE_CTX_VALID``; the observed live success word ``0x00030000`` sets both.
  The bit assignment is observation-driven and fully configurable via the map.

Map file::

    {"format": "greeneye-state-map/1", "mode": "extend" | "replace",
     "entries": [
       {"chunk": "RAMFC", "label": "RAMFC_TARGET", "offset": "0x48",
        "width": 4,
        "bits": [{"name": "ENG_CTX_VALID", "lo": 16, "hi": 16,
                  "values": {"0": "clear", "1": "set"}}],
        "note": "..."}
     ]}

A user entry with the same ``chunk`` and ``offset`` replaces the bundled
entry; new chunk/offset pairs extend the table.  ``mode: replace`` drops the
bundled table first.  An entry without ``bits`` decodes as a named value.

Honesty: this tool names observed words; it does not prove their meaning.  An
unmapped word is silence, not absence.  Field offsets without evidence stay
unnamed until a map supplies them.  Offline only: no hardware, no module, no
guest, no network.
"""
from __future__ import annotations

import argparse
import json
import os
import re
import shutil
import sys
import tempfile
from typing import Any

DECODE_FORMAT = "greeneye-state-decode/1"
DIFF_FORMAT = "greeneye-state-diff/1"
SNAPSHOT_FORMAT = "greeneye-server-snapshot/1"
MAP_FORMAT = "greeneye-state-map/1"
DEMO_FORMAT = "greeneye-state-decode-demo/1"

WORD_BYTES = 4
WORD_MASK = 0xFFFFFFFF
WORD_WIDTHS = (4, 8)

AGGREGATE_FORMAT = "aggregate"
AGGREGATE_PREFIX = "PHYS_"
KV_KIND = "kv"


class StateDecodeError(ValueError):
    """An input, map or request the tool cannot honour."""


# ---------------------------------------------------------------------------
# Bundled field table
# ---------------------------------------------------------------------------
# Every entry is an observation from live GSP bring-up traces (2026-10).  The
# table is intentionally tiny: unnamed offsets stay unnamed until evidence
# earns them a name, and the map file carries everything else.
BUILTIN_MAP: dict[str, Any] = {
    "format": MAP_FORMAT,
    "mode": "extend",
    "entries": [
        {
            "chunk": "INSTANCE",
            "label": "MAGIC_0FACE",
            "offset": "0x010",
            "width": 4,
            "note": "Instance magic observed as 0xface at chunk byte 0x010.",
        },
        {
            "chunk": "INSTANCE",
            "label": "GPFIFO_VA",
            "offset": "0x048",
            "width": 4,
            "note": "GPFIFO VA observed as 0x100000 at chunk byte 0x048.",
        },
        {
            "chunk": "RAMFC",
            "label": "RAMFC_TARGET",
            "offset": "0x048",
            "width": 4,
            "bits": [
                {"name": "ENG_CTX_VALID", "lo": 16, "hi": 16},
                {"name": "CE_CTX_VALID", "lo": 17, "hi": 17},
            ],
            "note": ("Engine/CE context-valid bits; the observed live success "
                     "word 0x00030000 sets both.  Bits are configurable via "
                     "--map."),
        },
    ],
}

# ---------------------------------------------------------------------------
# Number and token parsing
# ---------------------------------------------------------------------------

_EQ_RE = re.compile(
    r"^\s*(?P<label>[A-Za-z_][A-Za-z0-9_.-]*)\s*"
    r"\[\s*(?P<off>[0-9a-fA-FxX]+)\s*\]\s*=\s*(?P<val>[0-9a-fA-FxX]+)\s*$")

_ROW_RE = re.compile(
    r"(?P<label>[A-Za-z_][A-Za-z0-9_.-]*)\s*"
    r"\[\s*(?P<off>[0-9a-fA-FxX]+)\s*\]\s*:\s*"
    r"(?P<words>[0-9a-fA-FxX]+(?:\s+[0-9a-fA-FxX]+)*)\s*$")

_HEXDUMP_RE = re.compile(
    r"^\s*(?P<off>[0-9a-fA-FxX]{2,16})\s*:\s*"
    r"(?P<words>[0-9a-fA-FxX]+(?:\s+[0-9a-fA-FxX]+)*)\s*$")

_HEX_RE = re.compile(r"[0-9a-fA-F]+")

_TEXT_BYTES = frozenset(b"\t\n\r") | frozenset(range(0x20, 0x7F))


def parse_number(value: Any, *, why: str = "number") -> int:
    """Parse an int, a ``0x`` string, or a bare token.

    Bare tokens with a hex letter (``face``) or a leading zero and more
    digits (``0040``) are read as hex, matching dump padding; other bare
    digit strings are decimal.  Write ``0x..`` when in doubt.
    """
    if isinstance(value, bool):
        raise StateDecodeError(f"bad {why} {value!r}")
    if isinstance(value, int):
        return value
    if not isinstance(value, str):
        raise StateDecodeError(f"bad {why} {value!r}")
    text = value.strip()
    if not text:
        raise StateDecodeError(f"bad {why} {value!r}")
    sign = 1
    if text[0] in "+-":
        if text[0] == "-":
            sign = -1
        text = text[1:]
    low = text.lower()
    if low.startswith("0x"):
        base, digits = 16, text[2:]
    elif re.fullmatch(r"[0-9]+", text):
        base = 16 if text.startswith("0") and len(text) > 1 else 10
        digits = text
    elif _HEX_RE.fullmatch(text):
        base, digits = 16, text
    else:
        raise StateDecodeError(f"bad {why} {value!r}")
    try:
        return sign * int(digits, base)
    except ValueError as exc:
        raise StateDecodeError(f"bad {why} {value!r}") from exc


def _parse_word(value: Any, *, where: str) -> int:
    number = parse_number(value, why=where)
    if not 0 <= number <= WORD_MASK:
        raise StateDecodeError(f"{where} {value!r} does not fit in 32 bits")
    return number


def _hex(value: int, width: int = 4) -> str:
    return f"{value:#0{2 + width * 2}x}"


def _parse_base(value: Any) -> int:
    if value is None:
        return 0
    return parse_number(value, why="base")


# ---------------------------------------------------------------------------
# Map loading (bundled <- override/extension)
# ---------------------------------------------------------------------------

def _normalize_entry(raw: Any, *, where: str) -> dict[str, Any]:
    if not isinstance(raw, dict):
        raise StateDecodeError(f"{where} must be an object")
    chunk = raw.get("chunk")
    label = raw.get("label")
    if not isinstance(chunk, str) or not chunk:
        raise StateDecodeError(f"{where} needs a non-empty chunk")
    if not isinstance(label, str) or not label:
        raise StateDecodeError(f"{where} needs a non-empty label")
    if raw.get("offset") is None:
        raise StateDecodeError(f"{where} needs an offset")
    offset = parse_number(raw["offset"], why=f"{where} offset")
    width = raw.get("width", 4)
    width = parse_number(width, why=f"{where} width")
    if width not in WORD_WIDTHS:
        raise StateDecodeError(f"{where} width {width!r} is not 4 or 8")
    if offset < 0 or offset % WORD_BYTES:
        raise StateDecodeError(f"{where} offset {offset:#x} is not word-aligned")
    bits_raw = raw.get("bits") or []
    if not isinstance(bits_raw, list):
        raise StateDecodeError(f"{where} bits must be a list")
    nbits = width * 8
    bits = []
    for index, bit in enumerate(bits_raw):
        if not isinstance(bit, dict):
            raise StateDecodeError(f"{where} bits[{index}] must be an object")
        name = bit.get("name")
        if not isinstance(name, str) or not name:
            raise StateDecodeError(f"{where} bits[{index}] needs a name")
        lo = parse_number(bit.get("lo"), why=f"{where} bits[{index}].lo")
        hi = parse_number(bit.get("hi"), why=f"{where} bits[{index}].hi")
        if not 0 <= lo <= hi < nbits:
            raise StateDecodeError(
                f"{where} bits[{index}] range {lo}..{hi} outside width {width}")
        values = bit.get("values")
        norm_values: dict[int, str] = {}
        if values is not None:
            if not isinstance(values, dict):
                raise StateDecodeError(
                    f"{where} bits[{index}].values must be an object")
            for key, text in values.items():
                norm_values[parse_number(key, why=f"{where} values key")] = str(text)
        bits.append({"name": name, "lo": lo, "hi": hi, "values": norm_values})
    note = raw.get("note")
    return {
        "chunk": chunk,
        "label": label,
        "offset": offset,
        "width": width,
        "bits": bits,
        "note": note if isinstance(note, str) else None,
    }


def load_map(path: str | None = None) -> tuple[dict[tuple[str, int], dict], str]:
    """Build the field table; returns ``(table, source)``.

    ``table`` is keyed by ``(chunk.lower(), offset)``.  Without ``path`` the
    bundled table is used.  With ``path``, entries merge over the bundled
    table (same chunk+offset replaces, new pairs extend) unless the file sets
    ``"mode": "replace"``.
    """
    entries: list[Any] = list(BUILTIN_MAP["entries"])
    source = "builtin"
    if path:
        if not os.path.isfile(path):
            raise StateDecodeError(f"map not found: {path}")
        with open(path, "r", encoding="utf-8") as handle:
            doc = json.load(handle)
        source = os.path.abspath(path)
        if isinstance(doc, list):
            raw_entries, mode = doc, "extend"
        elif isinstance(doc, dict):
            fmt = doc.get("format", MAP_FORMAT)
            if fmt != MAP_FORMAT:
                raise StateDecodeError(
                    f"unsupported map format {fmt!r} (want {MAP_FORMAT})")
            raw_entries = doc.get("entries")
            mode = doc.get("mode", "extend")
        else:
            raise StateDecodeError(f"map {path} must be an object or a list")
        if mode not in ("extend", "replace"):
            raise StateDecodeError(f"map mode {mode!r} is not extend/replace")
        if not isinstance(raw_entries, list):
            raise StateDecodeError(f"map {path} needs an entries list")
        if mode == "replace":
            entries = []
        entries.extend(raw_entries)
    table: dict[tuple[str, int], dict] = {}
    for index, raw in enumerate(entries):
        entry = _normalize_entry(raw, where=f"map entry {index}")
        table[(entry["chunk"].lower(), entry["offset"])] = entry
    return table, source


# ---------------------------------------------------------------------------
# Input loading (auto-detected per input)
# ---------------------------------------------------------------------------

def _read_bytes(path: str) -> bytes:
    if not os.path.isfile(path):
        raise StateDecodeError(f"input not found: {path}")
    with open(path, "rb") as handle:
        return handle.read()


def _try_json(data: bytes) -> Any:
    """Return parsed JSON when the bytes look like JSON, else ``None``."""
    try:
        text = data.decode("utf-8")
    except UnicodeDecodeError:
        return None
    stripped = text.lstrip()
    if not stripped.startswith("{"):
        return None
    try:
        return json.loads(text)
    except json.JSONDecodeError as exc:
        raise StateDecodeError(f"invalid JSON input: {exc}") from exc


def _try_text(data: bytes) -> str | None:
    try:
        return data.decode("utf-8")
    except UnicodeDecodeError:
        return None


def _looks_binary(data: bytes) -> bool:
    if not data or len(data) % WORD_BYTES:
        return False
    return any(byte not in _TEXT_BYTES for byte in data)


def _chunk_from_binary(data: bytes, label: str, base: int, source: str) -> dict:
    if not data:
        raise StateDecodeError(f"binary input {source} is empty")
    if len(data) % WORD_BYTES:
        raise StateDecodeError(
            f"binary input {source} size {len(data)} is not a multiple of 4")
    words = {offset: int.from_bytes(data[offset:offset + WORD_BYTES], "little")
             for offset in range(0, len(data), WORD_BYTES)}
    return {"label": label, "base": base, "words": words,
            "format": "binary", "source": source}


def _document(path: str, fmt: str, label: str | None, base: int,
              chunks: list[dict]) -> dict:
    return {
        "path": os.path.abspath(path),
        "format": fmt,
        "label": label,
        "base": base,
        "chunks": chunks,
    }


# ---------------------------------------------------------------------------
# Aggregate state groups (``GROUP: key=value ...``)
# ---------------------------------------------------------------------------
# A group head is a name token at line start or after a ``|`` separator, e.g.
# ``rm_call_pdb: vaBase=0x100000``.  Covers group names like ``vgsp-state``
# and ``rm_call``.  A kv token starts at a token boundary (whitespace or
# string start), so annotations such as ``(VAL=0x1f7800)`` stay raw text
# instead of becoming a second ``VAL`` field.
_AGG_HEAD_RE = re.compile(
    r"(?:^|\|)[ \t]*(?P<group>[A-Za-z0-9_.-]+):[ \t]+")

_KV_RE = re.compile(
    r"(?<!\S)(?P<key>[A-Za-z0-9_.-]+)=(?P<value>\S*)")


def parse_aggregate_line(line: str) -> list[dict[str, Any]]:
    """Parse one aggregate state line into ``{group, raw, kvs}`` dicts.

    A group head is accepted only when the token right after the colon is
    itself a ``key=value`` token (the shape ``^GROUP:\\s+key=``); structured
    lines whose first token is not a kv (``status: writePtr slot=29 ...``,
    ``peer: host readPtr @cmd+0x20 = 8``) stay unparsed.  A line may hold
    several ``|``-separated groups, in which case each becomes its own group.
    Non-aggregate lines return ``[]``.
    """
    heads = list(_AGG_HEAD_RE.finditer(line))
    if not heads:
        return []
    groups = []
    for index, head in enumerate(heads):
        end = heads[index + 1].start() if index + 1 < len(heads) else len(line)
        body = line[head.end():end]
        if not _KV_RE.match(body):
            continue
        kvs = _extract_kvs(body)
        groups.append({
            "group": head.group("group"),
            "raw": line[head.start("group"):end].strip(),
            "kvs": kvs,
        })
    return groups


def _parse_kv_value(raw: str) -> tuple[Any, bool]:
    """Parse an aggregate value with the module's number convention.

    Returns ``(value, numeric)``; unparseable values stay raw strings so no
    spelling is lost (``raw`` on the field always keeps the captured token).
    """
    if not raw:
        return raw, False
    try:
        return parse_number(raw, why="aggregate value"), True
    except StateDecodeError:
        return raw, False


def _extract_kvs(text: str) -> list[dict[str, Any]]:
    kvs = []
    for match in _KV_RE.finditer(text):
        raw_value = match.group("value")
        value, numeric = _parse_kv_value(raw_value)
        kvs.append({"key": match.group("key"), "raw": raw_value,
                    "value": value, "numeric": numeric})
    return kvs


def _aggregate_chunk(group: dict[str, Any], base: int,
                     source: str | None) -> dict:
    return {
        "label": AGGREGATE_PREFIX + group["group"],
        "group": group["group"],
        "base": base,
        "words": {},
        "format": AGGREGATE_FORMAT,
        "source": source,
        "raw": group["raw"],
        "kvs": group["kvs"],
    }


def parse_text(text: str, *, default_label: str | None = None,
               default_base: int = 0, source: str | None = None) -> list[dict]:
    """Parse the text/hexdump/row/aggregate formats into chunks.

    Chunk names are case-insensitive: ``INSTANCE`` and ``inst`` land in one
    chunk, displayed with the first spelling seen.  Aggregate groups (format
    ``aggregate``, label ``PHYS_<group>``) are kept as separate chunks in
    line order after the word chunks.  Every line that matches none of the
    four patterns is ignored.
    """
    chunks: dict[str, dict] = {}
    aggregate: list[dict] = []

    def chunk_for(label: str) -> dict:
        key = label.lower()
        chunk = chunks.get(key)
        if chunk is None:
            chunk = {"label": label, "base": default_base, "words": {},
                     "format": "text", "source": source}
            chunks[key] = chunk
        return chunk

    def put(label: str, offset: int, value: int, where: str) -> None:
        if offset < 0 or offset % WORD_BYTES:
            raise StateDecodeError(f"{where}: offset {offset:#x} is not word-aligned")
        if not 0 <= value <= WORD_MASK:
            raise StateDecodeError(f"{where}: value {value:#x} does not fit in 32 bits")
        chunk_for(label)["words"][offset] = value

    for lineno, raw_line in enumerate(text.splitlines(), 1):
        line = raw_line.strip()
        if not line:
            continue
        where = f"{source or '<text>'}:{lineno}"
        match = _EQ_RE.match(line)
        if match:
            offset = parse_number(match.group("off"), why=f"{where} offset")
            value = parse_number(match.group("val"), why=f"{where} value")
            put(match.group("label"), offset, value, where)
            continue
        match = _ROW_RE.search(line)
        if match:
            offset = parse_number(match.group("off"), why=f"{where} offset")
            for index, token in enumerate(match.group("words").split()):
                put(match.group("label"), offset + index * WORD_BYTES,
                    int(token, 16), where)
            continue
        match = _HEXDUMP_RE.match(line)
        if match:
            label = default_label or "RAW"
            offset = int(match.group("off"), 16)
            for index, token in enumerate(match.group("words").split()):
                put(label, offset + index * WORD_BYTES, int(token, 16), where)
            continue
        for group in parse_aggregate_line(line):
            aggregate.append(_aggregate_chunk(group, default_base, source))
    return [chunks[key] for key in chunks] + aggregate


def load_input(spec: dict) -> dict:
    """Load one input spec dict (path/label/base/binary) into a document."""
    path = spec.get("path")
    if not path:
        raise StateDecodeError("input spec needs a path")
    data = _read_bytes(path)
    label = spec.get("label")
    base = _parse_base(spec.get("base"))
    if spec.get("binary"):
        chunk = _chunk_from_binary(data, label or "RAW", base, path)
        return _document(path, "binary", label, base, [chunk])
    doc = _try_json(data)
    if doc is not None:
        return _document_from_json(path, doc, label, base)
    text = _try_text(data)
    if text is not None:
        chunks = parse_text(text, default_label=label, default_base=base,
                            source=path)
        if chunks:
            fmt = (AGGREGATE_FORMAT
                   if all(chunk.get("format") == AGGREGATE_FORMAT
                          for chunk in chunks) else "text")
            return _document(path, fmt, label, base, chunks)
    if _looks_binary(data):
        chunk = _chunk_from_binary(data, label or "RAW", base, path)
        return _document(path, "binary", label, base, [chunk])
    raise StateDecodeError(
        f"cannot decode {path}: not text fields, not {SNAPSHOT_FORMAT} JSON, "
        f"not raw u32 words")


def _document_from_json(path: str, doc: Any, label: str | None,
                        base: int) -> dict:
    if isinstance(doc, dict) and doc.get("format") == DECODE_FORMAT:
        raise StateDecodeError(f"{path} is a decoded report; use `diff` on it")
    if not isinstance(doc, dict) or doc.get("schema") != SNAPSHOT_FORMAT:
        got = doc.get("schema") if isinstance(doc, dict) else type(doc).__name__
        raise StateDecodeError(
            f"unsupported JSON input {path}: schema={got!r} "
            f"(want {SNAPSHOT_FORMAT})")
    raw_chunks = doc.get("chunks")
    if not isinstance(raw_chunks, list) or not raw_chunks:
        raise StateDecodeError(f"snapshot {path} has no chunks")
    chunks = []
    for index, raw in enumerate(raw_chunks):
        if not isinstance(raw, dict):
            raise StateDecodeError(f"{path}:chunks[{index}] must be an object")
        chunk_label = raw.get("label") or label or "RAW"
        chunk_base = (_parse_base(raw["base"]) if raw.get("base") is not None
                      else base)
        words_raw = raw.get("words")
        if not isinstance(words_raw, list):
            raise StateDecodeError(
                f"{path}:chunks[{index}] needs a words list")
        words = {}
        for position, word in enumerate(words_raw):
            words[position * WORD_BYTES] = _parse_word(
                word, where=f"{path}:chunks[{index}].words[{position}]")
        chunks.append({"label": str(chunk_label), "base": chunk_base,
                       "words": words, "format": "snapshot-json",
                       "source": path})
    return _document(path, "snapshot-json", label, base, chunks)


# ---------------------------------------------------------------------------
# Decode
# ---------------------------------------------------------------------------

def _read_field_value(words: dict[int, int], offset: int,
                      width: int) -> int | None:
    """Little-endian read of a 4/8-byte field; ``None`` when words are absent."""
    data = b""
    for step in range(0, width, WORD_BYTES):
        word = words.get(offset + step)
        if word is None:
            return None
        data += word.to_bytes(WORD_BYTES, "little")
    return int.from_bytes(data, "little")


def _bit_state(bit: dict, value: int) -> str:
    values = bit.get("values") or {}
    if value in values:
        return values[value]
    mask = (1 << (bit["hi"] - bit["lo"] + 1)) - 1
    if value == 0:
        return "clear"
    if value == mask:
        return "set"
    return f"{value:#x}"


def _decode_field(entry: dict, value: int) -> dict:
    width = entry["width"]
    field: dict[str, Any] = {
        "name": entry["label"],
        "offset": f"{entry['offset']:#x}",
        "width": width,
        "kind": "bits" if entry["bits"] else "value",
        "raw": _hex(value, width),
        "value": value,
    }
    if entry.get("note"):
        field["note"] = entry["note"]
    if entry["bits"]:
        bitfields = []
        for bit in entry["bits"]:
            raw_bit = (value >> bit["lo"]) & ((1 << (bit["hi"] - bit["lo"] + 1)) - 1)
            bitfields.append({
                "name": bit["name"],
                "lo": bit["lo"],
                "hi": bit["hi"],
                "value": raw_bit,
                "state": _bit_state(bit, raw_bit),
            })
        field["bitfields"] = bitfields
    return field


def _decode_aggregate_chunk(chunk: dict) -> dict:
    """Decode an aggregate group chunk into the ``greeneye-state-decode/1`` shape.

    There are no words: the named fields *are* the kv pairs, in line order,
    with duplicate keys separated by a 0-based ``index``.
    """
    fields = []
    occurrences: dict[str, int] = {}
    for kv in chunk.get("kvs", []):
        key = kv["key"]
        index = occurrences.get(key, 0)
        occurrences[key] = index + 1
        fields.append({
            "name": key,
            "kind": KV_KIND,
            "index": index,
            "offset": None,
            "width": 0,
            "raw": kv["raw"],
            "value": kv["value"],
            "numeric": kv["numeric"],
        })
    return {
        "label": chunk["label"],
        "group": chunk.get("group"),
        "base": f"{chunk['base']:#x}",
        "source": chunk.get("source"),
        "input_format": chunk.get("format"),
        "word_width": WORD_BYTES,
        "word_count": 0,
        "words": {},
        "fields": fields,
        "unmapped": [],
        "unmapped_count": 0,
        "kv_count": len(fields),
        "raw": chunk.get("raw"),
    }


def decode_chunk(chunk: dict, entries: dict[tuple[str, int], dict]) -> dict:
    """Decode one internal chunk into the ``greeneye-state-decode/1`` shape."""
    if chunk.get("format") == AGGREGATE_FORMAT:
        return _decode_aggregate_chunk(chunk)
    label = chunk["label"]
    words: dict[int, int] = chunk["words"]
    matched = sorted(
        (entry for (chunk_key, _off), entry in entries.items()
         if chunk_key == label.lower()),
        key=lambda entry: (entry["offset"], entry["label"]))
    fields = []
    covered: set[int] = set()
    for entry in matched:
        value = _read_field_value(words, entry["offset"], entry["width"])
        if value is None:
            continue
        fields.append(_decode_field(entry, value))
        covered.update(range(entry["offset"],
                             entry["offset"] + entry["width"], WORD_BYTES))
    unmapped = [{"offset": f"{offset:#x}", "raw": _hex(words[offset])}
                for offset in sorted(words) if offset not in covered]
    return {
        "label": label,
        "base": f"{chunk['base']:#x}",
        "source": chunk.get("source"),
        "input_format": chunk.get("format"),
        "word_width": WORD_BYTES,
        "word_count": len(words),
        "words": {f"{offset:#x}": _hex(value)
                  for offset, value in sorted(words.items())},
        "fields": fields,
        "unmapped": unmapped,
        "unmapped_count": len(unmapped),
    }


def decode_specs(specs: list[dict], entries: dict[tuple[str, int], dict],
                 map_source: str = "builtin") -> dict:
    """Load and decode input specs into a ``greeneye-state-decode/1`` report."""
    sources = []
    chunks = []
    for spec in specs:
        document = load_input(spec)
        sources.append({
            "path": document["path"],
            "format": document["format"],
            "label": document["label"],
            "base": f"{document['base']:#x}",
            "chunk_labels": [chunk["label"] for chunk in document["chunks"]],
        })
        for chunk in document["chunks"]:
            chunks.append(decode_chunk(chunk, entries))
    chunks.sort(key=lambda chunk: (chunk["label"].lower(), chunk["label"],
                                   int(chunk["base"], 16)))
    return {
        "format": DECODE_FORMAT,
        "map_source": map_source,
        "sources": sources,
        "chunks": chunks,
        "limits": [
            "Field names come from the bundled/extended map; an unmapped word "
            "is silence, not absence.",
            "Offsets are chunk-relative bytes; base is recorded provenance and "
            "does not shift field lookup.",
            "An aggregate chunk (label PHYS_<group>, input_format aggregate) "
            "carries its own kv fields; the map does not apply and kv values "
            "carry no word/bit semantics.",
            "No timing (L2) or device-environment (L3) claim: this is a field "
            "decoder over captured words.",
        ],
    }


# ---------------------------------------------------------------------------
# Diff
# ---------------------------------------------------------------------------

def _validate_report(doc: Any, side: str) -> None:
    if not isinstance(doc, dict) or doc.get("format") != DECODE_FORMAT:
        raise StateDecodeError(f"{side} is not a {DECODE_FORMAT} report")
    if not isinstance(doc.get("chunks"), list):
        raise StateDecodeError(f"{side} report has no chunks list")


def _words_to_int(chunk: dict) -> dict[int, int]:
    return {int(offset, 16): int(raw, 16)
            for offset, raw in chunk["words"].items()}


def _field_index(chunk: dict | None) -> dict[tuple[int, str], dict]:
    if chunk is None:
        return {}
    return {(int(field["offset"], 16), field["name"]): field
            for field in chunk["fields"]}


def _field_summary(field: dict | None) -> str | None:
    if field is None:
        return None
    if field.get("kind") == "bits":
        parts = [f"{bit['name']}={bit['state']}"
                 for bit in field.get("bitfields", [])]
        return ", ".join(parts) if parts else field["raw"]
    return f"value={field['raw']}"


def _changed_fields(left: dict | None, right: dict | None) -> list[dict]:
    left_fields = _field_index(left)
    right_fields = _field_index(right)
    rows = []
    for offset, name in sorted(set(left_fields) | set(right_fields)):
        left_field = left_fields.get((offset, name))
        right_field = right_fields.get((offset, name))
        if (left_field is not None and right_field is not None
                and left_field["raw"] == right_field["raw"]):
            continue
        if left_field is None:
            status = "added"
        elif right_field is None:
            status = "removed"
        else:
            status = "changed"
        row: dict[str, Any] = {
            "offset": f"{offset:#x}",
            "name": name,
            "status": status,
            "old": left_field["raw"] if left_field else None,
            "new": right_field["raw"] if right_field else None,
            "old_summary": _field_summary(left_field),
            "new_summary": _field_summary(right_field),
        }
        if (left_field is not None and right_field is not None
                and left_field.get("kind") == right_field.get("kind") == "bits"):
            left_bits = {bit["name"]: bit for bit in left_field["bitfields"]}
            right_bits = {bit["name"]: bit for bit in right_field["bitfields"]}
            bits = []
            for bit_name in sorted(set(left_bits) | set(right_bits)):
                bits.append({
                    "name": bit_name,
                    "old": (left_bits[bit_name]["state"]
                            if bit_name in left_bits else None),
                    "new": (right_bits[bit_name]["state"]
                            if bit_name in right_bits else None),
                })
            row["bits"] = bits
        rows.append(row)
    return rows


def _word_rows(words: dict[int, int]) -> list[dict]:
    return [{"offset": f"{offset:#x}", "raw": _hex(raw)}
            for offset, raw in sorted(words.items())]


def _is_aggregate_chunk(chunk: dict | None) -> bool:
    return bool(chunk) and chunk.get("input_format") == AGGREGATE_FORMAT


def _kv_index(chunk: dict | None) -> dict[tuple[str, int], dict]:
    """Index kv fields by ``(name, occurrence)`` so duplicate keys survive."""
    if chunk is None:
        return {}
    return {(field["name"], int(field.get("index", 0))): field
            for field in chunk.get("fields", [])}


def _kv_rows(left: dict | None, right: dict | None) -> list[dict]:
    """Classified kv diff rows (added / removed / changed) in key order."""
    left_kvs = _kv_index(left)
    right_kvs = _kv_index(right)
    rows = []
    for name, index in sorted(set(left_kvs) | set(right_kvs),
                              key=lambda key: (key[0].lower(), key[0], key[1])):
        left_field = left_kvs.get((name, index))
        right_field = right_kvs.get((name, index))
        if left_field is not None and right_field is not None:
            if (left_field.get("value") == right_field.get("value")
                    and bool(left_field.get("numeric"))
                    == bool(right_field.get("numeric"))):
                continue
            status = "changed"
        elif right_field is not None:
            status = "added"
        else:
            status = "removed"
        rows.append({
            "name": name,
            "index": index,
            "kind": KV_KIND,
            "offset": None,
            "status": status,
            "old": left_field.get("value") if left_field else None,
            "new": right_field.get("value") if right_field else None,
            "old_raw": left_field.get("raw") if left_field else None,
            "new_raw": right_field.get("raw") if right_field else None,
            "old_numeric": left_field.get("numeric") if left_field else None,
            "new_numeric": right_field.get("numeric") if right_field else None,
        })
    return rows


def _classify_fields(rows: list[dict]) -> tuple[list[dict], list[dict], list[dict]]:
    return ([row for row in rows if row.get("status") == "added"],
            [row for row in rows if row.get("status") == "removed"],
            [row for row in rows if row.get("status") == "changed"])


def _diff_aggregate_chunk(left: dict | None, right: dict | None) -> dict:
    """Diff two aggregate (kv) chunks with explicit added/removed/changed."""
    present = right if left is None else left
    rows = _kv_rows(left, right)
    fields_added, fields_removed, fields_changed = _classify_fields(rows)
    if left is None or right is None:
        status = "right_only" if left is None else "left_only"
    else:
        status = "changed" if rows else "identical"
    return {
        "label": present["label"],
        "base": present["base"],
        "left_base": left["base"] if left else None,
        "right_base": right["base"] if right else None,
        "status": status,
        "added": [],
        "removed": [],
        "changed": [],
        "changed_fields": rows,
        "fields_added": fields_added,
        "fields_removed": fields_removed,
        "fields_changed": fields_changed,
    }


def _diff_chunk(left: dict | None, right: dict | None) -> dict:
    if _is_aggregate_chunk(left) or _is_aggregate_chunk(right):
        return _diff_aggregate_chunk(left, right)
    if left is None or right is None:
        present = right if left is None else left
        words = _words_to_int(present)
        rows = _word_rows(words)
        changed_fields = _changed_fields(left, right)
        fields_added, fields_removed, fields_changed = _classify_fields(changed_fields)
        row = {
            "label": present["label"],
            "base": present["base"],
            "left_base": left["base"] if left else None,
            "right_base": right["base"] if right else None,
            "status": "right_only" if left is None else "left_only",
            "added": rows if left is None else [],
            "removed": rows if right is None else [],
            "changed": [],
            "changed_fields": changed_fields,
            "fields_added": fields_added,
            "fields_removed": fields_removed,
            "fields_changed": fields_changed,
        }
        return row
    left_words = _words_to_int(left)
    right_words = _words_to_int(right)
    added = _word_rows({offset: right_words[offset]
                        for offset in right_words if offset not in left_words})
    removed = _word_rows({offset: left_words[offset]
                          for offset in left_words if offset not in right_words})
    changed = [{"offset": f"{offset:#x}", "old": _hex(left_words[offset]),
                "new": _hex(right_words[offset])}
               for offset in sorted(set(left_words) & set(right_words))
               if left_words[offset] != right_words[offset]]
    changed_fields = _changed_fields(left, right)
    fields_added, fields_removed, fields_changed = _classify_fields(changed_fields)
    status = "changed" if (added or removed or changed or changed_fields) \
        else "identical"
    return {
        "label": left["label"],
        "base": left["base"],
        "left_base": left["base"],
        "right_base": right["base"],
        "status": status,
        "added": added,
        "removed": removed,
        "changed": changed,
        "changed_fields": changed_fields,
        "fields_added": fields_added,
        "fields_removed": fields_removed,
        "fields_changed": fields_changed,
    }


def diff_reports(left: dict, right: dict) -> dict:
    """Deterministic word/field diff of two decoded reports."""
    _validate_report(left, "left")
    _validate_report(right, "right")
    left_groups: dict[str, list[dict]] = {}
    right_groups: dict[str, list[dict]] = {}
    for chunk in left["chunks"]:
        left_groups.setdefault(chunk["label"].lower(), []).append(chunk)
    for chunk in right["chunks"]:
        right_groups.setdefault(chunk["label"].lower(), []).append(chunk)
    labels = sorted(set(left_groups) | set(right_groups))
    chunks = []
    for label in labels:
        left_list = left_groups.get(label, [])
        right_list = right_groups.get(label, [])
        for index in range(max(len(left_list), len(right_list))):
            left_chunk = left_list[index] if index < len(left_list) else None
            right_chunk = right_list[index] if index < len(right_list) else None
            chunks.append(_diff_chunk(left_chunk, right_chunk))
    summary = {
        "chunks": len(chunks),
        "changed_chunks": sum(1 for chunk in chunks
                              if chunk["status"] != "identical"),
        "added": sum(len(chunk["added"]) for chunk in chunks),
        "removed": sum(len(chunk["removed"]) for chunk in chunks),
        "changed_words": sum(len(chunk["changed"]) for chunk in chunks),
        "changed_fields": sum(len(chunk["changed_fields"]) for chunk in chunks),
        "fields_added": sum(len(chunk.get("fields_added", []))
                            for chunk in chunks),
        "fields_removed": sum(len(chunk.get("fields_removed", []))
                              for chunk in chunks),
        "fields_changed": sum(len(chunk.get("fields_changed", []))
                              for chunk in chunks),
    }
    return {
        "format": DIFF_FORMAT,
        "left": {"format": left["format"], "map_source": left.get("map_source"),
                 "chunks": len(left["chunks"])},
        "right": {"format": right["format"], "map_source": right.get("map_source"),
                  "chunks": len(right["chunks"])},
        "chunks": chunks,
        "summary": summary,
        "identical": all(chunk["status"] == "identical" for chunk in chunks),
        "limits": [
            "Word/field diff only; an unchanged word does not prove untested "
            "behaviour.",
            "Chunks pair by label and occurrence order; a differing base is "
            "recorded but does not re-pair.",
            "Aggregate kv fields compare by parsed value and numeric-ness: a "
            "raw spelling change that keeps the same value (0x10 vs 16) is "
            "not reported as changed.",
        ],
    }


# ---------------------------------------------------------------------------
# Rendering
# ---------------------------------------------------------------------------

def render_decode(report: dict) -> str:
    """Readable field table for humans; the JSON report stays canonical."""
    lines = []
    for chunk in report["chunks"]:
        if chunk.get("input_format") == AGGREGATE_FORMAT:
            kv_count = chunk.get("kv_count", len(chunk["fields"]))
            lines.append(
                f"chunk {chunk['label']} base={chunk['base']} "
                f"kv={kv_count} (aggregate)")
            for field in chunk["fields"]:
                index = field.get("index", 0)
                name = (field["name"] if not index
                        else f"{field['name']}[{index}]")
                lines.append(f"  {'kv':>6}  {field['raw']:<12} {name:<20} "
                             f"value={field['value']!r}")
            continue
        lines.append(
            f"chunk {chunk['label']} base={chunk['base']} "
            f"words={chunk['word_count']} mapped={len(chunk['fields'])} "
            f"unmapped={chunk['unmapped_count']}")
        for field in chunk["fields"]:
            if field["kind"] == "bits":
                detail = " ".join(f"{bit['name']}={bit['state']}"
                                  for bit in field["bitfields"])
            else:
                detail = f"value={field['raw']}"
            lines.append(f"  {field['offset']:>6}  {field['raw']:<12} "
                         f"{field['name']:<20} {detail}")
        nonzero = [word for word in chunk["unmapped"]
                   if int(word["raw"], 16)]
        if nonzero:
            shown = " ".join(f"{word['offset']}={word['raw']}"
                             for word in nonzero[:12])
            more = "" if len(nonzero) <= 12 else f" (+{len(nonzero) - 12} more)"
            lines.append(f"  unmapped nonzero: {shown}{more}")
    return "\n".join(lines)


def render_diff(report: dict) -> str:
    """Readable diff for humans; the JSON report stays canonical."""
    lines = []
    for chunk in report["chunks"]:
        lines.append(f"chunk {chunk['label']} base={chunk['base']}: "
                     f"{chunk['status']}")
        for word in chunk["added"]:
            lines.append(f"  added    {word['offset']} {word['raw']}")
        for word in chunk["removed"]:
            lines.append(f"  removed  {word['offset']} {word['raw']}")
        for word in chunk["changed"]:
            lines.append(f"  changed  {word['offset']} "
                         f"{word['old']} -> {word['new']}")
        for field in chunk["changed_fields"]:
            if field.get("kind") == KV_KIND or field.get("offset") is None:
                index = field.get("index", 0)
                name = (field["name"] if not index
                        else f"{field['name']}[{index}]")
                old_raw = field.get("old_raw")
                new_raw = field.get("new_raw")
                old_raw = "-" if old_raw is None else old_raw
                new_raw = "-" if new_raw is None else new_raw
                lines.append(f"    kv {name} {field.get('status', 'changed')}: "
                             f"{old_raw} -> {new_raw}")
                continue
            lines.append(f"    field {field['name']} @ {field['offset']}: "
                         f"{field['old']} -> {field['new']}  "
                         f"({field['old_summary']} -> {field['new_summary']})")
            for bit in field.get("bits", []):
                lines.append(f"      bit {bit['name']}: "
                             f"{bit['old']} -> {bit['new']}")
    lines.append(f"summary: {json.dumps(report['summary'], sort_keys=True)} "
                 f"identical={report['identical']}")
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Demo
# ---------------------------------------------------------------------------

def _demo_words(word48: int) -> list[str]:
    words = ["0x0"] * 20  # chunk words 0x00..0x4c
    words[0x10 // WORD_BYTES] = "0xface"
    words[0x48 // WORD_BYTES] = _hex(word48)
    return words


def _demo_snapshot(name: str, *, gpfifo_va: int, ramfc_target: int) -> dict:
    return {
        "schema": SNAPSHOT_FORMAT,
        "source": name,
        "chunks": [
            {"label": "INSTANCE", "base": "0x0",
             "words": _demo_words(gpfifo_va)},
            {"label": "RAMFC", "base": "0x0",
             "words": _demo_words(ramfc_target)},
        ],
    }


def run_demo(out: str | None = None) -> dict:
    """Craft two snapshots in a tempdir, decode+diff them, and report.

    Expected: INSTANCE word 0x048 moves 0x100000 -> 0x200000 and RAMFC word
    0x048 moves 0x00030000 -> 0x00010000 (CE_CTX_VALID clears), i.e. two
    changed words and two changed named fields.
    """
    demo_dir = tempfile.mkdtemp(prefix="greeneye-state-decode-demo-")
    try:
        left_path = os.path.join(demo_dir, "left.json")
        right_path = os.path.join(demo_dir, "right.json")
        left_snapshot = _demo_snapshot("demo-left", gpfifo_va=0x100000,
                                       ramfc_target=0x00030000)
        right_snapshot = _demo_snapshot("demo-right", gpfifo_va=0x200000,
                                        ramfc_target=0x00010000)
        _write_json(left_path, left_snapshot)
        _write_json(right_path, right_snapshot)
        entries, map_source = load_map(None)
        left = decode_specs(
            [{"path": left_path, "label": None, "base": None, "binary": False}],
            entries, map_source)
        right = decode_specs(
            [{"path": right_path, "label": None, "base": None, "binary": False}],
            entries, map_source)
        diff = diff_reports(left, right)
        ok = (not diff["identical"]
              and diff["summary"]["changed_words"] == 2
              and diff["summary"]["changed_fields"] == 2
              and diff["summary"]["added"] == 0
              and diff["summary"]["removed"] == 0)
        demo = {
            "format": DEMO_FORMAT,
            "ok": ok,
            "left": left,
            "right": right,
            "diff": diff,
        }
        if out:
            os.makedirs(out, exist_ok=True)
            artifacts = {}
            for name, doc in (("state-decode-left.json", left),
                              ("state-decode-right.json", right),
                              ("state-diff.json", diff)):
                artifacts[name] = _write_json(os.path.join(out, name), doc)
            for name, path in (("state-snapshot-left.json", left_path),
                               ("state-snapshot-right.json", right_path)):
                target = os.path.join(out, name)
                shutil.copyfile(path, target)
                artifacts[name] = os.path.abspath(target)
            demo["artifacts"] = artifacts
        return demo
    finally:
        shutil.rmtree(demo_dir, ignore_errors=True)


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

class _InputAction(argparse.Action):
    """Collect repeatable ``--input``/``--bin`` specs in command order."""

    def __init__(self, option_strings, dest, binary=False, **kwargs):
        self.binary = binary
        super().__init__(option_strings, dest, **kwargs)

    def __call__(self, parser, namespace, values, option_string=None):
        specs = getattr(namespace, self.dest, None)
        if specs is None:
            specs = []
            setattr(namespace, self.dest, specs)
        spec = {"path": values, "label": None, "base": None,
                "binary": self.binary}
        specs.append(spec)
        setattr(namespace, "_current_spec", spec)


class _InputMetaAction(argparse.Action):
    """Attach ``--label``/``--base`` to the preceding input, or set a default."""

    def __call__(self, parser, namespace, values, option_string=None):
        current = getattr(namespace, "_current_spec", None)
        if current is not None:
            current[self.dest] = values
        setattr(namespace, self.dest, values)


def _apply_defaults(specs: list[dict], label: str | None,
                    base: str | None) -> list[dict]:
    resolved = []
    for spec in specs:
        item = dict(spec)
        if item.get("label") is None:
            item["label"] = label
        if item.get("base") is None:
            item["base"] = base
        resolved.append(item)
    return resolved


def _peek_report(path: str) -> dict | None:
    data = _read_bytes(path)
    doc = _try_json(data)
    if isinstance(doc, dict) and doc.get("format") == DECODE_FORMAT:
        _validate_report(doc, path)
        return doc
    return None


def _load_side(spec: dict, entries: dict[tuple[str, int], dict],
               map_source: str) -> dict:
    report = _peek_report(spec["path"])
    if report is not None:
        return report
    return decode_specs([spec], entries, map_source)


def _write_json(path: str, doc: Any) -> str:
    absolute = os.path.abspath(path)
    parent = os.path.dirname(absolute)
    if parent:
        os.makedirs(parent, exist_ok=True)
    with open(absolute, "w", encoding="utf-8") as handle:
        json.dump(doc, handle, indent=2, sort_keys=True)
        handle.write("\n")
    return absolute


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="state_decode.py",
        description="Decode engine-visible channel state words and aggregate "
                    "GROUP: key=value state groups into named fields, and diff "
                    "two captures (offline).")
    sub = parser.add_subparsers(dest="command")

    decode = sub.add_parser(
        "decode", help="decode one or more raw inputs (state words, hexdumps, "
                       "snapshot JSON, or aggregate key=value groups) into a "
                       "field table")
    decode.add_argument("--input", action=_InputAction, dest="inputs",
                        default=None, metavar="FILE",
                        help="input file; repeatable, auto-detected format "
                             "(LABEL[offset]=value, row/hexdump words, "
                             "greeneye-server-snapshot/1 JSON, or aggregate "
                             "'GROUP: key=value ...' state groups)")
    decode.add_argument("--bin", action=_InputAction, dest="inputs",
                        default=None, metavar="FILE",
                        help="raw little-endian u32 input; repeatable")
    decode.add_argument("--label", action=_InputMetaAction, default=None,
                        help="chunk label for the preceding --input/--bin "
                             "(default for the rest)")
    decode.add_argument("--base", action=_InputMetaAction, default="0x0",
                        help="engine address of chunk offset 0 for the "
                             "preceding input (default 0x0)")
    decode.add_argument("--map", dest="map_path", default=None,
                        help=f"{MAP_FORMAT} override/extension file")
    decode.add_argument("--json", dest="json_path", default=None,
                        help="write the decoded report JSON here")

    diff = sub.add_parser(
        "diff", help="diff two decoded reports or two raw inputs (state "
                     "words or aggregate key=value groups); kv changes are "
                     "reported as added/removed/changed")
    diff.add_argument("left", help=f"{DECODE_FORMAT} report or raw input")
    diff.add_argument("right", help=f"{DECODE_FORMAT} report or raw input")
    diff.add_argument("--left-label", dest="left_label", default=None,
                      help="chunk label for a raw left input")
    diff.add_argument("--left-base", dest="left_base", default="0x0",
                      help="base for a raw left input")
    diff.add_argument("--left-bin", dest="left_bin", action="store_true",
                      help="force the left input to raw u32 words")
    diff.add_argument("--right-label", dest="right_label", default=None,
                      help="chunk label for a raw right input")
    diff.add_argument("--right-base", dest="right_base", default="0x0",
                      help="base for a raw right input")
    diff.add_argument("--right-bin", dest="right_bin", action="store_true",
                      help="force the right input to raw u32 words")
    diff.add_argument("--map", dest="map_path", default=None,
                      help=f"{MAP_FORMAT} override/extension file")
    diff.add_argument("--json", dest="json_path", default=None,
                      help="write the diff report JSON here")

    demo = sub.add_parser(
        "demo", help="craft two snapshots, decode+diff them, print the result")
    demo.add_argument("--out", default=None,
                      help="write demo snapshots and reports to this directory")
    return parser


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    try:
        if args.command == "decode":
            specs = _apply_defaults(list(args.inputs or []), args.label,
                                    args.base)
            if not specs:
                raise StateDecodeError("decode needs at least one --input/--bin")
            entries, map_source = load_map(args.map_path)
            report = decode_specs(specs, entries, map_source)
            print(render_decode(report))
            if args.json_path:
                _write_json(args.json_path, report)
            return 0
        if args.command == "diff":
            entries, map_source = load_map(args.map_path)
            left = _load_side({"path": args.left, "label": args.left_label,
                               "base": args.left_base,
                               "binary": args.left_bin}, entries, map_source)
            right = _load_side({"path": args.right, "label": args.right_label,
                                "base": args.right_base,
                                "binary": args.right_bin}, entries, map_source)
            report = diff_reports(left, right)
            print(render_diff(report))
            if args.json_path:
                _write_json(args.json_path, report)
            return 0 if report["identical"] else 3
        if args.command == "demo":
            demo = run_demo(args.out)
            print(f"demo: {demo['format']} ok={demo['ok']}")
            print(render_decode(demo["left"]))
            print(render_diff(demo["diff"]))
            print(json.dumps({"ok": demo["ok"],
                              "summary": demo["diff"]["summary"]},
                             indent=2, sort_keys=True))
            return 0 if demo["ok"] else 3
        parser.print_help()
        return 2
    except StateDecodeError as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2


if __name__ == "__main__":
    raise SystemExit(main())