Phase 34: registry API redesign — align/spine/sources + pairs() quickstart + namespace inversion (1.17.0)

.github/workflows/schema-drift.yml

@@ -18,13 +18,17 @@ on:
       - "packages/core/src/mostlyright/_internal/merge/**"
       - "packages/core/src/mostlyright/international.py"
       - "packages/core/src/mostlyright/qc.py"
+      - "packages/core/src/mostlyright/registry/**"
+      - "packages/core/src/mostlyright/contracts/**"
       - "packages/markets/src/mostlyright/markets/catalog/kalshi_stations.py"
       - "packages/markets/src/mostlyright/markets/_per_event_station.py"
       - "packages/markets/src/mostlyright/markets/polymarket_city_stations.json"
+      - "packages/weather/src/mostlyright/weather/**"
       - "scripts/export_schemas.py"
       - "schemas/**"
       - "packages-ts/codegen/**"
       - "packages-ts/*/src/**/generated/**"
+      - "packages-ts/weather/catalog.json"
       - ".github/workflows/schema-drift.yml"
   pull_request:
     paths:
@@ -34,13 +38,17 @@ on:
       - "packages/core/src/mostlyright/_internal/merge/**"
       - "packages/core/src/mostlyright/international.py"
       - "packages/core/src/mostlyright/qc.py"
+      - "packages/core/src/mostlyright/registry/**"
+      - "packages/core/src/mostlyright/contracts/**"
       - "packages/markets/src/mostlyright/markets/catalog/kalshi_stations.py"
       - "packages/markets/src/mostlyright/markets/_per_event_station.py"
       - "packages/markets/src/mostlyright/markets/polymarket_city_stations.json"
+      - "packages/weather/src/mostlyright/weather/**"
       - "scripts/export_schemas.py"
       - "schemas/**"
       - "packages-ts/codegen/**"
       - "packages-ts/*/src/**/generated/**"
+      - "packages-ts/weather/catalog.json"
       - ".github/workflows/schema-drift.yml"
 
 jobs:
@@ -80,7 +88,7 @@ jobs:
 
       - name: Check for schema or codegen drift
         run: |
-          if ! git diff --exit-code schemas/ packages-ts/*/src/**/generated/; then
+          if ! git diff --exit-code schemas/ packages-ts/*/src/**/generated/ packages-ts/weather/catalog.json; then
             echo "::error::Schema or codegen drift detected. Run 'uv run python scripts/export_schemas.py && pnpm codegen' locally and commit the result."
             exit 1
           fi

CHANGELOG.md

@@ -4,6 +4,106 @@ All notable changes to `mostlyright`. The format follows [Keep a Changelog](http
 
 ## [Unreleased]
 
+## [1.17.0] — 2026-07-14 — Registry API redesign: the `align` / `spine` / `sources` ladder + per-domain `pairs()`
+
+Minor release, dual-SDK (PyPI 1.17.0 + npm 1.17.0 in lockstep). Phase 34 answers
+the researcher feedback on the shipped composer ("too much magic — I can't tell a
+feature from the target at a call site; let me build the DataFrame myself") by
+splitting `dataset()`'s four fused concerns into **two orthogonal axes + one
+composition operator**: SOURCES (`mr.<domain>.<table>(entity, window)` → X),
+LABELS (`mr.<domain>.label.<name>(entity, window)` → a spine with `y`), and
+**`mr.align(spine, *sources)`** — a leakage-guarded as-of join frozen at two
+concepts. Every intermediate product is a plain, inspectable `pd.DataFrame`.
+
+**This release is additive-plus-shims. Nothing you run today breaks** — the
+default `research()` / `dataset()` output is byte-identical to 1.16 (live parity
+gate 5/5 byte-green), every relocated symbol keeps an importable
+`DeprecationWarning` shim, and **all 2.0 removals are DOCUMENTED only** (no shim
+removed this release; ≥2 minors of warning runway).
+
+Migration guide (where-did-each-kwarg-go table, the ladder, the symbol-move map,
+TypeScript-on-1.17, econ-unchanged): [`docs/migration/v117-align-spine-sources.md`](docs/migration/v117-align-spine-sources.md).
+
+### Added
+
+- **`mr.align(spine, *sources)` — the frozen composition operator (D-34.01..05).**
+  A pure collapse + as-of/equality join + **per-source leakage audit** so a
+  raised `LeakageError` names WHICH source leaked and never blames a clean
+  co-aligned source. Signature is exactly `(spine, *sources)` — all policy
+  (revision authority, `pit_fidelity`, staleness) lives on the source specs. The
+  bitemporal `SourceContract` (event_time + knowledge_time, `revision_order`
+  tie-break, schema id + version, per-column units, license flag, `pit_fidelity`,
+  `valid_from` coverage, native frequency, `availability py|ts`) EXPRESSES the
+  legacy climate dedup (`report_type_priority` STRICT `>`, first-seen-wins) with
+  no special case inside `align()` (Path A — the cheapest falsifier, run first).
+- **The LABEL / SPINE axis + raw spine constructors (D-34.09..12).** `mr.spine(df,
+  *, entity, decision_time, y)` (the BYO bridge; loud `ContractError` on a missing
+  mapped column, never guesses); `weather.days(stations, from_date, to_date, *,
+  tz_override=None)` (the public bare per-settlement-day spine; a list mints a
+  long-format panel byte-equal to the per-station loop); `weather.forecasts(entity,
+  ..., source="iem_mos", model=None, models=None)` (a registered bitemporal source
+  wrapping the shipped forecast join — the landing site for the four forecast
+  kwargs); and the `.label.`-registered spine factories `weather.label.cli()` /
+  `weather.label.daily_extremes()` / `markets.*.label.settlement()` (y columns
+  byte-identical to the recipes). A **spine is the primitive; a label is a spine
+  factory** over the same domain constructor, so train and trade share the
+  calendar-minting site (the structural fix for backtest/live settlement skew).
+- **Per-domain `pairs()` quickstart (D-34.21).** `weather.pairs(entity, from_date,
+  to_date, *, label="cli")` — capped at ≤5 params, two positional dates, a
+  docstring showing its own `weather.days()` → `weather.label.cli()` → `align()`
+  desugaring, and a visible **graduation error** naming spine+align (never a bare
+  `TypeError`) when you pass an unsupported kwarg. `markets.kalshi.pairs` /
+  `markets.polymarket.pairs` are the renamed delegators.
+- **Generalized `discover(text?, **filters)` (D-34.13/14).** Cross-domain catalog
+  search over the registration metadata (id/kind/domain/columns/units/availability/
+  license/PIT fidelity) with deterministic field-weighted token scoring (no fuzzy
+  dep), per-domain entity **alias resolvers** (`"nyc"` → KNYC/KLGA, preserving the
+  cross-venue settlement note), a runnable language-tagged `{py, ts}` `usage` per
+  row, and an `availability` runtime filter. Keyword-only `city=` still works.
+- **Cross-SDK `align()` conformance fixtures (D-34.14/25).** A shared four-axis
+  JSON suite (tie-break authority ⟂ arrival + first-seen tie, `<=` boundary
+  inclusivity, nanosecond precision, NaN preservation) under
+  `tests/fixtures/parity/conformance/`, driven as a HARD gate by Python against
+  the real join core and read by the identical fixtures from the TS suite. A
+  registry-generated `@mostlyrightmd/weather/catalog` lazy static-JSON subpath
+  (byte-deterministic under `export_schemas.py --check`), kept OUT of the
+  size-budgeted meta barrel (TS-BUNDLE-01).
+- **Migration guide + error-copy conformance (D-34.24/26).**
+  `docs/migration/v117-align-spine-sources.md` (the 26-kwarg → new-home table, the
+  four forecast kwargs → `weather.forecasts()`, label's 5 jobs → 4 call shapes,
+  the three orphan kwargs homed, the namespace-inversion symbol map, TypeScript-on-1.17,
+  the econ-unchanged F-2 follow-up, and PIT-transform-out-of-scope). Every
+  user-facing error string from Phase 34 is audited against
+  `docs/error-copy-style-guide.md` (four required fields: source id, row/entity,
+  both timestamps where temporal, concrete fix) and built through the single
+  `_errmsg` construction path — including the unknown-entity `did you mean`
+  suggestion (`EntityNotFoundError`).
+
+### Changed
+
+- **Namespace inversion — root now reads as the product pitch (D-34.20).** Root =
+  machinery (`align`, `spine`, `discover`, `provenance`, `LeakageError` /
+  `ContractError` / `NoDataError`, `registry`, `contracts`, `__version__`) +
+  domains (`weather` / `markets` / `econ`). A symbol stays top-level only if it is
+  meaningful without naming a domain.
+- **Collapsed error taxonomy (D-34.23).** `MostlyRightError` → `LeakageError` /
+  `ContractError` / `NoDataError`; `LiveStreamError` re-parented under `NoDataError`
+  (additive MRO) so `issubclass(NoCWOPDataError, NoDataError)` is True. The three
+  are importable one deep (`except mr.LeakageError:`).
+
+### Deprecated
+
+- **Relocated root symbols keep byte-stable importable shims (removal at 2.0).**
+  `from mostlyright import research/dataset/Station/CATALOG/StationCatalog` and
+  `mostlyright.live` now resolve via a once-per-session `DeprecationWarning` shim
+  naming the `mostlyright.weather.*` home (`mostlyright.research is
+  mostlyright.weather.research` — same object; parity is output bytes, not import
+  path). `markets.kalshi.dataset()` / `markets.polymarket.dataset()` → `pairs()`
+  with a deprecation shim. **Removal target: 2.0 (≥2 minors out), documented only.**
+- **The D-22 label-default `FutureWarning` is GONE (D-34.22).** The 2.0 flip
+  (`"cli"` → `None`) is cancelled — there is no implicit label default in the new
+  surface, so an OMITTED label stays `"cli"` byte-stable with no warning, forever.
+
 ## [1.16.0] — 2026-07-14 — Economic indicators vertical: first published `mostlyrightmd-econ` / `@mostlyrightmd/econ` dist
 
 First release of the **econ vertical** — CPI, PPI, nonfarm payrolls, unemployment,

README.md

@@ -252,6 +252,7 @@ table, coverage map, auto-routing, cheap-CONUS steering, DSRF gating, the 28 TB
 - **Quickstart + concepts:** <https://mostlyright.md/docs/sdk/>
 - **`dataset()` — the alignment engine:** [`docs/dataset.md`](docs/dataset.md) — the label axis, the contributor protocol, panels, and the honest with/without comparison.
 - **Source identity — the cross-vertical kwarg contract:** [`docs/source-identity.md`](docs/source-identity.md) — `source=` / `delivery=` / grain, the labels-only firewall, and the fetch-provenance ledger.
+- **Migrating to 1.17.0 — the `align` / `spine` / `sources` ladder:** [`docs/migration/v117-align-spine-sources.md`](docs/migration/v117-align-spine-sources.md) — the where-did-each-`dataset()`-kwarg-go table (all 26), `label`'s 5 jobs → 4 call shapes, per-domain `pairs()`, the namespace-inversion symbol map, TypeScript-on-1.17, and the econ-unchanged note. Additive-plus-shims; the D-22 `FutureWarning` is gone.
 - **Migrating to 1.15.0:** [`docs/migration-1.15.md`](docs/migration-1.15.md) — the D-22 default-label `FutureWarning`, `include_*` → `features=`, and `contract=` → the markets layer.
 - **API reference:** <https://mostlyright.md/docs/sdk/> (Python + TypeScript reference auto-generated per release)
 - **Migration from the legacy hosted-API client:** <https://mostlyright.md/docs/sdk/migration/legacy/>

docs/error-copy-style-guide.md

@@ -0,0 +1,80 @@
+# Error-copy style guide
+
+**Status:** wave-1 contract (Phase 34 01, R-17). Every user-facing error string
+written in waves 1-4 conforms to this guide. Plan **34-08** performs only the
+final audit against it — it does NOT author error copy.
+
+Errors are product surface: they are the moat's voice. A researcher who trips the
+leakage guard should learn, from the message alone, *which* source leaked, *by
+how much*, and *exactly what to do next* — without opening a traceback or the
+source.
+
+## The four required fields
+
+Every user-facing error raised by `align()` / the source contract MUST carry:
+
+1. **Offending source id** — the `SourceContract.id` (e.g. `weather.climate.cli`)
+   at fault. In a multi-source `align()`, name the ONE source that failed; never
+   blame a clean co-aligned source (R-22).
+2. **Row / entity** — the entity (station, ticker, …) and/or the row index the
+   error is about, so the user can locate it in their own frame.
+3. **Both timestamps, where the error is temporal** — for a leak, print BOTH the
+   leaking `knowledge_time` and the `decision_time` cutoff it crossed. One
+   timestamp alone is not actionable.
+4. **Concrete fix / next call** — the exact next action: a filter to apply, a
+   contract field to rename, or a verb to call (e.g. `mr.provenance(frame)`).
+
+Non-temporal errors (a malformed contract) satisfy field 3 vacuously.
+
+## Single construction path
+
+All `align()` / contract raises build their message text through the shared
+helper at **`packages/core/src/mostlyright/_errmsg.py`**:
+
+- `leakage_message(...)` → the copy for `LeakageError` (fields 1-4).
+- `contract_message(...)` → the copy for `ContractError` (fields 1, 2, 4).
+
+Do NOT hand-format error strings at the raise site. The exception CLASS
+(`core/exceptions.py`) holds the STRUCTURED payload (`source`,
+`violating_count`, `sample_violations`, `field`, …); the `_errmsg` builder holds
+the WORDING. Keeping wording in one module is what lets 34-08 audit copy in one
+place and what keeps Python/TS copy in lockstep.
+
+## Worked example: `LeakageError`
+
+A two-source `align()` where only `weather.forecasts.gfs` carries a row whose
+`knowledge_time` is after the spine `decision_time`:
+
+```
+Leakage detected in source 'weather.forecasts.gfs': 3 row(s) carry a
+knowledge_time after the spine decision_time cutoff 2025-01-02T00:00:00+00:00
+(e.g. knowledge_time=2025-01-05T00:00:00+00:00). Fix: filter source
+'weather.forecasts.gfs' to knowledge_time <= your decision_time before calling
+align(), or call mr.provenance(frame) to inspect the offending rows.
+```
+
+Checklist: offending source id ✅ (`weather.forecasts.gfs`); row/entity ✅
+(count + `sample_violations` carry `row_idx`); both timestamps ✅
+(`knowledge_time` + `decision_time` cutoff); concrete fix ✅ (filter to
+`knowledge_time <= decision_time`, or `mr.provenance(frame)`). The clean
+co-aligned source is never named.
+
+## Worked example: `ContractError`
+
+A source spec declares a `prefix` that does not end with `_`:
+
+```
+Contract violation in source 'weather.obs.iem' (field 'prefix'): prefix must be
+a non-empty string ending with '_' (got 'obs'). Fix: set prefix to a column
+namespace ending in '_' (e.g. 'obs_').
+```
+
+Checklist: offending source id ✅ (`weather.obs.iem`); field/entity ✅ (`prefix`);
+timestamps ✅ (vacuous — non-temporal); concrete fix ✅ (the exact value to set).
+
+## Ownership
+
+- **Waves 1-4** write every new error string against this guide, through
+  `_errmsg`.
+- **34-08** runs the final audit: it verifies each user-facing raise routes
+  through `_errmsg` and carries all four fields. It does not re-author copy.