plan-kernel 0.1.1__py3-none-any.whl

plan_kernel/prelude.py

@@ -0,0 +1,77 @@
+"""BPLAN op prelude — boot.plan-style wrappers auto-loaded on kernel start.
+
+For each ``(name, arity)`` in ``runtime.bplan_deps.ALL_DEPS``, this module
+constructs the boot.plan-style wrapper:
+
+.. code-block:: text
+
+    (#bind Name
+      (#pin
+        (#law "Name" (Name a b ...)
+          ((#pin "B") ("Name" a b ...)))))
+
+and evaluates it against the supplied env. After loading, expressions like
+``(Add 2 3)``, ``(Inc 41)``, ``(Eq x y)`` work in any cell.
+
+Under Phase E (the Marduk swap), the runtime is :mod:`marduk.runtime` and
+the BPLAN op table is :mod:`marduk.runtime.bplan`. Wrappers for op names
+in ``ALL_DEPS`` that aren't yet implemented in Marduk's op table still
+*bind* successfully — the wrapper Law is constructed without evaluating
+its body — but calling them at runtime will raise NotImplementedError
+from the BPLAN dispatcher. Add the op upstream rather than working
+around it here.
+"""
+
+from __future__ import annotations
+
+from marduk.asm import Env, eval_form, parse_many
+from marduk.runtime.strnat import str_nat
+
+from .runtime.bplan_deps import ALL_DEPS
+
+
+__all__ = ["PRELUDE_NAMES", "load_prelude"]
+
+
+# Single-letter argument names. ``ALL_DEPS`` arities cap at 6 (``Elim``);
+# 26 letters is plenty.
+_ARG_LETTERS = "abcdefghijklmnopqrstuvwxyz"
+
+
+def _arg_names(arity: int) -> str:
+    if arity > len(_ARG_LETTERS):
+        raise ValueError(
+            f"prelude: arity {arity} exceeds supported letters ({len(_ARG_LETTERS)})"
+        )
+    return " ".join(_ARG_LETTERS[i] for i in range(arity))
+
+
+def _wrapper_source(name: str, arity: int) -> str:
+    args = _arg_names(arity)
+    sig = f"{name} {args}"
+    body = f'((#pin "B") ("{name}" {args}))'
+    return f'(#bind {name} (#pin (#law "{name}" ({sig}) {body})))'
+
+
+def load_prelude(env: Env) -> set[int]:
+    """Load every BPLAN op wrapper into ``env``.
+
+    Returns the set of name nats that were bound — useful for the
+    evaluator's ``%env`` magic to filter prelude noise from user bindings.
+    """
+    bound: set[int] = set()
+    for name, arity in ALL_DEPS.items():
+        if arity < 1:
+            continue
+        src = _wrapper_source(name, arity)
+        for form in parse_many(src):
+            eval_form(form, env)
+        bound.add(str_nat(name))
+    return bound
+
+
+# Precomputed set of all prelude name nats. Equivalent to the return value
+# of ``load_prelude(...)`` but available without performing the load.
+PRELUDE_NAMES: frozenset[int] = frozenset(
+    str_nat(name) for name, arity in ALL_DEPS.items() if arity >= 1
+)

plan_kernel/render.py

@@ -0,0 +1,161 @@
+"""Structural value renderer.
+
+``render_value(val)`` returns a ``(text/plain, text/html)`` pair the
+kernel emits as a Jupyter MIME bundle. Both forms are depth-bounded so
+a pathological structure (a malformed App tree, a Pin loop) can't blow
+the stack while we're trying to *show* it.
+
+Format:
+
+- Nat ``n``           → ``"42"`` (decimal).
+- Pin ``v``           → ``"<v>"``.
+- Pin ``Law``         → ``"<{'name'…}>"`` when ``pretty=True`` (default);
+                        otherwise expanded as ``"<{name arity body}>"``.
+- Law ``{a n b}``     → ``"{'name' arity body}"``; ``name`` is decoded
+                        via ``nat_str`` and shown single-quoted (or
+                        decimal if the nat doesn't decode to printable
+                        UTF-8).
+- App ``f x``         → ``"(f x)"``.
+
+The HTML output uses inline ``style="…"`` (Jupyter strips ``<style>``
+blocks) and a cross-theme palette that reads on both light and dark
+backgrounds.
+
+Phase E note: this module now reads Marduk's ``Val`` accessors —
+``.head``/``.tail`` for App, ``.item`` for Pin, ``.args`` for Law's
+arity (a ``Val``, not an int), ``.name`` (also a ``Val``). The
+predicates ``is_app``/``is_law``/etc. come from the runtime shim,
+which dispatches on ``val.type``.
+"""
+
+from __future__ import annotations
+
+import html
+
+from marduk.runtime.strnat import nat_str
+
+from .runtime.plan import is_app, is_law, is_nat, is_pin
+
+
+__all__ = ["render_value"]
+
+
+_DEFAULT_DEPTH = 32
+
+# Cross-theme-friendly palette.
+_NAT   = "color:#0097a7"                         # cyan
+_LAW   = "color:#e65100;font-style:italic"       # orange italic
+_NAME  = "color:#388e3c"                         # green (decoded name)
+_MUTED = "color:#999"                            # gray (brackets)
+
+
+def render_value(val, *, pretty: bool = True,
+                 max_depth: int = _DEFAULT_DEPTH) -> tuple[str, str]:
+    """Return ``(text, html)`` for ``val``.
+
+    Parameters
+    ----------
+    pretty
+        Collapse ``Pin(Law(...))`` to ``<{name…}>`` for terse display
+        (default). Set to ``False`` to fully expand into
+        ``<{name arity body}>``.
+    max_depth
+        Recursion bound. Past this depth the renderer emits an ellipsis.
+    """
+    text = _text(val, depth=0, pretty=pretty, max_depth=max_depth)
+    body = _html(val, depth=0, pretty=pretty, max_depth=max_depth)
+    full_html = (
+        '<code style="font-family:ui-monospace,SFMono-Regular,Menlo,monospace;'
+        f'font-size:0.9em">{body}</code>'
+    )
+    return text, full_html
+
+
+# ---------------------------------------------------------------------------
+# text/plain
+# ---------------------------------------------------------------------------
+
+def _text(val, *, depth: int, pretty: bool, max_depth: int) -> str:
+    if depth >= max_depth:
+        return "..."
+    if is_nat(val):
+        return str(val.nat)
+    if is_pin(val):
+        if pretty and is_law(val.item):
+            return f"<{{{_law_name_text(val.item)}…}}>"
+        inner = _text(val.item, depth=depth + 1, pretty=pretty, max_depth=max_depth)
+        return f"<{inner}>"
+    if is_law(val):
+        body = _text(val.body, depth=depth + 1, pretty=pretty, max_depth=max_depth)
+        return f"{{{_law_name_text(val)} {val.args.nat} {body}}}"
+    if is_app(val):
+        f = _text(val.head, depth=depth + 1, pretty=pretty, max_depth=max_depth)
+        a = _text(val.tail, depth=depth + 1, pretty=pretty, max_depth=max_depth)
+        return f"({f} {a})"
+    return repr(val)
+
+
+def _law_name_text(law) -> str:
+    """Decode a law's ``name`` via ``nat_str`` for display.
+
+    Returns ``'identifier'`` (single-quoted) for printable UTF-8 nats, or
+    decimal for nats that don't decode. Non-nat names recurse through the
+    text renderer with a small depth bound.
+    """
+    if is_nat(law.name):
+        s = nat_str(law.name.nat)
+        if s and not s.startswith("<nat:"):
+            return f"'{s}'"
+        return str(law.name.nat)
+    return _text(law.name, depth=0, pretty=True, max_depth=4)
+
+
+# ---------------------------------------------------------------------------
+# text/html
+# ---------------------------------------------------------------------------
+
+def _html(val, *, depth: int, pretty: bool, max_depth: int) -> str:
+    if depth >= max_depth:
+        return f'<span style="{_MUTED}">…</span>'
+    if is_nat(val):
+        return f'<span style="{_NAT}">{val.nat}</span>'
+    if is_pin(val):
+        if pretty and is_law(val.item):
+            return (
+                f'<span style="{_MUTED}">&lt;{{</span>'
+                f"{_law_name_html(val.item)}"
+                f'<span style="{_MUTED}">…}}&gt;</span>'
+            )
+        inner = _html(val.item, depth=depth + 1, pretty=pretty, max_depth=max_depth)
+        return (
+            f'<span style="{_MUTED}">&lt;</span>'
+            f"{inner}"
+            f'<span style="{_MUTED}">&gt;</span>'
+        )
+    if is_law(val):
+        body = _html(val.body, depth=depth + 1, pretty=pretty, max_depth=max_depth)
+        return (
+            f'<span style="{_MUTED}">{{</span>'
+            f"{_law_name_html(val)} "
+            f'<span style="{_NAT}">{val.args.nat}</span> '
+            f"{body}"
+            f'<span style="{_MUTED}">}}</span>'
+        )
+    if is_app(val):
+        f = _html(val.head, depth=depth + 1, pretty=pretty, max_depth=max_depth)
+        a = _html(val.tail, depth=depth + 1, pretty=pretty, max_depth=max_depth)
+        return (
+            f'<span style="{_MUTED}">(</span>'
+            f"{f} {a}"
+            f'<span style="{_MUTED}">)</span>'
+        )
+    return html.escape(repr(val), quote=False)
+
+
+def _law_name_html(law) -> str:
+    if is_nat(law.name):
+        s = nat_str(law.name.nat)
+        if s and not s.startswith("<nat:"):
+            return f'<span style="{_NAME}">\'{html.escape(s)}\'</span>'
+        return f'<span style="{_NAT}">{law.name.nat}</span>'
+    return f'<span style="{_LAW}">{html.escape(repr(law.name))}</span>'

plan_kernel/runtime/__init__.py

@@ -0,0 +1 @@
+"""Vendored PLAN runtime — see VENDOR.md for source provenance and sync policy."""

plan_kernel/runtime/bplan.py

@@ -0,0 +1,20 @@
+"""BPLAN harness — compatibility shim.
+
+The legacy plan-kernel BPLAN harness implemented jet-based dispatch on
+top of the old runtime. Phase E moves the canonical BPLAN op table into
+:mod:`marduk.runtime.bplan`, where dispatch is integrated with the
+spec-faithful core. This module re-exports the new table so callers
+that import from ``plan_kernel.runtime.bplan`` continue to resolve.
+
+Note: the legacy file used to define a separate ``bevaluate`` driver
+distinct from ``evaluate``. With Marduk both modes share the same
+evaluator (the spec-faithful core does the right thing without a jet
+overlay), so the historic distinction has gone away — ``bevaluate``
+here is an alias for ``evaluate``.
+"""
+
+from marduk.runtime import evaluate as bevaluate
+from marduk.runtime.bplan import OPS, dispatch
+
+
+__all__ = ["OPS", "dispatch", "bevaluate"]

plan_kernel/runtime/bplan_deps.py

@@ -0,0 +1,115 @@
+"""
+BPLAN named-op dependencies of the Gallowglass codegen.
+
+Per `DECISIONS.md §"Upstream PLAN authority"`, the canonical PLAN spec is
+`vendor/reaver/src/hs/Plan.hs`. PLAN proper and the Plan Asm text format are
+frozen; the BPLAN named-op set may drift over time.
+
+This module enumerates every BPLAN intrinsic that gallowglass-emitted code
+relies on, by name and arity. `tests/sanity/test_bplan_deps.py` greps the
+pinned `vendor/reaver/src/hs/Plan.hs` and asserts presence at the right arity.
+This is the canary that fires when `vendor.lock` is bumped to a Reaver SHA
+that has renamed, removed, or rearity'd one of our deps.
+
+Each entry: `name -> arity`.
+
+Categories:
+  Core primitives — needed by codegen for opcode-equivalent operations.
+  Arithmetic/bytes — needed by Core.Nat / Core.Text / Core.Bytes prelude.
+  RPLAN — needed for I/O (deferred; see Phase G).
+"""
+
+from __future__ import annotations
+
+
+# Core primitives gallowglass emits directly from codegen.
+# Replaces the legacy P(N(0))..P(N(4)) opcode-pin shape with BPLAN named-Law
+# references that delegate to (P("B")) ("Name" args).
+CORE_PRIMITIVES: dict[str, int] = {
+    'Pin':   1,    # was P(N(0))
+    'Law':   3,    # was P(N(1)) / MkLaw
+    'Inc':   1,    # was P(N(2))
+    'Elim':  6,    # was P(N(3)) / Case_  — canonical 6-arity dispatch
+    'Force': 1,    # was P(N(4))
+}
+
+
+# Prelude arithmetic / introspection — used by the BPLAN harness as Python
+# fast-path jets, but their existence in Reaver is what makes gallowglass-
+# emitted prelude code actually run on Reaver at all.
+PRELUDE_INTRINSICS: dict[str, int] = {
+    # Arithmetic
+    'Add': 2,
+    'Sub': 2,
+    'Mul': 2,
+    'Div': 2,
+    'Mod': 2,
+    'Dec': 1,
+    # Comparison — full set
+    'Eq':  2,
+    'Ne':  2,
+    'Lt':  2,
+    'Le':  2,
+    'Gt':  2,
+    'Ge':  2,
+    'Cmp': 2,
+    # Boolean / control
+    'Truth': 1,
+    'Or':    2,
+    'And':   2,
+    'If':    3,
+    'Ifz':   3,
+    # Bit ops (used by bytes encoding)
+    'Lsh': 2,
+    'Rsh': 2,
+    'Bex': 1,    # 2^n — used for bytesBar high-bit decoding in REPL demos
+    # Introspection (used in the harness; future codegen may emit these)
+    'Type':  1,
+    'IsPin': 1,
+    'IsLaw': 1,
+    'IsApp': 1,
+    'IsNat': 1,
+    'Hd':    1,
+    'Sz':    1,
+    'Unpin': 1,
+    'Arity': 1,
+    'Name':  1,
+    'Body':  1,
+    # Sequencing
+    'Seq':  2,
+    # Diagnostics
+    'Trace': 2,
+    # Small Case dispatchers — Case<N> takes one nat plus N-1 indexed
+    # branches plus a fallback, so total arity is N+1.
+    'Case2':   3,
+    'Case3':   4,
+    'Case4':   5,
+    'Case5':   6,
+    'Case6':   7,
+    'Case7':   8,
+    'Case8':   9,
+    'Case9':  10,
+    'Case10': 11,
+    'Case11': 12,
+    'Case12': 13,
+    'Case13': 14,
+    'Case14': 15,
+    'Case15': 16,
+    'Case16': 17,
+}
+
+
+# All BPLAN deps as a single dict, suitable for the sanity test.
+ALL_DEPS: dict[str, int] = {
+    **CORE_PRIMITIVES,
+    **PRELUDE_INTRINSICS,
+}
+
+
+# strNat encoding helper — packs UTF-8 bytes little-endian into a Python int.
+# Mirrors `bootstrap.codegen.encode_name`.  Defined here so `bplan_deps`
+# stays free of bootstrap dependencies and can be imported from tests.
+def str_nat(s: str) -> int:
+    """Encode s as a little-endian nat (Reaver's `strNat`)."""
+    raw = s.encode('utf-8')
+    return int.from_bytes(raw, 'little')

plan_kernel/runtime/plan.py

@@ -0,0 +1,133 @@
+"""PLAN runtime — compatibility shim re-exporting Marduk's runtime under
+the legacy plan-kernel API names.
+
+Plan-kernel originally vendored a copy of the gallowglass harness at
+``runtime/plan.py``. As part of the Phase E swap, the runtime is now
+provided by :mod:`marduk.runtime`; this file maps the old names
+(``A``, ``L``, ``N``, ``P``, ``is_app``/``is_law``/``is_nat``/``is_pin``,
+``_unapp``, ``evaluate``, ``str_nat``, ``nat_str``) onto the new API so
+existing callers don't have to change.
+
+A few semantics differ from the legacy runtime that matter for callers:
+
+* ``L(arity, name, body)`` constructs a Marduk law via the smart
+  constructor — it forces the body's let-binding spine via ``B`` (per
+  spec), so callers shouldn't expect deferred evaluation of binding
+  values.
+* ``N(n)`` returns a ``Val`` (not a raw int). Comparisons of the form
+  ``some_val == 0`` no longer work — use ``some_val.nat == 0``.
+"""
+
+from __future__ import annotations
+
+from marduk.runtime import (
+    Val, Hol,
+    Nat as _Nat,
+    Pin as _Pin,
+    App as _App,
+    Law as _Law,
+    evaluate as _evaluate,
+    force,
+    PlanError,
+    PlanLoop,
+)
+from marduk.runtime.strnat import str_nat, nat_str
+
+
+__all__ = [
+    # constructors (legacy short names)
+    "A", "L", "N", "P", "Hol",
+    # new long names also exposed for forward-compat
+    "App", "Law", "Nat", "Pin", "Val",
+    # type predicates
+    "is_app", "is_law", "is_nat", "is_pin",
+    # spine flatten
+    "_unapp", "unapp",
+    # drivers
+    "evaluate", "force",
+    # str-nat helpers
+    "str_nat", "nat_str",
+    # exceptions
+    "PlanError", "PlanLoop",
+]
+
+
+# ---- New-API aliases -------------------------------------------------------
+
+App = _App
+Law = _Law
+Nat = _Nat
+Pin = _Pin
+evaluate = _evaluate
+
+
+# ---- Legacy short-name aliases --------------------------------------------
+
+def _coerce(x):
+    """Coerce a Python int to a Marduk ``Val``; pass other ``Val`` through.
+
+    Plan-kernel's legacy runtime treated raw Python ints as nats, so call
+    sites like ``P(5)`` meant "pin a nat 5". Marduk has no raw-int
+    representation for nats — every nat is a ``Val``. The legacy
+    constructor shims auto-coerce so existing code keeps working.
+    """
+    if isinstance(x, Val):
+        return x
+    if isinstance(x, int):
+        return _Nat(x)
+    return x
+
+
+def A(f, x):
+    """Legacy alias for :func:`marduk.runtime.App`."""
+    return _App(_coerce(f), _coerce(x))
+
+
+def L(arity, name, body):
+    """Legacy law constructor: ``L(arity, name, body)``.
+
+    Plan-kernel's ``class L`` was ``__init__(self, arity, name, body)``.
+    Marduk's smart constructor uses ``Law(name, arity, body)``; this
+    shim flips the order back, wraps int arity in a ``Nat``, and
+    coerces int name/body args.
+    """
+    arity_val = arity if isinstance(arity, Val) else _Nat(arity)
+    return _Law(_coerce(name), arity_val, _coerce(body))
+
+
+def N(n):
+    """Legacy alias for :func:`marduk.runtime.Nat`. Wraps an int as a Val."""
+    return _Nat(n)
+
+
+def P(item):
+    """Legacy alias for :func:`marduk.runtime.Pin`."""
+    return _Pin(_coerce(item))
+
+
+# ---- Type predicates -------------------------------------------------------
+
+def is_app(v):
+    return isinstance(v, Val) and v.type == "app"
+
+
+def is_law(v):
+    return isinstance(v, Val) and v.type == "law"
+
+
+def is_nat(v):
+    return isinstance(v, Val) and v.type == "nat"
+
+
+def is_pin(v):
+    return isinstance(v, Val) and v.type == "pin"
+
+
+# ---- Spine flatten ---------------------------------------------------------
+
+def unapp(v):
+    """Public alias for :attr:`marduk.runtime.Val.spine`."""
+    return v.spine
+
+
+_unapp = unapp