Shorten packaged example paths (MAX_PATH) and fix flagship A123 org id

[jsimonclark]

What

• Drop the redundant <type>- prefix from the component example filenames
  in both examples/** and the packaged mirror src/battinfo/data/examples/**
  (<type>/<type>-<uid>.json -> <type>/<uid>.json), across 14 component
  directories (98 file renames total).
• Fix the dead A123 organization IRI
  organization/9k3e-absq-8131-vyjd -> organization/8z6j-n7vw-e73w-smh7
  ("A123 Systems", verified live) in the flagship cell-spec, the A123
  organization record, and every other file embedding it.
• Add a CI guard (tests/test_packaged_example_path_length.py) that fails if
  any packaged example path regrows past the budget.

Why

• MAX_PATH (blind 0.8 review, major): on default Windows
  (LongPathsEnabled=0) pip install fails when a packaged data file's path
  crosses 260 chars. The worst offender duplicated its directory in the
  filename, e.g.
  current-collector-spec/current-collector-spec-vkaf-f5bv-fwt2-e6yz.json
  at 93 chars below site-packages. The 0.8 PyPI release widens Windows
  exposure, so this lands first.
• Dead org IRI: the flagship manufacturer.id 404s on w3id and on the
  registry's own resolver; the live A123 org is 8z6j-n7vw-e73w-smh7.

How

• Renamed only the filename (record content is byte-identical apart from the
  A123 IRI fix). The runtime loaders glob *.json and derive record ids from
  file content, not the filename, so no loader changes were needed.
• Left five record dirs (cell-instance/, cell-spec/, dataset/, test/,
  test-protocol/) and material/ unchanged: their filenames are referenced
  by name in tests owned by a sibling agent (including a constructed
  material-{uid}.json path in tests/test_phase4.py), and they are already
  short (<= 75 chars below site-packages), so renaming them would gain nothing
  for the budget while breaking those tests. The redundant-prefix directories
  that actually threatened MAX_PATH are all in the renamed set.
• Regenerated the packaged mirror via scripts/sync_examples.py and the web
  artifacts via scripts/gen_web_jsonld.py, scripts/gen_web_examples.py, and
  web/scripts/sync-examples.mjs (outputs not hand-edited).
• Packaging is glob-based (package-data = data/**/*), so no MANIFEST/packaging
  changes were needed.

Rename map

<type>/<type>-<uid>.json -> <type>/<uid>.json in:
channel, current-collector, current-collector-spec, electrode,
electrode-spec, electrolyte, electrolyte-spec, equipment,
equipment-spec, housing, housing-spec, material-spec, separator,
separator-spec.

Worst-case packaged path (below site-packages)

	worst example	worst any packaged file
before	93	93 (same example)
after	82 (cell-spec/research/pouch-single-layer-detailed.example.json)	87 (data/profiles/cell-spec/generated/quantitative-properties.schema.fragment.json)

The remaining 82-char ceiling is the descriptive
cell-spec/research/*.example.json records, which are referenced by name in
several sibling-owned tests and so are not renamed here. The 87-char worst-any
file is a generated schema fragment under data/profiles/ (outside this PR's
territory) — flagged for a follow-up if the sub-80 target is to be met fully.

Testing

• uv run pytest: 1602 passed, 1 skipped.
• uv run ruff check src tests scripts .tools: clean. uv run mypy: clean
  (69 files).
• scripts/sync_examples.py --check, examples/web drift guards, and the
  schema-version stamp guard: green.
• New guard proven to fail on a planted 93-char filename, then pass after
  removal.
• git grep 9k3e-absq-8131-vyjd: no matches.

Deep-path wheel install (Windows, LongPathsEnabled=0):

Wheel content worst-case paths (below site-packages):
  OLD (origin/main)    worst example:  93  .../current-collector-spec/current-collector-spec-vkaf-f5bv-fwt2-e6yz.json
  NEW (fixed)          worst example:  82  .../cell-spec/research/pouch-single-layer-detailed.example.json

PROOF 1 - FIXED wheel, functional install at 119-char site-packages
  pip install rc: 0
  battinfo 0.7.0 | loaded https://w3id.org/battinfo/spec/vkaf-f5bv-fwt2-e6yz
  installed example path len below sp: 70

PROOF 2 - OLD vs NEW at 167-char site-packages, --no-deps
  OLD: pip rc 1 | OSError [Errno 2] ... current-collector-spec-vkaf-f5bv-fwt2-e6yz.json
       HINT: system does not have Windows Long Path support enabled
  NEW: pip rc 0 | 113 example files installed

Notes / seams

• docs/engineering-cell-description.md (owned here) updated for the renamed
  housing-spec/ example paths.
• docs/guides/01-concepts.ipynb output cell and
  tests/fixtures/served/flagship-cell-spec.jsonld carried the dead org IRI;
  both fixed (the flagship id fix authorizes editing every embedding).
• No quickstart / getting-started / Guide 6 pages were touched. No renamed
  example path appears in those sibling-owned pages.
• The served archive/R2 copy of the flagship is regenerated by the operator
  later (out of scope here).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
batt-info	Ready	Preview	Aug 1, 2026 12:39am