refactor phase 5: API surface — one query(), eager validation, YAML schema, no how=

[hussainsultan]

Phase 5 of the refactor, stacked on #301. Per maintainer direction this PR makes clean breaking changes (no deprecation shims) with tests, examples, and docs updated in-step. Full suite: 1743 passed, exit 0; make examples-core green; SQL snapshots byte-identical.

One query(), one compare_periods()

The four drifted copies (SemanticModel / SemanticJoin / SemanticFilter / op-level SemanticJoinOp — the last silently missing time_grains) are replaced by one documented implementation on the SemanticTable base. Every semantic expression now accepts the identical parameter set, and grouped/aggregated results gain .query()/.compare_periods() where they previously raised AttributeError.

Eager validation with suggestions

query() now fails at construction on unknown dimension/measure names:

• before: XorqTypeError: Column 'revenu' is not found in table. Existing columns: 'region', 'amount' — at execute, leaking physical columns
• after: UnknownFieldError: Unknown measure 'revenu'. Declared measures: ['revenue']. Did you mean: measure 'revenue'? — at construction

Raw table columns and unique suffix matches on joined models remain valid dimension spellings, so nothing legitimate got stricter.

YAML configs are schema-validated at load

The audit's silent-typo class is closed: dimension: / measurez: used to load as models with zero dimensions; they now raise DefinitionError naming the model, the key, and accepted spellings with did-you-mean hints. Field sections must be mappings, smallest_time_grain values are validated at load (not first query), and a non-left how: in a YAML join fails at load with the left-join+filter guidance.

how= is gone

join_one/join_many accepted how= only to raise for anything but "left" — dead surface. The parameter is removed from every wrapper, the op-level methods, YAML, and serialization reconstruction (stored how values are informational; semantic joins are always LEFT, join_cross carries how="cross" internally).

Worth reading in the diff: the removal sweep initially stripped how="left" from two pandas merge / raw-ibis join fixtures, which default to INNER — the soundness suites flagged the changed row counts immediately and those fixtures were restored untouched. That's the invariant suites doing exactly their job.

Namespace + protocol

• to_tagged/from_tagged move to boring_semantic_layer.serialization; the five graph_* helpers demote to boring_semantic_layer.graph_utils. to_untagged stays top-level (the documented plain-ibis escape hatch, used by examples).
• .name/.description are defined once on the SemanticTable base: aggregates/limits answer None instead of raising AttributeError: 'Table' object has no attribute 'name'.

Deferred (named, not forgotten)

Fluent time_grain/time_range/having methods (the JSON path — and now every expression's .query() — already provides them), index() returning an expression wrapper, StrEnums for grains/directions, and the full docstring pass over expr.py's public surface.

🤖 Generated with Claude Code