hanna/fabrica

docs(decisions): record store, sqlx TLS, and build-source decisions

c231ea9 · hanna committed on 2026-07-25

Log the phase-3 choices: `sqlx::Any` over per-dialect code paths, building
sqlx without a TLS backend, and widening the Nix build source to keep `.sql`
migration files.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

docs/decisions.md +52 −0

@@ @@ -118,3 +118,55 @@ exist; create directories during validation. @@
 a single-operator forge. Tolerating missing files lets one binary serve both a
 bare first-run machine and a fully-configured one. Side-effect-free validation
 keeps `config check` safe to run anywhere.
 ## 2026-07-24 — Store runs over `sqlx::Any`, not per-dialect code paths
 **Decision:** The `store` crate uses a single `sqlx::Any` pool and writes each
 statement once, rather than a `Store` trait with separate `SqlitePool` and
 `PgPool` implementations. Three dialect differences are mediated explicitly:
 placeholders use the `$1,$2` syntax both SQLite and Postgres accept (only MySQL
 needs `?`); booleans bind as Rust `bool` (encodes correctly for both) and are
 read back through `Store::get_bool`, which decodes SQLite's `INTEGER` storage and
 Postgres's native `BOOLEAN`; timestamps and ids are already portable (`BIGINT`
 ms, `TEXT` ULID).
 **Alternatives:** A `Store` trait with two concrete pool implementations (the
 spec's other blessed option), duplicating every query per dialect.
 **Rationale:** The spec explicitly permits "runtime queries over `AnyPool`". One
 code path is far less surface to keep in sync than two, and the portability rules
 (portable SQL subset, no compile-time-checked macros) already constrain us to the
 intersection where `Any` is safe. The single genuinely divergent read — booleans
 — is funnelled through one helper, which is exactly the "the trait maps them"
 seam the spec calls for. Migrations remain two dialect-specific `.sql` sets,
 embedded via `sqlx::migrate!` and selected at runtime by backend.
 ## 2026-07-24 — sqlx built without a TLS backend (for now)
 **Decision:** `sqlx` is pulled with `default-features = false` and no
 `tls-*` feature; Postgres connections are plaintext.
 **Alternatives:** Enable `tls-rustls-ring` (or native-tls) so Postgres-over-TLS
 works out of the box.
 **Rationale:** TLS is only relevant to a remote Postgres, which is a phase-17
 deployment concern; SQLite (the default) and local/socket Postgres need none.
 Omitting it keeps the dependency tree small and, notably, keeps `ring` out of the
 graph so `cargo-deny`'s license set stays clean without special-casing. To be
 revisited when deployment against a managed Postgres is implemented; the change
 is a one-line feature addition plus a `deny.toml` license allowance.
 ## 2026-07-24 — Nix build source keeps `.sql` migration files
 **Decision:** `flake.nix` replaces `craneLib.cleanCargoSource` with a
 `cleanSourceWith` filter that additionally keeps `*.sql`, because
 `sqlx::migrate!` embeds the migration files at compile time (and a store test
 `include_str!`s them for the schema-equivalence check).
 **Alternatives:** Move migrations under a path crane already keeps; generate them
 into `OUT_DIR`.
 **Rationale:** Crane's cargo-source filter strips non-Rust files, which would
 break every derivation that compiles `store`. Widening the filter is the minimal,
 explicit fix and leaves room to add further asset globs (themes, vendored htmx)
 the same way in later phases.