marduk-plan 0.2.0__tar.gz

marduk_plan-0.2.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: marduk-plan
+Version: 0.2.0
+Summary: Python implementation of the PLAN instruction set.
+Author-email: Neal Davis <davisneale@gmail.com>
+Project-URL: Homepage, https://github.com/sigilante/marduk
+Project-URL: Repository, https://github.com/sigilante/marduk
+Keywords: plan,bplan,interpreter,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Interpreters
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# marduk
+
+A standalone Python runtime for the [PLAN virtual machine](https://github.com/xocore-tech/PLAN).
+
+**Status:** pre-alpha. The package is a placeholder — the spec-faithful core, BPLAN op coverage, and jet overlay land in subsequent commits. Until then, callers that need a Python PLAN runtime use [`packages/plan-kernel/`](../plan-kernel/)'s vendored harness.
+
+## Goals
+
+- **Spec-faithful core.** A direct translation of [`vendor/reaver/doc/plan-spec.txt`](https://github.com/xocore-tech/PLAN) — `E`/`R`/`H`/`J`/`B`/`S`/`C`/`I`/`X` as Python functions over a `Thunk`-cell value type with update-in-place `force`. Strictness comes from the spec's `;` sequencing, not from Python's evaluation order.
+- **Complete BPLAN op coverage.** All of Reaver's `op 66` named primitives, including the IO family that today's harness stubs.
+- **Jet overlay.** An optional id-keyed performance layer; correctness lives in the spec-faithful interpreter regardless of jet presence.
+- **Differential against Reaver.** A small Plan Asm corpus run on both Marduk and Reaver in CI.
+- **No coupling to gallowglass.** Marduk imports nothing from gallowglass; gallowglass eventually depends on Marduk as a library.
+
+## Non-goals
+
+- Native-speed PLAN execution. Marduk is correctness-first; production workloads belong on Reaver.
+- Hosting Reaver-itself-as-BPLAN. A future possibility once IO ops and performance reach the bar; not in scope for the initial release.
+
+## Layout
+
+```
+packages/marduk/
+├── marduk/         # Python package
+│   └── __init__.py
+├── tests/
+└── pyproject.toml
+```
+
+## License
+
+MIT.

marduk_plan-0.2.0/README.md

@@ -0,0 +1,32 @@
+# marduk
+
+A standalone Python runtime for the [PLAN virtual machine](https://github.com/xocore-tech/PLAN).
+
+**Status:** pre-alpha. The package is a placeholder — the spec-faithful core, BPLAN op coverage, and jet overlay land in subsequent commits. Until then, callers that need a Python PLAN runtime use [`packages/plan-kernel/`](../plan-kernel/)'s vendored harness.
+
+## Goals
+
+- **Spec-faithful core.** A direct translation of [`vendor/reaver/doc/plan-spec.txt`](https://github.com/xocore-tech/PLAN) — `E`/`R`/`H`/`J`/`B`/`S`/`C`/`I`/`X` as Python functions over a `Thunk`-cell value type with update-in-place `force`. Strictness comes from the spec's `;` sequencing, not from Python's evaluation order.
+- **Complete BPLAN op coverage.** All of Reaver's `op 66` named primitives, including the IO family that today's harness stubs.
+- **Jet overlay.** An optional id-keyed performance layer; correctness lives in the spec-faithful interpreter regardless of jet presence.
+- **Differential against Reaver.** A small Plan Asm corpus run on both Marduk and Reaver in CI.
+- **No coupling to gallowglass.** Marduk imports nothing from gallowglass; gallowglass eventually depends on Marduk as a library.
+
+## Non-goals
+
+- Native-speed PLAN execution. Marduk is correctness-first; production workloads belong on Reaver.
+- Hosting Reaver-itself-as-BPLAN. A future possibility once IO ops and performance reach the bar; not in scope for the initial release.
+
+## Layout
+
+```
+packages/marduk/
+├── marduk/         # Python package
+│   └── __init__.py
+├── tests/
+└── pyproject.toml
+```
+
+## License
+
+MIT.

marduk_plan-0.2.0/marduk/__init__.py

@@ -0,0 +1,45 @@
+"""Marduk — standalone Python runtime for the PLAN virtual machine.
+
+This package is a thunked, spec-faithful translation of
+``vendor/reaver/doc/plan-spec.txt`` into Python. The core interpreter
+(spec rules E/F/X/S and friends, plus the ``Val`` cell type that supports
+update-in-place for letrec / Y / fix) lives in :mod:`marduk.runtime.core`.
+
+Public surface, re-exported from :mod:`marduk.runtime`:
+
+* ``Val`` — universal cell type.
+* ``Hol``, ``Nat``, ``Pin``, ``App``, ``Law`` — smart constructors.
+* ``evaluate(v)`` — force to WHNF.
+* ``force(v)`` — force the App spine to NF (pins and law bodies stay opaque).
+* ``PlanError``, ``PlanLoop`` — exceptions for stuck states and hole-loops.
+
+Optional jet overlay (see :mod:`marduk.runtime.jets`):
+
+* ``register_jet(law, fn)`` — install a native Python implementation
+  for a specific Law value.
+* ``set_jets(bool)`` / ``jets_enabled()`` — global on/off switch. Use
+  ``set_jets(False)`` to force every law to evaluate via the
+  spec-faithful path (correctness oracle / differential testing).
+
+Plan Asm I/O lives in :mod:`marduk.asm`.
+"""
+
+from .runtime import (
+    Val,
+    Hol, Nat, Pin, App, Law,
+    evaluate, force,
+    PlanError, PlanLoop,
+    register_jet, lookup_jet, clear_jets,
+    set_jets, jets_enabled,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "Val",
+    "Hol", "Nat", "Pin", "App", "Law",
+    "evaluate", "force",
+    "PlanError", "PlanLoop",
+    "register_jet", "lookup_jet", "clear_jets",
+    "set_jets", "jets_enabled",
+]

marduk_plan-0.2.0/marduk/asm/__init__.py

@@ -0,0 +1,46 @@
+"""marduk.asm — Plan Asm I/O.
+
+Read, macro-expand, and print Plan Asm text against the Marduk runtime.
+
+* :func:`parse` / :func:`parse_many` — Plan Asm text → ``Val``.
+* :class:`Env` — top-level mutable environment for ``#bind``.
+* :func:`macroexpand` / :func:`thunk` / :func:`eval_form` — the macro-layer
+  pipeline. ``eval_form(val, env)`` is the full driver: macroexpand →
+  thunk → runtime evaluate.
+* :func:`dump` — ``Val`` → Plan Asm text (best-effort round-trippable).
+
+A typical interactive flow:
+
+    >>> from marduk.asm import parse, eval_form, Env, dump
+    >>> env = Env()
+    >>> # Bind ``add`` to a 2-arg law that calls BPLAN's Add.
+    >>> form = parse('(#bind add (#law "add" (self n m) (Add n m)))')
+    >>> # ``Add`` would need to be in env first; see prelude wiring.
+
+The expander's API is shape-compatible with plan-kernel's lifted-from
+predecessor so the kernel's evaluator can swap the import path with
+minimal change.
+"""
+
+from .reader import ParseError, parse, parse_many
+from .expander import (
+    Env,
+    MacroError,
+    macroexpand,
+    thunk,
+    eval_form,
+)
+from .printer import dump
+from .prelude import load_prelude, make_bplan_wrapper, PRELUDE_NAMES, BPLAN
+
+
+__all__ = [
+    # reader
+    "ParseError", "parse", "parse_many",
+    # expander
+    "Env", "MacroError", "macroexpand", "thunk", "eval_form",
+    # printer
+    "dump",
+    # prelude
+    "load_prelude", "make_bplan_wrapper", "PRELUDE_NAMES", "BPLAN",
+]