ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/battle/aiauthor.py

@@ -0,0 +1,305 @@
+"""Phase-6c-ii: enemy-AI branch AUTHORING -- the write-side companion to the 6a disassembler + 6b same-length
+patcher. Where 6b retunes a CONSTANT in place (no byte moves), this ADDS or REPLACES a whole AI function (a new
+phase branch, a counter, a rewritten body) -- the first LENGTH-CHANGING AI edit.
+
+It is a thin bridge: assemble the readable AI source with the Phase-6c command assembler
+(:func:`ff9mapkit.eb.cmdasm.assemble_block`), then splice the resulting body into the forked battle ``.eb`` with
+the existing byte-safe length-changing primitives (:mod:`ff9mapkit.eb.edit`), which do the entry-table + intra-entry
+``fpos`` fixup. Battle ``.eb`` is the same container/interpreter as a field script, and ``replace_function_body``
+is already used on battle ebs (to re-author Main_Init for an edited spawn), so the machinery is proven; what 6c
+adds is the way to WRITE the new bytecode by hand.
+
+The AI-phase tags the engine dispatches (project-ff9-battle-tuning): 1 Main, 6 Counter, 7 ATB, 9 Dying (tag 0 =
+the entry's Init). A fuller battle linter -- valid tags, an Attack index in range, a terminating RET -- is the next
+step (Phase 6c-iii); these wrappers stay deliberately thin.
+"""
+from __future__ import annotations
+
+from ..eb import cmdasm, disasm
+from ..eb import edit as _edit
+from ..eb.model import EbScript
+from .ailint import TERMINATOR_OPS as _TERMINATOR_OPS    # the flow-terminators (RET/TerminateEntry/GameOver/...),
+
+# the AI-phase function tags an enemy-type entry dispatches (0 = Init, the spawn binding, edited via Main_Init).
+AI_PHASE_TAGS = {1: "Main", 6: "Counter", 7: "ATB", 9: "Dying"}
+
+# (`_TERMINATOR_OPS` shared with the linter so the two never drift.) The engine has NO per-function length bound,
+# so an authored body that doesn't END in one of these runs the IP off into adjacent bytecode at runtime.
+
+
+class AiAuthorError(ValueError):
+    pass
+
+
+def _check_entry(eb_bytes: bytes, entry_index: int):
+    """Re-parse + bounds-check the entry; returns the parsed EbScript. Raises a clean error on a bad index."""
+    try:
+        eb = EbScript.from_bytes(eb_bytes)
+    except (ValueError, IndexError) as ex:
+        raise AiAuthorError(f"malformed battle .eb: {type(ex).__name__}: {ex}")
+    if not 0 <= entry_index < len(eb.entries) or eb.entries[entry_index].empty:
+        raise AiAuthorError(f"entry {entry_index} is out of range / empty "
+                            f"({sum(not e.empty for e in eb.entries)} non-empty entries)")
+    return eb
+
+
+def add_ai_function(eb_bytes: bytes, entry_index: int, tag: int, block_text: str) -> bytes:
+    """Assemble ``block_text`` (cmdasm) and ADD it as a NEW function ``tag`` to enemy-AI entry ``entry_index``.
+
+    Returns the new eb bytes (the entry's function table grows by one slot, every existing func's ``fpos`` and
+    every later entry's table offset are fixed up by :func:`eb.edit.add_function`). Raises if ``tag`` already
+    exists on that entry (use :func:`replace_ai_function` to rewrite an existing one)."""
+    eb = _check_entry(eb_bytes, entry_index)
+    if eb.entries[entry_index].func_by_tag(tag) is not None:
+        raise AiAuthorError(f"entry {entry_index} already has a function with tag {tag} "
+                            f"({AI_PHASE_TAGS.get(tag, '?')}) -- use replace_ai_function to rewrite it")
+    body = _assemble(block_text)
+    return _edit.add_function(eb_bytes, entry_index, tag, body)
+
+
+def replace_ai_function(eb_bytes: bytes, entry_index: int, tag: int, block_text: str) -> bytes:
+    """Assemble ``block_text`` and REPLACE function ``tag``'s body in entry ``entry_index`` (any length).
+
+    The later functions' ``fpos`` + later entries' offsets shift by the size delta (handled by
+    :func:`eb.edit.replace_function_body`). Raises if ``tag`` is absent."""
+    eb = _check_entry(eb_bytes, entry_index)
+    if eb.entries[entry_index].func_by_tag(tag) is None:
+        raise AiAuthorError(f"entry {entry_index} has no function with tag {tag} -- use add_ai_function to add it")
+    body = _assemble(block_text)
+    return _edit.replace_function_body(eb_bytes, entry_index, tag, body)
+
+
+def apply_ai_functions(eb_bytes: bytes, specs) -> bytes:
+    """Apply a list of ``[[scene.ai_function]]`` specs (add / replace AI functions) to ``eb_bytes`` IN ORDER.
+
+    Each spec is a table: ``entry`` (int, the enemy-type entry), ``tag`` (int, the AI-phase tag), ``source`` (str,
+    the `cmdasm` command block), and optional ``replace`` (bool, default false -> add; true -> replace the body).
+    Length-changing -- run this AFTER the same-length `[[scene.ai_patch]]` so the patch offsets are still valid."""
+    if not isinstance(specs, list):
+        raise AiAuthorError("[[scene.ai_function]] must be a list of tables")
+    eb = eb_bytes
+    for n, spec in enumerate(specs, 1):
+        if not isinstance(spec, dict):
+            raise AiAuthorError(f"[[scene.ai_function]] #{n} must be a table (got {type(spec).__name__})")
+        try:
+            entry, tag = int(spec["entry"]), int(spec["tag"])
+        except (KeyError, TypeError, ValueError):
+            raise AiAuthorError(f"[[scene.ai_function]] #{n} needs integer entry + tag (and a source string)")
+        if not 0 <= tag <= 0xFFFF:                          # the func-table slot stores tag as a u16 (else struct
+            raise AiAuthorError(f"[[scene.ai_function]] #{n} tag {tag} out of range (0-65535); the AI-phase tags "
+                                f"are {sorted(AI_PHASE_TAGS)}")   # would raise a raw error deep in eb.edit)
+        source = spec.get("source")
+        if not isinstance(source, str) or not source.strip():
+            raise AiAuthorError(f"[[scene.ai_function]] #{n} needs a non-empty source string")
+        src = source.replace(";", "\n")                     # accept ';' as a line separator (one-line TOML source)
+        eb = replace_ai_function(eb, entry, tag, src) if spec.get("replace") else add_ai_function(eb, entry, tag, src)
+    return eb
+
+
+def validate_ai_functions(eb_bytes: bytes, specs, *, atk_count: int | None = None) -> list:
+    """Dry-run :func:`apply_ai_functions` + LINT the result; return error strings (empty == ok) for the offline
+    build validate. Catches a bad entry/tag/source, a duplicate/missing tag, AND a structural fault in the
+    authored AI (a non-terminating branch, an out-of-bounds jump, an out-of-range Attack index when ``atk_count``
+    is given) via :mod:`ff9mapkit.battle.ailint`."""
+    from . import ailint as _ailint
+    try:
+        out = apply_ai_functions(eb_bytes, specs)
+    except AiAuthorError as ex:
+        return [str(ex)]
+    return [f"lint: {i}" for i in _ailint.lint_ai(out, atk_count=atk_count)]
+
+
+# ---------------------------------------------------------------------------------------------------------------
+# Phase-6c (productized): INSERT a branch into an existing function (the length-changing primitive made declarative)
+# + the HP-PHASE convenience that generates the branch. `ai_function` REPLACES a whole function; these SPLICE a
+# fragment into one -- the missing surface that the in-game-proven coin-flip / HP-phase branches needed by hand.
+# ---------------------------------------------------------------------------------------------------------------
+
+_VAR_RE = __import__("re").compile(r"^[A-Za-z]+\.[A-Za-z0-9]+\[\d+\]$")   # a Source.Type[i] variable token
+
+
+def _func_pretty(eb_bytes: bytes, entry_index: int, tag: int):
+    """(EbScript, Func, [(off, mnemonic, [operand_str]) ...]) for entry/tag -- the NAMED decode (battleai)."""
+    from .battleai import _decode_func_pretty
+    eb = _check_entry(eb_bytes, entry_index)
+    f = eb.entries[entry_index].func_by_tag(tag)
+    if f is None:
+        raise AiAuthorError(f"entry {entry_index} has no function tag {tag} ({AI_PHASE_TAGS.get(tag, '?')})")
+    instrs = list(_decode_func_pretty(eb.data, f.abs_start, min(f.abs_end, len(eb.data))))
+    return eb, f, instrs
+
+
+def _locate_insert(f, instrs, spec, n: int) -> int:
+    """Resolve a spec's locator to an ABSOLUTE byte offset inside function ``f``. Locators: ``before``/``after`` =
+    a command mnemonic (insert before / after the FIRST match), or ``at`` = a body offset (0 = prepend)."""
+    have = [k for k in ("before", "after", "at") if k in spec]
+    if len(have) != 1:
+        raise AiAuthorError(f"#{n} needs exactly one locator: before = \"<mnemonic>\" | after = \"<mnemonic>\" | "
+                            f"at = <body offset> (got {have or 'none'})")
+    boundaries = {off for off, _, _ in instrs}           # the instruction-start offsets = the only valid insert points
+    if "at" in spec:
+        try:
+            rel = int(spec["at"])
+        except (TypeError, ValueError):
+            raise AiAuthorError(f"#{n} at must be an integer body offset")
+        if not 0 <= rel < f.length:                      # f.length (the end) is NOT insertable -- see the append note
+            raise AiAuthorError(f"#{n} at = {rel} is outside the func body (0-{f.length - 1}); to add code at the "
+                                f"end, splice before the terminator (before = \"RET\"), not after it")
+        if f.abs_start + rel not in boundaries:          # mid-instruction insert would split an opcode -> corrupt
+            valid = sorted(o - f.abs_start for o in boundaries)
+            raise AiAuthorError(f"#{n} at = {rel} is not an instruction boundary (would split an instruction); "
+                                f"valid body offsets are {valid}")
+        return f.abs_start + rel
+    key = "before" if "before" in spec else "after"
+    mnem = spec[key]
+    offs = [off for off, mn, _ in instrs if mn == mnem]   # offsets of each instruction with that mnemonic
+    if not offs:
+        present = sorted({mn for _, mn, _ in instrs})
+        raise AiAuthorError(f"#{n} {key} = {mnem!r}: no such instruction in the function (has: {', '.join(present)})")
+    if key == "before":
+        return offs[0]
+    seq = [off for off, _, _ in instrs] + [f.abs_end]    # after: the byte AFTER the first match = the next instr's off
+    nxt = seq[seq.index(offs[0]) + 1]
+    if nxt == f.abs_end:                                 # the match is the LAST instruction -> would append past the
+        raise AiAuthorError(f"#{n} after = {mnem!r}: that is the function's LAST instruction; you cannot append "    # end
+                            f"after the final instruction -- splice before the terminator instead (before = ...)")
+    return nxt
+
+
+def apply_ai_inserts(eb_bytes: bytes, specs) -> bytes:
+    """Apply a list of ``[[scene.ai_insert]]`` specs IN ORDER. Each splices an assembled FRAGMENT into a function:
+    ``entry`` + ``tag`` (which function), a locator (``before``/``after`` = a command mnemonic, or ``at`` = a body
+    offset), and ``source`` (the `cmdasm` block -- a FRAGMENT, NOT required to end in RET; it flows into the rest of
+    the function). Splice = :func:`eb.edit.insert_in_function` (fpos fixup; it refuses if one of the function's own
+    jumps STRADDLES the insert point -- surfaced as a clean error). Length-changing -> run AFTER `ai_patch`."""
+    if not isinstance(specs, list):
+        raise AiAuthorError("[[scene.ai_insert]] must be a list of tables")
+    eb = eb_bytes
+    for n, spec in enumerate(specs, 1):
+        if not isinstance(spec, dict):
+            raise AiAuthorError(f"[[scene.ai_insert]] #{n} must be a table (got {type(spec).__name__})")
+        try:
+            entry, tag = int(spec["entry"]), int(spec["tag"])
+        except (KeyError, TypeError, ValueError):
+            raise AiAuthorError(f"[[scene.ai_insert]] #{n} needs integer entry + tag")
+        source = spec.get("source")
+        if not isinstance(source, str) or not source.strip():
+            raise AiAuthorError(f"[[scene.ai_insert]] #{n} needs a non-empty source string")
+        try:
+            body = cmdasm.assemble_block(source.replace(";", "\n"))
+        except cmdasm.CmdAsmError as ex:
+            raise AiAuthorError(f"[[scene.ai_insert]] #{n} source did not assemble: {ex}")
+        _eb, f, instrs = _func_pretty(eb, entry, tag)
+        abs_off = _locate_insert(f, instrs, spec, n)
+        try:
+            eb = _edit.insert_in_function(eb, entry, tag, abs_off - f.abs_start, body)
+        except ValueError as ex:                          # a straddling jump / bad offset from the splice primitive
+            raise AiAuthorError(f"[[scene.ai_insert]] #{n}: {ex}")
+    return eb
+
+
+def _gen_hp_phase(stat: str, below: float, then_atk: int, else_atk: int, var: str, n: int,
+                  atk_count: int | None = None) -> str:
+    """Generate the `cmdasm` source for a stat-threshold branch: when SELF ``stat`` < ``below`` of max, set the
+    attack-index var to ``then_atk``, else ``else_atk``. Uses the exact ``_E``/``B_PICK``/``B_COUNT`` extract idiom
+    56 shipping bosses use for 'cur vs fraction-of-max' (the ``_E`` ops bind the read target via the SysList)."""
+    pair = {"hp": ("cur.hp", "max.hp"), "mp": ("cur.mp", "max.mp"), "at": ("cur.at", "max.at")}.get(stat)
+    if pair is None:
+        raise AiAuthorError(f"[[scene.ai_phase]] #{n}: stat must be hp/mp/at (got {stat!r})")
+    if not 0.0 < below < 1.0:
+        raise AiAuthorError(f"[[scene.ai_phase]] #{n}: below must be a fraction 0<below<1 (e.g. 0.5 = half)")
+    div = round(1.0 / below)                              # the proven idiom is cur < max/DIV (a unit fraction)
+    if not 2 <= div <= 0xFFFF or abs(1.0 / div - below) > 1e-6:   # div is emitted as a 2-byte const(N) -> <= 0xFFFF
+        raise AiAuthorError(f"[[scene.ai_phase]] #{n}: below = {below} must be a unit fraction 1/N with 2<=N<=65535 "
+                            f"(0.5, 0.25, 0.2, …) to use the cur < max/N idiom")
+    # then/else index the scene's GLOBAL enemy_attack[] table. The offline lint CANNOT range-check it (the value is
+    # written into a variable, so the Attack operand is an expression, not an immediate) -- so guard it HERE when the
+    # scene's attack count is known, else fall back to the byte ceiling.
+    hi = (atk_count - 1) if atk_count else 0xFF
+    for nm, v in (("then", then_atk), ("else", else_atk)):
+        if not 0 <= v <= hi:
+            scope = f" (scene has {atk_count} attacks)" if atk_count else ""
+            raise AiAuthorError(f"[[scene.ai_phase]] #{n}: {nm} attack index {v} out of range (0-{hi}){scope}")
+    cur, mx = pair
+    return "\n".join([
+        f"SET({{B_SYSLIST[1] B_MEMBER({cur}) B_SYSLIST[1] B_MEMBER({mx}) B_PICK const({div}) B_DIV B_LT_E B_COUNT B_EXPR_END}})",
+        "JMP_IFNOT(L_phase_else)",
+        f"SET({{{var} const({then_atk}) B_LET B_EXPR_END}})",
+        "JMP(L_phase_done)",
+        "L_phase_else:",
+        f"SET({{{var} const({else_atk}) B_LET B_EXPR_END}})",
+        "L_phase_done:",
+    ])
+
+
+def _infer_attack_var(instrs, n: int) -> str:
+    """The variable an `Attack` command reads as its index, so the phase branch can override it. Requires exactly
+    one `Attack` whose operand is a single ``{ Source.Type[i] B_EXPR_END }`` expression."""
+    atks = [ops for _, mn, ops in instrs if mn == "Attack"]
+    if len(atks) != 1:
+        raise AiAuthorError(f"[[scene.ai_phase]] #{n}: the function must have exactly ONE Attack (found "
+                            f"{len(atks)}) -- use [[scene.ai_insert]] with an explicit source instead")
+    toks = atks[0][0].strip().strip("{}").split() if atks[0] else []
+    if len(toks) != 2 or toks[1] != "B_EXPR_END" or not _VAR_RE.match(toks[0]):
+        raise AiAuthorError(f"[[scene.ai_phase]] #{n}: the Attack must read a single variable (e.g. "
+                            f"Attack({{Instance.Byte[18] B_EXPR_END}})); this one is Attack({atks[0][0] if atks[0] else ''}) "
+                            f"-- use [[scene.ai_insert]] instead")
+    return toks[0]
+
+
+def apply_ai_phases(eb_bytes: bytes, specs, *, atk_count: int | None = None) -> bytes:
+    """Apply ``[[scene.ai_phase]]`` specs: a high-level "enrage below X% HP" surface that GENERATES an HP-threshold
+    branch and splices it before the function's `Attack`. Each spec: ``entry`` + ``tag``; ``stat`` (hp/mp/at,
+    default hp); ``below`` (unit fraction, default 0.5); ``then`` / ``else`` (the attack index below / above the
+    threshold). The attack-index variable is INFERRED from the function's `Attack`. Built on `apply_ai_inserts``.
+    ``atk_count`` (when known) range-checks then/else against the scene's attack table -- the one fault the composed
+    lint can't see, since the index flows through a runtime variable."""
+    if not isinstance(specs, list):
+        raise AiAuthorError("[[scene.ai_phase]] must be a list of tables")
+    eb = eb_bytes
+    for n, spec in enumerate(specs, 1):
+        if not isinstance(spec, dict):
+            raise AiAuthorError(f"[[scene.ai_phase]] #{n} must be a table (got {type(spec).__name__})")
+        try:
+            entry, tag = int(spec["entry"]), int(spec["tag"])
+            then_atk, else_atk = int(spec["then"]), int(spec["else"])
+            below = float(spec.get("below", 0.5))            # a non-numeric below -> a clean AiAuthorError, not a crash
+        except (KeyError, TypeError, ValueError):
+            raise AiAuthorError(f"[[scene.ai_phase]] #{n} needs integer entry, tag, then, else and a numeric below")
+        stat = str(spec.get("stat", "hp"))
+        _eb, _f, instrs = _func_pretty(eb, entry, tag)
+        var = _infer_attack_var(instrs, n)
+        source = _gen_hp_phase(stat, below, then_atk, else_atk, var, n, atk_count=atk_count)
+        eb = apply_ai_inserts(eb, [{"entry": entry, "tag": tag, "source": source, "before": "Attack"}])
+    return eb
+
+
+def validate_ai_edits(eb_bytes: bytes, *, inserts=None, phases=None, atk_count: int | None = None) -> list:
+    """Dry-run :func:`apply_ai_inserts` / :func:`apply_ai_phases` + LINT the composed result (for the build's offline
+    validate). Returns error strings (empty == ok) -- never raises on a bad spec (returns it as an error string)."""
+    from . import ailint as _ailint
+    out = eb_bytes
+    try:
+        if phases:
+            out = apply_ai_phases(out, phases, atk_count=atk_count)
+        if inserts:
+            out = apply_ai_inserts(out, inserts)
+    except AiAuthorError as ex:
+        return [str(ex)]
+    return [f"lint: {i}" for i in _ailint.lint_ai(out, atk_count=atk_count)]
+
+
+def _assemble(block_text: str) -> bytes:
+    try:
+        body = cmdasm.assemble_block(block_text)
+    except cmdasm.CmdAsmError as ex:
+        raise AiAuthorError(f"AI source did not assemble: {ex}")
+    # Require a flow terminator: the engine has no per-function length bound, so a body that doesn't end in RET
+    # (0x04) / TerminateEntry (0x1C) runs the IP off the end into adjacent bytecode at runtime (a runaway AI turn).
+    last = None
+    for last in disasm.iter_code(body, 0, len(body)):
+        pass
+    if last is None or last.op not in _TERMINATOR_OPS:
+        raise AiAuthorError("an AI branch must END in RET() (or TerminateEntry) -- otherwise the engine runs the "
+                            "instruction pointer off the function into adjacent bytecode at runtime")
+    return body

ff9mapkit/battle/ailint.py

@@ -0,0 +1,140 @@
+"""Phase-6c-iii: the enemy-AI LINTER -- validate a battle scene's AI bytecode OFFLINE (the "I can't see the game"
+superpower applied to the AI stack). The capstone of Phase 6c: 6a reads the AI, 6b patches a constant, 6c-i/-ii
+author expressions/branches, and this CHECKS the result before deploy.
+
+The checks are all SOUND -- a shipping scene must lint CLEAN (validated by a sweep over real battle scenes), so
+every check passes valid AI and only flags a genuine fault:
+
+  * decode -- every entry/function decodes cleanly to its declared boundary (a truncated/corrupt eb).
+  * jump bounds -- every relative jump (JMP/JMP_IFNOT/JMP_IF) lands ON an instruction inside its own function (a
+    jump out of bounds / into the middle of an instruction = a desync/crash; this also catches a backward
+    JMP_IFNOT, whose offset the engine reads UNSIGNED -> a huge out-of-bounds target).
+  * reachable terminator -- a forward reachability walk (follow jumps + fall-through, conditional = both, bound by
+    visited offsets so loops terminate); flag a function where a path falls through the END without hitting a
+    terminator (RET 0x04 / TerminateEntry 0x1C). The engine has NO per-function length bound, so such a path runs
+    the IP off into adjacent bytecode. (Trailing NOP padding after a RET/loop is correctly UNREACHABLE -> clean.)
+  * attack index -- an IMMEDIATE Attack (0x38) operand must be < the scene's attack count (an out-of-range index
+    reads past the scene's `atk[]` table). Skipped when the index is an expression (computed at runtime) or when
+    the attack count is unknown.
+
+Read-only + offline. Provenance: only opcode NAMES are used; the donor bytes are read live.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..eb import disasm
+from ..eb.model import EbScript
+
+# the flow-TERMINATOR opcodes -- a path reaching one ENDS (the engine's per-function dispatch stops via adFin(),
+# the IP never advances into adjacent bytecode). RET (case 4) + DELETE/TerminateEntry (case 28) are the common
+# pair; the high ops whose DoEventCode return code (3-8) also routes through adFin() terminate identically:
+# Battle 0x2A / Field 0x2B / WorldMap 0xB6 / STOP 0x4F / TetraMaster 0xAE / GameOver 0xF5 (verified vs EBin.cs).
+# (Shared with aiauthor's authoring guard so the two never drift.)
+TERMINATOR_OPS = {0x04, 0x1C, 0x2A, 0x2B, 0x4F, 0xAE, 0xB6, 0xF5}
+_TERMINATORS = TERMINATOR_OPS
+_JUMP_OPS = {0x01, 0x02, 0x03}  # JMP / JMP_IFNOT / JMP_IF (op<0x10, a 2-byte relative offset operand)
+_JUMP_TABLE_OPS = {0x06, 0x0B, 0x0D}   # SWITCHEX / SWITCH / SWITCH2 -- a multi-target dispatch (conservatively
+#                                        treated as terminating a reachability path: it transfers control onward)
+_ATTACK_OP = 0x38               # the Attack command -- operand 0 selects an attack from the scene's atk[] table
+
+
+@dataclass
+class AiIssue:
+    severity: str               # "error" | "warning"
+    where: str                  # e.g. "entry1/tag5 @1159"
+    message: str
+
+    def __str__(self) -> str:
+        return f"[{self.severity}] {self.where}: {self.message}"
+
+
+def _jump_target(ins) -> int | None:
+    """The absolute target of a relative jump, or None if its offset is an expression (computed at runtime).
+
+    Signedness MATCHES the engine: JMP (0x01, ``bra``) and JMP_IF (0x03, ``bne``->``bra``) read a SIGNED int16
+    (``getShortIP``); JMP_IFNOT (0x02, ``beq``) reads its skip offset UNSIGNED (``getUShortIP``) -- so a backward
+    JMP_IFNOT becomes a huge forward target the bounds check flags (the exact fault the linter exists to catch)."""
+    if ins.arg_is_expr[0]:
+        return None
+    raw = ins.imm(0)
+    if ins.op == 0x02:                                           # JMP_IFNOT (beq) -- engine reads this UNSIGNED
+        return ins.end + raw
+    return ins.end + (raw - 0x10000 if raw >= 0x8000 else raw)   # JMP / JMP_IF -- signed int16
+
+
+def _lint_function(data: bytes, where: str, start: int, end: int, atk_count) -> list:
+    issues: list = []
+    instrs: dict = {}
+    try:
+        for ins in disasm.iter_code(data, start, end):
+            instrs[ins.off] = ins
+    except (IndexError, KeyError):
+        return [AiIssue("error", where, "bytecode does not decode cleanly (truncated/corrupt)")]
+    if not instrs:
+        return [AiIssue("error", where, "empty function body")]
+    last = instrs[max(instrs)]
+    if last.end != end:                                     # decode under/overran the declared boundary
+        return [AiIssue("error", where, f"bytecode does not decode to the function boundary "
+                                        f"(last instr ends at {last.end}, boundary {end})")]
+
+    # jump bounds + attack index (per instruction)
+    for off, ins in instrs.items():
+        if ins.op in _JUMP_OPS:
+            tgt = _jump_target(ins)
+            if tgt is not None and (tgt < start or tgt >= end or tgt not in instrs):
+                issues.append(AiIssue("error", f"{where} @{off}",
+                                      f"{disasm.op_name(ins.op)} target {tgt} is outside the function / not an "
+                                      f"instruction boundary [{start}..{end})"))
+        elif ins.op == _ATTACK_OP and atk_count is not None and ins.args and not ins.arg_is_expr[0]:
+            idx = ins.imm(0)
+            if idx is not None and idx >= atk_count:
+                issues.append(AiIssue("error", f"{where} @{off}",
+                                      f"Attack index {idx} >= the scene's attack count {atk_count}"))
+
+    # reachable terminator -- a forward walk; flag a path that falls through the end without a terminator
+    seen: set = set()
+    stack = [start]
+    ran_off = False
+    while stack:
+        o = stack.pop()
+        if o >= end:                                        # a path fell through the function boundary
+            ran_off = True
+            continue
+        if o in seen or o not in instrs:                    # already explored, or a bad target (already flagged)
+            continue
+        seen.add(o)
+        op = instrs[o].op
+        if op in _TERMINATORS or op in _JUMP_TABLE_OPS:     # path ends here (RET / dispatched onward)
+            continue
+        if op == 0x01:                                      # unconditional JMP -> its target only
+            tgt = _jump_target(instrs[o])
+            stack.append(tgt if tgt is not None else instrs[o].end)
+        elif op in (0x02, 0x03):                            # conditional -> the target AND the fall-through
+            tgt = _jump_target(instrs[o])
+            if tgt is not None:
+                stack.append(tgt)
+            stack.append(instrs[o].end)
+        else:
+            stack.append(instrs[o].end)                     # fall through to the next instruction
+    if ran_off:
+        issues.append(AiIssue("error", where, "a control-flow path runs off the end of the function without a "
+                                              "terminator (RET/TerminateEntry) -- the engine would execute "
+                                              "adjacent bytecode at runtime"))
+    return issues
+
+
+def lint_ai(eb_bytes: bytes, *, atk_count: int | None = None) -> list:
+    """Lint a battle scene's enemy-AI ``.eb`` -> a list of :class:`AiIssue` (empty == clean). ``atk_count`` (the
+    scene's attack-table size, from ``scene_data.parse_counts``) enables the Attack-index range check. Read-only."""
+    try:
+        eb = EbScript.from_bytes(eb_bytes)
+    except (ValueError, IndexError) as ex:
+        return [AiIssue("error", "eb", f"malformed battle .eb: {type(ex).__name__}: {ex}")]
+    issues: list = []
+    for e in eb.entries:
+        if e.empty:
+            continue
+        for f in e.funcs:
+            issues += _lint_function(eb.data, f"entry{e.index}/tag{f.tag}", f.abs_start, f.abs_end, atk_count)
+    return issues

ff9mapkit/battle/aipatch.py

@@ -0,0 +1,175 @@
+"""Phase-6b: SAME-LENGTH enemy-AI constant patches -- the first AI *authoring* step (read = Phase-6a `battleai`).
+
+An enemy's AI is the per-scene ``EVT_BATTLE_*.eb`` bytecode. The safest authoring edit is a *literal* one: change
+a numeric CONSTANT in place without moving any bytes -- an HP threshold a phase-switch compares (``B_CONST`` in
+an expression), the attack index a turn selects (a ``BTLCMD`` immediate), a ``Wait`` count. No length change means
+no ``fpos``/entry-table fixup and no risk of mis-packing -- byte-accurate by construction (the eb-codec identity
+holds), exactly like ``scene_data``'s surgical raw16 patch.
+
+Addressing is by BYTE OFFSET (from ``battle-ai --sites``) + a required OLD-value guard: the patch only applies if
+the constant at that offset currently equals ``old`` (so a stale/wrong offset fails LOUD instead of corrupting a
+random byte), and ``new`` must fit the SAME byte width. Because a battle eb's bytecode is language-identical
+(only the 84-byte name field differs), the same offset patches every language's eb.
+
+This reaches NUMERIC LITERALS only (command immediates + ``B_CONST``/``B_CONST4`` expression literals) -- the
+"same-length literal patch" tier. Structural AI changes (new branches, an expression assembler, retargeting which
+variable is read) are Phase-6c. Read-the-AI-first is mandatory: there is no semantic search; you cite the offset
+the disassembler prints.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..eb._optables import OP_ARG_COUNT
+from ..eb import disasm as _disasm
+from ..eb.model import EbScript
+
+_I32 = 2 ** 31 - 1
+
+
+class AiPatchError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Site:
+    """One patchable numeric constant in the AI bytecode."""
+    offset: int        # absolute byte offset of the constant's first byte (the patch target)
+    width: int         # byte width (1/2/3/4) -- a same-length patch occupies exactly these bytes
+    value: int         # the current little-endian unsigned value
+    where: str         # human context, e.g. "entry2/tag1 BTLCMD arg0" or "entry2/tag1 expr-const"
+    vmax: int          # the largest value the ENGINE accepts here (usually 2^(8w)-1; B_CONST4 masks to 26 bits)
+
+
+def _full_max(width: int) -> int:
+    return (1 << (8 * width)) - 1
+
+
+def _le(raw: bytes, pos: int, sz: int) -> int:
+    v = 0
+    for k in range(sz):
+        v |= raw[pos + k] << (8 * k)
+    return v
+
+
+def _expr_constants(raw: bytes, pos: int, ctx: str) -> tuple[list, int]:
+    """Walk one expression token stream (mirrors :func:`disasm.pretty_expr`), collecting the ``B_CONST`` (2-byte)
+    and ``B_CONST4`` (4-byte) literal sites. Returns (sites, new_pos)."""
+    sites = []
+    while True:
+        o = raw[pos]; pos += 1
+        isconst = o in (0x7D, 0x7E)
+        isvar = o >= 0xC0 or o in (0x29, 0x5F, 0x78, 0x79, 0x7A)
+        if not isconst and not isvar:
+            if o == 0x7F:
+                break
+            continue
+        if o == 0x7E:                                   # B_CONST4 -- a 4-byte literal, MASKED to 26 bits in-engine
+            sites.append(Site(pos, 4, _le(raw, pos, 4), f"{ctx} expr-const4", 0x3FFFFFF)); pos += 4
+        elif o == 0x7D:                                 # B_CONST -- a 2-byte literal (signed 16; byte-faithful)
+            sites.append(Site(pos, 2, _le(raw, pos, 2), f"{ctx} expr-const", _full_max(2))); pos += 2
+        elif o >= 0xE0 or o == 0x78:                    # long var / B_OBJSPECA -- 2 operand bytes (NOT a literal)
+            pos += 2
+        else:                                           # short var / B_SYSLIST / B_SYSVAR / B_MEMBER / B_PTR
+            pos += 1
+    return sites, pos
+
+
+def _func_constants(raw: bytes, start: int, end: int, ctx: str) -> list:
+    """Collect every patchable numeric constant in ``raw[start:end]`` (command immediates + expression literals).
+    Mirrors :func:`disasm.read_code`'s operand walk exactly so the offsets always line up with the disassembly."""
+    sites = []
+    pos = start
+    guard = 0
+    while pos < end and guard < 100000:
+        guard += 1
+        op = raw[pos]; pos += 1
+        if op == 0xFF:
+            op = 0x100 | raw[pos]; pos += 1
+        ac = OP_ARG_COUNT[op] if op < len(OP_ARG_COUNT) else 0
+        arg_flag = 0
+        if op >= 0x10 and ac != 0:
+            arg_flag = raw[pos]; pos += 1
+        if op == 0x05:
+            arg_flag = 1
+        if ac < 0:
+            ac = raw[pos]; pos += 1
+            if op == 0x0D:
+                ac |= raw[pos] << 8; pos += 1
+            if op == 0x06:
+                ac = 1 + 2 * ac
+            elif op in (0x0B, 0x0D):
+                ac = 2 + ac
+        for i in range(ac):
+            if arg_flag & (1 << i):
+                esites, pos = _expr_constants(raw, pos, ctx)
+                sites += esites
+            else:
+                sz = _disasm.argsize(op, i)
+                if sz:
+                    sites.append(Site(pos, sz, _le(raw, pos, sz), f"{ctx} {_disasm.op_name(op)} arg{i}", _full_max(sz)))
+                pos += sz
+    return sites
+
+
+def constant_sites(eb_bytes: bytes) -> list:
+    """Every patchable numeric constant in a battle ``.eb``'s AI, in byte order. The ``offset`` of each is the
+    ``at`` you cite in an ``[[scene.ai_patch]]``; the disassembler (``battle-ai --sites``) prints them."""
+    try:                                                 # a truncated/corrupt eb (e.g. a bad funcCount) can index
+        eb = EbScript.from_bytes(eb_bytes)               # past the buffer during parse -> raise a CLEAN error, not
+    except (ValueError, IndexError) as ex:               # a raw IndexError (mirrors battleai.disassemble_ai)
+        raise AiPatchError(f"malformed/truncated AI .eb: {type(ex).__name__}: {ex}")
+    out = []
+    for e in eb.entries:
+        if e.empty:
+            continue
+        for f in e.funcs:
+            ctx = f"entry{e.index}/tag{f.tag}"
+            out += _func_constants(eb.data, f.abs_start, min(f.abs_end, len(eb.data)), ctx)
+    return out
+
+
+def apply_ai_patches(eb_bytes: bytes, patches) -> tuple[bytes, list]:
+    """Apply ``[{at, old, new}, ...]`` same-length constant patches to ``eb_bytes``. Each ``at`` must be a real
+    constant site whose current value == ``old`` (the guard) and whose width fits ``new``. Returns (patched, warns).
+    Raises AiPatchError on a bad offset / old-mismatch / width-overflow -- so a wrong patch fails the build, never
+    the game."""
+    if not isinstance(patches, list):
+        raise AiPatchError("[[scene.ai_patch]] must be a list of tables")
+    sites = {s.offset: s for s in constant_sites(eb_bytes)}
+    b = bytearray(eb_bytes)
+    warnings: list = []
+    seen: dict = {}
+    for n, p in enumerate(patches):
+        if not isinstance(p, dict):
+            raise AiPatchError(f"[[scene.ai_patch]] #{n} must be a table (got {type(p).__name__})")
+        at, old, new = p.get("at"), p.get("old"), p.get("new")
+        for k, v in (("at", at), ("old", old), ("new", new)):
+            if not isinstance(v, int) or isinstance(v, bool):
+                raise AiPatchError(f"[[scene.ai_patch]] #{n} needs integer {k} (at = offset, old/new = values)")
+        if at in seen:
+            warnings.append(f"[[scene.ai_patch]] #{n} and #{seen[at]} both patch offset {at} -- the later wins")
+        seen[at] = n
+        site = sites.get(at)
+        if site is None:
+            raise AiPatchError(f"[[scene.ai_patch]] #{n}: no patchable constant at offset {at} "
+                               f"(cite an offset from `battle-ai --sites`)")
+        if site.value != old:
+            raise AiPatchError(f"[[scene.ai_patch]] #{n}: expected old = {old} at offset {at}, but the eb has "
+                               f"{site.value} ({site.where}) -- wrong offset, or already patched?")
+        if not 0 <= new <= site.vmax:                    # site.vmax handles ANY width + the B_CONST4 26-bit mask
+            note = " (the engine masks this B_CONST4 literal to 26 bits)" if site.vmax == 0x3FFFFFF else ""
+            raise AiPatchError(f"[[scene.ai_patch]] #{n}: new = {new} does not fit the {site.width}-byte constant "
+                               f"at offset {at} (0-{site.vmax}){note} -- a same-length patch can't widen it")
+        for k in range(site.width):                      # little-endian, generic width (1/2/3/4) -> no struct map
+            b[at + k] = (new >> (8 * k)) & 0xFF
+    return bytes(b), warnings
+
+
+def validate_patches(eb_bytes: bytes, patches) -> list:
+    """Offline problems (empty => OK): re-run the patch on a copy and surface any AiPatchError as a message."""
+    try:
+        apply_ai_patches(eb_bytes, patches)
+        return []
+    except AiPatchError as ex:
+        return [str(ex)]