behavior-contracts 0.1.2__py3-none-any.whl

behavior_contracts/__init__.py

@@ -0,0 +1,108 @@
+"""behavior-contracts — 多言語 IR-Runtime 共通層（Python 実装）。
+
+runtime-boundary.md で COMMON と判定された「薄い核」プリミティブのみを公開する。
+DynamoDB / graphddb 固有の概念（backend 実行・key resolution・retry Tuning・hydrate・
+bundle 形式）は一切含まない。TS 参照実装 ``ts/src/*`` の意味論を完全一致で移植したもの。
+
+公開 COMMON プリミティブ（runtime-boundary.md §2.1）:
+  - validate_envelope     — spec-version fail-closed 検査
+  - evaluate_expression   — expression-ir.md の規範評価
+  - render_template       — ``{param}`` 束縛描画（strict）
+  - run_plan              — 実行計画の骨格実行（stage / Skip 伝播 / Policy Kind）
+  - canonical_value / canonical_json / py_float_repr — 決定的正準直列化
+  - assert_portable       — Portability Guard（IR 可搬性不変条件）
+  - decode_value / deep_equals — conformance runner adapter 共通部
+"""
+
+from __future__ import annotations
+
+# ── 対応する仕様バージョン（IR/vector の spec version。ライブラリ semver とは別管理）──
+SPEC_VERSIONS = {
+    "expression": 1,
+    "template": 1,
+    "plan": 1,
+    "canonical": 1,
+}
+
+# validate_envelope に渡す graphddb 形式の既定 supported 版（``"<major>.<minor>"``）。
+ENVELOPE_SPEC_VERSION = "1.1"
+
+# ── expression（evaluate_expression） ──────────────────────────────────────────
+from .expr_eval import (  # noqa: E402
+    ExprFailure,
+    cmp_code_points,
+    encode_value,
+    evaluate as evaluate_expression,
+)
+
+# ── template（render_template） ────────────────────────────────────────────────
+from .template import (  # noqa: E402
+    TemplateFailure,
+    render_template,
+    resolve_partial,
+)
+
+# ── plan（run_plan） ───────────────────────────────────────────────────────────
+from .plan import (  # noqa: E402
+    PlanFailure,
+    final_tree,
+    run_plan,
+)
+
+# ── canonical（canonical_value / canonical_json / py_float_repr） ─────────────
+from .canonical import (  # noqa: E402
+    CanonicalFailure,
+    canonical_json,
+    canonical_value,
+    py_float_repr,
+)
+
+# ── envelope（validate_envelope） ──────────────────────────────────────────────
+from .envelope import (  # noqa: E402
+    EnvelopeFailure,
+    validate_envelope,
+)
+
+# ── guard（Portability Guard） ────────────────────────────────────────────────
+from .guard import (  # noqa: E402
+    PortabilityError,
+    assert_portable,
+)
+
+# ── conformance runner adapter 共通部 ─────────────────────────────────────────
+from .codec import (  # noqa: E402
+    decode_value,
+    deep_equals,
+)
+
+__all__ = [
+    "SPEC_VERSIONS",
+    "ENVELOPE_SPEC_VERSION",
+    # expression
+    "evaluate_expression",
+    "encode_value",
+    "cmp_code_points",
+    "ExprFailure",
+    # template
+    "render_template",
+    "resolve_partial",
+    "TemplateFailure",
+    # plan
+    "run_plan",
+    "final_tree",
+    "PlanFailure",
+    # canonical
+    "canonical_value",
+    "canonical_json",
+    "py_float_repr",
+    "CanonicalFailure",
+    # envelope
+    "validate_envelope",
+    "EnvelopeFailure",
+    # guard
+    "assert_portable",
+    "PortabilityError",
+    # codec
+    "decode_value",
+    "deep_equals",
+]

behavior_contracts/canonical.py

@@ -0,0 +1,222 @@
+"""canonical.py — canonical-serialization.md の参照実装（Python port）。
+
+TS 参照実装 ``ts/src/canonical.ts`` の意味論を完全一致で移植。3 プリミティブ:
+  - py_float_repr(n)     : CPython repr(float) 相当の正準10進（parity SSoT = Python）
+  - canonical_value(v)   : key identity（トップレベルのみキーソート）  — §2 serializeContractKey
+  - canonical_json(v)    : fingerprint（全階層キーソート）             — §3 canonicalJson
+
+値モデルは expr_eval と共有（int / float / str / bool / None / list / dict）。
+runtime 値の直列化:
+  - int   → 素の 10 進整数（範囲外も 10 進で素通し。DynamoDB N 値層）
+  - float → py_float_repr（§4.1）。NaN/±Inf は Failure（§4.1-6）
+
+**Python parity SSoT の要点**: py_float_repr は CPython の ``repr(float)`` を SSoT とする。
+Python では ``repr(float)`` そのものが CPython の最短往復10進 + scientific 閾値
+(decpt<=-4 || decpt>16) + 指数 2 桁 pad と一致する。したがって Python port は
+``repr()`` 準拠で実装し、TS 参照アルゴリズムと byte 一致することを検証する。
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+Value = Any
+
+_CANONICAL_FAILURE_CODES = frozenset({"NAN_OR_INF", "INVALID_VALUE"})
+
+
+class CanonicalFailure(Exception):
+    """canonical 直列化の Failure（NAN_OR_INF / INVALID_VALUE）。"""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _fail(code: str, message: str) -> "None":
+    raise CanonicalFailure(code, message)
+
+
+def _is_int(v: Value) -> bool:
+    return isinstance(v, int) and not isinstance(v, bool)
+
+
+def _is_plain_object(v: Value) -> bool:
+    return isinstance(v, dict)
+
+
+# ── §4.1 float の正準10進（CPython repr(float)）────────────────────────────────
+def py_float_repr(n: float) -> str:
+    """CPython の ``repr(float)`` / ``json.dumps(float)`` と byte 一致する 10 進表現。
+
+    規則（canonical-serialization.md §4.1 / CPython format_float_short('r')）:
+      1. 最短往復 digits。
+      2. scientific 判定: decpt <= -4 || decpt > 16 で指数表記。
+      3. 指数は符号つき・最低 2 桁 zero-pad（e+05 / e-07）。
+      4. 整数値 float は ``.0`` を保つ（123 → "123.0"）。
+      5. -0.0 は "-0.0"、+0.0 は "0.0"。
+      6. NaN / ±Inf は Failure。
+
+    実装: CPython の ``repr(float)`` は既にこの正準表現を生成するため、そこから
+    digits/decpt を導出し TS 参照実装 (formatFixed/formatScientific) と同一の分岐で
+    組み立てる。これにより仕様の閾値ロジックを Python 側でも明示的に踏む。
+    """
+    if not isinstance(n, float):
+        # int が渡された場合など。仕様上 floatRepr は float のみ。
+        _fail("INVALID_VALUE", f"py_float_repr expects a float, got {type(n).__name__}")
+    if math.isnan(n) or math.isinf(n):
+        _fail("NAN_OR_INF", f"non-finite float cannot be serialized: {n}")
+
+    # §4.1-5: -0.0 を signbit で捕捉。
+    if n == 0.0:
+        return "-0.0" if math.copysign(1.0, n) < 0 else "0.0"
+
+    neg = n < 0
+    abs_n = abs(n)
+
+    digits, decpt = _shortest_digits(abs_n)
+
+    if decpt <= -4 or decpt > 16:
+        body = _format_scientific(digits, decpt)
+    else:
+        body = _format_fixed(digits, decpt)
+
+    return "-" + body if neg else body
+
+
+def _shortest_digits(abs_n: float):
+    """正の有限 float → shortest round-trip digits と decpt（値 = 0.<digits> × 10^decpt）。
+
+    CPython の ``repr(float)`` が shortest round-trip を出すので、それを指数正規化して
+    digits と 10 進指数を取り出す（TS 実装が ``Number#toString`` から取り出すのと同じ手順）。
+    """
+    # repr は "123.0" / "1.5" / "1e-07" / "1.25e+30" 等（Python の正準表現）。
+    s = repr(abs_n)
+    e_idx = s.find("e")
+    if e_idx >= 0:
+        mantissa = s[:e_idx]
+        exp = int(s[e_idx + 1 :])
+    else:
+        mantissa = s
+        exp = 0
+
+    dot = mantissa.find(".")
+    if dot >= 0:
+        int_part = mantissa[:dot]
+        frac_part = mantissa[dot + 1 :]
+    else:
+        int_part = mantissa
+        frac_part = ""
+
+    all_digits = int_part + frac_part
+    # decpt(暫定) = 整数部桁数 + exp
+    decpt = len(int_part) + exp
+
+    # 先頭ゼロ除去（"0025" → "25" で decpt を減らす）。
+    lead = 0
+    while lead < len(all_digits) - 1 and all_digits[lead] == "0":
+        lead += 1
+    if lead > 0:
+        all_digits = all_digits[lead:]
+        decpt -= lead
+
+    # 末尾ゼロ除去（有効数字のみ）。
+    all_digits = all_digits.rstrip("0")
+    if all_digits == "":
+        return "0", 1
+    return all_digits, decpt
+
+
+def _format_fixed(digits: str, decpt: int) -> str:
+    """固定小数点表記。整数値 float は ``.0`` を付ける（§4.1-4）。"""
+    if decpt <= 0:
+        return "0." + "0" * (-decpt) + digits
+    if decpt >= len(digits):
+        return digits + "0" * (decpt - len(digits)) + ".0"
+    return digits[:decpt] + "." + digits[decpt:]
+
+
+def _format_scientific(digits: str, decpt: int) -> str:
+    """指数表記。d.ddde±XX（指数は最低 2 桁 zero-pad）（§4.1-2/3）。"""
+    first = digits[0]
+    rest = digits[1:]
+    mant = f"{first}.{rest}" if rest else first
+    e = decpt - 1
+    sign = "-" if e < 0 else "+"
+    mag = str(abs(e)).rjust(2, "0")
+    return f"{mant}e{sign}{mag}"
+
+
+# ── §2 canonical_value（serialize_contract_key）— トップレベルのみキーソート ──────
+def canonical_value(v: Value) -> str:
+    """key identity 用の正準直列化。
+
+    トップレベル object のキーのみ昇順ソートし、compact JSON を返す。ネスト値は挿入順のまま
+    （canonical-serialization.md §2）。
+    """
+    if _is_plain_object(v):
+        keys = sorted(v.keys(), key=_code_point_sort_key)
+        parts = [f"{_json_string(k)}:{_encode_nested(v[k])}" for k in keys]
+        return "{" + ",".join(parts) + "}"
+    return _encode_nested(v)
+
+
+# ── §3 canonical_json — 全階層キーソート ────────────────────────────────────────
+def canonical_json(v: Value) -> str:
+    """fingerprint 用。全 object 階層のキーを昇順ソート（配列は順序保持）。"""
+    if _is_plain_object(v):
+        keys = sorted(v.keys(), key=_code_point_sort_key)
+        parts = [f"{_json_string(k)}:{canonical_json(v[k])}" for k in keys]
+        return "{" + ",".join(parts) + "}"
+    if isinstance(v, list):
+        return "[" + ",".join(canonical_json(e) for e in v) + "]"
+    return _scalar_json(v)
+
+
+# ── 内部: ネスト値の直列化（canonical_value 用。ネスト object は挿入順）──────────────
+def _encode_nested(v: Value) -> str:
+    if _is_plain_object(v):
+        parts = [f"{_json_string(k)}:{_encode_nested(v[k])}" for k in v.keys()]
+        return "{" + ",".join(parts) + "}"
+    if isinstance(v, list):
+        return "[" + ",".join(_encode_nested(e) for e in v) + "]"
+    return _scalar_json(v)
+
+
+def _scalar_json(v: Value) -> str:
+    """スカラ（int/float/str/bool/None）の JSON 直列化。float は py_float_repr。"""
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, str):
+        return _json_string(v)
+    if _is_int(v):
+        return str(v)  # int: 素の 10 進整数（値層 JSON number）
+    if isinstance(v, float):
+        return py_float_repr(v)  # float: CPython repr（§4.1）
+    _fail("INVALID_VALUE", "cannot serialize value of unknown type")
+
+
+def _json_string(s: str) -> str:
+    """文字列を JSON 直列化（ensure_ascii=False = 非 ASCII 素通し）。
+
+    TS の ``JSON.stringify`` と一致させるため、Python の ``json.dumps`` を
+    ``ensure_ascii=False`` で使う（compact separators は文字列単体では無関係）。
+    """
+    return json.dumps(s, ensure_ascii=False)
+
+
+def _code_point_sort_key(s: str):
+    """Unicode code-point 順のソートキー（正準キーソートの規範。全言語共通）。
+
+    canonical-serialization.md §2/§6: オブジェクトキーのソートは **code-point 順** が規範
+    （expression-ir.md §6 の文字列比較 = code-point 順と整合。UTF-16 code unit 順ではない —
+    astral-plane（U+10000+）キーで両者は食い違う）。Python の ``str`` はタプル化した
+    code point 列で比較されるので、ここでは code point のタプルを返す（``sorted`` の既定
+    ``str`` 比較と同一だが、規範が code-point であることを明示するための明示キー）。
+    BMP 内では code-point == UTF-16 なので既存 vector は不変。
+    """
+    return [ord(ch) for ch in s]

behavior_contracts/codec.py

@@ -0,0 +1,88 @@
+"""codec.py — conformance runner adapter の共通部（Python port）。
+
+TS 参照実装 ``ts/src/codec.ts`` の意味論を移植。golden vector の型付き値エンコード
+（``{int:"..."}`` / ``{float:n}`` / ``{nan}`` / ``{inf}`` / 素の JSON number 分類）と
+runtime 値の相互変換、および int/float を型で区別する深い等価判定。全言語 runner が
+同じ判定規則で同じ pass/fail を出すための共有ロジック（PROTOCOL.md §4）。
+
+**Python の int/float 分類の要点**: Python の ``json.load`` は整数値の JSON number を
+``int``、小数部ありを ``float`` として復元する（TS のように精度損失しない）。したがって
+``decode_value`` は「Python の型をそのまま尊重しつつ ``{int}``/``{float}``/``{nan}``/``{inf}``
+ラッパを解く」だけでよい。
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+Value = Any
+
+
+def _is_int(v: Value) -> bool:
+    return isinstance(v, int) and not isinstance(v, bool)
+
+
+def decode_value(x: Any) -> Value:
+    """golden vector の JSON 値表現を runtime 値へ復元する。
+
+    - 素の JSON number: 整数値 → int、小数部あり → float（Python の json が既に区別）。
+    - ``{int:"..."}`` → int（安全整数域外も正確）。
+    - ``{float:n}``  → float（整数値 float を明示）。
+    - ``{nan}`` / ``{inf: ±1}`` → NaN / ±Inf。
+    """
+    if x is None or isinstance(x, bool) or isinstance(x, str):
+        return x
+    if _is_int(x):
+        return int(x)
+    if isinstance(x, float):
+        return x
+    if isinstance(x, list):
+        return [decode_value(e) for e in x]
+    if isinstance(x, dict):
+        keys = list(x.keys())
+        if len(keys) == 1:
+            k = keys[0]
+            if k == "int" and isinstance(x["int"], str):
+                return int(x["int"])
+            if k == "float" and isinstance(x["float"], (int, float)) and not isinstance(
+                x["float"], bool
+            ):
+                return float(x["float"])
+            if k == "nan":
+                return float("nan")
+            if k == "inf":
+                return float("-inf") if x["inf"] < 0 else float("inf")
+        return {k: decode_value(v) for k, v in x.items()}
+    raise ValueError(f"cannot decode value: {x!s}")
+
+
+def deep_equals(a: Value, b: Value) -> bool:
+    """int/float を型で区別する深い等価（PROTOCOL.md §4）。
+
+    int と float は等しくない。NaN は NaN と等しいとみなす（Failure 判定用）。
+    """
+    if a is None or b is None:
+        return a is b
+    # bool は int の前に判定（bool ≠ int）。
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if _is_int(a) or _is_int(b):
+        return _is_int(a) and _is_int(b) and a == b
+    if isinstance(a, float) or isinstance(b, float):
+        if not (isinstance(a, float) and isinstance(b, float)):
+            return False
+        return a == b or (math.isnan(a) and math.isnan(b))
+    if isinstance(a, str) or isinstance(b, str):
+        return isinstance(a, str) and isinstance(b, str) and a == b
+    if isinstance(a, list):
+        if not isinstance(b, list) or len(a) != len(b):
+            return False
+        return all(deep_equals(x, y) for x, y in zip(a, b))
+    if isinstance(b, list):
+        return False
+    if isinstance(a, dict) and isinstance(b, dict):
+        if set(a.keys()) != set(b.keys()):
+            return False
+        return all(deep_equals(a[k], b[k]) for k in a)
+    return False