pairl 1.5.0__py3-none-any.whl

pairl/__init__.py

@@ -0,0 +1,27 @@
+"""PAIRL v1.5 reference implementation: parser, validator, canonicalizer, renderer."""
+
+from .core import (
+    SPEC_VERSION,
+    ColumnarBlock,
+    Message,
+    Record,
+    parse,
+)
+from .canonical import canonicalize, compute_hash, hash_ref, serialize_record
+from .render import render
+from .validate import Result, validate
+
+__all__ = [
+    "SPEC_VERSION",
+    "Message",
+    "Record",
+    "ColumnarBlock",
+    "parse",
+    "validate",
+    "Result",
+    "canonicalize",
+    "serialize_record",
+    "compute_hash",
+    "hash_ref",
+    "render",
+]

pairl/__main__.py

@@ -0,0 +1,56 @@
+"""CLI: python -m pairl <validate|render|hash> [--strict] <file.pairl>"""
+
+from __future__ import annotations
+
+import sys
+
+from . import canonicalize, compute_hash, parse, render, validate
+
+
+def _usage() -> int:
+    print("usage: python -m pairl <validate|render|hash|canon> [--strict] <file.pairl>")
+    return 2
+
+
+def main(argv: list[str]) -> int:
+    args = argv[1:]
+    if len(args) < 2:
+        return _usage()
+    cmd = args[0]
+    strict = "--strict" in args
+    files = [a for a in args[1:] if not a.startswith("-")]
+    if not files:
+        return _usage()
+    path = files[0]
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+    except OSError as e:
+        print(f"error: {e}")
+        return 2
+
+    msg = parse(text)
+
+    if cmd == "validate":
+        res = validate(msg, strict=strict)
+        for e in res.errors:
+            print(f"  ✗ {e}")
+        for w in res.warnings:
+            print(f"  ⚠ {w}")
+        print(f"{'✓ PASSED' if res.valid else '✗ FAILED'} — {path}")
+        return 0 if res.valid else 1
+    if cmd == "render":
+        sys.stdout.write(render(msg))
+        return 0
+    if cmd == "hash":
+        print(f"ref:hash:sha256:{compute_hash(msg)}")
+        return 0
+    if cmd == "canon":
+        sys.stdout.write(canonicalize(msg, for_hash=not strict))
+        return 0
+    return _usage()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

pairl/canonical.py

@@ -0,0 +1,77 @@
+"""Canonicalization and hashing (SPEC §9).
+
+Columnar blocks are expanded to `#type key=value` records before
+canonicalization (§9.4a), so a message hashes identically in either form.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from .core import Message, Record
+
+# Canonical header order (§9.1). Unknown headers are appended, sorted.
+_HEADER_ORDER = ["v", "id", "mid", "sid", "ts", "p", "parent", "root", "deps", "budget", "quota"]
+_ATOM_OK = set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789:._/@+-")
+
+
+def _needs_quote(v: str) -> bool:
+    return v == "" or any(c not in _ATOM_OK for c in v)
+
+
+def _fmt_value(v: str) -> str:
+    if _needs_quote(v):
+        return '"' + v.replace('"', '\\"') + '"'
+    return v
+
+
+def serialize_record(r: Record) -> str:
+    if r.kind == "marker":
+        if r.parent is not None:  # verbose #msg
+            return f"#msg {r.name} r={r.role} parent={r.parent}"
+        return f"#{r.name}"
+
+    if r.kind == "intent":
+        params = ",".join(f"{k}={_fmt_value(v)}" for k, v in r.kv.items())
+        head = f"{r.name}{{{params}}}" if r.kv or True else r.name
+    else:
+        pairs = " ".join(f"{k}={_fmt_value(v)}" for k, v in r.kv.items())
+        head = f"#{r.name} {pairs}".rstrip()
+
+    trail = ""
+    if r.m:
+        trail += f" @m={r.m}"
+    if r.rid:
+        trail += f" @rid={r.rid}"
+    return head + trail
+
+
+def canonicalize(msg: Message, *, for_hash: bool = True) -> str:
+    """Produce the canonical text. With for_hash, @hash is omitted (§9.6)."""
+    lines: list[str] = []
+    keys = list(msg.headers.keys())
+    ordered = [k for k in _HEADER_ORDER if k in msg.headers]
+    ordered += sorted(k for k in keys if k not in _HEADER_ORDER and k != "hash")
+    if not for_hash and "hash" in msg.headers:
+        ordered.append("hash")
+    for k in ordered:
+        lines.append(f"@{k} {msg.headers[k]}")
+
+    lines.append("")  # blank line separating header block from body
+
+    # Records already include columnar rows expanded into Record objects (§9.4a),
+    # so iterating msg.records yields the canonical, expanded body.
+    for r in msg.records:
+        lines.append(serialize_record(r))
+
+    return "\n".join(lines) + "\n"
+
+
+def compute_hash(msg: Message) -> str:
+    canon = canonicalize(msg, for_hash=True)
+    digest = hashlib.sha256(canon.encode("utf-8")).hexdigest()
+    return digest
+
+
+def hash_ref(msg: Message) -> str:
+    return f"ref:hash:sha256:{compute_hash(msg)}"

pairl/core.py

@@ -0,0 +1,250 @@
+"""PAIRL v1.5 data model and parser.
+
+Parses a PAIRL message (headers + body records) into a typed AST, including
+v1.3 turn markers, v1.4 short references, and v1.5 columnar record blocks.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+SPEC_VERSION = "1.5"
+
+# Record types whose key schema is fixed (columnar-eligible). #fact/#ref have a
+# variable key (the key is data) and are not columnar.
+FIXED_SCHEMA_TYPES = {"evid", "rule", "cost", "quota", "call", "ret", "think", "edit"}
+COLUMNAR_FORBIDDEN = {"fact", "ref"}
+
+_COL_HEADER = re.compile(r"^#([a-z][a-z0-9_]*)\[([^\]]*)\]$")
+_COMPACT_MARKER = re.compile(r"^#([uas])([0-9]{1,7})$")
+_MSG_MARKER = re.compile(r"^#msg\s+(\S+)\s+r=(\S+)\s+parent=(\S+)\s*$")
+_INTENT = re.compile(r"^([a-z0-9]{2,4}|[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+)(\{.*\})?(\s+@.*)?$")
+_TRAILING_TAG = re.compile(r"@(m|rid)=([^\s]+)")
+
+
+@dataclass
+class Record:
+    """A single body record (or a columnar row expanded to a record)."""
+
+    kind: str                      # fact, ref, evid, rule, cost, quota, call, ret, think, edit, s, intent, marker
+    name: Optional[str] = None     # intent name; record type tag; marker id
+    kv: dict[str, str] = field(default_factory=dict)
+    rid: Optional[str] = None
+    m: Optional[str] = None        # @m= turn binding
+    raw: str = ""
+    from_columnar: bool = False
+    # marker-specific
+    role: Optional[str] = None
+    parent: Optional[str] = None
+
+
+@dataclass
+class ColumnarBlock:
+    rtype: str
+    columns: list[str]
+    rows: list[list[tuple[str, bool]]]  # each row: list of (value, was_quoted)
+    raw_header: str = ""
+
+
+@dataclass
+class Message:
+    headers: dict[str, str] = field(default_factory=dict)
+    records: list[Record] = field(default_factory=list)
+    blocks: list[ColumnarBlock] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)  # parse-level errors
+
+    @property
+    def msg_id(self) -> Optional[str]:
+        return self.headers.get("id") or self.headers.get("mid")
+
+
+def split_fields(s: str) -> list[tuple[str, bool]]:
+    """Tokenize a whitespace-separated row into (value, was_quoted) fields.
+
+    A double-quoted field (with \\" escaping) is one field and may contain spaces.
+    """
+    out: list[tuple[str, bool]] = []
+    i, n = 0, len(s)
+    while i < n:
+        if s[i] == " ":
+            i += 1
+            continue
+        if s[i] == '"':
+            i += 1
+            buf: list[str] = []
+            while i < n:
+                if s[i] == "\\" and i + 1 < n and s[i + 1] == '"':
+                    buf.append('"')
+                    i += 2
+                    continue
+                if s[i] == '"':
+                    i += 1
+                    break
+                buf.append(s[i])
+                i += 1
+            out.append(("".join(buf), True))
+        else:
+            start = i
+            while i < n and s[i] != " ":
+                i += 1
+            out.append((s[start:i], False))
+    return out
+
+
+def _parse_kvpairs(s: str) -> dict[str, str]:
+    """Parse `key=value` pairs (space- or comma-separated), respecting quotes."""
+    kv: dict[str, str] = {}
+    i, n = 0, len(s)
+    while i < n:
+        if s[i] in " ,":
+            i += 1
+            continue
+        # key
+        kstart = i
+        while i < n and s[i] not in "=":
+            if s[i] in " ,":
+                break
+            i += 1
+        key = s[kstart:i]
+        if i >= n or s[i] != "=":
+            # bare token, skip
+            continue
+        i += 1  # skip '='
+        # value: quoted or atom up to space/comma
+        if i < n and s[i] == '"':
+            i += 1
+            buf: list[str] = []
+            while i < n:
+                if s[i] == "\\" and i + 1 < n and s[i + 1] == '"':
+                    buf.append('"')
+                    i += 2
+                    continue
+                if s[i] == '"':
+                    i += 1
+                    break
+                buf.append(s[i])
+                i += 1
+            kv[key] = "".join(buf)
+        else:
+            vstart = i
+            while i < n and s[i] not in " ,":
+                i += 1
+            kv[key] = s[vstart:i]
+    return kv
+
+
+def _strip_trailing_tags(line: str) -> tuple[str, Optional[str], Optional[str]]:
+    """Return (line_without_tags, m, rid)."""
+    m_val = rid_val = None
+    # iteratively peel trailing @m=/@rid= tokens
+    while True:
+        mt = re.search(r"\s+@(m|rid)=([^\s]+)\s*$", line)
+        if not mt:
+            break
+        if mt.group(1) == "rid":
+            rid_val = mt.group(2)
+        else:
+            m_val = mt.group(2)
+        line = line[: mt.start()]
+    return line.rstrip(), m_val, rid_val
+
+
+def parse(text: str) -> Message:
+    msg = Message()
+    parts = text.strip("\n").split("\n\n", 1)
+    if len(parts) != 2:
+        # tolerate header-only or body-only, but record an error
+        msg.errors.append("message must have a header block and a body separated by a blank line")
+        if not parts:
+            return msg
+        # treat the single part as headers if it looks like headers, else body
+        single = parts[0]
+        if single.lstrip().startswith("@"):
+            header_part, body_part = single, ""
+        else:
+            header_part, body_part = "", single
+    else:
+        header_part, body_part = parts
+
+    for line in header_part.split("\n"):
+        line = line.strip()
+        if not line:
+            continue
+        if not line.startswith("@"):
+            msg.errors.append(f"invalid header line (must start with @): {line}")
+            continue
+        m = re.match(r"@(\w+)\s+(.+)$", line)
+        if m:
+            msg.headers[m.group(1)] = m.group(2).strip()
+        else:
+            msg.errors.append(f"malformed header: {line}")
+
+    lines = [ln.rstrip() for ln in body_part.split("\n")]
+    i = 0
+    while i < len(lines):
+        line = lines[i].strip()
+        if not line or line == "---":
+            i += 1
+            continue
+
+        hm = _COL_HEADER.match(line)
+        if hm:
+            rtype = hm.group(1)
+            cols = [c.strip() for c in hm.group(2).split(",")]
+            rows: list[list[tuple[str, bool]]] = []
+            i += 1
+            while i < len(lines):
+                row = lines[i].strip()
+                if not row or row.startswith("#") or row == "---":
+                    break
+                fields, mval, ridval = _strip_trailing_tags(row)
+                cells = split_fields(fields)
+                rows.append(cells)
+                rec = Record(kind=rtype, name=rtype, from_columnar=True, raw=lines[i],
+                             rid=ridval, m=mval)
+                for col, (val, _q) in zip(cols, cells):
+                    rec.kv[col] = val
+                msg.records.append(rec)
+                i += 1
+            msg.blocks.append(ColumnarBlock(rtype=rtype, columns=cols, rows=rows, raw_header=line))
+            continue
+
+        msg.records.append(_parse_record(line))
+        i += 1
+
+    return msg
+
+
+def _parse_record(line: str) -> Record:
+    raw = line
+    cm = _COMPACT_MARKER.match(line)
+    if cm:
+        return Record(kind="marker", name=f"{cm.group(1)}{cm.group(2)}",
+                      role=cm.group(1), raw=raw)
+    mm = _MSG_MARKER.match(line)
+    if mm:
+        return Record(kind="marker", name=mm.group(1), role=mm.group(2),
+                      parent=mm.group(3), raw=raw)
+
+    body, mval, ridval = _strip_trailing_tags(line)
+
+    if body.startswith("#"):
+        mtype = re.match(r"^#([a-z][a-z0-9_]*)\s*(.*)$", body, re.DOTALL)
+        if mtype:
+            tag, rest = mtype.group(1), mtype.group(2)
+            return Record(kind=tag, name=tag, kv=_parse_kvpairs(rest),
+                          rid=ridval, m=mval, raw=raw)
+
+    # intent: name{params}
+    im = _INTENT.match(body)
+    if im:
+        name = im.group(1)
+        params = {}
+        if im.group(2):
+            inner = im.group(2)[1:-1]
+            params = _parse_kvpairs(inner)
+        return Record(kind="intent", name=name, kv=params, rid=ridval, m=mval, raw=raw)
+
+    return Record(kind="unknown", raw=raw, rid=ridval, m=mval)

pairl/render.py

@@ -0,0 +1,105 @@
+"""Deterministic PAIRL -> human-readable renderer.
+
+This is a faithful, template-based rendering (no LLM): it never invents facts
+and reproduces all #fact/#evid values verbatim (SPEC §12). For fluent natural
+language, feed the message to an LLM renderer instead.
+"""
+
+from __future__ import annotations
+
+from .core import Message, Record
+
+_INTENT_LABELS = {
+    "req": "Request", "qst": "Question", "ack": "Acknowledgement", "pln": "Plan",
+    "nxt": "Next action", "sum": "Summary", "upd": "Status update", "fin": "Done",
+    "blk": "Blocked", "ctx": "Context", "fnd": "Findings", "evl": "Assessment",
+    "cmp": "Comparison", "lst": "List", "def": "Clarification", "wrn": "Warning",
+    "agr": "Agreement", "dis": "Disagreement", "alt": "Alternative", "emf": "Emphasis",
+    "cnt": "Contrast", "rpt": "Report (unconfirmed)", "off": "Official", "inc": "Incident",
+    "apx": "Apology", "thx": "Thanks", "grt": "Greeting", "cls": "Closing", "bid": "Cost proposal",
+}
+_ROLE = {"u": "User", "a": "Assistant", "s": "System"}
+
+
+def render(msg: Message) -> str:
+    out: list[str] = []
+    mid = msg.msg_id or "(no id)"
+    out.append(f"# PAIRL message {mid}")
+    meta = []
+    if msg.headers.get("ts"):
+        meta.append(f"time {msg.headers['ts']}")
+    if msg.headers.get("p"):
+        meta.append(f"in reply to {msg.headers['p']}")
+    if msg.headers.get("budget"):
+        meta.append(f"budget {msg.headers['budget']}")
+    if meta:
+        out.append("_" + " · ".join(meta) + "_")
+    out.append("")
+
+    current_turn = None
+    for r in msg.records:
+        if r.kind == "marker":
+            current_turn = r
+            speaker = _ROLE.get(r.role or "", r.role or "?")
+            out.append(f"## {speaker} ({r.name})")
+            continue
+        line = _render_record(r)
+        if line:
+            out.append(line)
+
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _render_record(r: Record) -> str:
+    if r.kind == "intent":
+        label = _INTENT_LABELS.get(r.name or "", (r.name or "intent"))
+        topic = r.kv.get("t")
+        s = f"- **{label}**"
+        if topic:
+            s += f": {topic.replace('_', ' ')}"
+        mood = r.kv.get("m")
+        if mood == "!":
+            s += " (urgent)"
+        return s
+    if r.kind == "fact":
+        return "  - " + "; ".join(f"{k} = {v}" for k, v in r.kv.items())
+    if r.kind == "evid":
+        claim = r.kv.get("claim", "")
+        src = r.kv.get("src", "?")
+        conf = r.kv.get("conf", "?")
+        try:
+            conf = f"{float(conf) * 100:.0f}%"
+        except ValueError:
+            pass
+        return f'  - Evidence: "{claim}" — source {src}, confidence {conf}'
+    if r.kind == "ref":
+        return "  - Reference: " + "; ".join(f"{k} → {v}" for k, v in r.kv.items())
+    if r.kind == "rule":
+        return "  - Rule: " + ", ".join(f"{k}={v}" for k, v in r.kv.items())
+    if r.kind == "cost":
+        val = r.kv.get("val", "?")
+        cur = r.kv.get("cur", "")
+        extra = f" ({r.kv['model']})" if r.kv.get("model") else ""
+        return f"  - Cost: {val} {cur}{extra}".rstrip()
+    if r.kind == "quota":
+        t = r.kv.get("type", "?")
+        used = r.kv.get("used")
+        total = r.kv.get("total")
+        rem = r.kv.get("rem")
+        bits = [f"{t}"]
+        if used and total:
+            bits.append(f"used {used}/{total}")
+        if rem:
+            bits.append(f"{rem} remaining")
+        return "  - Quota: " + ", ".join(bits)
+    if r.kind == "call":
+        return f"  - Tool call: {r.kv.get('tool', '?')}"
+    if r.kind == "ret":
+        return f"  - Tool result ({r.kv.get('status', '?')})"
+    if r.kind == "think":
+        return f"  - Reasoning: {r.kv.get('summary', '')}"
+    if r.kind == "edit":
+        return f"  - Edit: {r.kv.get('file', '?')} ({r.kv.get('changes', '?')} changes)"
+    if r.kind == "s":
+        return None
+    return None

pairl/validate.py

@@ -0,0 +1,206 @@
+"""PAIRL v1.5 validation rules (V1–V12) operating on a parsed Message."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .core import COLUMNAR_FORBIDDEN, Message, split_fields
+
+_REF = re.compile(r"^ref:[A-Za-z0-9_-]+:[^\s]+$")
+_SLOC = re.compile(r"^@[A-Za-z0-9]{1,8}(?:#[A-Za-z0-9_-]{1,8})?$")
+_BARE_DEP = re.compile(r"^[A-Za-z0-9]{1,8}(?:#[A-Za-z0-9_-]{1,8})?$")
+_BUDGET = re.compile(r"^([0-9]+(?:\.[0-9]+)?)([A-Za-z]{1,16})$")
+_NUMERIC_INTENT_KEYS = {"l", "m"}
+
+
+def is_valid_ref(v: str) -> bool:
+    if not v.startswith("ref:") or " " in v:
+        return False
+    main = v.split("#", 1)[0]
+    return len(main.split(":")) >= 3 and bool(_REF.match(main))
+
+
+def is_sloc_ref(v: str) -> bool:
+    return bool(_SLOC.match(v))
+
+
+@dataclass
+class Result:
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def valid(self) -> bool:
+        return not self.errors
+
+
+def validate(msg: Message, strict: bool = False) -> Result:
+    res = Result()
+    res.errors.extend(msg.errors)
+
+    # Required headers
+    for h in ("v", "ts"):
+        if h not in msg.headers:
+            res.errors.append(f"missing required header: @{h}")
+    if "id" not in msg.headers and "mid" not in msg.headers:
+        res.errors.append("missing required header: @id (or legacy @mid)")
+
+    _v1_no_new_facts(msg, res, strict)
+    _v2_evidence(msg, res)
+    _v3_refs(msg, res)
+    _v6_rid_unique(msg, res)
+    _v8_budget(msg, res)
+    _v9_tool_chain(msg, res, strict)
+    _v11_turn_markers(msg, res)
+    _v12_columnar(msg, res)
+    return res
+
+
+def _has_rule(msg: Message, name: str) -> bool:
+    return any(r.kind == "rule" and r.kv.get(name) == "true" for r in msg.records)
+
+
+def _v1_no_new_facts(msg: Message, res: Result, strict: bool) -> None:
+    enforce = strict and _has_rule(msg, "no_new_facts")
+    for r in msg.records:
+        if r.kind != "intent":
+            continue
+        for k, v in r.kv.items():
+            if re.search(r"https?://", v):
+                _emit(res, enforce, f"V1: intent param '{k}' has a URL (move to #ref): {v}")
+            elif re.search(r"[a-fA-F0-9]{12,}", v):
+                _emit(res, enforce, f"V1: intent param '{k}' looks like a hash (move to #ref): {v}")
+            elif k not in _NUMERIC_INTENT_KEYS and re.search(r"\d", v):
+                _emit(res, enforce, f"V1: intent param '{k}' has a number (consider #fact): {k}={v}")
+
+
+def _v2_evidence(msg: Message, res: Result) -> None:
+    for r in msg.records:
+        if r.kind != "evid":
+            continue
+        missing = [k for k in ("claim", "src", "conf") if k not in r.kv]
+        if missing:
+            res.errors.append(f"V2: #evid missing {', '.join(missing)}: {r.raw}")
+            continue
+        try:
+            c = float(r.kv["conf"])
+            if not (0.0 <= c <= 1.0):
+                res.errors.append(f"V2: #evid conf must be in [0,1]: {r.raw}")
+        except ValueError:
+            res.errors.append(f"V2: #evid conf is not a number: {r.raw}")
+
+
+def _v3_refs(msg: Message, res: Result) -> None:
+    for r in msg.records:
+        if r.kind == "ref":
+            for v in r.kv.values():
+                if not (is_valid_ref(v) or is_sloc_ref(v)):
+                    res.errors.append(f"V3: invalid ref format: {v}")
+    deps = msg.headers.get("deps")
+    if deps:
+        for d in deps.split(","):
+            d = d.strip()
+            if not d or not (is_valid_ref(d) or is_sloc_ref(d) or _BARE_DEP.match(d)):
+                res.errors.append(f"V3: invalid @deps entry: {d!r}")
+    for k in ("p", "root", "parent"):
+        v = msg.headers.get(k)
+        if v and v.startswith("ref:") and not is_valid_ref(v):
+            res.errors.append(f"V3: invalid ref in @{k}: {v}")
+
+
+def _v6_rid_unique(msg: Message, res: Result) -> None:
+    seen: set[str] = set()
+    for r in msg.records:
+        if r.rid:
+            low = r.rid.lower()
+            if low in seen:
+                res.errors.append(f"V6: duplicate @rid: {r.rid}")
+            seen.add(low)
+
+
+def _v8_budget(msg: Message, res: Result) -> None:
+    b = msg.headers.get("budget")
+    if not b:
+        return
+    bm = _BUDGET.match(b)
+    if not bm:
+        res.errors.append(f"V8: invalid @budget format: {b}")
+        return
+    limit, cur = float(bm.group(1)), bm.group(2)
+    total = 0.0
+    for r in msg.records:
+        if r.kind == "cost" and r.kv.get("cur") == cur:
+            try:
+                total += float(r.kv.get("val", "0"))
+            except ValueError:
+                pass
+    if total > limit:
+        res.errors.append(f"V8: total cost {total} {cur} exceeds budget {limit} {cur}")
+
+
+def _v9_tool_chain(msg: Message, res: Result, strict: bool) -> None:
+    call_rids = {r.rid.lower() for r in msg.records if r.kind == "call" and r.rid}
+    for r in msg.records:
+        if r.kind == "call" and "tool" not in r.kv:
+            res.errors.append(f"V9: #call missing 'tool': {r.raw}")
+        elif r.kind == "ret":
+            if "call" not in r.kv:
+                res.errors.append(f"V9: #ret missing 'call': {r.raw}")
+            elif r.kv["call"].lower() not in call_rids:
+                _emit(res, strict, f"V9: #ret references unknown call '{r.kv['call']}': {r.raw}")
+            status = r.kv.get("status")
+            if status is None:
+                res.errors.append(f"V9: #ret missing 'status': {r.raw}")
+            elif status not in ("ok", "err"):
+                res.errors.append(f"V9: #ret status must be ok|err: {r.raw}")
+        elif r.kind == "think" and "summary" not in r.kv:
+            res.errors.append(f"V9: #think missing 'summary': {r.raw}")
+        elif r.kind == "edit":
+            if "file" not in r.kv:
+                res.errors.append(f"V9: #edit missing 'file': {r.raw}")
+            ch = r.kv.get("changes")
+            if ch is None or not ch.isdigit() or int(ch) < 1:
+                res.errors.append(f"V9: #edit 'changes' must be a positive integer: {r.raw}")
+
+
+def _v11_turn_markers(msg: Message, res: Result) -> None:
+    ids: set[str] = set()
+    refs: list[tuple[str, str]] = []
+    for r in msg.records:
+        if r.kind == "marker":
+            if r.name in ids:
+                res.errors.append(f"V11: duplicate turn marker {r.name}")
+            ids.add(r.name)
+            if r.parent and r.parent != "-":
+                refs.append((r.parent, "parent"))
+        if r.m:
+            refs.append((r.m, "@m"))
+    if ids:
+        for ref_id, kind in refs:
+            if ref_id not in ids:
+                res.errors.append(f"V11: {kind}={ref_id} references undeclared turn marker")
+
+
+def _v12_columnar(msg: Message, res: Result) -> None:
+    for blk in msg.blocks:
+        label = f"#{blk.rtype}[{','.join(blk.columns)}]"
+        if blk.rtype in COLUMNAR_FORBIDDEN:
+            res.errors.append(f"V12: columnar form not allowed for #{blk.rtype} (key is data): {label}")
+        if not blk.columns or any(not re.fullmatch(r"[a-z][a-z0-9_]*", c) for c in blk.columns):
+            res.errors.append(f"V12: malformed column list: {label}")
+            continue
+        if len(set(blk.columns)) != len(blk.columns):
+            res.errors.append(f"V12: duplicate column key in {label}")
+        if not blk.rows:
+            res.warnings.append(f"V12: columnar block has no rows: {label}")
+        for row in blk.rows:
+            if len(row) != len(blk.columns):
+                vals = " ".join(('"%s"' % v if q else v) for v, q in row)
+                res.errors.append(
+                    f"V12: row has {len(row)} field(s), expected {len(blk.columns)} for {label}: {vals}"
+                )
+
+
+def _emit(res: Result, as_error: bool, msg: str) -> None:
+    (res.errors if as_error else res.warnings).append(msg)

pairl-1.5.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: pairl
+Version: 1.5.0
+Summary: PAIRL v1.5 reference implementation — parser, validator, canonicalizer, and renderer
+Project-URL: Homepage, https://pairl.dev
+Project-URL: Repository, https://github.com/dwehrmann/PAIRL
+Author: PAIRL
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agent,compression,llm,pairl,protocol
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pairl (Python)
+
+Reference implementation of the [PAIRL v1.5](../../SPEC.md) protocol: parser,
+validator (rules V1–V12), canonicalizer + SHA-256 hashing, and a deterministic
+human-readable renderer. Pure standard library, no runtime dependencies.
+
+## Install
+
+```bash
+pip install -e impl/python      # from the repo root
+```
+
+## Library
+
+```python
+import pairl
+
+msg = pairl.parse(open("message.pairl").read())
+
+res = pairl.validate(msg)            # rules V1–V12
+print(res.valid, res.errors, res.warnings)
+
+print(pairl.compute_hash(msg))       # canonical SHA-256 (columnar-invariant)
+print(pairl.render(msg))             # faithful human-readable rendering
+```
+
+Columnar blocks (`#evid[claim,src,conf]` + positional rows, §3.4) are parsed and
+expanded to their canonical `#type key=value` records, so a message **hashes
+identically** whether sent in columnar or `key=value` form (§9.4a).
+
+## CLI
+
+```bash
+python -m pairl validate [--strict] message.pairl
+python -m pairl render   message.pairl
+python -m pairl hash     message.pairl
+python -m pairl canon    message.pairl
+```
+
+## Test
+
+```bash
+cd impl/python && python -m unittest discover -s tests
+```

pairl-1.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pairl/__init__.py,sha256=pjlJtXIrfEQVMxp2RBArdIiwDcfj2ED5wFbJvqMt2pQ,549
+pairl/__main__.py,sha256=tP3jJnY3t8zzL3eZZ35Afk7i6ONVKxnFfswamakhtyA,1436
+pairl/canonical.py,sha256=6OHy8hjRc5PhJr9a7S3kx0_Eo6TTvV4QPkoHKinpsM4,2463
+pairl/core.py,sha256=WSb_c1D2c7OG64Gkb1ooV5P7ftebMReVIhORdlqE4Zs,8170
+pairl/render.py,sha256=KzE7xIl4p4ehVqQ8IH6XSGNTJm9-1lQOTifAREC-77c,3864
+pairl/validate.py,sha256=IkmwYWr6DQbxCRJ_kT4yUZS9lm9GUYdS4prhf7S9SVo,7772
+pairl-1.5.0.dist-info/METADATA,sha256=9IN-D3CdYKhHua3ot6TIzMX5zQ1AOULyI0dK_NUtIxo,1575
+pairl-1.5.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pairl-1.5.0.dist-info/entry_points.txt,sha256=f5EYhxH0hucZNgxLrcyh5aNuy8ZpD6dZ0LwsoydyDMo,46
+pairl-1.5.0.dist-info/licenses/LICENSE,sha256=8SuCyXM72P2YmDaKMKew2GxhI5HYpRsy0m6Gz2wgt3c,10766
+pairl-1.5.0.dist-info/RECORD,,

pairl-1.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pairl-1.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pairl = pairl.__main__:main

pairl-1.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright 2026 PAIRL Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.