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

 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.