Swift → TypeScript cutover (2026-07)#

Context for why decant is a single Bun + TypeScript app and why the project
invariants read the way they do. Written 2026-08-03 from the migration
records.

What existed before#

Until 2026-07-04, decant was three coupled apps: Rust crates (parsers, ingest,
a background daemon that owned the SQLite archive), a Phoenix (Elixir) web
UI talking to the daemon behind a bearer-token API, and a Swift macOS menu
bar app. The pre-cutover tree is preserved in the signed pre-typescript
tag.

The decision#

The stated optimization target was contributor accessibility for AI
developers — one language, one process, one repo-root app. Enabling spikes
happened 2026-07-02 (Bun's bun:sqlite FTS5 support passed; Bun fullstack
HTML imports chosen over Vite so bun build --compile can ship single
binaries embedding the UI). The macOS app was dropped at cutover.

How it landed#

PR #20 carried the entire migration in one PR (284 files, +16k/−40k),
deleting crates/, web/, and macos/; merged to main 2026-07-04 together
with #22 (UI parity). Follow-up audits on 2026-07-04 and 2026-07-06 verified
the punch-list items were resolved in code (server request guards, ingest
test restoration, release workflow, UI parity items).

Durable decisions that trace to the cutover#

One process owns SQLite (invariant 2): the daemon/token/second-app
architecture is what the cutover removed; do not reintroduce it.
Core modules stay print-free (invariant 1) — output policy lives in
src/cli.ts.
npm distribution uses the optionalDependencies platform-package pattern
(launcher .cjs shim + per-platform compiled binaries) because npx runs
under Node while the app needs bun:sqlite.
Toolchain: Bun runtime, Biome, commander, native fs.watch plus a sweep
(Bun's watcher needed a 2026-04 upstream fix for new subdirectories on
Linux).
The golden-parity oracle (test/golden/) predates the cutover: it was the
byte-determinism harness proving the TS port matched the Rust behavior, and
it remains the regression net for parser changes.

Useful archaeology pointers#

pre-typescript (signed tag): the last pre-cutover commit; the old Rust
schema tracked versions 1–8 in schema_migrations, which is why pre-v8
archives are rebuild-only today.
The npm scope decision (@dosu/decant, no plan to claim unscoped
decant) dates to the same period.