feat: unify hosted ABI with reusable ASL runtime

Makefile

@@ -10,5 +10,5 @@ test:
 	ctest --test-dir $(BUILD_DIR) --output-on-failure
 
 check: test
-	$(PYTHON) -m py_compile src/pto_asl_model/*.py scripts/pto-asl-run
+	PYTHONPATH=src $(PYTHON) -m compileall -q src scripts tools
 	git diff --check

README.md

@@ -6,16 +6,26 @@ consumer boundary for functional runners such as SuperScalarModel `gfrun`.
 
 PTO architectural semantics remain owned by
 [`PTO-ISA/pto-spec`](https://github.com/PTO-ISA/pto-spec). This repository owns
-model lifecycle, hosted execution, transport, ABI, ELF loading, and validation.
+hosted execution, ABI, ELF loading, and validation.
 
 Development changes land through pull requests. The initial ASLRef backend is
 tracked by the repository issue list.
 
 ## Reference runner
 
-The first closure runs consecutive PTO instructions inside one ASLRef process.
-It accepts a checked static ELF whose load segments fit the explicit hosted
-memory bound, plus an assembled PTO ASL file:
+The hosted ELF command is the one model entry used by both the command line
+tool and the C ABI. It runs consecutive instructions in one ASLRef process;
+ASL owns fetch, instruction length selection, decode, legality, faults, and
+architectural state transitions. The model owns ELF validation/loading, the
+guest-memory image, stop/result handling, and the process boundary.
+
+The Python package also exposes strict, passive architectural-state DTOs and
+canonical serialization helpers. They do not map memory, authorize accesses,
+load images, initialize stacks, reset or restore execution, or provide another
+instruction engine. The hosted runner and PTO ASL remain the sole live memory
+and execution authority.
+
+The hosted runner accepts a checked static ELF and an assembled PTO ASL file.
 
 ```bash
 scripts/pto-asl-run \
@@ -78,3 +88,7 @@ promotion gates.
 The reset contract is in [`docs/model-ndf-v1.md`](docs/model-ndf-v1.md). The
 snapshot lifecycle, identity, transport, and promotion gates are in
 [`docs/worker-snapshot-design.md`](docs/worker-snapshot-design.md).
+
+Run repository checks with `make check`. The C/C++ consumer links
+`PTOASLModel::pto_asl_model` and calls the versioned
+`pto_model_run_elf` function declared in `include/pto/pto_asl_model.h`.

docs/design.md

@@ -0,0 +1,50 @@
+# Standalone design
+
+`pto-asl-model` is an integration layer around the executable PTO ASL
+specification.  It intentionally keeps the semantic boundary small:
+
+```text
+pto_model_run_elf() → canonical runner → ASLRef → ExecuteNextPTOInstruction()
+                              ↓
+                         result, manifest
+```
+
+The package does not import simulator, emulator, benchmark, or compiler
+modules.  The specification checkout and its generated artifact are explicit
+runtime inputs. This makes the model usable from a clean checkout without
+creating a second PTO execution API.
+
+ELF parsing, sidecar validation, artifact identity, and hosted execution stay
+behind the single `pto_model_run_elf()` entry. The Python package contains only
+passive, strict architectural-state serialization and path helpers alongside
+that runner. It has no second image, memory, stack, lifecycle, or snapshot
+authority.
+
+The package owns no duplicate instruction handlers or live memory policy. A
+future native backend must implement the same observable state contract and be
+admitted by differential tests before it is used for bulk workloads.
+
+## Specification lifecycle
+
+The normal lifecycle is:
+
+1. Edit the modular ASL sources in the specification checkout.
+2. Regenerate and type-check `build/pto-spec.asl` there.
+3. Invoke `pto_model_run_elf()` or `scripts/pto-asl-run` with the exact lock,
+   generated ASL artifact, ELF, and sidecar inputs.
+
+Generated ASL artifacts, ASLRef build outputs, and ELF outputs are not package
+source files.
+
+## Repository split
+
+This repository owns only the model boundary and its tests.  The following
+remain external inputs or downstream consumers:
+
+| Concern | Owner |
+| --- | --- |
+| ISA semantics, encodings, catalogs | PTO ASL specification |
+| ASL interpretation | ASLRef toolchain |
+| ELF production | compiler/assembler toolchain |
+| high-throughput execution | future native backend |
+| timing/performance | timing model |

docs/migration.md

@@ -0,0 +1,43 @@
+# Standalone checkout guide
+
+This directory is the complete Python-side ASL model boundary.  It can be
+installed and tested without importing any other local project.
+
+## Inputs
+
+The model deliberately does not vendor the specification or ASLRef build.
+Point it at a PTO specification checkout whose generated artifact is ready:
+
+```bash
+export PTO_SPEC_ROOT=/path/to/pto-spec
+```
+
+The specification checkout must contain `build/pto-spec.asl`, the generated
+decoder/source-order files, `scripts/aslref`, and `.aslref-version`.
+
+## Install and validate
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+make test
+make check PTO_SPEC=/path/to/pto-spec
+```
+
+`make test` includes deterministic Python and C/C++ ABI tests. `make check`
+adds bytecode compilation and whitespace validation.
+
+## Python data contract
+
+The installable Python package contains strict, passive architectural-state
+serialization and path helpers. These DTOs can describe observed memory data,
+but they do not map storage, enforce access permissions, initialize a stack,
+load an image, or reset/restore a live model. Generated ASL and ASLRef remain
+explicit inputs to the canonical `pto_model_run_elf()` runner.
+
+## Extension points
+
+Keep ISA semantics in ASL. The hosted `pto_model_run_elf()` path alone handles
+ELF identity, sidecars, live memory, and execution. Reusable Python code is
+limited to passive state serialization and repository-path discovery.

docs/step-contract.md

@@ -0,0 +1,24 @@
+# Canonical next-instruction contract
+
+PTO has one hosted model entry and one ASL next-instruction entry:
+
+```text
+pto_model_run_elf()
+  -> pto_asl_model.runner.run()
+  -> ExecuteNextPTOInstruction()
+```
+
+The hosted runner owns ELF validation, sidecar and lock identity, memory-image
+initialization, stop/result policy, manifests, and the ASLRef process. PTO-SPEC
+ASL owns fetch, instruction-width selection, decode, legality, faults, PC/TPC,
+and architectural state transitions.
+
+There is no supported compatibility decoder, explicit-width step command,
+arbitrary instruction-handler call, or alternate runtime commit path. Runtime
+image, memory, stack, reset, restore, and snapshot-lifecycle classes are not
+part of the package. Architectural-state DTOs are passive serialization data;
+they cannot initialize or mutate the live runner.
+
+Any future accelerated backend must preserve this boundary and prove parity
+before admission. It may not introduce a private PTO decoder, opcode table,
+termination recognizer, or semantic fallback.

pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pto-asl-model"
+version = "0.1.0"
+description = "ASL-backed functional model runtime for PTO instruction validation"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [{name = "PTO-ISA contributors"}]
+dependencies = []
+
+[project.optional-dependencies]
+test = []
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pto_asl_model = ["architecture_state.schema.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

src/pto_asl_model/__init__.py

@@ -1,11 +1,42 @@
-"""PTO ASLRef-backed functional-model tooling."""
+"""ASL-backed functional model for PTO instruction validation."""
 
 from .runner import ElfError, ElfImage, LoadSegment, RunConfiguration, run
 
+from .state import (
+    ArchitectureState,
+    BlockState,
+    FaultState,
+    MemoryRegion,
+    MemoryState,
+    ScalarState,
+    SharedState,
+    SharedTile,
+    StateEnvelope,
+    TileDescriptor,
+    TileState,
+    TileValue,
+    canonical_hash,
+    canonical_json,
+    state_diff,
+)
+from .paths import repository_root, resolve_pto_spec
+
 __all__ = [
-    "ElfError",
-    "ElfImage",
-    "LoadSegment",
-    "RunConfiguration",
-    "run",
+    "ElfError", "ElfImage", "LoadSegment", "RunConfiguration", "run",
+    "ArchitectureState",
+    "BlockState",
+    "FaultState",
+    "MemoryRegion",
+    "MemoryState",
+    "ScalarState",
+    "SharedState",
+    "SharedTile",
+    "StateEnvelope",
+    "TileDescriptor",
+    "TileState",
+    "TileValue",
+    "canonical_hash",
+    "canonical_json",
+    "state_diff",
+    "repository_root", "resolve_pto_spec",
 ]