--- name: museum-path-based-naming-and-redirects description: "Museum doc pages renamed from content-hash to archive-path addresses (option 3 the owner chose), with a mined redirect-ledger for every old hash address, ahead of public publication" metadata: node_type: memory type: project originSessionId: fae52f6b-22d1-486f-b92c-8bd84ef3f320 modified: 2026-07-21T02:59:18.347Z --- DONE (2026-07-20, commits 43390e6 + 0f3d846), ahead of the planned public Cloudflare Pages exhibit (see `planning/2.8.5/plans/MUSEUM_MASTER_PLAN.md` §17). Owner chose, from three options explained to him, **option 3: path-based doc addresses PLUS a redirect table from the old hash addresses** — not the zero-work content-hash status quo, and not path-based names alone with no redirect table. **Doc pages** (`museum/generate.mjs`) went from `docs/<sha256(bytes)[:12]>.html` to `docs/<archive-rel-path>.html`, mirroring the archive's own directory tree. Reasoning that held up under scrutiny: - **Collisions**: proven, not assumed — a runtime `seenSlugsLower` guard aborts the build if two rels ever fold to the same path case-insensitively (Windows checkouts fold case). Zero collisions across the current 244-document archive. - **Deduplication loss is a non-issue, arguably a fix**: the old hash scheme let two different-content-identical documents silently share one page, whichever was written last in manifest order winning — a reader following path A's link could land on a page describing path B. Path-based naming makes every rel always show its own path. The lobby's independent `findDuplicates` warning (currently 0 groups) is unaffected. - **Character safety needed no new sanitization**: `rel` is already a real path on this exact Windows disk; appending a constant `docs/`/`.html` wrapper can't make it unsafe. **Redirect ledger** (`museum/redirect-ledger.json`, committed, tracked): mined ONCE via `node museum/generate.mjs --migrate-redirects` from this repo's OWN git history — 389 distinct hash-named doc pages have existed across all history, 244 still current, the rest recoverable only by walking history and increasingly hard to recover with every future regen once path-based names land (there is no ongoing source of new hash addresses once path-based naming is in place, so this ritual should not need to run again). ⚠ **First mining pass under-counted (305 vs the true 389)** — git's content-similarity rename detection was pairing up unrelated hash pages as "renames" of each other (they share large boilerplate around a short doc body), hiding them from `--diff-filter=A`. Fixed with `--no-renames` on both git log calls in `migrateRedirectLedger()`. Worth remembering if this or a similar history-mining approach is reused elsewhere: **always pass `--no-renames` when mining `git log --diff-filter=A` for "was this exact path ever added," on any tree with many similar-shaped generated files.** **Redirect mechanism: HTML meta-refresh stubs, not Cloudflare's native `_redirects`.** Deliberate, because the museum must also open correctly as local files from disk (per the publication plan) — a `_redirects` rule does nothing for a `file://` open, so an old bookmark would 404 locally with zero recourse. A committed stub is a real file at the old path everywhere (Cloudflare, any other static host, or raw disk). Considered and rejected pairing with a `_redirects` file too (skips the meta-refresh flash on Cloudflare specifically) — no SEO/crawler stakes on a personal archive exhibit, so it would be a second, redundant bookkeeping system solving a problem nobody has. **Also folded in**: [[museum-thumb-render-nondeterminism]] got fixed in the same session (its own memory entry now has the full story and a correction to the earlier "PNG encoder jitter" diagnosis). Verified per this project's established standard: fresh GitHub clone AND a bare-clone-derived clone, both `git status` clean at stamp `80bf9bb · f64fb7397980c9cb`, byte-identical to each other and to two back-to-back local regenerations; 4,986 internal links checked, 0 broken; a redirect stub confirmed resolving to its new nested page when served over HTTP (search + doc-page rendering also spot-checked this way). File `://` execution of the meta-refresh itself was **not** separately re-verified via screen automation this session (the sandboxed preview renders out-of-project `file://` paths as non-executing static snapshots, and the real desktop browser was only available read-only, with no Claude-in-Chrome connected) — relying instead on meta-refresh being a protocol-agnostic HTML mechanism, unlike `fetch()`, which this same codebase already routes around for `file://` via `<script src>` for its search corpus. Worth a real `file://` click-through next time a desktop browser is actually controllable, but not blocking. Related: [[museum-lf-normalization]], [[museum-readme-txt-leak]] — the LF-normalization and README.txt-leak fixes this one follows the same "prove it from a fresh AND a bare-derived clone" discipline as.