From 980213ed62f04e2cfe31b8310c9bf073d185eb6f Mon Sep 17 00:00:00 2001 From: Shay Date: Sat, 23 May 2026 10:29:59 -0700 Subject: [PATCH] feat(binding-graph): Phase 1 data model (ADR-0132) (#171) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Frozen dataclasses + deterministic allocator + invariants for the Semantic-Symbolic Binding Graph proposed in PR #170. Pure data layer: no parser, no solver, no adapter, no runtime wiring. Phases 2-5 deferred to follow-up PRs. - generate/binding_graph/model.py: SourceSpanLink, SymbolBinding, BoundFact, BoundEquation, BoundUnknown, BoundConstraint, and the top-level SemanticSymbolicBindingGraph container. All @dataclass(frozen=True, slots=True). Refusal-first construction via typed BindingGraphError. Cross-collection referential integrity enforced at __post_init__. - generate/binding_graph/allocation.py: pure deterministic allocate_symbols() — same input order yields byte-equal output. - generate/binding_graph/__init__.py: public API surface. - tests/test_binding_graph_model.py: 69 tests covering frozen invariants, slots enforcement, refusal paths, allocation determinism, canonical-string round-trip, cross-collection integrity. - docs/decisions/ADR-0132-binding-graph-data-model.md: ratifies Phase 1 only; explicit Phase 2-5 deferred section citing #170. --- .../ADR-0132-binding-graph-data-model.md | 132 +++++ generate/binding_graph/__init__.py | 48 ++ generate/binding_graph/allocation.py | 108 ++++ generate/binding_graph/model.py | 454 ++++++++++++++ tests/test_binding_graph_model.py | 553 ++++++++++++++++++ 5 files changed, 1295 insertions(+) create mode 100644 docs/decisions/ADR-0132-binding-graph-data-model.md create mode 100644 generate/binding_graph/__init__.py create mode 100644 generate/binding_graph/allocation.py create mode 100644 generate/binding_graph/model.py create mode 100644 tests/test_binding_graph_model.py diff --git a/docs/decisions/ADR-0132-binding-graph-data-model.md b/docs/decisions/ADR-0132-binding-graph-data-model.md new file mode 100644 index 00000000..02b9f72d --- /dev/null +++ b/docs/decisions/ADR-0132-binding-graph-data-model.md @@ -0,0 +1,132 @@ +# ADR-0132 — Semantic-Symbolic Binding Graph: Phase 1 data model + +**Status:** Accepted (Phase 1 only; Phases 2–5 deferred) +**Date:** 2026-05-23 +**Parent proposal:** `docs/implementation/semantic-symbolic-binding-graph-proposal.md` (PR #170) +**Related:** ADR-0115..0118 (math parser/solver/verifier/realizer), ADR-0126 +(candidate-graph parser), ADR-0127 (units pack), ADR-0131 (math-expert +rebench / proof corridor) + +--- + +## Context + +PR #170 proposed a `SemanticSymbolicBindingGraph` as the typed compiler +boundary between natural-language semantic parsing and symbolic / +equational solving. The proposal explicitly recommends shipping it in +phases, starting with a *data-model-only* first PR — no parser, solver, +adapter, or wiring — so the abstraction has a reviewable seam before any +runtime behavior depends on it. + +This ADR ratifies that Phase 1 (`SSBG-1`) scope and pins the resulting +data model. + +## Decision + +Add a pure data layer under `generate/binding_graph/`: + +- `model.py` — frozen, slots-bearing dataclasses: + - `SourceSpanLink` — `(source_id, start, end, text)` with strict + half-open-interval validation. + - `SymbolBinding` — stable `symbol_id` (Python identifier), human- + readable `name`, closed-vocabulary `semantic_role`, optional + `entity` / `unit`, mandatory `source_span` + `introduced_by`. + - `BoundFact` — `symbol_id = value [unit]` lifted from language. + - `BoundEquation` — `lhs_symbol_id := rhs_canonical` with + `dependencies: frozenset[str]`, `operation_kind`, `unit_proof`, + closed-vocabulary `admissibility_status`, and a typed + `refusal_reason` invariant (required iff `status == "refused"`). + - `BoundUnknown` — question target bound to a known symbol. + - `BoundConstraint` — canonical-string predicate over one symbol. + - `SemanticSymbolicBindingGraph` — top-level container; enforces + cross-collection referential integrity at construction. +- `allocation.py` — `allocate_symbols(noun_phrases, *, source_span, + introduced_by, semantic_role, prefix)`. Pure, deterministic, refusal- + first. Identical input → identical `tuple[SymbolBinding, ...]`, + byte-for-byte. +- `__init__.py` — public API surface. + +### Closed vocabularies + +- `SEMANTIC_ROLES = {entity, quantity, rate, duration, count, total, + difference, ratio, unknown}` +- `ADMISSIBILITY_STATUSES = {admitted, pending, refused}` + +Extending either is a deliberate ADR change. + +### Discipline (load-bearing) + +1. **Pure data layer.** No I/O, no parser calls, no algebra calls, no + `numpy`, no runtime field touch. The package is importable with zero + side effects. +2. **Immutability.** Every dataclass is `@dataclass(frozen=True, + slots=True)`. Every collection field is `tuple` or `frozenset`. + `SourceSpanLink`/`SymbolBinding`/etc. are equality- and hash-stable. +3. **Refusal-first.** Invalid construction raises typed + `BindingGraphError` (sibling of `SymbolicError`). Empty strings, + non-identifier ids, unknown roles, empty/inverted spans, and + missing/spurious `refusal_reason` all refuse. +4. **No coupling to the symbolic substrate.** `rhs_canonical` and + `predicate` are *strings*. The binding graph does not import + `Polynomial` from `generate.math_symbolic_normalizer` — decoupling is + the entire point of the layer. The string contract aligns with + ADR-0131's byte-equality discriminator. +5. **Deterministic allocation.** Symbol ids follow + `{prefix}_{slug}_{index:03d}`; collisions are disambiguated by the + numeric suffix, so same input → byte-equal output across runs. + +### Cross-collection invariants + +`SemanticSymbolicBindingGraph.__post_init__` enforces: + +- `symbols` carries unique `symbol_id` values; +- every `BoundFact.symbol_id` references a known symbol; +- every `BoundEquation.lhs_symbol_id` and every dependency references a + known symbol; +- every `BoundUnknown.symbol_id` references a known symbol; +- every `BoundConstraint.symbol_id` references a known symbol; +- every sub-collection is a `tuple` (lists are rejected at + construction). + +### Acceptance evidence + +- 69 tests in `tests/test_binding_graph_model.py`, covering frozen + invariants, slots enforcement, refusal paths, allocation determinism, + canonical-string round-trip, and cross-collection integrity. +- `pyright` clean on new files. +- Runtime behavior byte-identical to `main`: nothing imports the new + package yet. + +## Consequences + +- A reviewable seam for the binding graph exists without committing to + any specific NL parser, unit algebra, or solver behavior. +- Subsequent phases (see below) can land independently behind the same + typed boundary. +- The byte-equality discriminator from ADR-0131 is reinforced: the + binding graph speaks the symbolic substrate by canonical string, so + graph hashes are stable iff substrate canonicalization is stable. + +## Phase 2+ deferred (explicitly out of scope here) + +- **Phase SSBG-2** — adapter from existing `MathProblemGraph` into the + binding graph; goal is representational parity with current bounded + math behavior, no behavior change. +- **Phase SSBG-3** — unit-aware equation binding using the ratified + units pack (ADR-0127); admit/refuse based on dimension algebra. +- **Phase SSBG-4** — question-target binding; refuse on ambiguous or + unbound questions. +- **Phase SSBG-5** — integration with the bounded grammar lane + (ADR-0131 Benchmark 3); each case carries expected binding-graph + shape. + +These phases land in separate PRs against `main`, each with its own +ADR, lane evidence, and refusal coverage. They will not be stacked on +this PR's branch. + +## Non-goals (carried forward from PR #170) + +This is not a general NL understanding system, not a chain-of-thought +generator, not a substitute for symbolic equivalence (ADR-0131.1.B), +not a reopening of arbitrary GSM8K parser expansion, and not a +promotion gate by itself. diff --git a/generate/binding_graph/__init__.py b/generate/binding_graph/__init__.py new file mode 100644 index 00000000..2ceee898 --- /dev/null +++ b/generate/binding_graph/__init__.py @@ -0,0 +1,48 @@ +"""ADR-0132 — Semantic-Symbolic Binding Graph, Phase 1 (data model only). + +This package introduces the typed compiler boundary between natural-language +semantic parsing and symbolic/equational solving proposed in +``docs/implementation/semantic-symbolic-binding-graph-proposal.md``. + +Phase 1 is intentionally a pure data layer: + + - frozen dataclasses with immutable collections, + - deterministic symbol allocation, + - refusal-first construction (typed ``BindingGraphError``), + - no I/O, no parser calls, no algebra calls, no numpy, + - no coupling to ``generate.math_symbolic_normalizer.Polynomial``; + symbolic expressions are referenced by canonical string form only. + +Phases 2-5 (adapter, unit-aware binding, question target binding, bounded +grammar integration) are deferred to follow-up PRs. +""" + +from __future__ import annotations + +from .allocation import allocate_symbols +from .model import ( + ADMISSIBILITY_STATUSES, + SEMANTIC_ROLES, + BindingGraphError, + BoundConstraint, + BoundEquation, + BoundFact, + BoundUnknown, + SemanticSymbolicBindingGraph, + SourceSpanLink, + SymbolBinding, +) + +__all__ = ( + "ADMISSIBILITY_STATUSES", + "SEMANTIC_ROLES", + "BindingGraphError", + "BoundConstraint", + "BoundEquation", + "BoundFact", + "BoundUnknown", + "SemanticSymbolicBindingGraph", + "SourceSpanLink", + "SymbolBinding", + "allocate_symbols", +) diff --git a/generate/binding_graph/allocation.py b/generate/binding_graph/allocation.py new file mode 100644 index 00000000..5e06a16b --- /dev/null +++ b/generate/binding_graph/allocation.py @@ -0,0 +1,108 @@ +"""ADR-0132 — Deterministic symbol allocator (Phase 1). + +Given a sorted iterable of natural-language noun-phrases plus a single +source span anchoring them, return a stable ``tuple[SymbolBinding, ...]`` +in the same order. Identical input → identical output, byte-for-byte. + +This is the smallest useful allocator: pure transformation, no parsing, +no entity resolution. Phases 2+ will layer entity/unit inference on top. +""" + +from __future__ import annotations + +import re +from collections.abc import Iterable + +from .model import BindingGraphError, SEMANTIC_ROLES, SourceSpanLink, SymbolBinding + +_SLUG_NON_ALNUM = re.compile(r"[^a-z0-9]+") + + +def _slugify(phrase: str) -> str: + """Lowercase ASCII slug. Non-alphanumeric runs collapse to ``_``.""" + lowered = phrase.strip().lower() + slug = _SLUG_NON_ALNUM.sub("_", lowered).strip("_") + return slug + + +def allocate_symbols( + noun_phrases: Iterable[str], + *, + source_span: SourceSpanLink, + introduced_by: str, + semantic_role: str = "quantity", + prefix: str = "sym", +) -> tuple[SymbolBinding, ...]: + """Allocate a deterministic ``tuple[SymbolBinding, ...]``. + + ``noun_phrases`` is consumed in given order. Caller is responsible + for sorting if order-stability across input shapes is required — + this function preserves the order it is handed. + + Symbol ids follow ``{prefix}_{slug}_{index:03d}``. The numeric + suffix disambiguates duplicate slugs (e.g. two empty phrases would + refuse — see below — but two phrases that slugify the same are + legal and disambiguated by position). + + Refuses on: + - empty iterable, + - any phrase that slugifies to the empty string, + - duplicate symbol_id collisions (cannot occur given the indexed + suffix; defensive check retained). + """ + if semantic_role not in SEMANTIC_ROLES: + raise BindingGraphError( + f"allocate_symbols.semantic_role must be one of " + f"{sorted(SEMANTIC_ROLES)}; got {semantic_role!r}" + ) + if not isinstance(introduced_by, str) or introduced_by == "": + raise BindingGraphError( + "allocate_symbols.introduced_by must be a non-empty str" + ) + if not isinstance(prefix, str) or not prefix.isidentifier(): + raise BindingGraphError( + f"allocate_symbols.prefix must be a Python identifier; " + f"got {prefix!r}" + ) + if not isinstance(source_span, SourceSpanLink): + raise BindingGraphError( + "allocate_symbols.source_span must be a SourceSpanLink" + ) + + phrases = tuple(noun_phrases) + if not phrases: + raise BindingGraphError( + "allocate_symbols requires at least one noun-phrase" + ) + + bindings: list[SymbolBinding] = [] + seen_ids: set[str] = set() + for index, phrase in enumerate(phrases): + if not isinstance(phrase, str) or phrase.strip() == "": + raise BindingGraphError( + f"allocate_symbols phrase at index {index} must be a " + f"non-empty str; got {phrase!r}" + ) + slug = _slugify(phrase) + if slug == "": + raise BindingGraphError( + f"allocate_symbols phrase at index {index} slugifies to " + f"empty; got {phrase!r}" + ) + symbol_id = f"{prefix}_{slug}_{index:03d}" + if symbol_id in seen_ids: + raise BindingGraphError( + f"allocate_symbols produced duplicate symbol_id " + f"{symbol_id!r} (this should not happen)" + ) + seen_ids.add(symbol_id) + bindings.append( + SymbolBinding( + symbol_id=symbol_id, + name=phrase.strip(), + semantic_role=semantic_role, + source_span=source_span, + introduced_by=introduced_by, + ) + ) + return tuple(bindings) diff --git a/generate/binding_graph/model.py b/generate/binding_graph/model.py new file mode 100644 index 00000000..b3d36ad0 --- /dev/null +++ b/generate/binding_graph/model.py @@ -0,0 +1,454 @@ +"""ADR-0132 — Frozen data model for the Semantic-Symbolic Binding Graph. + +This module is the typed compiler boundary between natural language and +symbolic reasoning. It deliberately holds *only data* — no parser, no +solver, no algebra. Every dataclass is ``frozen=True, slots=True`` and +every collection field is an immutable ``tuple`` or ``frozenset``. + +Refusal-first: invalid construction raises ``BindingGraphError`` rather +than silently coercing. + +No coupling to ``Polynomial``: symbolic expressions are referenced by +their canonical *string* form (the byte-equality discriminator from +ADR-0131). This keeps the binding graph independent of the symbolic +substrate. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Final + +# --------------------------------------------------------------------------- +# Public errors +# --------------------------------------------------------------------------- + + +class BindingGraphError(ValueError): + """Raised on invalid binding-graph construction. + + Sibling of ``generate.math_symbolic_normalizer.SymbolicError``; + refusal-first by design, never silently coerces. + """ + + +# --------------------------------------------------------------------------- +# Closed vocabularies +# --------------------------------------------------------------------------- + +# Allowed semantic roles. Closed set; extend deliberately in a future ADR. +SEMANTIC_ROLES: Final[frozenset[str]] = frozenset( + { + "entity", + "quantity", + "rate", + "duration", + "count", + "total", + "difference", + "ratio", + "unknown", + } +) + +# Equation admissibility outcomes. ``"refused"`` requires ``refusal_reason``. +ADMISSIBILITY_STATUSES: Final[frozenset[str]] = frozenset( + {"admitted", "pending", "refused"} +) + + +def _require_non_empty_str(value: object, field_name: str) -> None: + if not isinstance(value, str) or value == "": + raise BindingGraphError( + f"{field_name} must be a non-empty str; got {value!r}" + ) + + +def _require_optional_str(value: object, field_name: str) -> None: + if value is not None and (not isinstance(value, str) or value == ""): + raise BindingGraphError( + f"{field_name} must be None or a non-empty str; got {value!r}" + ) + + +# --------------------------------------------------------------------------- +# SourceSpanLink +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class SourceSpanLink: + """An immutable pointer back to a slice of the original NL input. + + ``text`` is retained verbatim so downstream tooling can audit the + span without re-reading the source document. ``[start, end)`` is a + Python-style half-open interval over the source string. + """ + + source_id: str + start: int + end: int + text: str + + def __post_init__(self) -> None: + _require_non_empty_str(self.source_id, "SourceSpanLink.source_id") + if not isinstance(self.start, int) or isinstance(self.start, bool): + raise BindingGraphError( + f"SourceSpanLink.start must be int; got {self.start!r}" + ) + if not isinstance(self.end, int) or isinstance(self.end, bool): + raise BindingGraphError( + f"SourceSpanLink.end must be int; got {self.end!r}" + ) + if self.start < 0: + raise BindingGraphError( + f"SourceSpanLink.start must be >= 0; got {self.start}" + ) + if self.end <= self.start: + raise BindingGraphError( + f"SourceSpanLink.end must be > start; got start={self.start}, " + f"end={self.end}" + ) + if not isinstance(self.text, str) or self.text == "": + raise BindingGraphError( + f"SourceSpanLink.text must be a non-empty str; got {self.text!r}" + ) + + def to_canonical_string(self) -> str: + """Stable serialization for hashing / replay.""" + return f"{self.source_id}[{self.start}:{self.end}]" + + +# --------------------------------------------------------------------------- +# SymbolBinding +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class SymbolBinding: + """A single bound symbol: identifier + semantic context + provenance.""" + + symbol_id: str + name: str + semantic_role: str + source_span: SourceSpanLink + introduced_by: str + entity: str | None = None + unit: str | None = None + + def __post_init__(self) -> None: + _require_non_empty_str(self.symbol_id, "SymbolBinding.symbol_id") + if not self.symbol_id.isidentifier(): + raise BindingGraphError( + f"SymbolBinding.symbol_id must be a Python identifier; " + f"got {self.symbol_id!r}" + ) + _require_non_empty_str(self.name, "SymbolBinding.name") + if self.semantic_role not in SEMANTIC_ROLES: + raise BindingGraphError( + f"SymbolBinding.semantic_role must be one of " + f"{sorted(SEMANTIC_ROLES)}; got {self.semantic_role!r}" + ) + if not isinstance(self.source_span, SourceSpanLink): + raise BindingGraphError( + "SymbolBinding.source_span must be a SourceSpanLink; " + f"got {type(self.source_span).__name__}" + ) + _require_non_empty_str(self.introduced_by, "SymbolBinding.introduced_by") + _require_optional_str(self.entity, "SymbolBinding.entity") + _require_optional_str(self.unit, "SymbolBinding.unit") + + +# --------------------------------------------------------------------------- +# BoundFact +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class BoundFact: + """A grounded fact: ``symbol_id = value [unit]`` lifted from language.""" + + symbol_id: str + value: str + source_span: SourceSpanLink + unit: str | None = None + + def __post_init__(self) -> None: + _require_non_empty_str(self.symbol_id, "BoundFact.symbol_id") + if not self.symbol_id.isidentifier(): + raise BindingGraphError( + f"BoundFact.symbol_id must be a Python identifier; " + f"got {self.symbol_id!r}" + ) + _require_non_empty_str(self.value, "BoundFact.value") + if not isinstance(self.source_span, SourceSpanLink): + raise BindingGraphError( + "BoundFact.source_span must be a SourceSpanLink" + ) + _require_optional_str(self.unit, "BoundFact.unit") + + +# --------------------------------------------------------------------------- +# BoundEquation +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class BoundEquation: + """A derived symbolic relation with provenance. + + ``lhs_symbol_id`` is the symbol being defined. ``rhs_canonical`` is + the right-hand side as a canonical *string* — the binding graph + deliberately does not import ``Polynomial`` (decoupling layer). + + ``dependencies`` is the (immutable) set of symbols the rhs reads. + """ + + lhs_symbol_id: str + rhs_canonical: str + dependencies: frozenset[str] + operation_kind: str + unit_proof: str + admissibility_status: str + source_span: SourceSpanLink + refusal_reason: str | None = None + + def __post_init__(self) -> None: + _require_non_empty_str(self.lhs_symbol_id, "BoundEquation.lhs_symbol_id") + if not self.lhs_symbol_id.isidentifier(): + raise BindingGraphError( + f"BoundEquation.lhs_symbol_id must be a Python identifier; " + f"got {self.lhs_symbol_id!r}" + ) + _require_non_empty_str(self.rhs_canonical, "BoundEquation.rhs_canonical") + if not isinstance(self.dependencies, frozenset): + raise BindingGraphError( + "BoundEquation.dependencies must be a frozenset; " + f"got {type(self.dependencies).__name__}" + ) + for dep in self.dependencies: + if not isinstance(dep, str) or not dep.isidentifier(): + raise BindingGraphError( + f"BoundEquation.dependencies entries must be identifier " + f"strs; got {dep!r}" + ) + _require_non_empty_str(self.operation_kind, "BoundEquation.operation_kind") + _require_non_empty_str(self.unit_proof, "BoundEquation.unit_proof") + if self.admissibility_status not in ADMISSIBILITY_STATUSES: + raise BindingGraphError( + f"BoundEquation.admissibility_status must be one of " + f"{sorted(ADMISSIBILITY_STATUSES)}; " + f"got {self.admissibility_status!r}" + ) + if not isinstance(self.source_span, SourceSpanLink): + raise BindingGraphError( + "BoundEquation.source_span must be a SourceSpanLink" + ) + if self.admissibility_status == "refused": + if not ( + isinstance(self.refusal_reason, str) and self.refusal_reason != "" + ): + raise BindingGraphError( + "BoundEquation.refusal_reason is required when " + "admissibility_status == 'refused'" + ) + else: + if self.refusal_reason is not None: + raise BindingGraphError( + "BoundEquation.refusal_reason must be None unless " + "admissibility_status == 'refused'" + ) + + +# --------------------------------------------------------------------------- +# BoundUnknown +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class BoundUnknown: + """The target of the question, bound to a known symbol.""" + + symbol_id: str + question_span: SourceSpanLink + expected_unit: str | None = None + + def __post_init__(self) -> None: + _require_non_empty_str(self.symbol_id, "BoundUnknown.symbol_id") + if not self.symbol_id.isidentifier(): + raise BindingGraphError( + f"BoundUnknown.symbol_id must be a Python identifier; " + f"got {self.symbol_id!r}" + ) + if not isinstance(self.question_span, SourceSpanLink): + raise BindingGraphError( + "BoundUnknown.question_span must be a SourceSpanLink" + ) + _require_optional_str(self.expected_unit, "BoundUnknown.expected_unit") + + +# --------------------------------------------------------------------------- +# BoundConstraint +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class BoundConstraint: + """A predicate restricting a symbol's admissible values. + + ``predicate`` is a canonical *string* (e.g. ``"x >= 0"``). Like + ``BoundEquation.rhs_canonical``, this avoids importing the symbolic + substrate. + """ + + symbol_id: str + predicate: str + source_span: SourceSpanLink + + def __post_init__(self) -> None: + _require_non_empty_str(self.symbol_id, "BoundConstraint.symbol_id") + if not self.symbol_id.isidentifier(): + raise BindingGraphError( + f"BoundConstraint.symbol_id must be a Python identifier; " + f"got {self.symbol_id!r}" + ) + _require_non_empty_str(self.predicate, "BoundConstraint.predicate") + if not isinstance(self.source_span, SourceSpanLink): + raise BindingGraphError( + "BoundConstraint.source_span must be a SourceSpanLink" + ) + + +# --------------------------------------------------------------------------- +# SemanticSymbolicBindingGraph +# --------------------------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class SemanticSymbolicBindingGraph: + """Top-level immutable container. + + All five sub-collections are tuples (deterministic order is the + caller's responsibility — the model only enforces shape). + Cross-collection invariants enforced at construction: + + - every ``BoundFact.symbol_id`` references a known ``SymbolBinding``; + - every ``BoundEquation.lhs_symbol_id`` references a known symbol; + - every ``BoundEquation`` dependency references a known symbol; + - every ``BoundUnknown.symbol_id`` references a known symbol; + - every ``BoundConstraint.symbol_id`` references a known symbol; + - ``symbols`` carries unique ``symbol_id`` values. + """ + + symbols: tuple[SymbolBinding, ...] = field(default_factory=tuple) + facts: tuple[BoundFact, ...] = field(default_factory=tuple) + equations: tuple[BoundEquation, ...] = field(default_factory=tuple) + unknowns: tuple[BoundUnknown, ...] = field(default_factory=tuple) + constraints: tuple[BoundConstraint, ...] = field(default_factory=tuple) + provenance: tuple[SourceSpanLink, ...] = field(default_factory=tuple) + + def __post_init__(self) -> None: + for name, value, item_type in ( + ("symbols", self.symbols, SymbolBinding), + ("facts", self.facts, BoundFact), + ("equations", self.equations, BoundEquation), + ("unknowns", self.unknowns, BoundUnknown), + ("constraints", self.constraints, BoundConstraint), + ("provenance", self.provenance, SourceSpanLink), + ): + if not isinstance(value, tuple): + raise BindingGraphError( + f"SemanticSymbolicBindingGraph.{name} must be a tuple; " + f"got {type(value).__name__}" + ) + for item in value: + if not isinstance(item, item_type): + raise BindingGraphError( + f"SemanticSymbolicBindingGraph.{name} entries must be " + f"{item_type.__name__}; got {type(item).__name__}" + ) + + known_ids: set[str] = set() + for sym in self.symbols: + if sym.symbol_id in known_ids: + raise BindingGraphError( + f"Duplicate SymbolBinding.symbol_id: {sym.symbol_id!r}" + ) + known_ids.add(sym.symbol_id) + + for fact in self.facts: + if fact.symbol_id not in known_ids: + raise BindingGraphError( + f"BoundFact references unknown symbol_id " + f"{fact.symbol_id!r}" + ) + + for eq in self.equations: + if eq.lhs_symbol_id not in known_ids: + raise BindingGraphError( + f"BoundEquation references unknown lhs_symbol_id " + f"{eq.lhs_symbol_id!r}" + ) + for dep in eq.dependencies: + if dep not in known_ids: + raise BindingGraphError( + f"BoundEquation references unknown dependency " + f"{dep!r} (lhs={eq.lhs_symbol_id!r})" + ) + + for unk in self.unknowns: + if unk.symbol_id not in known_ids: + raise BindingGraphError( + f"BoundUnknown references unknown symbol_id " + f"{unk.symbol_id!r}" + ) + + for con in self.constraints: + if con.symbol_id not in known_ids: + raise BindingGraphError( + f"BoundConstraint references unknown symbol_id " + f"{con.symbol_id!r}" + ) + + def to_canonical_string(self) -> str: + """Deterministic string serialization for stable hashing. + + Sub-collections are emitted in *given* (caller-supplied) order; + the binding graph is identity-preserving by design. + """ + lines: list[str] = [] + for sym in self.symbols: + lines.append( + f"S {sym.symbol_id} {sym.name} {sym.semantic_role} " + f"entity={sym.entity} unit={sym.unit} " + f"span={sym.source_span.to_canonical_string()} " + f"by={sym.introduced_by}" + ) + for fact in self.facts: + lines.append( + f"F {fact.symbol_id} = {fact.value} unit={fact.unit} " + f"span={fact.source_span.to_canonical_string()}" + ) + for eq in self.equations: + deps = ",".join(sorted(eq.dependencies)) + lines.append( + f"E {eq.lhs_symbol_id} := {eq.rhs_canonical} " + f"op={eq.operation_kind} deps=[{deps}] " + f"unit_proof={eq.unit_proof} " + f"status={eq.admissibility_status} " + f"refusal={eq.refusal_reason} " + f"span={eq.source_span.to_canonical_string()}" + ) + for unk in self.unknowns: + lines.append( + f"U {unk.symbol_id} expected_unit={unk.expected_unit} " + f"qspan={unk.question_span.to_canonical_string()}" + ) + for con in self.constraints: + lines.append( + f"C {con.symbol_id} pred={con.predicate} " + f"span={con.source_span.to_canonical_string()}" + ) + for span in self.provenance: + lines.append(f"P {span.to_canonical_string()} text={span.text}") + return "\n".join(lines) diff --git a/tests/test_binding_graph_model.py b/tests/test_binding_graph_model.py new file mode 100644 index 00000000..e5277b4a --- /dev/null +++ b/tests/test_binding_graph_model.py @@ -0,0 +1,553 @@ +"""ADR-0132 — Tests for the Semantic-Symbolic Binding Graph data model. + +Covers: + - frozen / slots invariants (no field mutation, no attribute injection), + - construction-time refusals (typed BindingGraphError), + - cross-collection invariants on SemanticSymbolicBindingGraph, + - allocation determinism (byte-equal under replay), + - canonical string round-trip / stability. + +Pure data layer — no runtime, no parser, no algebra imports. +""" + +from __future__ import annotations + +import dataclasses + +import pytest + +from generate.binding_graph import ( + ADMISSIBILITY_STATUSES, + SEMANTIC_ROLES, + BindingGraphError, + BoundConstraint, + BoundEquation, + BoundFact, + BoundUnknown, + SemanticSymbolicBindingGraph, + SourceSpanLink, + SymbolBinding, + allocate_symbols, +) + + +# --------------------------------------------------------------------------- +# Fixtures / helpers +# --------------------------------------------------------------------------- + + +def _span( + *, source_id: str = "src1", start: int = 0, end: int = 5, text: str = "hello" +) -> SourceSpanLink: + return SourceSpanLink(source_id=source_id, start=start, end=end, text=text) + + +def _sym( + symbol_id: str = "sym_x_000", + *, + name: str = "x", + role: str = "quantity", + entity: str | None = None, + unit: str | None = None, +) -> SymbolBinding: + return SymbolBinding( + symbol_id=symbol_id, + name=name, + semantic_role=role, + source_span=_span(), + introduced_by="test", + entity=entity, + unit=unit, + ) + + +# --------------------------------------------------------------------------- +# Closed-vocabulary contracts +# --------------------------------------------------------------------------- + + +def test_semantic_roles_is_frozenset_and_closed() -> None: + assert isinstance(SEMANTIC_ROLES, frozenset) + assert "quantity" in SEMANTIC_ROLES + assert "unknown" in SEMANTIC_ROLES + # Closed vocabulary — adding new roles is a deliberate ADR change. + assert SEMANTIC_ROLES == { + "entity", "quantity", "rate", "duration", "count", + "total", "difference", "ratio", "unknown", + } + + +def test_admissibility_statuses_closed_set() -> None: + assert ADMISSIBILITY_STATUSES == {"admitted", "pending", "refused"} + + +# --------------------------------------------------------------------------- +# SourceSpanLink +# --------------------------------------------------------------------------- + + +def test_source_span_link_basic_construction() -> None: + span = SourceSpanLink(source_id="doc", start=3, end=8, text="apple") + assert span.text == "apple" + assert span.to_canonical_string() == "doc[3:8]" + + +def test_source_span_link_is_frozen() -> None: + span = _span() + with pytest.raises(dataclasses.FrozenInstanceError): + span.start = 99 # type: ignore[misc] + + +def test_source_span_link_refuses_empty_text() -> None: + with pytest.raises(BindingGraphError): + SourceSpanLink(source_id="doc", start=0, end=4, text="") + + +def test_source_span_link_refuses_empty_source_id() -> None: + with pytest.raises(BindingGraphError): + SourceSpanLink(source_id="", start=0, end=4, text="hi") + + +def test_source_span_link_refuses_negative_start() -> None: + with pytest.raises(BindingGraphError): + SourceSpanLink(source_id="d", start=-1, end=4, text="hi") + + +def test_source_span_link_refuses_end_le_start() -> None: + with pytest.raises(BindingGraphError): + SourceSpanLink(source_id="d", start=5, end=5, text="hi") + with pytest.raises(BindingGraphError): + SourceSpanLink(source_id="d", start=5, end=2, text="hi") + + +def test_source_span_link_refuses_bool_start() -> None: + # bool is a subclass of int — must refuse explicitly. + with pytest.raises(BindingGraphError): + SourceSpanLink(source_id="d", start=True, end=4, text="hi") # type: ignore[arg-type] + + +def test_source_span_link_equality_and_hash() -> None: + a = _span() + b = _span() + assert a == b + assert hash(a) == hash(b) + assert {a, b} == {a} + + +# --------------------------------------------------------------------------- +# SymbolBinding +# --------------------------------------------------------------------------- + + +def test_symbol_binding_basic_construction() -> None: + sym = _sym() + assert sym.symbol_id == "sym_x_000" + assert sym.entity is None + assert sym.unit is None + + +def test_symbol_binding_is_frozen() -> None: + sym = _sym() + with pytest.raises(dataclasses.FrozenInstanceError): + sym.name = "y" # type: ignore[misc] + + +def test_symbol_binding_uses_slots() -> None: + sym = _sym() + with pytest.raises((AttributeError, dataclasses.FrozenInstanceError)): + sym.extra = "nope" # type: ignore[attr-defined] + + +def test_symbol_binding_refuses_non_identifier_symbol_id() -> None: + with pytest.raises(BindingGraphError): + _sym(symbol_id="not an identifier") + + +def test_symbol_binding_refuses_empty_symbol_id() -> None: + with pytest.raises(BindingGraphError): + _sym(symbol_id="") + + +def test_symbol_binding_refuses_unknown_role() -> None: + with pytest.raises(BindingGraphError): + _sym(role="velocity") + + +@pytest.mark.parametrize("role", sorted(SEMANTIC_ROLES)) +def test_symbol_binding_accepts_every_documented_role(role: str) -> None: + sym = _sym(role=role) + assert sym.semantic_role == role + + +def test_symbol_binding_refuses_non_span_source() -> None: + with pytest.raises(BindingGraphError): + SymbolBinding( + symbol_id="x", + name="x", + semantic_role="quantity", + source_span="not-a-span", # type: ignore[arg-type] + introduced_by="t", + ) + + +def test_symbol_binding_optional_entity_unit() -> None: + sym = _sym(entity="Tina", unit="dollars/hour") + assert sym.entity == "Tina" + assert sym.unit == "dollars/hour" + + +def test_symbol_binding_refuses_empty_unit_string() -> None: + with pytest.raises(BindingGraphError): + _sym(unit="") + + +# --------------------------------------------------------------------------- +# BoundFact +# --------------------------------------------------------------------------- + + +def test_bound_fact_construction_and_frozen() -> None: + fact = BoundFact( + symbol_id="sym_x_000", value="5", source_span=_span(), unit="apples" + ) + assert fact.value == "5" + with pytest.raises(dataclasses.FrozenInstanceError): + fact.value = "6" # type: ignore[misc] + + +def test_bound_fact_refuses_non_identifier_symbol_id() -> None: + with pytest.raises(BindingGraphError): + BoundFact(symbol_id="not id", value="5", source_span=_span()) + + +def test_bound_fact_refuses_empty_value() -> None: + with pytest.raises(BindingGraphError): + BoundFact(symbol_id="sym_x_000", value="", source_span=_span()) + + +# --------------------------------------------------------------------------- +# BoundEquation +# --------------------------------------------------------------------------- + + +def _eq(**overrides: object) -> BoundEquation: + defaults: dict[str, object] = dict( + lhs_symbol_id="sym_y_000", + rhs_canonical="sym_x_000+1", + dependencies=frozenset({"sym_x_000"}), + operation_kind="affine", + unit_proof="apples == apples", + admissibility_status="admitted", + source_span=_span(), + ) + defaults.update(overrides) + return BoundEquation(**defaults) # type: ignore[arg-type] + + +def test_bound_equation_admitted_basic() -> None: + eq = _eq() + assert eq.refusal_reason is None + assert "sym_x_000" in eq.dependencies + + +def test_bound_equation_refused_requires_reason() -> None: + with pytest.raises(BindingGraphError): + _eq(admissibility_status="refused") + + +def test_bound_equation_refused_with_reason_ok() -> None: + eq = _eq(admissibility_status="refused", refusal_reason="unit mismatch") + assert eq.refusal_reason == "unit mismatch" + + +def test_bound_equation_non_refused_must_have_no_reason() -> None: + with pytest.raises(BindingGraphError): + _eq(admissibility_status="admitted", refusal_reason="nope") + + +def test_bound_equation_refuses_bad_status() -> None: + with pytest.raises(BindingGraphError): + _eq(admissibility_status="approved") + + +def test_bound_equation_refuses_mutable_dependency_set() -> None: + with pytest.raises(BindingGraphError): + _eq(dependencies={"sym_x_000"}) # type: ignore[arg-type] + + +def test_bound_equation_refuses_non_identifier_dependency() -> None: + with pytest.raises(BindingGraphError): + _eq(dependencies=frozenset({"bad id"})) + + +def test_bound_equation_refuses_non_identifier_lhs() -> None: + with pytest.raises(BindingGraphError): + _eq(lhs_symbol_id="bad lhs") + + +def test_bound_equation_is_frozen() -> None: + eq = _eq() + with pytest.raises(dataclasses.FrozenInstanceError): + eq.rhs_canonical = "other" # type: ignore[misc] + + +# --------------------------------------------------------------------------- +# BoundUnknown +# --------------------------------------------------------------------------- + + +def test_bound_unknown_construction() -> None: + unk = BoundUnknown( + symbol_id="sym_y_000", question_span=_span(), expected_unit="dollars" + ) + assert unk.expected_unit == "dollars" + + +def test_bound_unknown_refuses_bad_id() -> None: + with pytest.raises(BindingGraphError): + BoundUnknown(symbol_id="bad id", question_span=_span()) + + +def test_bound_unknown_refuses_non_span_question() -> None: + with pytest.raises(BindingGraphError): + BoundUnknown(symbol_id="sym_y_000", question_span="text") # type: ignore[arg-type] + + +# --------------------------------------------------------------------------- +# BoundConstraint +# --------------------------------------------------------------------------- + + +def test_bound_constraint_construction() -> None: + con = BoundConstraint( + symbol_id="sym_x_000", predicate="x >= 0", source_span=_span() + ) + assert con.predicate == "x >= 0" + + +def test_bound_constraint_refuses_empty_predicate() -> None: + with pytest.raises(BindingGraphError): + BoundConstraint( + symbol_id="sym_x_000", predicate="", source_span=_span() + ) + + +# --------------------------------------------------------------------------- +# SemanticSymbolicBindingGraph +# --------------------------------------------------------------------------- + + +def test_graph_empty_construction() -> None: + g = SemanticSymbolicBindingGraph() + assert g.symbols == () + assert g.facts == () + assert g.equations == () + assert g.unknowns == () + assert g.constraints == () + assert g.provenance == () + + +def test_graph_rejects_list_for_symbols() -> None: + with pytest.raises(BindingGraphError): + SemanticSymbolicBindingGraph(symbols=[_sym()]) # type: ignore[arg-type] + + +def test_graph_rejects_duplicate_symbol_id() -> None: + a = _sym("sym_x_000") + b = _sym("sym_x_000") + with pytest.raises(BindingGraphError): + SemanticSymbolicBindingGraph(symbols=(a, b)) + + +def test_graph_rejects_fact_referencing_unknown_symbol() -> None: + fact = BoundFact(symbol_id="sym_ghost_000", value="1", source_span=_span()) + with pytest.raises(BindingGraphError): + SemanticSymbolicBindingGraph(symbols=(_sym(),), facts=(fact,)) + + +def test_graph_rejects_equation_referencing_unknown_lhs() -> None: + eq = _eq(lhs_symbol_id="sym_ghost_000") + with pytest.raises(BindingGraphError): + SemanticSymbolicBindingGraph(symbols=(_sym(),), equations=(eq,)) + + +def test_graph_rejects_equation_with_unknown_dependency() -> None: + eq = _eq(dependencies=frozenset({"sym_ghost_000"})) + with pytest.raises(BindingGraphError): + SemanticSymbolicBindingGraph( + symbols=(_sym("sym_y_000"),), equations=(eq,) + ) + + +def test_graph_rejects_unknown_referencing_missing_symbol() -> None: + unk = BoundUnknown(symbol_id="sym_ghost_000", question_span=_span()) + with pytest.raises(BindingGraphError): + SemanticSymbolicBindingGraph(symbols=(_sym(),), unknowns=(unk,)) + + +def test_graph_rejects_constraint_referencing_missing_symbol() -> None: + con = BoundConstraint( + symbol_id="sym_ghost_000", predicate="x >= 0", source_span=_span() + ) + with pytest.raises(BindingGraphError): + SemanticSymbolicBindingGraph(symbols=(_sym(),), constraints=(con,)) + + +def test_graph_full_round_trip_canonical_string_stable() -> None: + syms = ( + _sym("sym_x_000", name="x"), + _sym("sym_y_000", name="y", role="unknown"), + ) + facts = ( + BoundFact(symbol_id="sym_x_000", value="5", source_span=_span(), unit="apples"), + ) + eqs = (_eq(),) + unks = (BoundUnknown(symbol_id="sym_y_000", question_span=_span()),) + cons = ( + BoundConstraint(symbol_id="sym_x_000", predicate="x >= 0", source_span=_span()), + ) + g1 = SemanticSymbolicBindingGraph( + symbols=syms, facts=facts, equations=eqs, unknowns=unks, constraints=cons + ) + g2 = SemanticSymbolicBindingGraph( + symbols=syms, facts=facts, equations=eqs, unknowns=unks, constraints=cons + ) + assert g1.to_canonical_string() == g2.to_canonical_string() + assert g1 == g2 + + +def test_graph_is_frozen() -> None: + g = SemanticSymbolicBindingGraph() + with pytest.raises(dataclasses.FrozenInstanceError): + g.symbols = (_sym(),) # type: ignore[misc] + + +def test_graph_canonical_string_order_sensitive() -> None: + a = _sym("sym_a_000", name="a") + b = _sym("sym_b_000", name="b") + g_ab = SemanticSymbolicBindingGraph(symbols=(a, b)) + g_ba = SemanticSymbolicBindingGraph(symbols=(b, a)) + # Caller controls order — identity-preserving by design. + assert g_ab.to_canonical_string() != g_ba.to_canonical_string() + + +# --------------------------------------------------------------------------- +# allocate_symbols — determinism +# --------------------------------------------------------------------------- + + +def test_allocate_symbols_basic() -> None: + span = _span() + out = allocate_symbols( + ("Tina", "wage", "hours"), source_span=span, introduced_by="parser_v1" + ) + assert len(out) == 3 + assert tuple(s.symbol_id for s in out) == ( + "sym_tina_000", "sym_wage_001", "sym_hours_002", + ) + assert all(isinstance(s, SymbolBinding) for s in out) + assert out[0].source_span == span + + +def test_allocate_symbols_is_deterministic_across_calls() -> None: + span = _span() + a = allocate_symbols( + ("alpha", "beta", "gamma"), source_span=span, introduced_by="t" + ) + b = allocate_symbols( + ("alpha", "beta", "gamma"), source_span=span, introduced_by="t" + ) + assert a == b + assert tuple(s.symbol_id for s in a) == tuple(s.symbol_id for s in b) + + +def test_allocate_symbols_disambiguates_collisions_by_index() -> None: + out = allocate_symbols( + ("price", "Price", "PRICE"), + source_span=_span(), + introduced_by="t", + ) + ids = tuple(s.symbol_id for s in out) + assert ids == ("sym_price_000", "sym_price_001", "sym_price_002") + assert len(set(ids)) == 3 + + +def test_allocate_symbols_slugifies_non_ascii_whitespace() -> None: + out = allocate_symbols( + ("dollars per hour", " spaced "), + source_span=_span(), + introduced_by="t", + ) + assert out[0].symbol_id == "sym_dollars_per_hour_000" + assert out[1].symbol_id == "sym_spaced_001" + assert out[1].name == "spaced" + + +def test_allocate_symbols_refuses_empty_iterable() -> None: + with pytest.raises(BindingGraphError): + allocate_symbols((), source_span=_span(), introduced_by="t") + + +def test_allocate_symbols_refuses_empty_phrase() -> None: + with pytest.raises(BindingGraphError): + allocate_symbols( + ("ok", " "), source_span=_span(), introduced_by="t" + ) + + +def test_allocate_symbols_refuses_unslugifiable_phrase() -> None: + with pytest.raises(BindingGraphError): + allocate_symbols( + ("ok", "!!!"), source_span=_span(), introduced_by="t" + ) + + +def test_allocate_symbols_refuses_unknown_role() -> None: + with pytest.raises(BindingGraphError): + allocate_symbols( + ("x",), + source_span=_span(), + introduced_by="t", + semantic_role="velocity", + ) + + +def test_allocate_symbols_refuses_bad_prefix() -> None: + with pytest.raises(BindingGraphError): + allocate_symbols( + ("x",), + source_span=_span(), + introduced_by="t", + prefix="not id", + ) + + +def test_allocate_symbols_refuses_empty_introduced_by() -> None: + with pytest.raises(BindingGraphError): + allocate_symbols(("x",), source_span=_span(), introduced_by="") + + +def test_allocate_symbols_role_threaded_through() -> None: + out = allocate_symbols( + ("earnings",), + source_span=_span(), + introduced_by="t", + semantic_role="total", + ) + assert out[0].semantic_role == "total" + + +def test_allocate_symbols_into_graph_round_trip() -> None: + syms = allocate_symbols( + ("apples", "oranges"), source_span=_span(), introduced_by="t" + ) + g = SemanticSymbolicBindingGraph(symbols=syms) + # Round trip through canonical string twice must be byte-equal. + s1 = g.to_canonical_string() + s2 = SemanticSymbolicBindingGraph(symbols=syms).to_canonical_string() + assert s1 == s2 + + +def test_allocate_symbols_returns_tuple() -> None: + out = allocate_symbols(("x",), source_span=_span(), introduced_by="t") + assert isinstance(out, tuple)