imlx-gate 0.1.0__py3-none-any.whl

imlx/__init__.py

@@ -0,0 +1,30 @@
+"""
+imlx
+====
+Reference implementation of IMLX: Invariant Markup Language (eXtended).
+
+Binary determinism: a deterministic pass/fail gate at input, a
+deterministic, auditable pass/fail at output. The model produces; the
+gate decides.
+
+Spec: SPEC.md v0.1.0-rc.1 (github.com/passert-ai/imlx). Foundation:
+the recovered iml-cli v1.0.0 validator core's result-object and CLI
+patterns, rebuilt spec-facing against SPEC v0.1. Zero runtime
+dependencies.
+"""
+
+__version__ = "0.1.0"
+
+from .gate import GateResult, gate_bytes, gate_file, run_file
+from .layer1 import Verdict, Reason, gate_layer1_bytes
+from .layer2 import gate_layer2, OPCODES
+from .declarations import Registries, parse_declarations
+from .executor import RunResult, FailureRecord, run
+from .trace import Trace, TraceEvent
+
+__all__ = [
+    "GateResult", "gate_bytes", "gate_file", "run_file",
+    "Verdict", "Reason", "gate_layer1_bytes", "gate_layer2",
+    "Registries", "parse_declarations", "RunResult", "FailureRecord",
+    "run", "Trace", "TraceEvent", "OPCODES", "__version__",
+]

imlx/charset.py

@@ -0,0 +1,165 @@
+"""
+imlx.charset
+============
+The closed alphabet (SPEC Section 6) and Layer 1 character law.
+
+Binary determinism: every check is a membership test over an enumerated set.
+Absence from the allowlist is what forbids (Law 1); the forbidden list in
+SPEC 6.3 exists only so this module can emit useful reason codes.
+
+Spec basis (SPEC.md v0.1.0-rc.1):
+- 5.1 encoding and line discipline
+- 6.1 allowed characters (content space)
+- 6.2 allowed constructs
+- 6.4 straight quote codification
+- 9   the @ reference namespace (program/declaration space only)
+
+IMPLEMENTATION NOTES (ratified in SPEC v0.1.0-rc.2):
+- PROGRAM_SPACE_EXTRA: characters permitted inside program-space and
+  declaration-space pipe-table cells beyond the content alphabet. `@` and
+  `=` are attested by SPEC Appendix B/D examples; `< > +` are included to
+  make SELECT predicates and COMPUTE operators expressible per 11.2
+  ("closed operator set"). Interpretation, not verbatim spec text.
+"""
+
+__version__ = "0.1.0"
+
+import re
+
+# ---------------------------------------------------------------------------
+# Character sets (SPEC 6.1, 6.4)
+# ---------------------------------------------------------------------------
+
+_LETTERS = set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz")
+_DIGITS = set("0123456789")
+
+# Punctuation allowed in content space, subject to positional rules
+# (SPEC 6.1). Straight double quote and apostrophe per 6.4.
+_CONTENT_PUNCT = set(". , : ; - ' \" ( ) [ ] | * # $ %".split()) | {"/", "?"}
+
+#: Every character legal anywhere in content space (positional rules are
+#: enforced in layer1, not here). LF is handled at the line level.
+CONTENT_CHARS = _LETTERS | _DIGITS | {" "} | _CONTENT_PUNCT
+
+#: Characters that MUST appear only inside $-fences in content space
+#: (SPEC 6.2 math fencing). `%` bare is legal only within %%PAGEBREAK%%.
+MATH_ONLY_CHARS = set("<>=+")
+
+#: Extra characters legal inside program-space / declaration-space /
+#: trace-space pipe-table cells (see module docstring).
+PROGRAM_SPACE_EXTRA = {"@", "=", "<", ">", "+", "_"}
+
+#: Full alphabet for program/declaration/trace table cells.
+PROGRAM_CELL_CHARS = CONTENT_CHARS | PROGRAM_SPACE_EXTRA
+
+#: Characters legal on an envelope opening line, beyond content letters and
+#: digits (SPEC 7.1): ::: { } = " - and space are all consumed by the exact
+#: line regex in layer1; no free-form check applies to envelope lines.
+
+# ---------------------------------------------------------------------------
+# Exact tokens and line-form regexes
+# ---------------------------------------------------------------------------
+
+PAGEBREAK_TOKEN = "%%PAGEBREAK%%"
+
+#: SPEC 5.2 header line 1.
+HEADER_IMLX_RE = re.compile(r"^IMLX: (\d+\.\d+)$")
+
+#: SPEC 5.2 header line 2: external pairing or the literal INLINE.
+HEADER_DECL_RE = re.compile(
+    r"^DECLARATIONS: (?:(INLINE)|([A-Za-z0-9._-]+\.imlx); (\d+\.\d+))$"
+)
+
+#: SPEC 10.3 declaration-file third header line.
+HEADER_DECLVER_RE = re.compile(r"^DECL_VERSION: (\d+\.\d+)$")
+
+#: SPEC 7.1 envelope opening line, exact form.
+ENVELOPE_OPEN_RE = re.compile(r'^::: \{custom-style="([A-Za-z][A-Za-z0-9_]*)"\}$')
+
+#: SPEC 7.1 envelope closing line.
+ENVELOPE_CLOSE = ":::"
+
+#: Headings: #, ##, ### + one space (SPEC 6.2). Deeper levels are illegal.
+HEADING_RE = re.compile(r"^(#{1,3}) (\S.*)$")
+HEADING_TOO_DEEP_RE = re.compile(r"^#{4,}")
+
+#: Bullets: `* ` and one indented sublevel `* * ` (SPEC 6.2).
+BULLET_RE = re.compile(r"^\* (?:\* )?(\S.*)$")
+
+#: Legal-numbered list line (SPEC 6.2): 1.1, 1.2 ... at line start.
+LEGAL_LIST_RE = re.compile(r"^\d+\.\d+ \S")
+
+#: Step numbering (SPEC 6.2): Step 1:, Step 2:, ... at line start.
+STEP_LINE_RE = re.compile(r"^Step \d+: \S")
+
+#: Pipe-table row: starts and ends with |, at least two pipes.
+TABLE_ROW_RE = re.compile(r"^\|.*\|$")
+
+#: Pipe-table separator row (SPEC 6.2): | :--- | :--- |
+TABLE_SEP_CELL = ":---"
+
+#: Reference name (SPEC 9): letters, digits, _, beginning with a letter.
+REFERENCE_RE = re.compile(r"^@([A-Za-z][A-Za-z0-9_]*)$")
+REFERENCE_SCAN_RE = re.compile(r"@([A-Za-z][A-Za-z0-9_]*)")
+
+#: Program-table header cells, exact (SPEC 11.1).
+PROGRAM_HEADER = ["step", "opcode", "operand", "bind", "style"]
+
+#: Trace-table header cells, exact (SPEC 13.6).
+TRACE_HEADER = ["seq", "event", "step", "opcode", "subject", "outcome", "digest"]
+
+#: DECLARE section heading (SPEC 10.4): `# DECLARE <kind>`.
+DECLARE_HEADING_RE = re.compile(r"^# DECLARE ([A-Z]+)$")
+
+
+# ---------------------------------------------------------------------------
+# Character-law checks
+# ---------------------------------------------------------------------------
+
+def illegal_content_chars(text: str) -> list[str]:
+    """Characters in ``text`` outside the content-space alphabet, fence-aware.
+
+    Outside $-fences the alphabet is CONTENT_CHARS; inside a fence the
+    mathematical symbols (SPEC 6.2) are additionally legal. Positional
+    rules remain layer1's job; this is membership.
+    """
+    outside, inside, _balanced = split_math_fences(text)
+    bad = {c for c in outside if c not in CONTENT_CHARS}
+    bad |= {c for c in inside if c not in CONTENT_CHARS | MATH_ONLY_CHARS}
+    return sorted(bad)
+
+
+def illegal_program_cell_chars(text: str) -> list[str]:
+    """Characters in a program/declaration/trace cell outside its alphabet."""
+    return sorted({c for c in text if c not in PROGRAM_CELL_CHARS})
+
+
+def split_math_fences(line: str):
+    """Split a line into (outside, inside) character streams by $-fences.
+
+    Returns (outside_text, inside_text, balanced) where ``balanced`` is
+    False if the line ends inside an unclosed fence (fences MUST close
+    within the line; multi-line blocks are hard-broken lines, SPEC 6.2).
+    """
+    outside: list[str] = []
+    inside: list[str] = []
+    in_fence = False
+    for ch in line:
+        if ch == "$":
+            in_fence = not in_fence
+            continue
+        (inside if in_fence else outside).append(ch)
+    return "".join(outside), "".join(inside), not in_fence
+
+
+def bare_math_chars_outside_fences(line: str) -> list[str]:
+    """Math-only characters appearing outside $-fences on a content line.
+
+    ``%`` is excluded when the line is exactly %%PAGEBREAK%% (caller
+    handles that line form before reaching here).
+    """
+    outside, _inside, _balanced = split_math_fences(line)
+    hits = [c for c in outside if c in MATH_ONLY_CHARS]
+    if "%" in outside:
+        hits.append("%")
+    return sorted(set(hits))

imlx/cli.py

@@ -0,0 +1,109 @@
+"""
+imlx.cli
+========
+Command-line interface. Zero dependencies (argparse), mirroring the
+recovered iml-cli's verdict-first ergonomics.
+
+    imlx gate ARTIFACT [--decls FILE] [--json]
+    imlx run ARTIFACT [--decls FILE] [--trace OUT] [--trace-json OUT] [--json]
+    imlx version
+
+Exit code IS the verdict: 0 = PASS, 1 = FAIL, 2 = usage error.
+"""
+
+__version__ = "0.1.0"
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__ as pkg_version
+from .gate import gate_file, run_file
+
+
+def _print_gate(result, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(result.to_dict(), indent=2))
+        return
+    print(f"Layer 1: {result.layer1.bit}")
+    for r in result.layer1.reasons:
+        print(f"  {r.code}  line {r.line}: {r.message}")
+    if result.layer2 is None:
+        if not result.layer1.passed:
+            print("Layer 2: not attempted (Layer 1 failed; nothing runs, SPEC 13.5)")
+        else:
+            print("Layer 2: not attempted (no declaration source; artifact remains "
+                  "fully Layer 1-validatable alone, SPEC 5.2)")
+    else:
+        print(f"Layer 2: {result.layer2.bit}")
+        for r in result.layer2.reasons:
+            print(f"  {r.code}  line {r.line}: {r.message}")
+    print(f"VERDICT: {result.verdict}")
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="imlx",
+                                     description="IMLX gate and executor. One bit.")
+    sub = parser.add_subparsers(dest="cmd")
+
+    p_gate = sub.add_parser("gate", help="render the conformance verdict")
+    p_gate.add_argument("artifact")
+    p_gate.add_argument("--decls", help="external declaration file")
+    p_gate.add_argument("--json", action="store_true")
+
+    p_run = sub.add_parser("run", help="gate, then execute (skeleton mode)")
+    p_run.add_argument("artifact")
+    p_run.add_argument("--decls")
+    p_run.add_argument("--trace", help="write canonical IMLX trace to this path")
+    p_run.add_argument("--trace-json", help="write JSON trace projection to this path")
+    p_run.add_argument("--json", action="store_true")
+
+    sub.add_parser("version", help="print version")
+
+    args = parser.parse_args(argv)
+    if args.cmd == "version":
+        print(f"imlx {pkg_version} (SPEC v0.1)")
+        return 0
+    if args.cmd is None:
+        parser.print_help()
+        return 2
+
+    if not Path(args.artifact).is_file():
+        print(f"error: no such file: {args.artifact}", file=sys.stderr)
+        return 2
+
+    if args.cmd == "gate":
+        result = gate_file(args.artifact, args.decls)
+        _print_gate(result, args.json)
+        return 0 if result.verdict in ("PASS", "L1-PASS") else 1
+
+    if args.cmd == "run":
+        result, run_result = run_file(args.artifact, args.decls)
+        if run_result is None:
+            _print_gate(result, args.json)
+            return 1
+        if args.trace:
+            Path(args.trace).write_text(run_result.trace.render_imlx(), encoding="utf-8")
+        if args.trace_json:
+            Path(args.trace_json).write_text(run_result.trace.render_json(), encoding="utf-8")
+        if args.json:
+            out = {"verdict": run_result.verdict,
+                   "events": [e.to_dict() for e in run_result.trace.events]}
+            if run_result.failure:
+                out["failure"] = run_result.failure.to_dict()
+            print(json.dumps(out, indent=2))
+        else:
+            print(run_result.trace.render_imlx(), end="")
+            if run_result.failure:
+                f = run_result.failure
+                print(f"FAILURE RECORD: step {f.step} {f.opcode} {f.reason_code} "
+                      f"[{f.contract}]")
+            print(f"VERDICT: {run_result.verdict}")
+        return 0 if run_result.verdict == "PASS" else 1
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

imlx/declarations.py

@@ -0,0 +1,167 @@
+"""
+imlx.declarations
+=================
+The declaration resolver (SPEC Section 10). Populates the registries Layer 2
+validates against: block types (with capabilities), procedures, converters,
+registers, symbols, policy data.
+
+- Exactly one declaration source per artifact, named by the header pairing
+  line (10.2). External is canonical; INLINE is permitted.
+- A declaration file is itself an IMLX artifact (10.3): same parser, no
+  second format. It MUST pass Layer 1.
+- Duplicates fail the gate: L2-DUP01. No precedence, no overlay, no merge.
+
+L2-DEC01 ("malformed declaration table": unknown DECLARE kind or wrong
+column set) is ratified in SPEC Appendix C as of v0.1.0-rc.2 and ships
+here with its fixtures.
+"""
+
+__version__ = "0.1.0"
+
+from dataclasses import dataclass, field
+
+from . import charset as cs
+from .layer1 import Document, Reason, Table, Verdict, gate_layer1_bytes
+
+#: SPEC 10.4: registry kinds and their REQUIRED columns.
+REQUIRED_COLUMNS: dict[str, list[str]] = {
+    "TYPE": ["name", "capabilities"],
+    "PROCEDURE": ["name", "arity", "operand_schema"],
+    "CONVERTER": ["name", "from_type", "to_type"],
+    "REGISTER": ["name", "type"],
+    "SYMBOL": ["sigil_name", "target"],
+    "POLICY": ["name", "kind", "payload_ref"],
+}
+
+#: Capabilities defined by SPEC 8. The only sanctioned relaxation mechanism.
+KNOWN_CAPABILITIES = {"legal_lists", "-"}
+
+
+@dataclass
+class Registries:
+    """The declaration space in force for one artifact."""
+    types: dict[str, dict] = field(default_factory=dict)        # name -> {capabilities}
+    procedures: dict[str, dict] = field(default_factory=dict)   # name -> {arity, operand_schema}
+    converters: dict[str, dict] = field(default_factory=dict)   # name -> {from_type, to_type}
+    registers: dict[str, dict] = field(default_factory=dict)    # name -> {type}
+    symbols: dict[str, str] = field(default_factory=dict)       # sigil_name -> target
+    policies: dict[str, dict] = field(default_factory=dict)     # name -> {kind, payload_ref}
+    source_name: str = ""
+    source_version: str = ""
+
+    _KIND_MAP = {
+        "TYPE": ("types", "name"),
+        "PROCEDURE": ("procedures", "name"),
+        "CONVERTER": ("converters", "name"),
+        "REGISTER": ("registers", "name"),
+        "SYMBOL": ("symbols", "sigil_name"),
+        "POLICY": ("policies", "name"),
+    }
+
+    def type_capabilities(self, type_name: str) -> set[str]:
+        entry = self.types.get(type_name)
+        if not entry:
+            return set()
+        caps = entry.get("capabilities", "-")
+        return set() if caps == "-" else {c.strip() for c in caps.split(";")}
+
+
+def parse_declarations(doc: Document, reasons: list[Reason]) -> Registries:
+    """Build registries from a document's # DECLARE sections (SPEC 10.4).
+
+    Works identically for a declaration file and for an INLINE artifact's
+    own declaration section: one parser, no second format (SPEC 10.3).
+    """
+    regs = Registries()
+    for tbl in doc.declaration_tables:
+        _ingest_table(tbl, regs, reasons)
+    return regs
+
+
+def _ingest_table(tbl: Table, regs: Registries, reasons: list[Reason]) -> None:
+    kind = tbl.declare_kind or ""
+    required = REQUIRED_COLUMNS.get(kind)
+    if required is None:
+        reasons.append(Reason("L2-DEC01", tbl.start_line,
+                              f"unknown DECLARE kind '{kind}' (SPEC 10.4 enumerates "
+                              f"{sorted(REQUIRED_COLUMNS)})"))
+        return
+    if tbl.header_cells != required:
+        reasons.append(Reason("L2-DEC01", tbl.start_line,
+                              f"DECLARE {kind} requires columns {required}, "
+                              f"found {tbl.header_cells} (SPEC 10.4)"))
+        return
+
+    attr, key_col = Registries._KIND_MAP[kind]
+    store = getattr(regs, attr)
+    key_idx = required.index(key_col)
+
+    for cells, ln in zip(tbl.rows, tbl.row_lines):
+        name = cells[key_idx]
+        if name in store:
+            reasons.append(Reason("L2-DUP01", ln,
+                                  f"duplicate {kind} declaration '{name}' "
+                                  f"(SPEC 10.2: no precedence, no overlay, no merge)"))
+            continue
+        if kind == "SYMBOL":
+            store[name] = cells[required.index("target")]
+        else:
+            store[name] = {col: cells[idx] for idx, col in enumerate(required) if idx != key_idx}
+        # entry-shape checks decidable without other registries
+        if kind == "TYPE":
+            caps = store[name]["capabilities"]
+            unknown = {c.strip() for c in caps.split(";")} - KNOWN_CAPABILITIES
+            if caps != "-" and unknown:
+                reasons.append(Reason("L2-DEC01", ln,
+                                      f"unknown capability {sorted(unknown)} "
+                                      f"(SPEC 8 defines: legal_lists)"))
+        if kind == "PROCEDURE" and not store[name]["arity"].isdigit():
+            reasons.append(Reason("L2-DEC01", ln, "PROCEDURE arity must be a non-negative integer"))
+        if kind == "SYMBOL" and not cs.REFERENCE_RE.match("@" + name):
+            reasons.append(Reason("L2-DEC01", ln,
+                                  "sigil_name must be letters, digits, _, beginning "
+                                  "with a letter (SPEC 9)"))
+
+
+def load_external_source(path_bytes: bytes, file_name: str,
+                         expected_name: str, expected_version: str,
+                         reasons: list[Reason]) -> Registries | None:
+    """Load and verify an external declaration file (SPEC 5.2, 10.3).
+
+    The Layer 2 gate MUST verify that the declaration source it was given
+    matches the name and version the artifact demands (L2-PAIR01), and the
+    file itself MUST pass Layer 1.
+    """
+    verdict, decl_doc = gate_layer1_bytes(path_bytes, file_name)
+    if not verdict.passed:
+        reasons.append(Reason("L2-PAIR01", 0,
+                              f"declaration file '{file_name}' fails Layer 1 "
+                              f"({verdict.reasons[0].code} at its line "
+                              f"{verdict.reasons[0].line}); a declaration file MUST "
+                              f"pass Layer 1 like any artifact (SPEC 10.3)"))
+        return None
+
+    if file_name != expected_name:
+        reasons.append(Reason("L2-PAIR01", 2,
+                              f"artifact header pairs '{expected_name}' but was given "
+                              f"'{file_name}' (SPEC 5.2)"))
+        return None
+
+    if decl_doc.header.decl_mode != "INLINE" or decl_doc.header.file_decl_version is None:
+        reasons.append(Reason("L2-PAIR01", 0,
+                              f"'{file_name}' is not a declaration file: its DECLARATIONS "
+                              f"line must read INLINE and it must carry DECL_VERSION "
+                              f"(SPEC 10.3)"))
+        return None
+
+    if decl_doc.header.file_decl_version != expected_version:
+        reasons.append(Reason("L2-PAIR01", 2,
+                              f"artifact header demands version {expected_version}; "
+                              f"'{file_name}' declares DECL_VERSION "
+                              f"{decl_doc.header.file_decl_version} (SPEC 5.2)"))
+        return None
+
+    regs = parse_declarations(decl_doc, reasons)
+    regs.source_name = file_name
+    regs.source_version = decl_doc.header.file_decl_version
+    return regs

imlx/executor.py

@@ -0,0 +1,213 @@
+"""
+imlx.executor
+=============
+The execution model (SPEC 13). State is the register file; steps execute in
+step-number order; SLOT fills are sequential, never parallel.
+
+- Skeleton mode (13.3): runs every program end-to-end with no engine; each
+  SLOT renders a placeholder displaying its full contract. Fully
+  deterministic; no network, no credentials; the mode conformance tests
+  run in.
+- Engine mode (13.4): an engine adapter fills SLOTs; the paired GATE is
+  applied immediately to what returns. The engine is outside the guarantee
+  boundary.
+- Failure semantics (13.5): a runtime GATE FAIL halts at that step with
+  verdict FAIL and a failure record (step, opcode, reason code, violated
+  contract). A conforming executor MUST NOT retry internally.
+
+SKELETON DIGEST CANON (SPEC 13.6, ratified v0.1.0-rc.2): the
+content of a skeleton-mode binding is defined as the canonical string
+``SKELETON|<step>|<opcode>|<operand>|<bind>`` (UTF-8). SPEC 13.6 requires
+byte-identical skeleton traces across implementations, which requires the
+digested content to be canonically defined; this string is that definition,
+ratified, and the trace fixtures pin it.
+"""
+
+__version__ = "0.1.0"
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from . import charset as cs
+from .declarations import Registries
+from .layer1 import Document
+from .layer2 import parse_steps, Step, SLOT_CONTRACT_KEYS
+from .trace import Trace, sha256_hex
+
+#: Engine adapter: contract dict -> payload string.
+EngineAdapter = Callable[[dict], str]
+
+
+@dataclass
+class FailureRecord:
+    """SPEC 13.5: step number, opcode, reason code, violated contract."""
+    step: int
+    opcode: str
+    reason_code: str
+    contract: str
+
+    def to_dict(self) -> dict:
+        return {"step": self.step, "opcode": self.opcode,
+                "reason_code": self.reason_code, "contract": self.contract}
+
+
+@dataclass
+class RunResult:
+    verdict: str  # PASS | FAIL
+    trace: Trace
+    registers: dict[str, str] = field(default_factory=dict)
+    failure: FailureRecord | None = None
+    outputs: list[tuple[str, str]] = field(default_factory=list)  # (type, content)
+
+
+def skeleton_content(st: Step) -> str:
+    """Canonical skeleton-mode binding content (module docstring)."""
+    return f"SKELETON|{st.number}|{st.opcode}|{st.operand}|{st.bind}"
+
+
+def slot_placeholder(contract: dict) -> str:
+    """SPEC 13.3: a placeholder displaying the SLOT's full contract."""
+    body = "; ".join(f"{k}={contract[k]}" for k in sorted(contract))
+    return f"[SLOT UNFILLED: {body}]"
+
+
+def parse_contract(operand: str) -> dict:
+    kv = {}
+    for p in (x.strip() for x in operand.split(";")):
+        if "=" in p:
+            k, v = p.split("=", 1)
+            kv[k] = v
+    return kv
+
+
+def run(doc: Document, registries: Registries,
+        engine: EngineAdapter | None = None,
+        policy_payloads: dict[str, list[str]] | None = None) -> RunResult:
+    """Execute a Layer 1- and Layer 2-passed document (SPEC 13).
+
+    ``policy_payloads`` supplies blocklist policy data (Law 6): a mapping
+    from POLICY name to its list of forbidden substrings. Policy is data
+    given to the gate, never spec or code content.
+    """
+    trace = Trace(doc.name)
+    trace.emit("GATE_L1", "-", "-", doc.name, "PASS")
+    l2_subject = (f"{registries.source_name}; {registries.source_version}"
+                  if registries.source_name else "INLINE")
+    trace.emit("GATE_L2", "-", "-", l2_subject, "PASS")
+
+    steps = parse_steps(doc)
+    registers: dict[str, str] = {}
+    slot_contracts: dict[str, dict] = {}
+    slot_payloads: dict[str, str] = {}
+    policy_payloads = policy_payloads or {}
+
+    for st in steps:
+        s = str(st.number)
+
+        if st.opcode == "SLOT":
+            contract = parse_contract(st.operand)
+            trace.emit("SLOT_OPEN", s, "SLOT", f"type={contract.get('type', '-')}", "DONE")
+            if engine is None:
+                registers[st.bind] = slot_placeholder(contract)
+                slot_contracts[st.bind] = contract
+                trace.emit("SLOT_FILL", s, "SLOT", st.bind, "SKELETON")
+            else:
+                payload = engine(contract)  # sequential, program order (13.2)
+                registers[st.bind] = payload
+                slot_contracts[st.bind] = contract
+                slot_payloads[st.bind] = payload
+                trace.emit("SLOT_FILL", s, "SLOT", st.bind, "FILLED",
+                           sha256_hex(payload))
+            continue
+
+        if st.opcode == "GATE":
+            target = st.operand.strip()
+            contract = slot_contracts.get(target, {})
+            if target in slot_payloads:  # engine mode: gate what returned
+                verdict, code = _gate_slot_payload(
+                    slot_payloads[target], contract, registries, policy_payloads)
+            else:  # skeleton fill: the placeholder is the deterministic pass
+                verdict, code = "PASS", ""
+            trace.emit("GATE_VERDICT", s, "GATE", target, verdict)
+            if st.bind != "-":
+                registers[st.bind] = verdict
+            if verdict == "FAIL":
+                trace.emit("HALT", s, "-", doc.name, "FAIL")
+                return RunResult(
+                    verdict="FAIL", trace=trace, registers=registers,
+                    failure=FailureRecord(step=st.number, opcode="GATE",
+                                          reason_code=code,
+                                          contract="; ".join(
+                                              f"{k}={contract[k]}"
+                                              for k in sorted(contract))))
+            continue
+
+        if st.opcode == "OUTPUT_PRINT":
+            target = st.operand.strip()
+            trace.emit("STEP", s, st.opcode, target, "DONE")
+            continue
+
+        # all other opcodes: deterministic step; binding opcodes emit BIND
+        subject = st.bind if st.bind != "-" else st.operand
+        trace.emit("STEP", s, st.opcode, subject, "DONE")
+        bind_name = st.bind if st.bind != "-" else None
+        if bind_name:
+            content = skeleton_content(st) if engine is None else \
+                _engine_mode_binding_content(st, registers)
+            registers[bind_name] = content
+            trace.emit("BIND", s, st.opcode, bind_name, "BOUND", sha256_hex(content))
+
+    # collect outputs after a completed run
+    outputs = [(st.style, registers.get(st.operand.strip(), ""))
+               for st in steps if st.opcode == "OUTPUT_PRINT"]
+
+    last = str(steps[-1].number) if steps else "-"
+    trace.emit("HALT", last, "-", doc.name, "PASS")
+    return RunResult(verdict="PASS", trace=trace, registers=registers,
+                     outputs=outputs)
+
+
+def _engine_mode_binding_content(st: Step, registers: dict[str, str]) -> str:
+    """Deterministic data-opcode semantics shared by both modes.
+
+    Phase 1 executes data opcodes symbolically: the binding's content is the
+    canonical step description. Real corpus-backed LOAD/QUERY semantics are
+    toolchain integrations layered on later; the trace interface does not
+    change. In engine mode the SLOT is the only moving part (SPEC 13.6).
+    """
+    return skeleton_content(st)
+
+
+# ---------------------------------------------------------------------------
+# The runtime GATE on a SLOT payload (SPEC 13.4, 11.2)
+# ---------------------------------------------------------------------------
+
+def _gate_slot_payload(payload: str, contract: dict, regs: Registries,
+                       policy_payloads: dict[str, list[str]]) -> tuple[str, str]:
+    """One-bit verdict on an engine payload: charset law + blocklist policy.
+
+    The charset law is always in force on what returns; the blocklist is
+    the policy data the contract names (Law 6). RT-GATE01 on FAIL.
+    """
+    # charset law: every payload line must satisfy content-space rules
+    for line in payload.split("\n"):
+        if line == "":
+            continue
+        if cs.illegal_content_chars(line):
+            return "FAIL", "RT-GATE01"
+        bare = cs.bare_math_chars_outside_fences(line)
+        if bare:
+            return "FAIL", "RT-GATE01"
+        if "@" in line:
+            return "FAIL", "RT-GATE01"
+
+    # blocklist policy
+    ref = contract.get("blocklist", "")
+    policy_name = ref[1:] if ref.startswith("@") else ref
+    target = regs.symbols.get(policy_name, policy_name)
+    blocked = policy_payloads.get(policy_name) or policy_payloads.get(target) or []
+    for term in blocked:
+        if term and term in payload:
+            return "FAIL", "RT-GATE01"
+
+    return "PASS", ""