behavior-contracts 0.1.2__py3-none-any.whl

behavior_contracts/conformance.py

@@ -0,0 +1,284 @@
+"""conformance.py — dsl-contracts conformance kit の Python runner。
+
+    python -m behavior_contracts.conformance
+    （または console script: behavior-contracts-conformance）
+
+conformance/vectors/*.json を読み、各 vector を本パッケージのプリミティブ
+（evaluate_expression / render_template / run_plan / canonical）へ通し、expect と比較して
+pass/fail を集計する。全 suite PASS で exit 0、1 件でも fail で exit 1。
+
+これは conformance/PROTOCOL.md の Python 実装。TS 参照 runner
+（examples/src/conformance-run.ts）と同じ JSON を読み、同じ判定規則で同じ pass/fail を出す。
+
+spec version fail-closed（§5）: 全 suite JSON の版を **pre-flight（実行前一括）** で照合し、
+1 つでも不一致なら vector を 1 件も実行せず exit 2 で loud reject する。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from . import (
+    SPEC_VERSIONS,
+    CanonicalFailure,
+    ExprFailure,
+    PlanFailure,
+    TemplateFailure,
+    canonical_json,
+    canonical_value,
+    decode_value,
+    deep_equals,
+    encode_value,
+    evaluate_expression,
+    final_tree,
+    py_float_repr,
+    render_template,
+    run_plan,
+)
+
+
+def _vectors_dir() -> Path:
+    """conformance/vectors ディレクトリを探す。
+
+    優先順: ``DSL_CONTRACTS_VECTORS`` 環境変数 → リポジトリ相対
+    （python/src/behavior_contracts/ から ../../../conformance/vectors）。
+    """
+    env = os.environ.get("DSL_CONTRACTS_VECTORS")
+    if env:
+        return Path(env)
+    here = Path(__file__).resolve()
+    # here = .../dsl-contracts/python/src/behavior_contracts/conformance.py
+    candidate = here.parents[3] / "conformance" / "vectors"
+    return candidate
+
+
+def _load_json(vectors_dir: Path, file: str) -> Any:
+    with open(vectors_dir / file, "r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+class _Tally:
+    __slots__ = ("passed", "failed")
+
+    def __init__(self) -> None:
+        self.passed = 0
+        self.failed = 0
+
+
+def _line(ok: bool, name: str, detail: str = "") -> None:
+    if ok:
+        print(f"  ✓ {name}")
+    else:
+        print(f"  ✗ {name}")
+        if detail:
+            print(f"      {detail}")
+
+
+# ── pre-flight version sweep（PROTOCOL.md §5）──────────────────────────────────
+def _preflight(vectors_dir: Path) -> Dict[str, Any]:
+    specs = [
+        ("expression.json", "expression", "exprVersion", SPEC_VERSIONS["expression"]),
+        ("template.json", "template", "templateVersion", SPEC_VERSIONS["template"]),
+        ("plan.json", "plan", "planVersion", SPEC_VERSIONS["plan"]),
+        ("canonical.json", "canonical", "canonicalVersion", SPEC_VERSIONS["canonical"]),
+    ]
+    loaded = [(f, suite, vk, want, _load_json(vectors_dir, f)) for (f, suite, vk, want) in specs]
+    mismatches = [(suite, doc.get(vk), want) for (_, suite, vk, want, doc) in loaded if doc.get(vk) != want]
+    if mismatches:
+        for suite, got, want in mismatches:
+            print(
+                f"FAIL-CLOSED: {suite} suite version {got} != supported {want}.",
+                file=sys.stderr,
+            )
+        print(
+            f"Refusing to run: {len(mismatches)} suite version mismatch(es). "
+            f"No vectors executed.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    return {suite: doc for (_, suite, _vk, _want, doc) in loaded}
+
+
+# ── expression suite ──────────────────────────────────────────────────────────
+def _run_expression(t: _Tally, doc: Any) -> None:
+    print(f"\nexpression.json (v{doc['exprVersion']}) — {len(doc['vectors'])} vectors")
+    for v in doc["vectors"]:
+        ok = False
+        detail = ""
+        try:
+            scope = decode_value(v["scope"]) if v.get("scope") is not None else {}
+            result = evaluate_expression(v["expr"], scope)
+            if "value" in v["expect"]:
+                ok = deep_equals(result, decode_value(v["expect"]["value"]))
+                if not ok:
+                    detail = (
+                        f"expected value {json.dumps(v['expect']['value'])}, "
+                        f"got {json.dumps(encode_value(result))}"
+                    )
+            else:
+                detail = f"expected Failure({v['expect']['failure']}), got a value"
+        except ExprFailure as e:
+            if "failure" in v["expect"]:
+                ok = e.code == v["expect"]["failure"]
+                if not ok:
+                    detail = f"expected Failure({v['expect']['failure']}), got Failure({e.code})"
+            else:
+                detail = f"expected a value, got Failure({e.code})"
+        _line(ok, v["name"], detail)
+        _bump(t, ok)
+
+
+# ── template suite ────────────────────────────────────────────────────────────
+def _run_template(t: _Tally, doc: Any) -> None:
+    print(f"\ntemplate.json (v{doc['templateVersion']}) — {len(doc['vectors'])} vectors")
+    for v in doc["vectors"]:
+        ok = False
+        detail = ""
+        params = {k: decode_value(val) for k, val in v["params"].items()}
+        try:
+            out = render_template(v["template"], params)
+            if "ok" in v["expect"]:
+                ok = out == v["expect"]["ok"]
+                if not ok:
+                    detail = f"expected {v['expect']['ok']!r}, got {out!r}"
+            else:
+                detail = f"expected Failure({v['expect']['failure']}), got {out!r}"
+        except TemplateFailure as e:
+            if "failure" in v["expect"]:
+                ok = e.code == v["expect"]["failure"]
+                if not ok:
+                    detail = f"expected Failure({v['expect']['failure']}), got Failure({e.code})"
+            else:
+                detail = f"expected {v['expect']['ok']!r}, got Failure({e.code})"
+        _line(ok, v["name"], detail)
+        _bump(t, ok)
+
+
+# ── canonical suite ───────────────────────────────────────────────────────────
+def _run_canonical(t: _Tally, doc: Any) -> None:
+    print(f"\ncanonical.json (v{doc['canonicalVersion']}) — {len(doc['vectors'])} vectors")
+    for v in doc["vectors"]:
+        ok = False
+        detail = ""
+        try:
+            val = decode_value(v["value"])
+            kind = v["kind"]
+            if kind == "canonicalValue":
+                out = canonical_value(val)
+            elif kind == "canonicalJson":
+                out = canonical_json(val)
+            elif kind == "floatRepr":
+                if not isinstance(val, float):
+                    raise ValueError(f"floatRepr expects a float, got {type(val).__name__}")
+                out = py_float_repr(val)
+            else:
+                raise ValueError(f"unknown kind: {kind}")
+            if "ok" in v["expect"]:
+                ok = out == v["expect"]["ok"]
+                if not ok:
+                    detail = f"expected {v['expect']['ok']!r}, got {out!r}"
+            else:
+                detail = f"expected Failure({v['expect']['failure']}), got {out!r}"
+        except CanonicalFailure as e:
+            if "failure" in v["expect"]:
+                ok = e.code == v["expect"]["failure"]
+                if not ok:
+                    detail = f"expected Failure({v['expect']['failure']}), got Failure({e.code})"
+            else:
+                detail = f"expected {v['expect']['ok']!r}, got Failure({e.code})"
+        _line(ok, v["name"], detail)
+        _bump(t, ok)
+
+
+# ── plan suite ────────────────────────────────────────────────────────────────
+def _run_plan(t: _Tally, doc: Any) -> None:
+    print(f"\nplan.json (v{doc['planVersion']}) — {len(doc['vectors'])} vectors")
+    for v in doc["vectors"]:
+        ok = False
+        detail = ""
+        plan = v.get("plan")
+        ops = v["ops"]
+        exec_map = v["exec"]
+
+        def make_exec(exec_map: Dict[str, Any]):
+            def exec_fn(op: Any, bound_value: Any) -> Dict[str, Any]:
+                o = exec_map.get(op["id"])
+                if o is None:
+                    raise ValueError(f"no mock outcome for op '{op['id']}'")
+                if "ok" in o:
+                    return {"ok": decode_value(o["ok"])}
+                return {"error": o["error"]}
+            return exec_fn
+
+        try:
+            res = run_plan(plan, ops, make_exec(exec_map))
+            if "failure" in v["expect"]:
+                detail = f"expected Failure({v['expect']['failure']}), got a full run"
+            else:
+                tree = final_tree(res["states"], ops)
+                exp_tree = {k: decode_value(val) for k, val in v["expect"]["tree"].items()}
+                tree_ok = canonical_json(tree) == canonical_json(exp_tree)
+                exec_ok = _same_set(res["executed"], v["expect"]["executed"])
+                skip_ok = _same_set(res["skipped"], v["expect"]["skipped"])
+                ok = tree_ok and exec_ok and skip_ok
+                if not ok:
+                    parts: List[str] = []
+                    if not tree_ok:
+                        parts.append(f"tree {canonical_json(tree)} != {canonical_json(exp_tree)}")
+                    if not exec_ok:
+                        parts.append(f"executed {res['executed']} != {v['expect']['executed']}")
+                    if not skip_ok:
+                        parts.append(f"skipped {res['skipped']} != {v['expect']['skipped']}")
+                    detail = "; ".join(parts)
+        except PlanFailure as e:
+            if "failure" in v["expect"]:
+                ok = e.code == v["expect"]["failure"]
+                if not ok:
+                    detail = f"expected Failure({v['expect']['failure']}), got Failure({e.code})"
+            else:
+                detail = f"expected a full run, got Failure({e.code})"
+        _line(ok, v["name"], detail)
+        _bump(t, ok)
+
+
+def _same_set(a: List[str], b: List[str]) -> bool:
+    return sorted(a) == sorted(b)
+
+
+def _bump(t: _Tally, ok: bool) -> None:
+    if ok:
+        t.passed += 1
+    else:
+        t.failed += 1
+
+
+def run(vectors_dir: Optional[Path] = None) -> int:
+    """conformance run を実行し、失敗数を返す（version mismatch は exit 2 で即終了）。"""
+    vd = vectors_dir or _vectors_dir()
+    print("dsl-contracts conformance kit — Python runner")
+
+    docs = _preflight(vd)  # STEP 1: pre-flight（不一致は exit 2）
+
+    # STEP 2: 全版一致を確認したうえで実行。
+    t = _Tally()
+    _run_expression(t, docs["expression"])
+    _run_template(t, docs["template"])
+    _run_plan(t, docs["plan"])
+    _run_canonical(t, docs["canonical"])
+
+    total = t.passed + t.failed
+    print(f"\n{t.passed} passed, {t.failed} failed / {total} vectors across 4 suites")
+    return t.failed
+
+
+def main() -> None:
+    failed = run()
+    sys.exit(1 if failed > 0 else 0)
+
+
+if __name__ == "__main__":
+    main()

behavior_contracts/envelope.py

@@ -0,0 +1,89 @@
+"""envelope.py — validate_envelope（spec-version fail-closed 検査）。Python port。
+
+TS 参照実装 ``ts/src/envelope.ts`` の意味論を完全一致で移植。graphddb の
+``_validate_spec_version``（``runtime.py``）を DSL 非依存に一般化したもの。DynamoDB 概念は
+ゼロ — ``<major>.<minor>`` の比較機構のみ。
+
+互換規則（graphddb と同一・PROTOCOL.md §5 の fail-closed 規律）:
+  - version 文字列は ``"<major>.<minor>"``（整数 2 つ）でなければならない。形式違反は fail-closed。
+  - major は supported major と一致しなければならない（major bump = 破壊的変更）。
+  - minor は supported minor 以下でなければならない（minor は additive）。
+  - 未知（範囲外）version は黙って通さず loud reject する。
+
+``supported`` は consumer が渡す（core は比較機構を提供するのみ）。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping, Optional
+
+_ENVELOPE_FAILURE_CODES = frozenset(
+    {"MISSING_VERSION", "MALFORMED_VERSION", "UNSUPPORTED_MAJOR", "UNSUPPORTED_MINOR"}
+)
+
+_VERSION_RE = re.compile(r"^\d+$")
+
+
+class EnvelopeFailure(Exception):
+    """envelope 検査の Failure。"""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _fail(code: str, message: str) -> "None":
+    raise EnvelopeFailure(code, message)
+
+
+def _parse_version(version: str, label: str):
+    parts = version.split(".")
+    if len(parts) != 2:
+        _fail("MALFORMED_VERSION", f"{label}: version '{version}' must be '<major>.<minor>'")
+    maj_s, min_s = parts
+    if not _VERSION_RE.match(maj_s) or not _VERSION_RE.match(min_s):
+        _fail(
+            "MALFORMED_VERSION",
+            f"{label}: version '{version}' must be two integers '<major>.<minor>'",
+        )
+    return int(maj_s), int(min_s)
+
+
+def validate_envelope(
+    envelope: Any,
+    supported: str,
+    *,
+    field: Optional[str] = None,
+    label: Optional[str] = None,
+) -> None:
+    """envelope の spec version を fail-closed で検査する。
+
+    :param envelope:  ``specVersion`` を持つ任意の document（graphddb の manifest/operations 等）。
+    :param supported: この runtime が対応する版 ``"<major>.<minor>"``（consumer が宣言）。
+    :param field:     version を読むフィールド名（既定 ``"specVersion"``）。
+    :param label:     エラーメッセージ用ラベル（既定 ``"envelope"``）。
+    :raises EnvelopeFailure: 形式違反・未対応 major/minor のとき。
+    """
+    field = field or "specVersion"
+    label = label or "envelope"
+    if not isinstance(envelope, Mapping):
+        _fail("MISSING_VERSION", f"{label}: not an object")
+    raw = envelope.get(field)
+    if not isinstance(raw, str):
+        _fail("MISSING_VERSION", f"{label}: missing string '{field}'")
+
+    got_major, got_minor = _parse_version(raw, label)
+    want_major, want_minor = _parse_version(supported, "supported")
+
+    if got_major != want_major:
+        _fail(
+            "UNSUPPORTED_MAJOR",
+            f"{label}: version {raw} has major {got_major} but runtime supports "
+            f"major {want_major}",
+        )
+    if got_minor > want_minor:
+        _fail(
+            "UNSUPPORTED_MINOR",
+            f"{label}: version {raw} has minor {got_minor} > supported minor {want_minor}",
+        )