Metadata-Version: 2.4
Name: behavior-contracts
Version: 0.7.1
Summary: Multi-language IR-Runtime common core (Python port). The COMMON 'thin core' primitives from dsl-contracts runtime-boundary.md — validate_envelope / evaluate_expression / render_template / run_plan / canonical_value / canonical_json / py_float_repr / assert_portable — with zero backend (DynamoDB/graphddb) dependencies.
Author: foo-log
License: MIT
Keywords: dsl,ir,runtime,conformance,canonical
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"

# behavior-contracts (Python)

The **COMMON "thin core"** runtime primitives from
[`runtime-boundary.md`](../docs/runtime-boundary.md), ported to Python from the
TypeScript reference implementation (`ts/src/*`) with **identical semantics**.

This package contains **only** the DSL-agnostic primitives that WS1 classified as
COMMON. It has **zero** backend (DynamoDB / graphddb) dependencies — no boto3, no
key marshalling, no retry tuning, no hydrate, no bundle format. Those stay in the
consumer (graphddb).

## Public API

```python
from behavior_contracts import (
    validate_envelope,     # spec-version fail-closed check
    evaluate_expression,   # expression-ir.md evaluator (i64-checked, truncated %, code-point cmp)
    render_template,        # {param} rendering (strict, Python str() parity)
    run_plan, final_tree,   # execution-plan skeleton (stage / Skip propagation / Policy Kind)
    canonical_value,        # key identity (top-level key sort)
    canonical_json,         # fingerprint (recursive key sort)
    py_float_repr,          # CPython repr(float) canonical decimal
    assert_portable,        # Portability Guard
    decode_value, deep_equals,  # conformance runner adapter (int/float type distinction)
    encode_value, resolve_partial, cmp_code_points,
    SPEC_VERSIONS, ENVELOPE_SPEC_VERSION,
)
```

Each COMMON primitive raises a typed `*Failure` exception carrying a `.code`
string matching the conformance protocol's failure-code set.

## §8 cross-language traps this port handles

- **`%` sign**: normative mod is *truncated* (dividend sign). Python's native `%`
  returns the divisor sign, so `evaluate_expression({"mod":[-7,2]}) == -1`
  (native `-7 % 2 == 1`). Implemented via truncated-quotient correction; float
  mod via `math.fmod`.
- **int is checked i64**: Python `int` is arbitrary-precision, so i64 bounds are
  enforced manually; overflow → `INT_OVERFLOW`.
- **string comparison**: code-point order. Python `str` compares by code point
  already (no UTF-16 surrogate hazard) — verified in tests.
- **NaN/Inf → Failure**; `div` always float with `|int| > 2^53` widening →
  `PRECISION_LOSS`; `py_float_repr` matches CPython `repr(float)` byte-for-byte
  (parametrized parity tests).
- **bool is not int**: `isinstance(x, bool)` is checked before `int` everywhere
  (Python's `bool <: int`).

## Conformance

Runs the 7 shared suites (164 vectors) from `../conformance/vectors/*.json`
through this package per [`../conformance/PROTOCOL.md`](../conformance/PROTOCOL.md),
including the pre-flight version fail-closed sweep.

```bash
python -m behavior_contracts.conformance      # → "164 passed, 0 failed / 164 vectors across 7 suites"
# or the console script:
behavior-contracts-conformance
```

Override the vectors location with `DSL_CONTRACTS_VECTORS=/path/to/vectors`.

## Tests

```bash
pip install -e ".[test]"
python -m pytest        # unit tests over the public API + the conformance runner as a test
```

## Docker integration: N/A

This package has **no external service dependency** (no database, no network) —
it is pure in-process logic over JSON-shaped values. There is therefore nothing
for a docker-compose integration harness to stand up; the conformance runner and
pytest exercise the full surface in-process. (The graphddb *adapter PoC* in WS4
Part B is where docker-backed integration applies, because graphddb talks to
DynamoDB Local.)
