core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

feat(binding-graph): Phase 1 data model (ADR-0132) (#171)

Browse source 
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.
This commit is contained in:
Shay 2026-05-23 10:29:59 -07:00 committed by GitHub
parent e0ba6d677d
commit 980213ed62
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 1295 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

132
docs/decisions/ADR-0132-binding-graph-data-model.md Normal file
View file

@ -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.

48
generate/binding_graph/__init__.py Normal file
View file

@ -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",
)

108
generate/binding_graph/allocation.py Normal file
View file

@ -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)

454
generate/binding_graph/model.py Normal file
View file

@ -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)

553
tests/test_binding_graph_model.py Normal file
View file

@ -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)