spec-kitty / spec-kitty/spec-kitty

Route inline meta.json reads in m_0_13_0_research_csv_schema_check.py onto load_meta* (deferred from #2091/read-surface-ssot-closeout WP15)

Open
#2,477 2 comments 0 reactions 0 assignees View on GitHub
deferred priority:P3 tech-debt
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 52m
Merged PRs (30d)
303

Description

## Context

Mission `read-surface-ssot-closeout-01KWZV91` (FR-005/FR-006, closes the #2091 inline-meta-read
census) routed the vast majority of inline `json.loads()` reads onto the canonical
`load_meta`/`load_meta_strict`/`load_meta_or_empty` readers in `mission_metadata.py`.

WP15 deliberately **deferred** the two per-entry `meta.json` reads in
`src/specify_cli/upgrade/migrations/m_0_13_0_research_csv_schema_check.py`:

- `detect()` — `meta_json.open()` + `json.load(f)` at (current) line ~56
- `up()` — `meta_json.open()` + `json.load(f)` at (current) line ~113

## Why deferred

This is a **historical, version-pinned migration** (`target_version = "0.13.0"`) exercised by
`tests/research/test_research_csv_schema_migration.py`. Historical migrations replay against
byte-exact legacy fixtures; routing the read onto `load_meta`'s newer error-contract
(`allow_missing`/`on_malformed` semantics introduced post-#2091) risks silently changing which
legacy `meta.json` shapes are tolerated vs. rejected mid-replay, which would invalidate the
migration's contract for real historical projects upgrading through 0.13.0.

## Ask

Route both sites onto the matching `load_meta*` adapter **with an explicit behavioral
equivalence check** against `tests/research/test_research_csv_schema_migration.py` (and any
other fixtures exercising this migration), OR make an explicit, documented decision that
frozen historical migrations are permanently exempt from the FR-005 read-routing (and encode
that exemption in the `tests/architectural/inline_meta_read_allowlist.yaml` gate introduced by
WP16, rather than leaving it an implicit path-exclude).

## References

- Mission: `kitty-specs/read-surface-ssot-closeout-01KWZV91/spec.md` (FR-005, FR-006)
- WP15: `kitty-specs/read-surface-ssot-closeout-01KWZV91/tasks/WP15-meta-migration-audit-matrix.md`
- WP16 (ratchet/allow-list): `kitty-specs/read-surface-ssot-closeout-01KWZV91/tasks/WP16-meta-read-ratchet.md`

Contributor guide

Open the contributing guide

Research direction

Read src/specify_cli/upgrade/migrations/m_0_13_0_research_csv_schema_check.py and the load_meta* adapters in mission_metadata.py, then run tests/research/test_research_csv_schema_migration.py against the historical fixtures. Compare both inline reads with adapter behavior; done means behavioral equivalence is verified, or the frozen-migration exemption is documented and encoded in tests/architectural/inline_meta_read_allowlist.yaml.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.