tools/encode to tools/transform URL Migration
1. Context
=/tools/encode/= is live with 37 cross-references in research and event pages.
=/tools/transform/= is deployed as a copy. Both are live. No redirects exist yet.
Shared URLs with ?chain= query params circulate in Slack, email, and bookmarks.
The ClojureScript namespace wal-sh.tools.encode is internal; not user-facing.
2. Phase 1: Test – current state
Both paths serve identical content. No redirects. Parallel-run window for verification.
- Verify:
curl -I https://wal.sh/tools/transform/= returns 200; =?chain= params render correctly. - Rollback: Remove =site/tools/transform/= and redeploy. Zero risk to encode path.
3. Phase 2: Redirect encode -> transform
Add a 301 in .htaccess. Query params must survive the redirect.
RedirectMatch 301 ^/tools/encode(/.*)?$ /tools/transform$1
Verify the rewrite preserves ?chain= by testing a known shared URL end-to-end.
- Files:
.htaccess(deploy viagmake deploy) - Verify:
curl -Lv "https://wal.sh/tools/encode/?chain=base64"lands on transform with param intact. - Rollback: Remove the
RedirectMatchline,gmake deploy.
4. Phase 3: Update references
Migrate the 37 [[https://wal.sh/tools/encode…]] and file: links in org sources.
Affected files (grep tools/encode):
site/tools/encode/index.org(self-refs, 9)site/tools/transform/index.org(copied self-refs, 9)site/events/defcon/{23,24,26,29,30,34}/index.orgsite/research/2026-reversible-pipeline-transforms/index.organdincludes/examples.orgsite/research/tainted-data-llm-pipelines.org
Run before editing: aq check -f site/tools/encode/index.org
- Verify:
grep -r "tools/encode" site/ --include"*.org"= returns zero results (minus the encode page itself). - Rollback: Git revert the reference-update commit. Redirect still handles live traffic.
5. Phase 4: Deprecate encode page
Remove site/tools/encode/index.org. The 301 redirect handles all legacy traffic.
- Files: delete
site/tools/encode/index.org; remove fromsite/tools/index.orgnav if present. - Verify:
curl -IL https://wal.sh/tools/encode/shows 301 -> 200 chain; no 404. - Rollback: Restore file from git. One-line revert.
6. Phase 5: Namespace rename (optional, deferred)
Rename wal-sh.tools.encode -> wal-sh.tools.transform in ClojureScript source.
Internal only; no user-visible URL or API surface affected.
Defer until after Phase 4 is stable in production for at least one week.
- Files: ClojureScript
src/namespace declarations and:requirereferences. - Verify:
gmake buildclean; no JS console errors on transform page. - Rollback: Git revert namespace commit; redeploy.
7. Formal model
The RewriteRule deployed in Phase 2 is one of the transitions in the
TLA+ redirect termination model. That spec proves this redirect composes
safely with the other .htaccess rules (no loops, no shadowing). The
prefix-shadow bug documented there – where Redirect silently matches
sub-paths – is exactly the risk if Phase 2 used Redirect instead of
RedirectMatch.
8. Go / No-Go Gates
| Gate | Condition |
|---|---|
| P1->P2 | transform returns 200 with intact ?chain= params |
| P2->P3 | 301 redirect confirmed with curl; no query param loss |
| P3->P4 | Zero tools/encode references in org sources (excluding encode page) |
| P4->P5 | One week of clean 301->200 traffic in server logs |