m68000-python 0.1.0__py3-none-any.whl

m68000_python/trace.py

@@ -0,0 +1,296 @@
+"""Deterministic boundary traces: write, read, and compare them incrementally.
+
+A trace is a JSON Lines file of :class:`~m68000_python.debug.StepRecord`
+values, one processor boundary per line (docs/trace-schema.md).  Two cores
+that produce equal traces for the same program and host behave identically
+as far as software can tell; ``first_trace_divergence`` finds where they do
+not without reading either trace to the end.
+"""
+
+import json
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, fields
+from itertools import zip_longest
+from typing import TextIO
+
+from m68000_python.debug import BoundaryKind, DebugSession, StepRecord
+from m68000_python.disasm import Instruction, disassemble_bytes
+from m68000_python.state import CPUState
+
+TRACE_SCHEMA_VERSION = 1
+TraceValue = int | bool | str | tuple | None
+_STATE_KEYS = tuple(field.name for field in fields(CPUState))
+_RECORD_KEYS = {"version", "sequence", "kind", "cycles", "instruction", "before", "after"}
+_MISSING = object()
+
+
+@dataclass(frozen=True, slots=True)
+class TraceDifference:
+    """One unequal observation at an aligned trace position."""
+
+    path: str
+    left: TraceValue
+    right: TraceValue
+
+    def __post_init__(self) -> None:
+        if type(self.path) is not str or not self.path:
+            raise ValueError("path must be a non-empty string")
+        if self.left == self.right:
+            raise ValueError("a TraceDifference records unequal values")
+
+    def as_dict(self) -> dict[str, TraceValue]:
+        return {"path": self.path, "left": self.left, "right": self.right}
+
+
+@dataclass(frozen=True, slots=True)
+class TraceDivergence:
+    """All differences at one aligned position."""
+
+    position: int
+    left: StepRecord | None
+    right: StepRecord | None
+    differences: tuple[TraceDifference, ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "position": self.position,
+            "left_sequence": None if self.left is None else self.left.sequence,
+            "right_sequence": None if self.right is None else self.right.sequence,
+            "differences": [difference.as_dict() for difference in self.differences],
+        }
+
+
+# -- records <-> JSON ---------------------------------------------------------
+
+
+def step_record_to_dict(record: StepRecord) -> dict[str, object]:
+    """The JSON-compatible form of one record (docs/trace-schema.md)."""
+    instruction = None
+    if record.instruction is not None:
+        instruction = {
+            "address": record.instruction.address,
+            "data": record.instruction.data.hex(),
+            "mnemonic": record.instruction.mnemonic,
+            "operands": list(record.instruction.operands),
+        }
+    out: dict[str, object] = {
+        "version": TRACE_SCHEMA_VERSION,
+        "sequence": record.sequence,
+        "kind": record.kind.value,
+        "cycles": record.cycles,
+        "instruction": instruction,
+        "before": _state_to_dict(record.before),
+        "after": _state_to_dict(record.after),
+    }
+    if record.accesses is not None:
+        out["accesses"] = [list(access) for access in record.accesses]
+    return out
+
+
+def step_record_from_dict(data: dict) -> StepRecord:
+    """Validate one decoded JSON record and rebuild it."""
+    if type(data) is not dict:
+        raise ValueError("a trace record must be a JSON object")
+    keys = set(data)
+    if not _RECORD_KEYS <= keys or keys - _RECORD_KEYS - {"accesses"}:
+        raise ValueError(f"trace record keys must be {sorted(_RECORD_KEYS)} (+ accesses)")
+    if data["version"] != TRACE_SCHEMA_VERSION:
+        raise ValueError(f"unsupported trace version {data['version']!r}")
+    for key in ("sequence", "cycles"):
+        if type(data[key]) is not int:
+            raise ValueError(f"{key} must be an integer")
+    if type(data["kind"]) is not str:
+        raise ValueError("kind must be a string")
+    instruction = None
+    if data["instruction"] is not None:
+        instruction = _instruction_from_dict(data["instruction"])
+    accesses = None
+    if "accesses" in data:
+        if type(data["accesses"]) is not list:
+            raise ValueError("accesses must be a list")
+        accesses = tuple(
+            tuple(access) if type(access) is list else access for access in data["accesses"]
+        )
+    return StepRecord(
+        sequence=data["sequence"],
+        kind=BoundaryKind(data["kind"]),
+        before=_state_from_dict(data["before"]),
+        after=_state_from_dict(data["after"]),
+        cycles=data["cycles"],
+        instruction=instruction,
+        accesses=accesses,
+    )
+
+
+def _instruction_from_dict(spec: object) -> Instruction:
+    """Rebuild an instruction from its bytes; text, when present, must be complete and agree.
+
+    A producer in another language writes only ``address`` and ``data``; this
+    package's disassembler supplies the text, so two traces of the same bytes
+    compare equal whoever wrote them.
+    """
+    if type(spec) is not dict:
+        raise ValueError("instruction must be an object or null")
+    keys = set(spec)
+    if not {"address", "data"} <= keys or keys - {"address", "data", "mnemonic", "operands"}:
+        raise ValueError("instruction fields are address, data and optionally mnemonic + operands")
+    if ("mnemonic" in keys) != ("operands" in keys):
+        raise ValueError("instruction fields mnemonic and operands come together")
+    if type(spec["address"]) is not int or type(spec["data"]) is not str:
+        raise ValueError("instruction address must be an integer and data a hex string")
+    try:
+        data = bytes.fromhex(spec["data"])
+    except ValueError:
+        raise ValueError("instruction data must be hexadecimal") from None
+    try:
+        instruction = disassemble_bytes(data, spec["address"])
+    except ValueError as exc:
+        raise ValueError(f"instruction data must hold exactly one instruction: {exc}") from None
+    if "mnemonic" in keys and (
+        spec["mnemonic"] != instruction.mnemonic or tuple(spec["operands"]) != instruction.operands
+    ):
+        raise ValueError("instruction text does not match its bytes")
+    return instruction
+
+
+def write_trace(records: Iterable[StepRecord], stream: TextIO) -> int:
+    """Write records as JSON Lines with sorted keys; return how many."""
+    count = 0
+    for record in records:
+        stream.write(json.dumps(step_record_to_dict(record), sort_keys=True, separators=(",", ":")))
+        stream.write("\n")
+        count += 1
+    return count
+
+
+def read_trace(stream: TextIO) -> Iterator[StepRecord]:
+    """Read JSON Lines records lazily; blank lines are ignored."""
+    for number, line in enumerate(stream, 1):
+        if not line.strip():
+            continue
+        try:
+            yield step_record_from_dict(json.loads(line))
+        except (ValueError, KeyError, TypeError) as exc:
+            raise ValueError(f"trace line {number}: {exc}") from exc
+
+
+def iter_session_steps(session: DebugSession, *, max_steps: int) -> Iterator[StepRecord]:
+    """Yield ``max_steps`` live boundaries from a session without buffering them."""
+    if type(max_steps) is not int or max_steps <= 0:
+        raise ValueError("max_steps must be a positive integer")
+    for _ in range(max_steps):
+        yield session.step()
+
+
+# -- comparison ---------------------------------------------------------------
+
+
+def compare_step_records(left: StepRecord, right: StepRecord) -> tuple[TraceDifference, ...]:
+    """Every differing field of two aligned records (sequence numbers are ignored).
+
+    Bus accesses are compared only when both records carry them.
+    """
+    _require_record(left, "compared records")
+    _require_record(right, "compared records")
+    out: list[TraceDifference] = []
+    _append(out, "kind", left.kind.value, right.kind.value)
+    _append(out, "cycles", left.cycles, right.cycles)
+    li, ri = left.instruction, right.instruction
+    if (li is None) != (ri is None):
+        _append(
+            out, "instruction", None if li is None else li.text, None if ri is None else ri.text
+        )
+    elif li is not None and ri is not None:
+        _append(out, "instruction.address", li.address, ri.address)
+        _append(out, "instruction.data", li.data.hex(), ri.data.hex())
+    for side in ("before", "after"):
+        a, b = getattr(left, side), getattr(right, side)
+        for key in _STATE_KEYS:
+            _append(out, f"{side}.{key}", getattr(a, key), getattr(b, key))
+    if left.accesses is not None and right.accesses is not None:
+        _append(out, "accesses", tuple(left.accesses), tuple(right.accesses))
+    return tuple(out)
+
+
+def iter_trace_divergences(
+    left: Iterable[StepRecord], right: Iterable[StepRecord]
+) -> Iterator[TraceDivergence]:
+    """Yield every unequal aligned position, lazily, until both traces end."""
+    for position, (a, b) in enumerate(zip_longest(left, right, fillvalue=_MISSING)):
+        if a is _MISSING:
+            _require_record(b, "traces")
+            yield TraceDivergence(position, None, b, (TraceDifference("record", None, "present"),))
+        elif b is _MISSING:
+            _require_record(a, "traces")
+            yield TraceDivergence(position, a, None, (TraceDifference("record", "present", None),))
+        else:
+            _require_record(a, "traces")
+            _require_record(b, "traces")
+            differences = compare_step_records(a, b)
+            if differences:
+                yield TraceDivergence(position, a, b, differences)
+
+
+def first_trace_divergence(
+    left: Iterable[StepRecord], right: Iterable[StepRecord]
+) -> TraceDivergence | None:
+    """The first unequal aligned position, or ``None`` when the traces are equal."""
+    return next(iter_trace_divergences(left, right), None)
+
+
+def first_session_divergence(
+    left: DebugSession, right: DebugSession, *, max_steps: int
+) -> TraceDivergence | None:
+    """Advance two live sessions in lockstep and stop at the first differing boundary.
+
+    Each session keeps its own bounded history, which is the context before
+    the divergence; nothing else is buffered.  ``max_steps`` is mandatory.
+    """
+    return first_trace_divergence(
+        iter_session_steps(left, max_steps=max_steps),
+        iter_session_steps(right, max_steps=max_steps),
+    )
+
+
+def _append(out: list, path: str, left: TraceValue, right: TraceValue) -> None:
+    if left != right:
+        out.append(TraceDifference(path, left, right))
+
+
+def _require_record(record: object, what: str) -> None:
+    if type(record) is not StepRecord:
+        raise TypeError(f"{what} must be StepRecord values")
+
+
+def _state_to_dict(state: CPUState) -> dict[str, object]:
+    out: dict[str, object] = {}
+    for key in _STATE_KEYS:
+        value = getattr(state, key)
+        out[key] = list(value) if isinstance(value, tuple) else value
+    return out
+
+
+def _state_from_dict(data: dict) -> CPUState:
+    if type(data) is not dict or set(data) != set(_STATE_KEYS):
+        raise ValueError(f"a state object must have exactly the keys {sorted(_STATE_KEYS)}")
+    values = {
+        key: tuple(value) if isinstance(value, list) else value for key, value in data.items()
+    }
+    return CPUState(**values)
+
+
+__all__ = [
+    "TRACE_SCHEMA_VERSION",
+    "TraceDifference",
+    "TraceDivergence",
+    "TraceValue",
+    "compare_step_records",
+    "first_session_divergence",
+    "first_trace_divergence",
+    "iter_session_steps",
+    "iter_trace_divergences",
+    "read_trace",
+    "step_record_from_dict",
+    "step_record_to_dict",
+    "write_trace",
+]

m68000_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,379 @@
+Metadata-Version: 2.5
+Name: m68000-python
+Version: 0.1.0
+Summary: Readable, pure-Python Motorola MC68000 instruction-core reference implementation
+Project-URL: Homepage, https://github.com/alewman/m68000-python
+Project-URL: Repository, https://github.com/alewman/m68000-python
+Project-URL: Issues, https://github.com/alewman/m68000-python/issues
+Project-URL: Changelog, https://github.com/alewman/m68000-python/blob/main/CHANGELOG.md
+Author: alewman
+License: MIT License
+        
+        Copyright (c) 2026 alewman
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.16.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# m68000-python
+
+[![CI](https://github.com/alewman/m68000-python/actions/workflows/ci.yml/badge.svg)](https://github.com/alewman/m68000-python/actions/workflows/ci.yml)
+[![Oracles](https://github.com/alewman/m68000-python/actions/workflows/oracles.yml/badge.svg)](https://github.com/alewman/m68000-python/actions/workflows/oracles.yml)
+
+A readable, pure-Python Motorola MC68000 **instruction-core reference
+implementation**.
+
+`m68000-python` is a processor core built to be read, learned from, embedded
+in real machines, and inspected by humans and AI tools. It implements the
+68000 instruction set, the prefetch queue, and the exception model at
+instruction boundaries, leaving memory maps, devices and machine scheduling
+to the host, in the same shape as [z80-python](https://github.com/alewman/z80-python),
+the family's reference core. Where z80-python could be checked exhaustively
+against hardware-captured values, no such oracle exists for the 68000, so
+this core carries a **claim boundary** instead: every behaviour is labelled
+by how many independent lines of evidence support it and how close to
+silicon the best of them is ([docs/claims.md](docs/claims.md)).
+
+The project is deliberately:
+
+- **readable** — every instruction is an ordinary Python method; a table
+  only routes each of the 65,536 first words to its method, which cites the
+  manual page its rule comes from and the corpus file that pins what the
+  manual leaves open;
+- **pure Python** — no runtime dependencies; CPython and PyPy;
+- **independently validated** — correctness claims come from external
+  oracles ranked by tier, and from referees built and run from pinned
+  sources, never from code-generation confidence;
+- **embeddable** — a host passes in its bus as callables and controls when
+  the processor advances; and
+- **inspectable** — processor state, disassembly in MAME's spelling, bounded
+  debugging with breakpoints, watchpoints and bus-access tracking,
+  structured traces, and `python -m m68000_python` for stepping a binary.
+
+## Validation
+
+Each oracle is named with its tier: where its expected values came from. A
+lower tier detects; the highest tier that checks a claim decides it
+([oracle tiers](docs/validation.md#the-tier-rule)). The core passes:
+
+- **hardware-captured:** every input of flamewing's 68k BCD verifier tables,
+  **525,312 cases** of `ABCD`, `SBCD` and `NBCD` recorded on two Sega Genesis
+  models, result and all five flags (`tests/test_bcd.py`);
+- **hardware-corrected, run:** WinUAE's CPU-tester core, whose 68000 its
+  author corrects against real Amigas with `cputest`, built here from a
+  pinned commit and run over the whole gate: **308,416 of 314,988** judged
+  cases agree, and every residual is an address-error or 2-clock difference
+  listed by name ([docs/referees.md](docs/referees.md));
+- **emulator-derived, the gate:** all **127 files, 317,500 cases** of the
+  pinned SingleStepTests/m68000 corpus, generated from MAME's
+  microcode-transcribed core, compared on registers, SR, both stack
+  pointers, the prefetch queue, RAM, the clock total and every bus access in
+  order with its function code, **no case excluded**; and the clock at which
+  each access ends within its step, over the 261,894 cases without an
+  address error (`tests/test_step_clocks.py`);
+- **emulator-derived, real code:** MAME 0.285 in lockstep, every register
+  before every instruction of **24,595,631 instructions** of System 16B
+  Altered Beast (every write and every instruction's clocks checked) and
+  **28,249,660** of Genesis Altered Beast;
+- **emulator-derived, detector:** SingleStepTests/680x0, **787,660 of
+  1,000,060** cases agree and every disagreement has a named cause, most
+  decided in the core's favour by the WinUAE run; and Musashi, an
+  independent hand-written core, run over the gate: 257,300 of 261,894
+  judged cases, every difference decided by a higher tier;
+- **documentation:** the interrupt and STOP scenarios, consistent with the
+  manual and with MAME's 5,579 lockstep interrupts; and every handler's
+  rule, cited to a page of Motorola's manuals in its docstring, with the
+  SingleStepTests file named wherever the manual is silent.
+
+Where the sources disagree the core follows the gate and the claim is
+**contested**: six address-error behaviours, three 2-clock questions and
+the double bus fault. Each is listed with what
+would settle it ([docs/claims.md](docs/claims.md)). The order of bus cycles
+and the exact clock totals rest on MAME's lineage alone, and the pages say so.
+
+What the evidence reaches is mapped: the suite executes all 45,815 defined
+first words ([docs/coverage.md](docs/coverage.md)), and of 176 seeded
+mutants it kills 174, the two survivors provably equivalent
+([docs/mutation.md](docs/mutation.md)). Exact revisions, hashes, commands
+and timings are in [the validation record](docs/validation.md).
+
+This is an instruction-level semantic and lifecycle claim. It is **not** a
+claim of cycle-accurate bus-pin behaviour, of wait states, or of a complete
+computer.
+
+### CI coverage
+
+The two badges cover different things, and neither covers everything:
+
+| Badge | Runs | When |
+| --- | --- | --- |
+| **CI** | the fast suite (decoder, readability, BCD tables, manual-derived and referee-pinned tests, the tooling), Ruff check and format, both examples, on CPython 3.11-3.14 and PyPy 3.11; the SingleStepTests gate and the `step_clocks` claim on CPython 3.14 and PyPy 3.11; a wheel build and installed-API smoke test | every push and pull request |
+| **Oracles** | the decoder against MAME's `m68000.lst`, the 680x0 detector, the WinUAE and Musashi referees built and calibrated, the coverage map and the mutation score, each failing if its number moves from the one the documents record | weekly, and on demand |
+
+**The MAME lockstep is certified locally, not in CI.** It needs MAME 0.285
+and the ROMs; its command lines, counts and timings are in
+[the validation record](docs/validation.md).
+
+## Vibe coded, oracle validated
+
+This core was written by an AI agent in one night from a brief, then taken
+through three verification rounds: coverage and mutation testing, referees
+built and run, and a claim boundary. That history is stated plainly because
+the correctness claim does not rest on it. Generated emulator code can be
+plausible and wrong, above all around the prefetch queue, address-error
+frames and undefined flags; the feedback loop was made stronger than the
+model's confidence, and four core bugs the gate could not see were found by
+the coverage work and the referees and fixed as failing tests first. See
+[AI-assisted development](docs/ai-assisted-development.md).
+
+## Version status
+
+The current release is **`0.1.0`** (see its [release note](docs/releases/0.1.0.md)
+and the [changelog](CHANGELOG.md)).
+
+### Install from PyPI
+
+```text
+python -m pip install m68000-python
+```
+
+### Install the source tree
+
+```text
+git clone https://github.com/alewman/m68000-python.git
+cd m68000-python
+python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]"
+```
+
+Recent Debian, Ubuntu, Fedora and Homebrew Pythons refuse `pip install` into
+the system interpreter (PEP 668); the virtual environment line above is the
+supported way around that. The distribution is named `m68000-python`; its
+import is `m68000_python`.
+
+## Minimal host
+
+The host owns memory and devices and passes the CPU its bus as four
+callables over a 24-bit address space. A bytearray serves the byte accesses
+as it is; two small functions assemble and split the words, big-endian as
+the chip does. `reset()` fetches SSP and PC from addresses 0 and 4.
+
+```python
+from m68000_python import M68000CPU
+
+memory = bytearray(1 << 16)
+
+
+def read_word(address):
+    return (memory[address] << 8) | memory[address + 1]
+
+
+def write_word(address, value):
+    memory[address] = value >> 8
+    memory[address + 1] = value & 0xFF
+
+
+memory[0:8] = (0x8000).to_bytes(4, "big") + (0x1000).to_bytes(4, "big")  # SSP, PC
+memory[0x1000:0x1004] = bytes((0x70, 0x05, 0x52, 0x80))  # moveq #5,D0; addq.l #1,D0
+cpu = M68000CPU(memory.__getitem__, read_word, memory.__setitem__, write_word)
+cpu.reset()
+assert cpu.step() == 4
+assert cpu.step() == 8
+assert cpu.R[0] == 6
+```
+
+`examples/minimal_m68000_host.py` is this program, run in CI;
+`examples/interrupt_host.py` adds a device that raises level 4. This is the
+embedding contract of the whole family: z80-python and m6800-python take
+their buses the same way.
+
+`step()` runs one instruction or one exception entry and returns its clock
+total. Registers (`R[0:8]` D0-D7, `R[8:16]` A0-A7, `SR`) are directly
+readable and writable; `PC` reads the address of the next instruction and
+`set_pc()` starts execution somewhere else. Optional constructor keywords,
+each free unless used: `acknowledge(level)` answers the interrupt-acknowledge
+cycle with a vector number, `AUTOVECTOR` or `SPURIOUS`; `function_codes=True`
+passes `fc=` on every access; `tas_write(address, value)` receives TAS's
+write half, which the Genesis bus drops; `address_error(address, write, fc)`
+is told about the access an address error aborted; `reset_devices()` sees
+the RESET instruction's pulse. A host raises `BusError` from a callable to
+assert BERR. Inside a callable, `cpu.step_clocks` says at which clock of the
+step the access ends, which a board needs to stall the CPU at the right
+point; the core models no wait states, so the host adds its own stall
+clocks to the total. [The interrupt lifecycle](docs/interrupt-lifecycle.md)
+has the whole host protocol.
+
+Speed, on the `base` workload of `benchmarks/m68000_core_benchmark.py`
+(2026-09-25, a shared machine at load 12): about 1.4 million instructions
+per second on CPython 3.14.4 and about 33 million on PyPy 7.3.20; a Mega
+Drive's 68000 executes about 1 million a second. The four workloads and the
+polish round's speed ladder are in [the validation record](docs/validation.md#speed).
+
+## Reference-core boundary
+
+`m68000-python` owns:
+
+- the 68000 instruction semantics, the two-word prefetch queue and the bus
+  sequence of every instruction, and the clock total of every step;
+- the registers, SR, both stack pointers, and the internal state that
+  decides what the next step does;
+- the exception model: group 0 (address error, and bus error when the host
+  asserts it), group 1 (trace, interrupts, illegal, privilege) and group 2
+  (TRAP, TRAPV, CHK, divide by zero), with their frames; and
+- processor-level observation and debugging values.
+
+A host machine owns:
+
+- ROM, RAM, memory maps, mappers, devices and open-bus values;
+- video, audio, input, DMA and a second processor's share of the bus;
+- frame, scanline, clock and interrupt scheduling, and wait states;
+- device resets and the RESET and HALT pins beyond the RESET instruction;
+- side-effect-free memory peeking; and
+- complete machine save states, deterministic replay and rewind.
+
+Accordingly, the project does not claim:
+
+- the contents of a bus-error frame (the vector is taken; the frame's
+  stacked PC, IR and I/N bit are not checked by any oracle here);
+- cycle placement inside an instruction beyond `step_clocks`, TAS's
+  read-modify-write shape, wait states, or pin timing;
+- the 68010 and later (VBR, loop mode, the 68010 frame, `MOVEC`, `MOVES`,
+  the 68020's bus and addressing), or the 68008's timing; or
+- a complete arcade board, console or computer.
+
+These are scope boundaries, not unfinished promises; the claim boundary in
+[docs/claims.md](docs/claims.md) is exact about each.
+
+## Learning and inspection
+
+New to the 68000? Read [Start here](docs/start-here.md) first: the register
+file, the status register, how an opcode word splits into fields, the twelve
+effective-address modes, the exception model and the prefetch queue, each
+section naming the module that implements it.
+
+The implementation is organised by instruction family behind a small public
+`M68000CPU` facade. Every opcode handler's docstring starts with its
+Motorola name, so `grep MOVEM src/` lands on the implementation, and ends
+with where its rule comes from: a page of the *M68000 Programmer's Reference
+Manual* or a table of the *User's Manual*, plus the SingleStepTests file,
+the WinUAE run or the hardware tables that pin any rule the manuals do not
+give (the PC an address error stacks, the order of bus cycles, an undefined
+flag). A test (`tests/test_readability.py`) enforces the name, the citation
+and the evidence line the same way the corpus gate enforces correctness.
+
+The tree also provides immutable `CPUState` capture and restoration for
+processor-owned state and a disassembler for every first word, in MAME's
+spelling, checked against MAME's own disassembly of 1,300 instructions of
+real game code. Disassembly requires an explicit side-effect-free word
+reader: debugging must not accidentally acknowledge a device.
+
+See [CPU state](docs/cpu-state.md), [disassembly](docs/disassembly.md),
+[undocumented behaviour](docs/undocumented-behavior.md) and
+[timing](docs/timing.md).
+
+## Diagnostics and tooling
+
+- `DebugSession` wraps an existing host with bounded execution, execute
+  breakpoints, watchpoints and bus-access tracking, boundary-kind records
+  and bounded history. It adds nothing to the hot path when unused.
+- `CommandDebugger` is a dependency-free text-stream frontend; `python -m
+  m68000_python --load FILE@ADDR --pc ADDR` or `--zip ROMS.zip:even,odd@0
+  --reset` steps a binary without writing a host.
+- Traces are versioned JSON Lines; `first_trace_divergence` and
+  `first_session_divergence` stop at the first differing boundary of two
+  files or two live machines, with every field named.
+- `python -m m68000_python.conformance trace|diff` runs a manifest (memory,
+  initial state, interrupt events, BERR ranges, replayed devices) on the
+  reference and diffs another core's trace against it, bus accesses
+  included: the kit and the certification ladder for a 68000 core in
+  another language.
+
+See [debug sessions](docs/debug-session.md), [trace comparison](docs/trace-comparison.md),
+[the trace schema](docs/trace-schema.md) and [conformance](docs/conformance.md).
+
+## Development
+
+Run the ordinary quality gate:
+
+```text
+python -m pytest -q
+python -m ruff check .
+python -m ruff format --check .
+python examples/minimal_m68000_host.py
+```
+
+The corpora are external artifacts and are not bundled. Fetch the pinned
+gate corpus (138 MB) with:
+
+```text
+python scripts/fetch_test_vectors.py
+python -m pytest -q tests/test_corpus.py tests/test_step_clocks.py
+```
+
+`--with-680x0` adds the second corpus (203 MB, unlicensed, detector only);
+`--files NOP,ABCD` fetches a few files for a quick start. The referees,
+the detector, the coverage map and the mutation run each have their command
+in the document that records their result.
+
+## Project records
+
+- [The claim boundary](docs/claims.md): every behaviour with its status
+- [0.1.0 release notes](docs/releases/0.1.0.md)
+- [Validation evidence and scope](docs/validation.md)
+- [Referees: WinUAE and Musashi, built and run](docs/referees.md)
+- [Coverage: what the evidence reaches](docs/coverage.md)
+- [Mutation: what the suite would notice](docs/mutation.md)
+- [Public API stability](docs/api-stability.md)
+- [Interrupt lifecycle](docs/interrupt-lifecycle.md)
+- [CPU state](docs/cpu-state.md)
+- [Disassembly](docs/disassembly.md)
+- [Debug sessions](docs/debug-session.md)
+- [Trace comparison](docs/trace-comparison.md)
+- [Trace schema](docs/trace-schema.md)
+- [Conformance: proving another core is the same CPU](docs/conformance.md)
+- [Start here: 68000 primer](docs/start-here.md)
+- [Timing](docs/timing.md)
+- [Undocumented behaviour](docs/undocumented-behavior.md)
+- [MAME as a trace oracle](docs/mame-oracle.md)
+- [AI-assisted development](docs/ai-assisted-development.md)
+- [Contribution guidance](CONTRIBUTING.md)
+- [History: the handoff brief and the worklog](docs/README.md)
+
+## License
+
+MIT. The Motorola manuals, MAME, WinUAE, Musashi, the SingleStepTests
+corpora and the BCD verifier retain their own licenses and are cited, not
+bundled.