core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/tests/test_binding_graph_model.py
Shay 3b30eb248a
feat(binding-graph): Phase 4 question-target binding (ADR-0135) (#179) 
Refines BoundUnknown from "the symbol whose value the solver determines"
to "the symbol at a specific temporal/state index with a specific
question-form". Two new required fields on BoundUnknown — state_index
(initial/terminal/Operation(operation_index)) and question_form
(count/rate/total/difference/ratio/identity) — populated by the new
pure-function resolver in generate/binding_graph/question_target.py.

The adapter (ADR-0133) now delegates Unknown -> BoundUnknown construction
to bound_unknown_from_math_problem_graph. No runtime wiring, no solver
invocation. Phase 5 (bounded-grammar / B3 integration) remains deferred.

Refusal-first via the new QuestionTargetError (sibling of AdapterError /
AdmissibilityError). Closed reason vocab: not_a_math_problem_graph,
unknown_entity_not_in_entities, apply_rate_unit_mismatch,
unmappable_question_form. Closed precedence rule on question_form
documented in ADR-0135 (compare_multiplicative > compare_additive >
apply_rate{numerator|denominator unit-match} > count); ambiguity refuses.

SemanticSymbolicBindingGraph.__post_init__ gains a cross-collection
guard: Operation(operation_index) must satisfy operation_index <
len(equations). canonical_string emission widened to include
state=... form=... tokens (hash differs from Phase 3 main by design —
not a regression; byte-equal across runs preserved).

Parents: ADR-0132 / ADR-0133 / ADR-0134.

Tests: +70 new (45 unit in test_binding_graph_question_target.py +
25 integration in test_binding_graph_adapter_question_target.py); 5
Phase 1+3 BoundUnknown fixtures migrated. Total binding-graph lane
295/1 pass (1 pre-existing test_symbol_binding_uses_slots failure on
Python 3.14, unrelated to Phase 4 — exists on origin/main). Pyright
clean on new and modified files. No edits to algebra/, chat/, core/,
or runtime hot path. Field invariant untouched.
2026-05-23 11:24:49 -07:00

579 lines
18 KiB
Python
Raw Blame History

"""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(),
state_index="terminal",
question_form="count",
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(),
state_index="terminal",
question_form="count",
)
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]
state_index="terminal",
question_form="count",
)
# ---------------------------------------------------------------------------
# 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(),
state_index="terminal",
question_form="count",
)
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(),
state_index="terminal",
question_form="count",
),
)
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)
Reference in a new issue View git blame Copy permalink