rose-ash/RESTRUCTURE_PLAN.md

Restructure Plan

Reorganise from flat shared/sx/ref/ to layered spec/ + hosts/ + web/ + sx/.

Recovery point: commit 1a3d7b3 on branch macros.

Phase 1: Directory structure

Create all directories. No file moves.

spec/tests/
hosts/python/
hosts/javascript/
web/adapters/
web/tests/
web/platforms/python/
web/platforms/javascript/
sx/platforms/python/
sx/platforms/javascript/

Phase 2: Spec files (git mv)

Move from shared/sx/ref/ to spec/:

• eval.sx, parser.sx, primitives.sx, render.sx
• cek.sx, frames.sx, special-forms.sx
• continuations.sx, callcc.sx, types.sx Move tests to spec/tests/:
• test-framework.sx, test.sx, test-eval.sx, test-parser.sx
• test-render.sx, test-cek.sx, test-continuations.sx, test-types.sx Remove boundary-core.sx from spec/ (it's a contract doc, not spec)

Phase 3: Host files (git mv)

Python host - move from shared/sx/ref/ to hosts/python/:

• bootstrap_py.py → hosts/python/bootstrap.py
• platform_py.py → hosts/python/platform.py
• py.sx → hosts/python/transpiler.sx
• boundary_parser.py → hosts/python/boundary_parser.py
• run_signal_tests.py, run_cek_tests.py, run_cek_reactive_tests.py, run_continuation_tests.py, run_type_tests.py → hosts/python/tests/

JS host - move from shared/sx/ref/ to hosts/javascript/:

• run_js_sx.py → hosts/javascript/bootstrap.py
• bootstrap_js.py → hosts/javascript/cli.py
• platform_js.py → hosts/javascript/platform.py
• js.sx → hosts/javascript/transpiler.sx

Generated output stays in place:

• shared/sx/ref/sx_ref.py (Python runtime)
• shared/static/scripts/sx-browser.js (JS runtime)

Phase 4: Web framework files (git mv)

Move from shared/sx/ref/ to web/:

• signals.sx → web/signals.sx
• engine.sx, orchestration.sx, boot.sx → web/
• router.sx, deps.sx, forms.sx, page-helpers.sx → web/ Move adapters to web/adapters/:
• adapter-dom.sx → web/adapters/dom.sx
• adapter-html.sx → web/adapters/html.sx
• adapter-sx.sx → web/adapters/sx.sx
• adapter-async.sx → web/adapters/async.sx Move web tests to web/tests/:
• test-signals.sx, test-aser.sx, test-engine.sx, etc. Move boundary-web.sx to web/boundary.sx Move boundary-app.sx to web/boundary-app.sx

Phase 5: Platform bindings

Web platforms:

• Extract DOM/browser primitives from platform_js.py → web/platforms/javascript/
• Extract IO/server primitives from platform_py.py → web/platforms/python/ App platforms:
• sx/sxc/pages/helpers.py → sx/platforms/python/helpers.py
• sx/sxc/init-client.sx.txt → sx/platforms/javascript/init.sx

Phase 6: Update imports

• All Python imports referencing shared.sx.ref.*
• Bootstrapper paths (ref_dir, _source_dirs, _find_sx)
• Docker volume mounts in docker-compose*.yml
• Test runner paths
• CLAUDE.md paths

Phase 7: Verify

• Both bootstrappers build
• All tests pass
• Dev container starts
• Website works
• Remove duplicate files from shared/sx/ref/

Notes

• Generated files (sx_ref.py, sx-browser.js) stay where they are
• The runtime imports from shared.sx.ref.sx_ref — that doesn't change
• Only the SOURCE .sx files and bootstrapper tools move
• Each phase is a separate commit for safe rollback