stack/docs/superpowers/specs/2026-08-17-ecfr-jump-links-design.md

eCFR Jump Links — Bidirectional CFR Cite ↔ URL (P41)

Date: 2026-08-17. Milestone: P41. Requested as: "the same [as P40's FR jump links] for eCFR — so a CFR cite goes back and forth."

Verified ground truth (2026-08-17)

• https://www.ecfr.gov/current/title-42/section-425.400 (short form) 302-redirects server-side to the canonical hierarchy URL (/current/title-42/chapter-IV/subchapter-B/part-425/subpart-E/section-425.400) — cite → URL needs no structure lookup; fragments survive redirects client-side.
• Paragraph anchors on section pages are semantic: id="p-425.400(c)(1)(iv)" — the fragment IS the cite's paragraph path (316 such anchors on § 425.400). Both directions are therefore deterministic string transforms.
• The eCFR versioner API is open (/api/versioner/v1/titles.json responds), but the plain /cite/ permalink endpoint 406s for non-browser clients — irrelevant, the short form covers it.
• bib holds 699 item_type='regulation' items with eCFR URLs — both part-level (…/title-42/part-414) and section-level (…/part-405/section-405.534) — the Title 42/45 Regulations collections. These are the placement targets and the validation index.

Decisions (inherited from P40's user-selected pattern)

Consumers: all (notebooks, :pincite:, Zotero child links, CLI). Addressing: cite (with/without paragraph path), URL (inverse), both directions. Persistence: no anchor grab needed — the transform is deterministic; the bib regulation index provides context/validation. Placement discipline: only place()d links reach Zotero.

Architecture

src/bib/cfrlink.py — parse, transmute, context, place. Hooks: bib/pincite.py (jump_url covers the existing cfr locator type), notebook helper cfr_md(), CLI stack bib cfr-jump. Zotero placement reuses the P40 fr_links table + _sync_fr_links path unchanged (rows carry page=0 and p_id=NULL for non-FR links — the sync only reads label/url; documented here rather than forking a parallel table).

Data model

CfrCite frozen dataclass: title: int, part: str, section: str ("425.400", empty for part-level cites), paras: tuple[str, ...] (("c","1","iv")), date: str ("" = current).

Parse (parse_cite(ref) -> CfrCite)

Accepted spellings (case-insensitive, C.F.R. dots optional, § optional, whitespace collapsed):

• 42 CFR 425.400(c)(1)(iv) / 42 C.F.R. § 425.400(c)(1)(iv)
• 42 CFR § 414.1425 / 42 CFR 414.1450(b)(1)
• 42 CFR Part 425 / 42 CFR part 425 subpart E (subpart ignored for URL purposes — the short form resolves placement) Title is required (bare § 425.400 raises naming the reason — the title selects the eCFR tree). Paragraph path parsed from consecutive parenthesized tokens.

Transmute

• url(cite) -> str: section: https://www.ecfr.gov/current/title-{t}/section-{s} + (#p-{s}({a})({b})… when paras present); part: https://www.ecfr.gov/current/title-{t}/part-{p}; date-pinned: /on/{date}/ replaces /current/ when cite.date.
• cite_of(url) -> str: inverse over every eCFR URL form — short, canonical full-hierarchy, /on/{date}/, with or without #p-… fragment. Emits the canonical spelling 42 CFR 425.400(c)(1)(iv) (part-level: 42 CFR Part 425).
• Round-trip law: cite_of(url(parse_cite(x))) == canonical spelling of x, and url(parse_cite(cite_of(u))) reproduces u's short form — tested explicitly.

Bib context + placement

• item_for(cite, store) -> str | "": match against regulation items' eCFR URLs — exact section item first, then the part item. Powers placement targets and lightweight validation ("is this cited reg in the library?"); a cite with no library item still transmutes (URL construction never requires the store).
• place(store, ref, *, label="") -> JumpLink: resolve + item_for (raises when no regulation item matches — placed links need a parent), upsert into fr_links (page=0), synced by the existing _sync_fr_links as linkMode=3 children.
• md_link(ref, *, text="") — store-free (deterministic URL).
• CLI: stack bib cfr-jump REF [--md] [--place [--label L]] and stack bib cfr-jump --url URL for the reverse direction (prints the cite).

:pincite:

Pincite.jump_url gains the cfr branch: locators like 42 CFR 425.400(c) resolve through cfrlink (no store data needed); non-title locators (§ 3.2-style, classified section) stay URL-less. Degradation contract unchanged ("", never raise).

Notebook

cfr_md() helper beside fr_md() (same graceful fallback shape, but store-free); the CY2027 notebook's 42 CFR 414.1450(b)(1) (APM revival), § 414.1425(c)(5)(ii) (QP alignment — spelled with title), and the PQM section's 42 CFR § 425.400(c) cites become live eCFR links. Gate: nb_integration.py single-notebook run.

Testing

• Parse: every accepted spelling + reject-without-title + part form.
• Transmute: URL forms incl. date pin and fragments; cite_of over short/canonical/dated/fragmented URLs; both round-trip laws.
• Context: item_for section-over-part preference against a fixture store; place on a regulation item; sync reuses the P40 linkMode=3 tests' path (one new test: CFR-placed row syncs identically).
• Live smoke: url(parse_cite("42 CFR 425.400(c)(1)(iv)")) fetches 200 with the fragment's anchor present in the body.

Out of scope

• eCFR structure/versioner grabs (no data needed for the transform; revisit only if full-hierarchy canonical URLs or historical snapshots become requirements).
• Quote → paragraph addressing for CFR text (would need section text ingestion; FR quotes already cover the rulemaking corpus).
• Auto-creating regulation items for cites not in the library.

P41 build outcomes (2026-08-17)

Issues #639–#641, milestone P41 (5 commits, b872d7d..HEAD, direct on main; TDD throughout).

• #639 (b872d7d): bib/cfrlink.py pure transmuter — 23 tests incl. both round-trip laws; live smoke: the generated …/section-425.400#p-425.400(c)(1)(iv) URL returns 200 with the fragment's anchor present in the body.
• #640: item_for (exact-section beats part over the 699 regulation items), place() reusing fr_links (page=0) and the untouched _sync_fr_links path, cfr-jump CLI with --url reverse mode. Live: all three rollout cites matched exact section-level regulation items (74YXT4TC / HFY6IREA / 95PQGJRP).
• #641: Pincite.jump_url cfr branch (store-free); notebook cfr_md() helper + live eCFR links for 42 CFR 414.1450(b)(1), 42 CFR 414.1425(c)(5)(ii), 42 CFR 425.400(c) (gate pass=1, in-container resolution proven); placed links synced via --tag source:ecfr (699 items, all URL-dedupe skips, fr_links: 3) onto the pre-existing Zotero regulation items (GEZXDVQ9 / AEHYQWRZ / 47GK4BZE — Zotero held the regs under pre-bib keys; the sync's URL dedupe attached children to them exactly as designed).
• Note: cite_of on a date-pinned URL returns the undated canonical cite (the date is a view parameter, not part of the citation) — by design, documented here.