parsanol 0.1.0__tar.gz

parsanol-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: parsanol
+Version: 0.1.0
+Summary: Python runtime for parsanol PARG artifacts: checksum-verified artifact load and wasm-grade parsing through the parsanol C ABI
+License: MIT
+Project-URL: Homepage, https://www.parsanol.org
+Project-URL: Repository, https://github.com/parsanol/parsanol-python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# parsanol (Python)
+
+Python runtime for **PARG artifacts** — checksummed `parsanol-tree/v2`
+envelopes that Ruby, Rust, WebAssembly, TypeScript, and now Python all
+parse identically.
+
+The engine is the real one: this package drives `libparsanol` (the
+pure-portable C ABI cdylib, the same binary the Ruby ffi tier ships) via
+`ctypes`. No second parser, no reimplementation.
+
+```python
+from parsanol import PargArtifact
+
+artifact = PargArtifact.from_path("demo.artifact.json")  # verifies sha256
+tree = artifact.parse("iso 12345", "identifier")         # shaped tree
+run = artifact.run_tests()                               # embedded tests replayed
+```
+
+On rejection, `parse` raises `ParseFailed` carrying the engine's failure
+wire (`offset`, ranked positions, expected set).
+
+## Status and honest boundaries (v0.1)
+
+| Capability | State |
+|---|---|
+| Artifact load + sha256 verification | **works** — the canonical-form port is byte-exact against the reference compiler (all 32 corpus checksums verify) |
+| Native parse (shaped tree, slice wire) | **works** |
+| Failure wire | **works** |
+| Embedded tests: accept / reject / capture | **works** — all 125 corpus cases replay with zero failures |
+| Embedded tests: example / shape | skipped (17 cases) — needs the bindings + flattening port ([ticket 0003](docs/tickets/0003-bindings-and-flattening.md)) |
+| `parse_recovering` | not yet — needs a C-ABI export ([ticket 0002](docs/tickets/0002-recovery-export.md)) |
+| Dynamic / runtime-state artifacts | rejected upstream by contract (Ruby-tier) |
+| Wheels on PyPI | not yet ([ticket 0001](docs/tickets/0001-packaging.md)) |
+
+## Development
+
+```sh
+cargo build -p parsanol-ffi --release          # in parsanol-rs
+export PARSANOL_CDYLIB=$RS/target/release/libparsanol.dylib
+ln -s ../parsanol-rs/corpus corpus             # for the corpus gate
+python3 -m pip install -e . pytest
+python3 -m pytest tests -q
+```
+
+The corpus gate (`tests/test_corpus.py`) pins the sizes: 125 cases, 17
+skips — when either moves, this repo moves with it deliberately.

parsanol-0.1.0/README.md

@@ -0,0 +1,46 @@
+# parsanol (Python)
+
+Python runtime for **PARG artifacts** — checksummed `parsanol-tree/v2`
+envelopes that Ruby, Rust, WebAssembly, TypeScript, and now Python all
+parse identically.
+
+The engine is the real one: this package drives `libparsanol` (the
+pure-portable C ABI cdylib, the same binary the Ruby ffi tier ships) via
+`ctypes`. No second parser, no reimplementation.
+
+```python
+from parsanol import PargArtifact
+
+artifact = PargArtifact.from_path("demo.artifact.json")  # verifies sha256
+tree = artifact.parse("iso 12345", "identifier")         # shaped tree
+run = artifact.run_tests()                               # embedded tests replayed
+```
+
+On rejection, `parse` raises `ParseFailed` carrying the engine's failure
+wire (`offset`, ranked positions, expected set).
+
+## Status and honest boundaries (v0.1)
+
+| Capability | State |
+|---|---|
+| Artifact load + sha256 verification | **works** — the canonical-form port is byte-exact against the reference compiler (all 32 corpus checksums verify) |
+| Native parse (shaped tree, slice wire) | **works** |
+| Failure wire | **works** |
+| Embedded tests: accept / reject / capture | **works** — all 125 corpus cases replay with zero failures |
+| Embedded tests: example / shape | skipped (17 cases) — needs the bindings + flattening port ([ticket 0003](docs/tickets/0003-bindings-and-flattening.md)) |
+| `parse_recovering` | not yet — needs a C-ABI export ([ticket 0002](docs/tickets/0002-recovery-export.md)) |
+| Dynamic / runtime-state artifacts | rejected upstream by contract (Ruby-tier) |
+| Wheels on PyPI | not yet ([ticket 0001](docs/tickets/0001-packaging.md)) |
+
+## Development
+
+```sh
+cargo build -p parsanol-ffi --release          # in parsanol-rs
+export PARSANOL_CDYLIB=$RS/target/release/libparsanol.dylib
+ln -s ../parsanol-rs/corpus corpus             # for the corpus gate
+python3 -m pip install -e . pytest
+python3 -m pytest tests -q
+```
+
+The corpus gate (`tests/test_corpus.py`) pins the sizes: 125 cases, 17
+skips — when either moves, this repo moves with it deliberately.

parsanol-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "parsanol"
+version = "0.1.0"
+description = "Python runtime for parsanol PARG artifacts: checksum-verified artifact load and wasm-grade parsing through the parsanol C ABI"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+# NOTE: the Python floor and the PyPI name are OWNER decisions (see
+# docs/tickets/0001-packaging.md); this skeleton uses the conservative
+# default so CI can run everywhere.
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Compilers",
+  "Topic :: Text Processing :: General",
+]
+
+[project.urls]
+Homepage = "https://www.parsanol.org"
+Repository = "https://github.com/parsanol/parsanol-python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+parsanol = ["lib/*.so", "lib/*.dylib", "lib/*.dll"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

parsanol-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

parsanol-0.1.0/src/parsanol/__init__.py

@@ -0,0 +1,31 @@
+"""parsanol — Python runtime for PARG artifacts.
+
+Loads checksummed parsanol-tree/v2 artifacts and parses through the parsanol
+C ABI (the same engine the Ruby, Rust, wasm, and TypeScript runtimes use).
+"""
+
+from .artifact import ParseFailed, PargArtifact, TestRun, apply_bindings
+from .bindings import Bindings, BindingsError, canonical as canonical_value, collect_captures
+from .canonical import canonical_json, checksum_hex, ruby_json_float, verify_checksum
+from ._ffi import ParsanolError, engine_version, load
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Bindings",
+    "BindingsError",
+    "PargArtifact",
+    "ParseFailed",
+    "ParsanolError",
+    "TestRun",
+    "apply_bindings",
+    "canonical_json",
+    "canonical_value",
+    "checksum_hex",
+    "collect_captures",
+    "engine_version",
+    "load",
+    "ruby_json_float",
+    "verify_checksum",
+    "__version__",
+]

parsanol-0.1.0/src/parsanol/_ffi.py

@@ -0,0 +1,166 @@
+"""ctypes binding for the parsanol C ABI (libparsanol cdylib).
+
+The C surface is the same pure-portable ABI the Ruby ffi tier drives:
+`parsanol_parg_parse` returns the shaped tree as JSON on success (null on
+failure), `parsanol_parg_error` returns the failure wire as JSON, and
+`parsanol_parg_free` releases both. Nothing here interprets trees — that is
+`parsanol.artifact`'s job.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import json
+import os
+from pathlib import Path
+
+_LIB_NAMES = (
+    "libparsanol.dylib",
+    "libparsanol.so",
+    "parsanol.dll",  # cargo emits no lib prefix on windows
+    "libparsanol.dll",
+)
+
+
+class ParsanolError(RuntimeError):
+    """The engine reported a hard error (registration, loading, ABI)."""
+
+
+def _candidate_paths() -> list[str]:
+    candidates: list[str] = []
+    env = os.environ.get("PARSANOL_CDYLIB")
+    if env:
+        candidates.append(env)
+    packaged = Path(__file__).resolve().parent / "lib"
+    for name in _LIB_NAMES:
+        candidates.append(str(packaged / name))
+    for name in _LIB_NAMES:
+        candidates.append(name)  # system loader search
+    return candidates
+
+
+_lib: ctypes.CDLL | None = None
+_version: str | None = None
+
+
+def load() -> ctypes.CDLL:
+    """dlopen the cdylib once and bind the entry points."""
+    global _lib, _version
+    if _lib is not None:
+        return _lib
+
+    errors: list[str] = []
+    lib: ctypes.CDLL | None = None
+    for candidate in _candidate_paths():
+        try:
+            lib = ctypes.CDLL(candidate)
+            break
+        except OSError as error:  # noqa: PERF203 - small fixed list
+            errors.append(f"{candidate}: {error}")
+    if lib is None:
+        raise ParsanolError(
+            "libparsanol not found (build it with `cargo build -p parsanol-ffi "
+            "--release` and point PARSANOL_CDYLIB at the dylib, or install a "
+            "wheel that vendors it). Tried:\n  " + "\n  ".join(errors)
+        )
+
+    lib.parsanol_parg_parse.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+    lib.parsanol_parg_parse.restype = ctypes.c_void_p
+    lib.parsanol_parg_error.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+    lib.parsanol_parg_error.restype = ctypes.c_void_p
+    lib.parsanol_parg_free.argtypes = [ctypes.c_void_p]
+    lib.parsanol_parg_free.restype = None
+    # parsanol >= 0.18.19: the recovery export. Optional so an older cdylib
+    # still loads; parse_recovering reports availability instead.
+    if hasattr(lib, "parsanol_parg_parse_recovering"):
+        lib.parsanol_parg_parse_recovering.argtypes = [
+            ctypes.c_char_p,
+            ctypes.c_char_p,
+            ctypes.c_char_p,
+        ]
+        lib.parsanol_parg_parse_recovering.restype = ctypes.c_void_p
+    # STATIC string — must never be freed (restype c_char_p copies it).
+    lib.parsanol_version.argtypes = []
+    lib.parsanol_version.restype = ctypes.c_char_p
+    lib.parsanol_c_last_error.argtypes = []
+    # STATIC string — must never be freed.
+    lib.parsanol_c_last_error.restype = ctypes.c_char_p
+
+    _lib = lib
+    _version = (lib.parsanol_version() or b"").decode("utf-8", errors="replace")
+    return lib
+
+
+def engine_version() -> str:
+    """The parsanol crate version compiled into the loaded cdylib."""
+    load()
+    assert _version is not None
+    return _version
+
+
+def _last_error() -> str:
+    assert _lib is not None
+    pointer = _lib.parsanol_c_last_error()
+    if not pointer:
+        return ""
+    return pointer.decode("utf-8", errors="replace")
+
+
+def _take_owned(pointer: int | None):
+    """Decode an OWNED C string (parse/error results) and free it."""
+    assert _lib is not None
+    if not pointer:
+        raise ParsanolError(_last_error() or "null result with no error text")
+    text = ctypes.string_at(pointer).decode("utf-8", errors="replace")
+    _lib.parsanol_parg_free(ctypes.c_void_p(pointer))
+    return text
+
+
+def parse_shaped(grammar_json: str, input_text: str) -> dict | list | str | None:
+    """Shaped (parsanol-shape) tree as Python objects; None on rejection."""
+    lib = load()
+    pointer = lib.parsanol_parg_parse(
+        grammar_json.encode("utf-8"), input_text.encode("utf-8")
+    )
+    if not pointer:
+        return None
+    return json.loads(_take_owned(pointer))
+
+
+def failure_wire(grammar_json: str, input_text: str) -> dict:
+    """The failure wire (offset, expected, ...) for a rejected input."""
+    lib = load()
+    pointer = lib.parsanol_parg_error(
+        grammar_json.encode("utf-8"), input_text.encode("utf-8")
+    )
+    if not pointer:
+        raise ParsanolError(_last_error() or "failure wire unavailable")
+    result = json.loads(_take_owned(pointer))
+    return result if isinstance(result, dict) else {}
+
+
+def recovery_available() -> bool:
+    """Whether the loaded cdylib exports the recovery ABI (>= 0.18.19)."""
+    return hasattr(load(), "parsanol_parg_parse_recovering")
+
+
+def parse_recovering(
+    envelope_json: str, entry: str | None, input_text: str
+) -> dict:
+    """The recovery envelope for an artifact envelope (checksum verified
+    engine-side). Requires a cdylib with the recovery export."""
+    lib = load()
+    if not hasattr(lib, "parsanol_parg_parse_recovering"):
+        raise ParsanolError(
+            "the loaded libparsanol lacks parsanol_parg_parse_recovering "
+            "(requires parsanol >= 0.18.19)"
+        )
+    pointer = lib.parsanol_parg_parse_recovering(
+        envelope_json.encode("utf-8"),
+        (entry.encode("utf-8") if entry is not None else None),
+        input_text.encode("utf-8"),
+    )
+    if not pointer:
+        raise ParsanolError(_last_error() or "recovery envelope unavailable")
+    result = json.loads(_take_owned(pointer))
+    return result if isinstance(result, dict) else {}

parsanol-0.1.0/src/parsanol/artifact.py

@@ -0,0 +1,217 @@
+"""PargArtifact: checksum-verified artifact load and native parsing."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import _ffi
+from .bindings import Bindings, canonical
+from .canonical import verify_checksum
+
+
+def apply_bindings(artifact: "PargArtifact", entry: str, shape) -> dict:
+    """Apply an entry's bindings to a shaped tree (the `example` layer)."""
+    return Bindings(artifact.envelope, entry).apply(shape)
+
+
+class ParseFailed(Exception):
+    """The input was rejected; `wire` carries the failure wire."""
+
+    def __init__(self, wire: dict):
+        self.wire = wire
+        offset = wire.get("offset")
+        expected = wire.get("expected") or []
+        what = ", ".join(expected[:4]) if expected else "no further input"
+        super().__init__(f"Failed to match at offset {offset}: expected {what}")
+
+
+@dataclass
+class TestRun:
+    """Result of replaying an artifact's embedded tests."""
+
+    total: int
+    failures: list[str]
+    skipped: list[str]
+
+    @property
+    def ok(self) -> bool:
+        return not self.failures
+
+
+class PargArtifact:
+    """A loaded parsanol-tree/v2 artifact.
+
+    Load verifies the sha256 checksum over the canonicalized envelope and
+    fails loudly on mismatch — never silently mis-parses.
+    """
+
+    def __init__(self, envelope_text: str):
+        self.envelope_text = envelope_text
+        envelope = json.loads(envelope_text)
+        verify_checksum(envelope)
+        self.envelope = envelope
+        entries = envelope.get("entries") or {}
+        default = envelope.get("default_entry")
+        if default is None and entries:
+            default = sorted(entries)[0]
+        self.default_entry: str | None = default
+
+    @classmethod
+    def from_path(cls, path: str | Path) -> "PargArtifact":
+        return cls(Path(path).read_text(encoding="utf-8"))
+
+    # -- structure ---------------------------------------------------------
+
+    @property
+    def checksum(self) -> str | None:
+        return self.envelope.get("checksum")
+
+    def entry_names(self) -> list[str]:
+        return sorted(self.envelope.get("entries") or {})
+
+    def _entry(self, entry: str | None) -> tuple[str, dict]:
+        entries = self.envelope.get("entries") or {}
+        name = entry or self.default_entry
+        if name is None or name not in entries:
+            raise KeyError(f"unknown entry {name!r}")
+        return name, entries[name]
+
+    def _grammar_json(self, entry: str | None) -> str:
+        _, resolved = self._entry(entry)
+        grammar = resolved.get("grammar")
+        if grammar is None:
+            raise KeyError(f"entry {entry!r} has no portable grammar")
+        return json.dumps(grammar, separators=(",", ":"), sort_keys=True)
+
+    # -- parsing -----------------------------------------------------------
+
+    def parse(self, input_text: str, entry: str | None = None):
+        """Shaped tree (Python objects) or raises ParseFailed."""
+        grammar_json = self._grammar_json(entry)
+        shaped = _ffi.parse_shaped(grammar_json, input_text)
+        if shaped is None:
+            raise ParseFailed(_ffi.failure_wire(grammar_json, input_text))
+        return shaped
+
+    def parse_wire(self, input_text: str, entry: str | None = None) -> dict:
+        """The failure wire for a rejected input (no exception)."""
+        return _ffi.failure_wire(self._grammar_json(entry), input_text)
+
+    def recovery_supported(self) -> bool:
+        """Whether the loaded engine exports the recovery ABI."""
+        return _ffi.recovery_available()
+
+    def parse_recovering(self, input_text: str, entry: str | None = None) -> dict:
+        """Best-effort recovery (never raises): `{ok: true, shape}` on
+        success; `{ok: false, partial, error, resyncs, captures,
+        consumed_upto}` on failure — the same envelope every other runtime
+        returns, declared resync spans included. The envelope is
+        checksum-verified engine-side. Requires parsanol >= 0.18.19."""
+        self._entry(entry)  # entry validation before the FFI call
+        return _ffi.parse_recovering(self.envelope_text, entry, input_text)
+
+    # -- embedded tests ------------------------------------------------------
+
+    def run_tests(self, entry: str | None = None) -> TestRun:
+        """Replay the artifact's embedded tests through the native engine.
+
+        Phases: accept / reject / capture (grammar layer) / example
+        (bindings layer) / shape (whole-tree layer) — the same five the
+        Ruby and Rust runners evaluate.
+        """
+        name, _resolved = self._entry(entry)
+        failures: list[str] = []
+        skipped: list[str] = []
+        total = 0
+        for test in self.envelope.get("tests") or []:
+            test_entry = test.get("entry") or name
+            if test_entry != name:
+                continue
+            total += 1
+            kind = test.get("kind")
+            text = test.get("input") or ""
+            label = f"{kind} {text!r}"
+            if kind not in ("accept", "reject", "capture", "example", "shape"):
+                skipped.append(f"{label}: {kind} not in the Python scope")
+                continue
+            try:
+                tree = self.parse(text, name)
+            except ParseFailed:
+                if kind != "reject":
+                    failures.append(f"{label}: expected a match, engine rejected")
+                continue
+            if kind == "reject":
+                failures.append(f"{label}: expected rejection, engine matched")
+                continue
+
+            reduced = reduce_slices(tree)
+            if kind == "capture":
+                problems = _check_capture(reduced, test.get("expect") or {})
+                failures.extend(f"{label}: {problem}" for problem in problems)
+            elif kind == "example":
+                problems = _check_example(self, name, reduced, test.get("expect") or {})
+                failures.extend(f"{label}: {problem}" for problem in problems)
+            elif kind == "shape":
+                if canonical(reduced) != canonical(test.get("expect")):
+                    failures.append(
+                        f"{label}: shape mismatch: expected {test.get('expect')!r}, "
+                        f"got {reduced!r}"
+                    )
+        return TestRun(total=total, failures=failures, skipped=skipped)
+
+
+def _check_example(artifact: "PargArtifact", entry: str, reduced, expect: dict) -> list[str]:
+    if not isinstance(expect, dict):
+        return [f"example expectations must be an object, got {expect!r}"]
+    try:
+        bound = apply_bindings(artifact, entry, reduced)
+    except Exception as error:  # bindings errors are test failures
+        return [f"bindings failed: {error}"]
+    problems: list[str] = []
+    for key, want in expect.items():
+        got = bound.get(key)
+        if canonical(got) != canonical(want):
+            problems.append(f"bound {key!r}: expected {want!r}, got {got!r}")
+    return problems
+
+
+_SLICE_KEYS = {"offset", "length", "line", "column", "value"}
+
+
+def reduce_slices(tree):
+    """Reduce slice wire objects ({offset, length, line, column, value}) to
+    their text — the comparison form the capture-test semantics expect.
+    Other dicts pass through untouched."""
+    if isinstance(tree, dict):
+        if set(tree) == _SLICE_KEYS:
+            return tree["value"]
+        return {key: reduce_slices(value) for key, value in tree.items()}
+    if isinstance(tree, list):
+        return [reduce_slices(item) for item in tree]
+    return tree
+
+
+def _check_capture(tree, expect: dict) -> list[str]:
+    """Corpus capture semantics: collect named captures from anywhere in
+    the flattened tree (first value wins) and compare presence + value."""
+    problems: list[str] = []
+    captures: dict = {}
+
+    def walk(value) -> None:
+        if isinstance(value, dict):
+            for key, item in value.items():
+                captures.setdefault(key, item)
+                walk(item)
+        elif isinstance(value, list):
+            for item in value:
+                walk(item)
+
+    walk(tree)
+    for key, want in expect.items():
+        if key not in captures:
+            problems.append(f"capture {key!r} missing from tree")
+        elif captures[key] != want:
+            problems.append(f"capture {key!r}: expected {want!r}, got {captures[key]!r}")
+    return problems

parsanol-0.1.0/src/parsanol/bindings.py

@@ -0,0 +1,259 @@
+"""Bindings application — a faithful port of `parsanol::parg::bindings`.
+
+Pipeline: capture collection (BFS over the shaped tree, identical order)
+→ preprocessing (table_lookup over embedded table rows) → casting
+(Ruby-semantics integer/float/string/boolean casts).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .canonical import ruby_json_float
+
+
+class BindingsError(Exception):
+    pass
+
+
+def is_leaf(value: Any) -> bool:
+    """Capture leaves arrive as {value, line, column, offset, length}."""
+    return isinstance(value, dict) and "value" in value
+
+
+def leaf_scalar(value: Any) -> Any:
+    return value["value"] if is_leaf(value) else value
+
+
+def collect_captures(shape: Any) -> dict[str, list[Any]]:
+    """BFS capture collection, identical traversal order to Ruby's queue."""
+    found: dict[str, list[Any]] = {}
+    queue: list[Any] = [shape]
+    while queue:
+        node = queue.pop(0)
+        if isinstance(node, dict):
+            for key, value in node.items():
+                found.setdefault(key, []).append(value)
+                if not is_leaf(value):
+                    queue.append(value)
+        elif isinstance(node, list):
+            queue.extend(node)
+    return found
+
+
+def to_ruby_string(value: Any) -> str:
+    """Ruby `value.to_s` for the JSON values bindings see."""
+    value = leaf_scalar(value)
+    if isinstance(value, str):
+        return value
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if value.is_integer() and math_finite(value):
+            return f"{value:.1f}"
+        return repr(value)
+    if value is None:
+        return ""
+    return ""
+
+
+def math_finite(value: float) -> bool:
+    import math
+
+    return math.isfinite(value)
+
+
+def _to_int(text: str) -> int:
+    negative = text.startswith("-")
+    body = text[1:] if negative else text
+    if body.startswith("0x"):
+        radix, digits = 16, body[2:]
+    elif body.startswith("0b"):
+        radix, digits = 2, body[2:]
+    elif body.startswith("0o"):
+        radix, digits = 8, body[2:]
+    else:
+        radix, digits = 10, body
+    try:
+        magnitude = int(digits.replace("_", ""), radix)
+    except ValueError as error:
+        raise BindingsError(f"cannot cast {text!r} to integer") from error
+    return -magnitude if negative else magnitude
+
+
+def cast_integer(value: Any) -> int:
+    value = leaf_scalar(value)
+    if isinstance(value, bool):
+        raise BindingsError(f"cannot cast {value!r} to integer")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        result = _to_int(value)
+        if not (-(2**63) <= result < 2**63):
+            raise BindingsError(f"integer out of i64 range: {text_safe(value)}")
+        return result
+    raise BindingsError(f"cannot cast {value!r} to integer")
+
+
+def text_safe(value: str) -> str:
+    return value
+
+
+def cast_float(value: Any) -> float:
+    value = leaf_scalar(value)
+    if isinstance(value, bool):
+        raise BindingsError(f"cannot cast {value!r} to float")
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value.strip())
+        except ValueError as error:
+            raise BindingsError(f"cannot cast {value!r} to float") from error
+    raise BindingsError(f"cannot cast {value!r} to float")
+
+
+def cast(value: Any, kind: str | None) -> Any:
+    value = leaf_scalar(value)
+    if kind == "integer":
+        return cast_integer(value)
+    if kind == "float":
+        return cast_float(value)
+    if kind == "string":
+        if isinstance(value, (str, int, float, bool)) or value is None:
+            return to_ruby_string(value)
+        raise BindingsError(f"cannot cast {value!r} to string")
+    if kind == "boolean":
+        return value is True or (
+            isinstance(value, str) and value.lower() == "true"
+        )
+    return value
+
+
+def canonical(value: Any) -> Any:
+    """The suite's comparison form: floats render as their B6 text, leaves
+    reduce to their scalar."""
+    if isinstance(value, float) and not isinstance(value, bool):
+        return ruby_json_float(value)
+    if isinstance(value, dict):
+        if is_leaf(value):
+            return canonical(leaf_scalar(value))
+        return {key: canonical(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [canonical(item) for item in value]
+    return value
+
+
+class Bindings:
+    """An entry's binding list with the embedded preprocess tables."""
+
+    def __init__(self, envelope: dict, entry: str):
+        self.envelope = envelope
+        entry_value = (envelope.get("entries") or {}).get(entry) or {}
+        self.list: list[dict] = entry_value.get("bindings") or []
+
+    def _preprocess_steps(self, name: str) -> list[dict]:
+        return ((self.envelope.get("preprocess") or {}).get(name)) or []
+
+    def _table_rows(self, name: str) -> list[dict]:
+        declared = (self.envelope.get("tables") or {}).get(name)
+        if not isinstance(declared, dict):
+            raise BindingsError(f"unknown table {name!r}")
+        rows = declared.get("rows")
+        if not isinstance(rows, list):
+            raise BindingsError(f"unknown table {name!r}")
+        return rows
+
+    def _preprocess(self, binding: dict, value: Any) -> Any:
+        name = binding.get("preprocess")
+        if not isinstance(name, str):
+            return value
+        for step in self._preprocess_steps(name):
+            op = step.get("op")
+            if op != "table_lookup":
+                raise BindingsError(f"unknown preprocess op {op!r}")
+            try:
+                table = step["table"]
+                source = step["from"]
+                target = step["to"]
+            except KeyError as error:
+                raise BindingsError(f"unknown preprocess op {op!r}") from error
+            needle = to_ruby_string(value)
+            mapped = None
+            for row in self._table_rows(table):
+                if not isinstance(row, dict):
+                    continue
+                if to_ruby_string(row.get(source)) == needle:
+                    mapped = row.get(target)
+                    break
+            if mapped is not None:
+                value = mapped
+        return value
+
+    def _finalize(self, binding: dict, value: Any) -> Any:
+        return cast(self._preprocess(binding, value), binding.get("type"))
+
+    @staticmethod
+    def _leaf_key(path: str) -> str:
+        if "[]" in path:
+            return path.rsplit("].", 1)[-1]
+        return path
+
+    def _assign_scalar(self, out: dict, binding: dict, captures: dict) -> None:
+        capture = binding.get("capture") or ""
+        path = binding.get("path") or ""
+        if "." in path or "[" in path:
+            raise BindingsError(f"nested binding path {path!r} for capture {capture!r}")
+        values = captures.get(capture)
+        if not values:
+            return
+        out[self._leaf_key(path)] = self._finalize(binding, values[0])
+
+    def _assign_array(self, out: dict, prefix: str, group: list[dict], captures: dict) -> None:
+        count = max(
+            (len(captures[b.get("capture") or ""]) for b in group if (b.get("capture") or "") in captures),
+            default=0,
+        )
+        if count == 0:
+            return
+        list_out: list[dict] = []
+        for index in range(count):
+            element: dict = {}
+            for binding in group:
+                capture = binding.get("capture") or ""
+                values = captures.get(capture)
+                if values is None or index >= len(values):
+                    continue
+                element[self._leaf_key(binding.get("path") or "")] = self._finalize(
+                    binding, values[index]
+                )
+            list_out.append(element)
+        out[prefix] = list_out
+
+    def apply(self, shape: Any) -> dict:
+        captures = collect_captures(shape)
+        scalars: list[dict] = []
+        arrays: list[tuple[str, dict]] = []
+        for binding in self.list:
+            if not isinstance(binding, dict):
+                continue
+            path = binding.get("path") or ""
+            if "[]" in path:
+                arrays.append((path.split("[]", 1)[0], binding))
+            else:
+                scalars.append(binding)
+
+        out: dict = {}
+        for binding in scalars:
+            self._assign_scalar(out, binding, captures)
+        # Ruby groups by prefix while preserving first-seen order.
+        order: list[str] = []
+        for prefix, _ in arrays:
+            if prefix not in order:
+                order.append(prefix)
+        for prefix in order:
+            group = [binding for candidate, binding in arrays if candidate == prefix]
+            self._assign_array(out, prefix, group, captures)
+        return out

parsanol-0.1.0/src/parsanol/canonical.py

@@ -0,0 +1,136 @@
+"""Canonical JSON and artifact checksums — a faithful port of the Rust
+reference (`parsanol::parg::canonical_json` / `checksum_hex`), so a Python
+verification agrees byte-for-byte with the compiler's sha256.
+
+Canonical form: object keys sorted, no whitespace, short escapes for
+``\\b \\t \\n \\f \\r " \\``, lowercase ``\\u00xx`` for other control
+characters, raw UTF-8 otherwise, and floats rendered with the B6 float form
+(shortest round-trip digits, Ruby JSON gem notation).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+
+
+def ruby_json_float(value: float) -> str:
+    """B6 float form: shortest round-trip digits, Ruby JSON notation."""
+    if value == 0.0:
+        return "-0.0" if math.copysign(1.0, value) < 0 else "0.0"
+    sign = "-" if value < 0 else ""
+
+    digits = exponent = None
+    for precision in range(18):
+        text = f"{value:.{precision}e}"
+        if float(text) == value:
+            mantissa, raw_exponent = text.split("e")
+            stripped = "".join(c for c in mantissa if c.isdigit()).rstrip("0")
+            digits = stripped or "0"
+            exponent = int(raw_exponent)
+            break
+    assert digits is not None and exponent is not None, f"unformattable float {value!r}"
+
+    if not (-9 <= exponent <= 14):
+        head, tail = digits[:1], digits[1:]
+        mantissa = head if not tail else f"{head}.{tail}"
+        return f"{sign}{mantissa}e{exponent:+03d}"
+
+    if exponent >= 0:
+        point = exponent + 1
+        if point >= len(digits):
+            return f"{sign}{digits}{'0' * (point - len(digits))}.0"
+        return f"{sign}{digits[:point]}.{digits[point:]}"
+    zeros = "0" * (-exponent - 1)
+    return f"{sign}0.{zeros}{digits}"
+
+
+def _write_canonical(value, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, float):
+        out.append(ruby_json_float(value))
+    elif isinstance(value, int):
+        out.append(str(value))
+    elif isinstance(value, str):
+        _write_canonical_string(value, out)
+    elif isinstance(value, list):
+        out.append("[")
+        for index, item in enumerate(value):
+            if index:
+                out.append(",")
+            _write_canonical(item, out)
+        out.append("]")
+    elif isinstance(value, dict):
+        out.append("{")
+        for index, key in enumerate(sorted(value)):
+            if index:
+                out.append(",")
+            _write_canonical_string(key, out)
+            out.append(":")
+            _write_canonical(value[key], out)
+        out.append("}")
+    else:  # pragma: no cover - envelopes are plain JSON by construction
+        raise TypeError(f"non-JSON value in envelope: {type(value)!r}")
+
+
+def _write_canonical_string(text: str, out: list[str]) -> None:
+    out.append('"')
+    for character in text:
+        if character == '"':
+            out.append('\\"')
+        elif character == "\\":
+            out.append("\\\\")
+        elif character == "\b":
+            out.append("\\b")
+        elif character == "\f":
+            out.append("\\f")
+        elif character == "\n":
+            out.append("\\n")
+        elif character == "\r":
+            out.append("\\r")
+        elif character == "\t":
+            out.append("\\t")
+        elif ord(character) < 0x20:
+            out.append(f"\\u{ord(character):04x}")
+        else:
+            out.append(character)
+    out.append('"')
+
+
+def canonical_json(value) -> str:
+    out: list[str] = []
+    _write_canonical(value, out)
+    return "".join(out)
+
+
+def canonical_from_json_text(text: str):
+    """Parse JSON text the way the canonical form expects.
+
+    `json.loads` already produces shortest-round-trip floats (repr-based),
+    and `ruby_json_float` re-derives the digits, so plain parsing preserves
+    the B6 form.
+    """
+    return json.loads(text)
+
+
+def checksum_hex(payload) -> str:
+    """`sha256:<hex>` over the canonical form of `payload`."""
+    digest = hashlib.sha256(canonical_json(payload).encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def verify_checksum(envelope: dict) -> None:
+    """Raise ValueError when the envelope's checksum does not verify."""
+    stored = envelope.get("checksum")
+    if not isinstance(stored, str):
+        raise ValueError("envelope has no checksum")
+    payload = {key: value for key, value in envelope.items() if key != "checksum"}
+    computed = checksum_hex(payload)
+    if stored != computed:
+        raise ValueError(f"checksum mismatch: stored {stored}, computed {computed}")

parsanol-0.1.0/src/parsanol.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: parsanol
+Version: 0.1.0
+Summary: Python runtime for parsanol PARG artifacts: checksum-verified artifact load and wasm-grade parsing through the parsanol C ABI
+License: MIT
+Project-URL: Homepage, https://www.parsanol.org
+Project-URL: Repository, https://github.com/parsanol/parsanol-python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# parsanol (Python)
+
+Python runtime for **PARG artifacts** — checksummed `parsanol-tree/v2`
+envelopes that Ruby, Rust, WebAssembly, TypeScript, and now Python all
+parse identically.
+
+The engine is the real one: this package drives `libparsanol` (the
+pure-portable C ABI cdylib, the same binary the Ruby ffi tier ships) via
+`ctypes`. No second parser, no reimplementation.
+
+```python
+from parsanol import PargArtifact
+
+artifact = PargArtifact.from_path("demo.artifact.json")  # verifies sha256
+tree = artifact.parse("iso 12345", "identifier")         # shaped tree
+run = artifact.run_tests()                               # embedded tests replayed
+```
+
+On rejection, `parse` raises `ParseFailed` carrying the engine's failure
+wire (`offset`, ranked positions, expected set).
+
+## Status and honest boundaries (v0.1)
+
+| Capability | State |
+|---|---|
+| Artifact load + sha256 verification | **works** — the canonical-form port is byte-exact against the reference compiler (all 32 corpus checksums verify) |
+| Native parse (shaped tree, slice wire) | **works** |
+| Failure wire | **works** |
+| Embedded tests: accept / reject / capture | **works** — all 125 corpus cases replay with zero failures |
+| Embedded tests: example / shape | skipped (17 cases) — needs the bindings + flattening port ([ticket 0003](docs/tickets/0003-bindings-and-flattening.md)) |
+| `parse_recovering` | not yet — needs a C-ABI export ([ticket 0002](docs/tickets/0002-recovery-export.md)) |
+| Dynamic / runtime-state artifacts | rejected upstream by contract (Ruby-tier) |
+| Wheels on PyPI | not yet ([ticket 0001](docs/tickets/0001-packaging.md)) |
+
+## Development
+
+```sh
+cargo build -p parsanol-ffi --release          # in parsanol-rs
+export PARSANOL_CDYLIB=$RS/target/release/libparsanol.dylib
+ln -s ../parsanol-rs/corpus corpus             # for the corpus gate
+python3 -m pip install -e . pytest
+python3 -m pytest tests -q
+```
+
+The corpus gate (`tests/test_corpus.py`) pins the sizes: 125 cases, 17
+skips — when either moves, this repo moves with it deliberately.

parsanol-0.1.0/src/parsanol.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/parsanol/__init__.py
+src/parsanol/_ffi.py
+src/parsanol/artifact.py
+src/parsanol/bindings.py
+src/parsanol/canonical.py
+src/parsanol.egg-info/PKG-INFO
+src/parsanol.egg-info/SOURCES.txt
+src/parsanol.egg-info/dependency_links.txt
+src/parsanol.egg-info/top_level.txt
+tests/test_binding.py
+tests/test_corpus.py
+tests/test_recovery.py

parsanol-0.1.0/src/parsanol.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

parsanol-0.1.0/src/parsanol.egg-info/top_level.txt

@@ -0,0 +1 @@
+parsanol

parsanol-0.1.0/tests/test_binding.py

@@ -0,0 +1,93 @@
+"""Binding smoke tests: engine load, shaped parse, failure wire, float form."""
+
+from __future__ import annotations
+
+import pytest
+
+from parsanol import PargArtifact, ParseFailed, canonical_json, engine_version, ruby_json_float
+
+GRAMMAR = '{"root": 0, "atoms": [{"Str": {"pattern": "ab"}}]}'
+
+
+def test_engine_loads_and_reports_version() -> None:
+    version = engine_version()
+    assert version
+    assert version.split(".")[0].isdigit()
+
+
+def test_shaped_parse_success() -> None:
+    from parsanol import _ffi
+
+    shaped = _ffi.parse_shaped(GRAMMAR, "ab")
+    assert shaped is not None
+    assert '"value":"ab"' in canonical_json(shaped) or "ab" in str(shaped)
+
+
+def test_failure_wire_carries_offset() -> None:
+    from parsanol import _ffi
+
+    wire = _ffi.failure_wire(GRAMMAR, "zz")
+    assert "offset" in wire
+
+
+def test_ruby_json_float_forms() -> None:
+    # Ground truth ported from parsanol-rs float_tests (Ruby JSON gem
+    # JSON.generate on ruby 3.4, JSON gem 2.x).
+    cases = [
+        (0.1, "0.1"),
+        (1.5, "1.5"),
+        (2.0, "2.0"),
+        (100.0, "100.0"),
+        (-2.5, "-2.5"),
+        (-0.0, "-0.0"),
+        (0.0, "0.0"),
+        (0.0001, "0.0001"),
+        (1e-5, "0.00001"),
+        (1e-8, "0.00000001"),
+        (1.5e-10, "1.5e-10"),
+        (5e-324, "5e-324"),
+        (12345.6789, "12345.6789"),
+        (123456789012345.0, "123456789012345.0"),
+        (999999999999999.9, "999999999999999.9"),
+        (1e15, "1e+15"),
+        (1e16, "1e+16"),
+        (1e17, "1e+17"),
+        (1e300, "1e+300"),
+        (1.7976931348623157e308, "1.7976931348623157e+308"),
+    ]
+    for value, want in cases:
+        assert ruby_json_float(value) == want, f"{value!r}: {ruby_json_float(value)!r} != {want!r}"
+
+
+def test_canonical_json_key_order_and_escapes() -> None:
+    assert canonical_json({"b": 1, "a": 2}) == '{"a":2,"b":1}'
+    assert canonical_json({"k": "a\"b\\c\n"}) == '{"k":"a\\"b\\\\c\\n"}'
+
+
+def test_checksum_rejects_tampering(tmp_path) -> None:
+    artifact = PargArtifact.from_path(
+        _corpus() / "recovery_resync_declared.json"
+    )
+    tampered = dict(artifact.envelope)
+    tampered["grammar"] = "Tampered"
+    import json
+
+    with pytest.raises(ValueError, match="checksum mismatch"):
+        PargArtifact(json.dumps(tampered))
+
+
+def test_parse_failure_raises_with_wire() -> None:
+    artifact = PargArtifact.from_path(_corpus() / "recovery_resync_declared.json")
+    with pytest.raises(ParseFailed) as excinfo:
+        artifact.parse("a=1;b=2;@@junk@@;c=3;d=4;", "main")
+    assert excinfo.value.wire.get("offset") == 8
+
+
+def _corpus():
+    import os
+    from pathlib import Path
+
+    return Path(
+        os.environ.get("PARSANOL_CORPUS_DIR", "")
+        or Path(__file__).resolve().parents[1] / "corpus" / "conformance"
+    )

parsanol-0.1.0/tests/test_corpus.py

@@ -0,0 +1,54 @@
+"""Corpus gate: every conformance artifact verifies and replays natively.
+
+Mirrors parsanol-rs `tests/conformance.rs` and the shipped-artifact audits:
+checksum verification must agree byte-for-byte with the reference compiler,
+and every embedded accept/reject/capture case must replay identically.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from parsanol import PargArtifact
+
+CORPUS_DIR = Path(
+    os.environ.get("PARSANOL_CORPUS_DIR", "")
+    or Path(__file__).resolve().parents[1] / "corpus" / "conformance"
+)
+
+
+def corpus_artifacts() -> list[Path]:
+    if not CORPUS_DIR.is_dir():
+        pytest.skip("corpus/conformance not present (set PARSANOL_CORPUS_DIR)")
+    paths = sorted(CORPUS_DIR.glob("*.json"))
+    assert paths, "corpus directory is empty"
+    return paths
+
+
+def test_every_artifact_checksum_verifies() -> None:
+    """The Python canonical form agrees with the reference compiler's
+    sha256 over every corpus artifact — the B6 float form included."""
+    verified = 0
+    for path in corpus_artifacts():
+        artifact = PargArtifact.from_path(path)
+        assert artifact.checksum and artifact.checksum.startswith("sha256:")
+        verified += 1
+    assert verified >= 30, f"unexpectedly small corpus: {verified}"
+
+
+def test_every_embedded_case_replays() -> None:
+    total = 0
+    skipped = 0
+    for path in corpus_artifacts():
+        artifact = PargArtifact.from_path(path)
+        for entry in artifact.entry_names():
+            run = artifact.run_tests(entry)
+            total += run.total
+            skipped += len(run.skipped)
+            assert not run.failures, f"{path.name}: {run.failures}"
+    # The full corpus is 125 cases, all five test phases now evaluated.
+    assert total == 125, f"corpus size moved: {total}"
+    assert skipped == 0, f"unexpected skips: {skipped}"

parsanol-0.1.0/tests/test_recovery.py

@@ -0,0 +1,67 @@
+"""Recovery through the C ABI: the envelope must equal the wasm wire,
+declared resync spans included (parsanol >= 0.18.19)."""
+
+from __future__ import annotations
+
+import pytest
+
+from parsanol import PargArtifact
+
+
+@pytest.fixture()
+def artifact() -> PargArtifact:
+    path = _corpus() / "recovery_resync_declared.json"
+    if not path.is_file():
+        pytest.skip("corpus not present")
+    return PargArtifact.from_path(path)
+
+
+def _corpus():
+    import os
+    from pathlib import Path
+
+    return Path(
+        os.environ.get("PARSANOL_CORPUS_DIR", "")
+        or Path(__file__).resolve().parents[1] / "corpus" / "conformance"
+    )
+
+
+def test_recovery_supported(artifact: PargArtifact) -> None:
+    if not artifact.recovery_supported():
+        pytest.skip("loaded libparsanol predates the recovery export (0.18.19)")
+
+
+def _require_recovery(artifact: PargArtifact) -> None:
+    if not artifact.recovery_supported():
+        pytest.skip("loaded libparsanol predates the recovery export (0.18.19)")
+
+
+def test_failure_envelope_with_declared_resync(artifact: PargArtifact) -> None:
+    _require_recovery(artifact)
+    env = artifact.parse_recovering("a=1;b=2;@@junk@@;c=3;d=4;", "main")
+    assert env["ok"] is False
+    items = env["partial"]["document"]
+    assert len(items) == 4, f"expected all four pairs, got {len(items)}"
+    third = env["partial"]["document"][2]
+    assert third["k"]["value"] == "c" and third["v"]["value"] == "3"
+    assert env["error"]["offset"] == 8
+    assert len(env["resyncs"]) == 1
+    span = env["resyncs"][0]
+    assert span["skipped"] == "@@junk@@;"
+    assert span["offset"] == 8
+    assert span["resumed_at"] == 17
+
+
+def test_success_envelope_is_the_shape(artifact: PargArtifact) -> None:
+    _require_recovery(artifact)
+    env = artifact.parse_recovering("a=1;b=2;", "main")
+    assert env["ok"] is True
+    assert env["shape"] == artifact.parse("a=1;b=2;", "main")
+
+
+def test_null_entry_selects_the_default(artifact: PargArtifact) -> None:
+    _require_recovery(artifact)
+    from parsanol import _ffi
+
+    env = _ffi.parse_recovering(artifact.envelope_text, None, "a=1;b=2;")
+    assert env["ok"] is True