imlx-gate 0.1.0__tar.gz

imlx_gate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Passert Professional Education Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imlx_gate-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: imlx-gate
+Version: 0.1.0
+Summary: IMLX: Invariant Markup Language (eXtended). Deterministic input contracts: a binary conformance gate, a total 21-opcode executor, and byte-identical execution traces.
+Author: Passert
+License: MIT
+Project-URL: Repository, https://github.com/passert-ai/imlx
+Keywords: determinism,markup,validation,gate,llm,pipeline
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# imlx
+
+Reference implementation of **IMLX: Invariant Markup Language (eXtended)** —
+a plain-text format so constrained that a small deterministic program can
+verify conformance completely and answer with a single bit.
+
+The model produces; the gate decides.
+
+- **Binary gate** — PASS or FAIL, per layer. No warnings, no partial
+  acceptance, no quirks mode.
+- **Closed alphabet** — anything not enumerated is forbidden by
+  construction. Validation is membership testing.
+- **21 opcodes, zero judgment** — every opcode is a computable function or
+  a decidable predicate. Semantic production happens inside a SLOT, outside
+  the language boundary, and the GATE decides what comes back.
+- **Total execution** — every program provably halts before it runs.
+- **Byte-identical traces** — a run's complete event log is itself a gated
+  IMLX document, byte-identical across runs and implementations in
+  skeleton mode. Proofs you can diff, animate, and audit.
+
+## Install
+
+    pip install imlx-gate
+
+Zero runtime dependencies. The distribution is `imlx-gate`; the import
+and the command are both `imlx`:
+
+    import imlx
+
+## Use
+
+    imlx gate artifact.imlx --decls decls.imlx     # verdict; exit code is the bit
+    imlx run artifact.imlx --trace out.trace.imlx  # gate, execute, emit the trace
+    imlx run artifact.imlx --trace-json out.json   # 1:1 JSON projection
+
+Python API:
+
+    from imlx import gate_file, run_file
+    result = gate_file("artifact.imlx", "decls.imlx")
+    result.verdict            # "PASS" | "FAIL" | "L1-PASS"
+    _, run_result = run_file("artifact.imlx", "decls.imlx")
+    run_result.trace.render_imlx()
+
+## Conformance
+
+The spec is normative; no implementation is. `tests/conformance` and
+`tests/adversarial` carry the fixture corpus: required verdicts, required
+reason codes, and pinned byte-exact traces. Matching the corpus is what
+conformance means. Divergence is a bug in at least one implementation —
+falsify this.
+
+Spec: SPEC.md v0.1 — github.com/passert-ai/imlx. License: MIT.

imlx_gate-0.1.0/README.md

@@ -0,0 +1,52 @@
+# imlx
+
+Reference implementation of **IMLX: Invariant Markup Language (eXtended)** —
+a plain-text format so constrained that a small deterministic program can
+verify conformance completely and answer with a single bit.
+
+The model produces; the gate decides.
+
+- **Binary gate** — PASS or FAIL, per layer. No warnings, no partial
+  acceptance, no quirks mode.
+- **Closed alphabet** — anything not enumerated is forbidden by
+  construction. Validation is membership testing.
+- **21 opcodes, zero judgment** — every opcode is a computable function or
+  a decidable predicate. Semantic production happens inside a SLOT, outside
+  the language boundary, and the GATE decides what comes back.
+- **Total execution** — every program provably halts before it runs.
+- **Byte-identical traces** — a run's complete event log is itself a gated
+  IMLX document, byte-identical across runs and implementations in
+  skeleton mode. Proofs you can diff, animate, and audit.
+
+## Install
+
+    pip install imlx-gate
+
+Zero runtime dependencies. The distribution is `imlx-gate`; the import
+and the command are both `imlx`:
+
+    import imlx
+
+## Use
+
+    imlx gate artifact.imlx --decls decls.imlx     # verdict; exit code is the bit
+    imlx run artifact.imlx --trace out.trace.imlx  # gate, execute, emit the trace
+    imlx run artifact.imlx --trace-json out.json   # 1:1 JSON projection
+
+Python API:
+
+    from imlx import gate_file, run_file
+    result = gate_file("artifact.imlx", "decls.imlx")
+    result.verdict            # "PASS" | "FAIL" | "L1-PASS"
+    _, run_result = run_file("artifact.imlx", "decls.imlx")
+    run_result.trace.render_imlx()
+
+## Conformance
+
+The spec is normative; no implementation is. `tests/conformance` and
+`tests/adversarial` carry the fixture corpus: required verdicts, required
+reason codes, and pinned byte-exact traces. Matching the corpus is what
+conformance means. Divergence is a bug in at least one implementation —
+falsify this.
+
+Spec: SPEC.md v0.1 — github.com/passert-ai/imlx. License: MIT.

imlx_gate-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "imlx-gate"
+version = "0.1.0"
+description = "IMLX: Invariant Markup Language (eXtended). Deterministic input contracts: a binary conformance gate, a total 21-opcode executor, and byte-identical execution traces."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Passert" }]
+keywords = ["determinism", "markup", "validation", "gate", "llm", "pipeline"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Markup",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+imlx = "imlx.cli:main"
+
+[project.urls]
+Repository = "https://github.com/passert-ai/imlx"
+
+[tool.setuptools.packages.find]
+where = ["src"]

imlx_gate-0.1.0/setup.cfg

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

imlx_gate-0.1.0/src/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_gate-0.1.0/src/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_gate-0.1.0/src/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_gate-0.1.0/src/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