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 via gmake deploy)
  • Verify: curl -Lv "https://wal.sh/tools/encode/?chain=base64" lands on transform with param intact.
  • Rollback: Remove the RedirectMatch line, 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.org
  • site/research/2026-reversible-pipeline-transforms/index.org and includes/examples.org
  • site/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 from site/tools/index.org nav 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 :require references.
  • Verify: gmake build clean; 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