refactor phase 2: typed errors, shared primitives, fail-closed pruning (SCC 13 → 10)

[hussainsultan]

Phase 2 of the SCC-driven refactor, stacked on #296. Theme: one implementation per primitive, and errors that say what went wrong. Full suite green (1693 passed, pytest exit 0).

Typed exception hierarchy + contextful errors

New bottom-layer errors.py: BSLError → DefinitionError / QueryError / UnknownFieldError / CompilationError / SerializationError / BackendError, exported from the package root. Each subclass also inherits the stdlib exception it replaces (ValueError/KeyError/RuntimeError), so existing except clauses and tests keep working through the migration.

Every .unwrap() on a returns.Result in yaml.py and query.py now goes through unwrap_or_raise, which names the model field and expression and chains the original exception. The worst error in the audit is gone:

• before: UnwrapFailedError: (no message)
• after: DefinitionError: Invalid expression for dimension 'b' ('_.b =='): Invalid Python syntax: ...

Typo suggestions are consolidated too: suggest / format_suggestions / suggest_kinded in errors.py replace the duplicated _typo_suggestion bodies in calc_compiler and measure_scope.

Correctness: join pruning now fails closed

When a measure or group key couldn't be analyzed for column requirements, the extractors silently contributed nothing — and a table whose only references were unanalyzable could be pruned from the join, silently changing results (audit finding). Analysis failures now require all columns (disabling pruning for that query) and log a warning naming the measure/key and cause. The dead parallel implementations in ops.py (TableColumnRequirements + both _extract_requirements_from_*, ~140 lines) are deleted — projection_utils.TableRequirements was the live path all along, so one requirements type remains.

Remaining silent fallbacks on correctness paths now log: the xorq-conversion fallback in _ensure_xorq_table, the grain-cardinality analysis swallow in expr.py (which feeds the join_one→join_many upgrade decision), and the four guard-skipping continues in _reject_shadowed_group_keys.

Shared primitives

• fieldref.py (bottom layer, unit-tested): split_prefixed / suffix_matches / resolve_suffix replace the verbatim-duplicated _parse_prefixed_field (ops + projection_utils) and four hand-rolled unique-suffix resolvers (ops, calc_compiler ×2, measure_scope).
• _SourcePassThroughOp mixin: Filter/OrderBy/Limit/Unnest each hand-wrote identical values/schema/get_dimensions/get_measures/get_calculated_measures delegates; one mixin now carries the protocol (~90 lines of boilerplate gone). Project/GroupBy deliberately untouched — they never had the get_* protocol and gaining it silently would change behavior.

SCC: 13 → 10 modules

utils.py needed ops only to isinstance-check _CallableWrapper (now duck-typed on ._fn, with a _is_deferred guard — a Deferred synthesizes attribute access, so a naive getattr fallback built bogus ._fn nodes; caught by the serialization round-trip suite and fixed). graph_utils needed only CalcMeasure (duck-typed on depends_on). Cutting those frees projection_utils too. The bottom layer no longer depends on the compiler; the residual SCC is ops/expr/query/api/format + serialization/*.

Deliberately deferred to phase 3

ReductionKind classifier, the dimension-proxy consolidation (7 near-identical classes), the join-tree visitor, and the remaining ~40 broad handlers deep in the pre-agg compiler — those code regions get restructured wholesale in phase 3's _to_untagged_with_preagg decomposition, so consolidating them now would be churn against next phase's diff.

Verification

• python3 -m pytest src/boring_semantic_layer: 1693 passed, exit 0
• SCC ratchet shrunk 13 → 10 in the same commits as the cuts; ruff check / format --check clean
• New unit tests for fieldref; the one test pinning the old contentless UnwrapFailedError updated to assert the typed, contextful error

🤖 Generated with Claude Code