#795 JSON Note: generic JSON-payload NOTE type (OP_NOTEJSON) replacing STATION:/INDUSTRY:/etc. text-prefix convention

[Allen D Byrne]

Umbrella feature ticket for 'JSON Note' -- a new native NOTE op type (OP_NOTEJSON=3) whose text is a raw JSON object, replacing the ad-hoc STATION:/INDUSTRY:/STORAGE:/YARD_TRACK:/HOUSE_TRACK:/REFERENCE: text-prefix mini-DSL that mcp/src/xtrkcad_mcp/stations.py currently hand-parses.

Full design: .claude/json-note-feature-design-2026-09-14-v1.md (initial brainstorm, 2026-09-14) and .claude/json-note-implementation-plan-2026-09-15-v1.md (detailed implementation plan, 2026-09-15, approved).

Scope: (1) native OP_NOTEJSON type + cJSON-based validate/pretty-print editor dialog, (2) per-kind JSON schemas for station/industry/storage/yard_track/house_track/reference, (3) MCP refactor to read JSON Notes directly (legacy prefix parsers deleted, not kept in parallel -- MCP has exactly one real consumer file), (4) one-time migration of the real NYE layout's 45 existing notes, (5) a new native 'Notes Report' (Reports feature) and matching MCP write_notes_report tool, both with Layer Group filtering, (6) MCP gains LAYERGROUP file-format parsing (previously absent), (7) native Reports Save button repurposed to export JSON/Markdown instead of a redundant plain-text dump (GTK's own Print already covers print-to-file).

Depends on Layer Groups (SF #782/#787/#789, feature-requests #222) for PARAMVERSION 13 -- git GTK3V2MAIN already has this merged; the Hg-side work forks from the Layer Groups Hg branch tip (bug-789-layergroups-docs-consistency-gtk3) rather than Hg's own GTK3V2MAIN (still at 12), since JSON Note's op-value addition needs the version bump to avoid a hard CHECKMSG/AbortProg() crash in old binaries reading a new file (verified precisely, not assumed).

Broken into individual bugs-tracker tickets per implementation phase, same process as Layer Groups.

[Allen D Byrne]

Phase B progress update (per-kind JSON schema design).

PR #211 (not yet merged, GTK3V2MAIN): https://github.com/adbyrne/XTrkCAD/pull/211

This settles the schema-design question left open when Phase A shipped schema-free:
what the JSON body should look like for each of the operational note kinds
(station/industry/storage/house_track/yard_track/reference). Design + documentation
only in this pass -- no code changes, no validate-on-save enforcement, no editor
template support. Those stay deferred until after the upcoming "Operations" report
family.

Grounded in two real sources rather than designed from scratch: the existing MCP
prefix-parser token grammars in stations.py (two kinds, station and storage, already
have a shipped JSON-side parser), and a real layout's data that was converted to JSON
Notes earlier this session. Where those two disagreed on a field name, the real
converted data won out over what were originally just internal Python variable names.

Final shape: every kind's own identifier field is named "id" for consistency
(matching what the Notes Report already reads generically for its own ID column).
station: id (required), optional terminus/switchback (booleans), optional ref_tag.
industry: id (required), optional name (defaults to id), optional station (the
connected station's own id). storage: id (required), optional name. house_track: id
(required) -- the id of whichever station OR industry this house track's capacity
belongs to (confirmed from real data this isn't station-only). yard_track: id
(required, the yard/station) plus label (required, this track's own display label).
reference: id (required, e.g. "MP_ZERO") plus an optional numeric mp_scale.

Also settled: unknown fields at the note's top level are always kept, never rejected.
No separate "entity"/"railroad" field is needed to say which railroad a note belongs
to on a layout with more than one -- the note's own layer, combined with Layer Groups,
already answers that.

This is documented as a convention, not an enforced schema -- nothing in the app
checks that a note claiming a given kind actually has the listed fields. A real
layout's own usage can reasonably diverge from it where that layout's own needs
don't require every field.

Holding PR #211 for review before merging.

[Allen D Byrne]

Status update: implementation and Phase B design/doc are both merged on git GTK3V2MAIN and the matching Hg bug branches are now pushed to SF. Flipping to needs-review pending merge into Hg mainline (held behind the Layer Groups review, per the linked dev mailing list request).

[Allen D Byrne]

Correction to my previous post: the Hg branch (bug-795-jsonnote-phaseb-schema-gtk3) is NOT yet pushed to SF -- I stated that incorrectly. It is merged on git GTK3V2MAIN and ready; the Hg push is still pending on my end and I will follow up here once it has actually landed. Status left at needs-review since the code itself is genuinely ready for review on git in the meantime.

[Allen D Byrne]

Follow-up: the Hg branch (bug-795-jsonnote-phaseb-schema-gtk3) is now actually pushed to SF, so the earlier premature claim is correct as of now.