# Decisions log

A running log of design decisions: date, decision, alternatives considered, and
rationale. Seeded with the decisions the spec (`spec.md`) already makes. Update
this file on any deviation from the spec (a **SHOULD** deviation **MUST** be
logged here).

---

## 2026-07-24 — Pack transport via `git` subprocess

**Decision:** Server-side clone/fetch/push is handled by spawning the `git`
binary (`git upload-pack` / `git receive-pack`), not by libgit2.

**Alternatives:** Implement the smart pack protocol on top of libgit2's object
layer; use a pure-Rust reimplementation (`gitoxide`).

**Rationale:** libgit2 is client-only for transport — it has no server-side
`upload-pack`/`receive-pack`. Spawning `git` is the supported, correct path.
libgit2 (via `git2`) is retained for in-process reads (refs, trees, blobs, log,
diff, signatures, `init_bare`). Consequence: `git` (≥ 2.41) MUST be on `PATH` at
runtime; the Nix derivation wraps the binary with git on PATH.

## 2026-07-24 — Repositories stored by id, not name

**Decision:** On disk, repos live at `{repo_dir}/{id[0..2]}/{id}.git` where `id`
is a lowercase ULID. The database is the only name→path authority.

**Alternatives:** Store repos by `{owner}/{name}.git` mirroring the URL.

**Rationale:** Renames and group moves become metadata-only (a DB update), never
touching the filesystem. Tradeoff: the tree is not human-browsable;
`fabrica repo path <user> <name>` resolves it for operators.

## 2026-07-24 — `/-/` route separator

**Decision:** Web and API routes disambiguate variable-length repo paths from
sub-resources with the GitLab `/-/` convention: everything before `/-/` is the
repo path, everything after is the view.

**Alternatives:** Fixed-depth paths; a query parameter for the view.

**Rationale:** Group nesting makes repo paths of unknown depth. `/-/` is an
unambiguous, well-understood separator.

## 2026-07-24 — Timestamps as epoch milliseconds

**Decision:** All timestamps are stored as `BIGINT` unix milliseconds (UTC). No
`DATETIME` / `TIMESTAMPTZ`.

**Alternatives:** Native date/time column types per dialect.

**Rationale:** One portable representation across SQLite and Postgres, ordered by
plain integer comparison. Ids are `TEXT` ULIDs (lexicographically sortable) used
for tie-breaking and ordering.

## 2026-07-24 — `serve` runs in the foreground; no `stop` subcommand

**Decision:** `fabrica serve` runs in the foreground by default and is stopped by
signalling its pid (`SIGTERM`/`SIGINT`). `--detach` double-forks and writes a pid
file. There is no `server start` / `server stop` pair.

**Alternatives:** A daemonizing `start`/`stop`/`restart` command set.

**Rationale:** Foreground is correct for systemd and Docker, which own process
lifecycle. This deviates from an earlier `server start`/`server stop` sketch.

## 2026-07-25 — Polish: signature cache wired; `theme list`/`gc` CLI deferred

**Decision:** The `moka` `SignatureCache` (bounded 4096, 10-minute TTL) is wired
into `AppState` and used by the commit list and commit page. The
`fabrica theme list` and `fabrica gc` CLI subcommands are **not** shipped.

**Alternatives:** Also cache attributes/highlight; implement `theme list`/`gc`.

**Rationale:** Signature verification is the measured hot path (list views verify
every row), so it is the one place caching earns its keep (§18 "moka where
measured"); the TTL bounds staleness after a key change without explicit
invalidation. `theme list` would need the embedded theme registry, which lives in
`web` and cannot be reached from `cli` (nothing may depend on `web`); the web theme
picker already lists every theme, so the CLI command is low value. `gc`
(trash reaping) is a maintenance convenience with no correctness impact; both are
tracked gaps, not blockers. The per-file highlight **timeout** guard (§8) also
remains deferred as noted earlier.

## 2026-07-25 — API nested into web via `nest_service`; web may depend on api

**Decision:** The `/api/v1` JSON surface is a self-contained `Router` built by
`api::router(store, config, secret)` with its own state applied, and `web` nests it
with `.nest_service("/api/v1", …)`. `web` depends on `api`.

**Alternatives:** Run the API on a separate port/server; have `api` depend on `web`
(forbidden — nothing may depend on `web`).

**Rationale:** The dependency rule bars anything depending on `web`, but says
nothing against `web → api` (both are top-level). Nesting keeps one server, one
port, and one middleware stack. Because the nested router is fully stated
(`Router<()>`), `nest_service` mounts it as a `Service` and strips the `/api/v1`
prefix, so `api` defines routes relative to root and never learns `web`'s
`AppState`. Repo sub-resources are parsed by scanning `{*rest}` for the first
keyword segment (`branches`/`tags`/`commits`/`tree`/`raw`); a repo named exactly
after one of those would be misrouted — a documented MVP limitation. The API
search returns name/description matches only (content search stays in `web`).

## 2026-07-25 — Search lives in `web`; `path:` is a substring for the MVP

**Decision:** Search (the qualifier parser, in-repo scan, and bounded global scan)
is implemented in `crates/web`, not a separate crate, using ripgrep's `grep`
engine. The `path:` qualifier matches as a case-insensitive **substring**, not a
full glob.

**Alternatives:** A dedicated `search` crate; full glob path matching via
`globset`.

**Rationale:** Search is a web-only feature with no other consumer, so a crate of
its own adds indirection for no reuse; the content scan runs inside the existing
`git_read` blocking closure. The global scan bounds itself with a
`Semaphore(search.concurrency)` and a `tokio::time::timeout(search.timeout_secs)`
deadline, returning partial results with an explicit notice on either the time or
`search.max_results` cap. A substring `path:` covers the common case; upgrading to
`globset` is a contained change if needed. `linguist-vendored`/`-generated`
exclusion is deferred (binary and >1 MiB files are already skipped).

## 2026-07-24 — Linear search, no index

**Decision:** Search (in-repo and global) is a linear scan over repo contents at
request time, with worker-pool, time-budget, and result-count bounds.

**Alternatives:** Maintain a `tantivy` full-text index.

**Rationale:** Appropriate for a small, private instance. A `tantivy` index is
the intended path if linear scan stops being fast enough.

## 2026-07-24 — Nix flake uses flake-parts

**Decision:** The flake is structured with `flake-parts` (module system,
`perSystem`) rather than `flake-utils`.

**Alternatives:** `flake-utils.lib.eachDefaultSystem`.

**Rationale:** flake-parts scales better as the flake grows (NixOS module,
container image, multiple checks) and gives a cleaner multi-output structure. The
spec permits either; picked one and stay consistent.

## 2026-07-24 — Secrets are a redact-by-default `Secret` newtype

**Decision:** Secret configuration values (`auth.secret`, `mail.password`) are
wrapped in a `config::Secret` newtype whose `Debug` and `Serialize` impls always
emit `<redacted>`. The real value is reachable only through `Secret::expose`.

**Alternatives:** Store secrets as plain `String` and redact them at each output
site (`config show`, error messages, logs).

**Rationale:** Redaction is the default and cannot be forgotten — a `Secret`
cannot leak through `tracing`, a `Debug`-formatted `Config`, `fabrica config
show`, or the JSON API, satisfying the spec's "secrets MUST NOT be logged,
echoed, or included in error messages". Site-by-site redaction is one missed
call away from a leak. Trade-off: serialization is lossy, so `Secret` is never
round-tripped through our own `Serialize` (figment reads the raw value into the
figment `Value` before deserialization, and `*_file` resolution reads from disk).

## 2026-07-24 — Strict config: unknown keys are errors, missing files are not

**Decision:** Every config struct is `#[serde(deny_unknown_fields)]`, so an
unknown key (typo, stale key, stray `FABRICA__*`) aborts the load. Missing files
at the fixed locations (`/etc`, XDG) and a missing `--config` path are tolerated
silently. Directory validation checks creatability without side effects (an
existing directory ancestor), never creating anything during `config check`.

**Alternatives:** Ignore unknown keys (serde default); require every file to
exist; create directories during validation.

**Rationale:** Failing fast on typos is worth more than forward-compatibility for
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.

## 2026-07-24 — Hand-rolled HS256 JWTs instead of a JWT crate

**Decision:** `crates/auth` implements the HS256 JSON Web Token construction
directly (base64url of a fixed JOSE header and a serde JSON payload, an
`hmac`/`sha2` HMAC-SHA256, constant-time verification via `Mac::verify_slice`)
rather than depending on `jsonwebtoken` or similar.

**Alternatives:** Use the `jsonwebtoken` crate.

**Rationale:** The mainstream JWT crates depend on `ring`, whose license set is
not in `deny.toml`'s allow-list (it carries OpenSSL-derived terms), so pulling
one in would fail `cargo-deny` — the same reason sqlx is built without a TLS
backend. The HS256 surface we need is tiny and well-specified; hand-rolling it is
a few dozen lines over crates already in the tree (`hmac`, `sha2`, `base64`,
`serde_json`) and lets us reject algorithm-confusion tokens explicitly. Tokens
are minted and verified only by fabrica, so interop with other JWT producers is a
non-goal.

## 2026-07-24 — `access()` takes the collaborator row and anonymous flag explicitly

**Decision:** The permission function is
`access(viewer: Option<&Viewer>, repo: &Repo, collaborator: Option<Permission>,
allow_anonymous: bool) -> Access`, widening the two-argument shape sketched in
the spec.

**Alternatives:** Keep the literal `access(viewer, repo)` signature and thread the
collaborator lookup and `instance.allow_anonymous` in via `Viewer` or a context
struct.

**Rationale:** Rule 3 needs the viewer's `repo_collaborators` row and rule 4 needs
`instance.allow_anonymous`; neither lives on `Viewer` or `Repo`. Passing them as
explicit parameters keeps `access` a pure function of its inputs — which is what
makes the exhaustive matrix test possible — and keeps the collaborator lookup at
the call site (the store), where it belongs. The five ordered rules are unchanged
from the spec.

## 2026-07-24 — `user` CLI pulled forward; store-backed commands self-migrate

**Decision:** The `fabrica user` command group (`add`, `passwd`, `list`,
`disable`, `enable`, `del`) is implemented now, alongside phase 4, rather than
waiting for the phase-8 CLI milestone. Every store-backed command applies pending
migrations on connect (idempotent), so a fresh install's first `user add`
bootstraps the database in one step.

**Alternatives:** Keep strictly to phase order and ship the `user` commands only
in phase 8; require a separate `fabrica migrate` before any `user` command works.

**Rationale:** The requested capability — set a user's password from the CLI when
SMTP is unavailable — is realized by `user passwd`, which needs both `auth`
(hashing) and `store` (persistence) but nothing from the intervening phases
(git/highlight). Building it now delivers that capability immediately and keeps
the auth crate exercised by a real caller. Self-migrating on connect is what makes
`user add` usable before `serve` has ever run; `serve --no-migrate` remains the
opt-out for the server path.

## 2026-07-24 — Interim `user add` without `--pass` creates an inactive account

**Decision:** Until the mail/invite flow ships (phase 9), `fabrica user add`
without `--pass` creates the user with a `NULL` password (unable to log in) and
prints guidance to run `fabrica user passwd`. CLI-set passwords clear
`must_change_password` (the operator chose a known credential).

**Alternatives:** Block `user add` until invites exist; always require `--pass`.

**Rationale:** The spec's `user add` mints an emailed activation link, which
depends on `crates/mail` (a later phase). The inactive-account-plus-guidance
behaviour is a faithful interim: no account is silently left in a login-capable
state without a credential, and the operator has an obvious next step. When mail
lands, this path grows the invite-and-email behaviour; the `passwd` fallback stays
for SMTP-disabled instances (`mail.backend = "none"`), which is exactly the case
that motivated it.

## 2026-07-24 — git2 pinned to the libgit2 nixpkgs ships (1.9.4)

**Decision:** `crates/git` depends on `git2` 0.20 with a direct
`libgit2-sys = "=0.18.3"` pin, and the build uses the **system** libgit2
(`LIBGIT2_NO_VENDOR=1`, already set in the flake) rather than the vendored copy.

**Alternatives:** Let `libgit2-sys` build its bundled libgit2 from source (drop
`LIBGIT2_NO_VENDOR`, add `cmake`); track `git2`'s latest `libgit2-sys`.

**Rationale:** `git2` 0.20's default `libgit2-sys` (0.18.7, bundling 1.9.6)
requires libgit2 ≥ 1.9.6 and aborts against nixpkgs' 1.9.4 under
`LIBGIT2_NO_VENDOR`. `libgit2-sys` 0.18.3 (bundling 1.9.2) requires ≥ 1.9.2,
which 1.9.4 satisfies. The exact pin makes the coupling explicit and stops a
stray `cargo update` from reintroducing the mismatch; bump it in lockstep when
nixpkgs bumps libgit2. Using the system lib keeps builds fast and avoids a `cmake`
build-dep and a second copy of libgit2 in the graph.

## 2026-07-24 — Dev shell sets LD_LIBRARY_PATH for dynamic libgit2

**Decision:** The `devShells.default` exports
`LD_LIBRARY_PATH = makeLibraryPath buildInputs`.

**Alternatives:** Rely on rpath; require developers to set it themselves.

**Rationale:** Test and bin artifacts built interactively (`cargo test`,
`cargo run` in the dev shell) link libgit2 dynamically but do not receive the Nix
build sandbox's rpath, so the loader cannot find `libgit2.so.1.9` and the binary
exits 127. The Nix build's own checks (`nix flake check`) embed rpath and are
unaffected; this only fixes the interactive `just check` path.

## 2026-07-24 — `.gitattributes` resolved by an own resolver, cached off `Repo`

**Decision:** `crates/git` resolves attributes itself (`attributes.rs`): it walks a
tree collecting every `.gitattributes` blob with its directory prefix, parses each
into ordered rules, and matches paths with `globset`. Precedence is "deeper
directory wins, later line within a file wins", implemented by applying
shallowest-first into a map. The `moka` cache (`AttributesCache`) keyed by tree oid
is a **separate** type the web layer holds, not a field on `Repo`.

**Alternatives:** Use libgit2's `Repository::get_attr`; cache inside `Repo`.

**Rationale:** libgit2's attribute lookup is oriented at a working tree and is
unreliable against a bare repo and for per-ref accuracy (§3.5). `Repo` is opened
per operation (per the phase-5 threading decision), so a cache on it would never
outlive a request; placing the `moka` cache in a standalone `AttributesCache`
lets the long-lived web state share resolved sets across requests without coupling
to the handle's lifetime.

## 2026-07-24 — Highlighting via inkjet (all grammars, default features)

**Decision:** `crates/highlight` uses `inkjet` 0.11.1 with default features (which
bundle every tree-sitter grammar plus the `constants` capture-name table). We use
its `highlight_raw` event stream and build per-line HTML ourselves rather than its
built-in HTML formatter.

**Alternatives:** Depend on `tree-sitter-highlight` directly with a hand-curated
grammar set; enable only `language-*` features for a smaller build.

**Rationale:** inkjet is MIT/Apache-2.0 and vendors its grammars' C source *inside
the single crate*, so they never appear as separate nodes in cargo-deny's graph and
the license gate stays green. Bundling all grammars honours "highlighting
everywhere code appears" without a curation burden; the build cost is paid once and
cached. The built-in formatter emits one blob, which cannot satisfy the
line-addressable/per-side-diff requirement (§8), so we consume the raw event stream
and fold captures onto our stable `hl-*` classes in one table. inkjet's grammars
link `libstdc++`, added to the flake `buildInputs` so the built binary rpaths it and
the dev shell's `LD_LIBRARY_PATH` picks it up.

## 2026-07-24 — Highlight guards; per-file timeout deferred

**Decision:** Highlighting can never fail a render: oversized (> `max_highlight_bytes`),
binary (NUL in the first 8 KiB), and minified (any line > 5000 bytes) inputs skip
straight to plain text, and any grammar panic is caught (`catch_unwind`) and
degraded the same way. The spec's per-file **timeout** guard is **not** yet
implemented.

**Alternatives:** Implement the timeout now via a watchdog thread and a
tree-sitter cancellation flag.

**Rationale:** The size, binary, minified, and panic guards cover every failure
mode observed in practice; a hung grammar is vanishingly rare and, when it happens,
is bounded by the `spawn_blocking` pool at the call site rather than by silently
corrupting a page. Wiring a hard per-file deadline (a cancellation flag polled by
the grammar, or a watchdog thread) is deferred to the polish phase, where the
highlight cache and measured hot paths land together. Tracked as a known gap.

## 2026-07-24 — GPG verification via rpgp, not sequoia-openpgp

**Decision:** OpenPGP signature verification uses the `pgp` crate (rpgp) 0.20, not
`sequoia-openpgp` as the spec names.

**Alternatives:** `sequoia-openpgp` (the spec's choice); shell out to `gpg`.

**Rationale:** `sequoia-openpgp` is **LGPL-2.0-or-later**, which is not in
`deny.toml`'s allow-list — pulling it in fails `cargo-deny`, the same class of
constraint that rules out `ring` and drove the hand-rolled JWT. `gpgme` shells out
to GnuPG (GPL). rpgp is `MIT OR Apache-2.0`, pure-Rust (ed25519-dalek/rsa/p256, no
`ring`, no OpenSSL/C), and covers the verification surface we need. SSH signatures
use `ssh-key` (also Apache-2.0/MIT, pure-Rust), as the spec specifies. This is a
**SHOULD** deviation logged here.

## 2026-07-24 — SignatureState ids are String; key expiry/revocation best-effort

**Decision:** `SignatureState` carries `String` ids rather than the spec sketch's
`Ulid`, and does not yet reject on GPG **key expiry or revocation**.

**Alternatives:** Depend on `ulid` in the git crate for typed ids; implement full
key-validity/revocation checking.

**Rationale:** The git crate has no `ulid` dependency and speaks ids as opaque
strings everywhere else (oids are hex `String`s); threading a `Ulid` type through
solely for these fields would add a dependency for no gain, since ids originate in
and return to the store as strings. On expiry/revocation: rpgp 0.20 exposes no
one-call "valid at time T" check for detached signatures, and revocation requires
manually scanning revocation signatures. SSH signature verification and GPG
signature **cryptographic** verification are complete and cover all four
`SignatureState` variants (tested); rejecting on GPG key expiry/revocation is a
documented best-effort gap to close alongside the signature cache wiring in the web
phase. Expired/revoked keys therefore currently verify as `Verified` if the
signature is otherwise valid — tracked as a known limitation.

## 2026-07-24 — Key ordinals are unique per user, not per (user, kind)

**Decision:** `create_key` assigns `keys.ordinal` as `max(ordinal)+1` over **all**
of a user's keys (both SSH and GPG), not per `(user, kind)`.

**Alternatives:** Per-`(user, kind)` ordinals, as the schema comment sketches.

**Rationale:** The spec's `fabrica key del <user> <index>` carries no `--type`, so
the index shown by `key list` must be unambiguous across a user's keys. Per-user
ordinals give exactly that while still satisfying the schema's
`UNIQUE (user_id, kind, ordinal)` (a per-user-unique value is a fortiori
per-`(user,kind)`-unique). Deleting a key never renumbers the survivors, as the
spec requires.

## 2026-07-24 — CLI resolves-or-generates the instance secret on first use

**Decision:** `fabrica token add` (and any future secret consumer) resolves the
HS256 signing secret via `context::ensure_secret`: inline `auth.secret`, else the
contents of `auth.secret_file` (default `{data_dir}/secret`), else a freshly
generated 32-byte secret written to that path at mode `0600`.

**Alternatives:** Require the operator to pre-provision a secret before any
token can be minted.

**Rationale:** The spec has the secret "generated on first run"; the CLI operates
directly on the data directory with no running server, so first-run generation must
happen there too. Centralizing it in one helper means `token add` today and `serve`
later sign with the same key. `auth::new_secret` provides the 32-byte base64url
value, keeping randomness in the auth crate.

## 2026-07-24 — Mail over native-TLS, not the spec's rustls transport

**Decision:** `crates/mail` uses `lettre` with the `tokio1-native-tls` transport,
not the `tokio1-rustls` transport the spec names.

**Alternatives:** `tokio1-rustls-tls` (the spec's choice).

**Rationale:** lettre's rustls transport pulls `rustls` → `ring`, whose license set
is outside `deny.toml`'s allow-list — the same constraint that shaped the JWT and
sqlx-TLS decisions. native-tls links the **system OpenSSL**, which is already a
flake `buildInput` (and present in the Debian runtime image), so it adds no new C
dependency and keeps `ring` out of the graph. Backends are `smtp` (native-TLS
`starttls`/`tls`/plaintext), `stdout`, and `none`; tests exercise the `stdout` and
`none` paths so `cargo test` needs no SMTP server. A **SHOULD** deviation logged
here. The invite token reuses `auth::new_session_token`'s shape (32 bytes,
base64url value emailed, SHA-256 stored).

## 2026-07-25 — `serve` wired in the binary; `cli` never depends on `web`

**Decision:** `fabrica serve` orchestration (load config → open store → build web
state → run) lives in the root binary (`src/serve.rs`). `cli::run` takes a serve
callback and hands back a `cli::ServeRequest`; the binary supplies the callback.
`cli` exposes `resolve_secret` for the binary to reuse.

**Alternatives:** Let `cli` depend on `web` and run the server directly.

**Rationale:** The architecture rule is absolute — **no crate may depend on
`web`** — and `serve` must start `web` (and later `ssh`/`api`). The only place
those top-level crates can be tied together is the binary, which already depends on
all of them. The callback keeps `cli` (the command tree) free of `web` while
`main.rs` stays a thin wiring layer. `--detach` is accepted but not yet
implemented (foreground is correct for systemd/Docker); deferred to deployment.

## 2026-07-25 — Web stack: axum 0.8, plain cookies, no global timeout

**Decision:** The web crate uses axum 0.8 + axum-extra cookies + maud + tower-http,
with **no TLS/rustls feature anywhere** (TLS terminates at a reverse proxy), so
`ring` stays out of the graph. Session and CSRF use **plain (unsigned) cookies**:
the session cookie is an opaque 32-byte token validated by SHA-256 lookup in the
`sessions` table; CSRF is double-submit (a non-`HttpOnly` `fabrica_csrf` cookie
matched against the `X-CSRF-Token` header htmx injects, or a `_csrf` form field).
There is **no global request timeout** layer.

**Alternatives:** `SignedCookieJar` (needs a `Key` + `FromRef`); tower-cookies; a
global `TimeoutLayer`.

**Rationale:** The session token is already unguessable and DB-validated, so cookie
signing adds machinery without materially improving security; double-submit CSRF
needs a JS-readable cookie regardless. A global timeout is actively **wrong** for
this app: pack-transport routes (§3.3) stream arbitrarily long clones and must
never be cut off, so timeouts (if any) belong per-route on non-git paths, added in
the polish phase. The theme picker is a real GET form (works without JS) that sets
a `fabrica_theme` cookie; `SIGHUP` re-scans `themes_dir` via an `RwLock<Assets>`.

## 2026-07-25 — Pack transport: 401 (not 404) for anonymous, buffered request

**Decision:** Smart-HTTP pack routes return **401** with
`WWW-Authenticate: Basic` for anonymous access to a repo they can't read (so git
prompts for credentials), whereas an authenticated stranger gets **404** (no
existence leak). This differs from the browse UI, which always 404s. The
upload-pack **request** (client wants, small) is buffered — decompressing gzip when
present — while the **response** pack streams straight from the child's stdout via
`ReaderStream`, never buffered. Push over HTTP (`git-receive-pack`) returns a
deliberate 403 naming the SSH URL.

**Alternatives:** 404 for anonymous too (no credential prompt, breaking
`git clone` of private repos); stream the request as well.

**Rationale:** git's HTTP client only sends Basic credentials after a 401
challenge, so a private clone is impossible without it — the spec mandates the 401.
The authenticated-stranger 404 preserves the no-leak invariant for logged-in users.
The upload-pack request is a few KB of wants, so buffering it (and handling
`Content-Encoding: gzip`) is simpler than streaming and violates no memory
constraint; the pack that must never be buffered is the response, which is
streamed. HTTP auth is username+password (or session cookie); API-token Basic auth
lands with the API phase. `fabrica hook post-receive` derives the repo id from the
`GIT_DIR` basename and loads config from `FABRICA_CONFIG` (set by the SSH/HTTP
server on the child) or the default location; a local push with neither set no-ops
cleanly, and it always exits 0 so a hook error never rejects an accepted push.

## 2026-07-25 — SSH via russh; the OpenSSL license is admitted for the crypto backend

**Decision:** `crates/ssh` uses `russh` 0.62 with its **default** crypto backend
`aws-lc-rs` (explicitly **not** `ring`). `deny.toml` gains three permissive
licenses its transitive tree needs — **`Unicode-DFS-2016`**, **`0BSD`**, and
**`bzip2-1.0.6`** — and `flake.nix` gains `cmake` (aws-lc-sys builds AWS-LC via
cmake).

**Alternatives:** the `ring` backend (also carries OpenSSL-family terms and is not
allowlisted); not shipping SSH at all.

**Rationale:** SSH is not optional for a git server (the DoD requires push over
SSH), the spec names russh, and russh cannot function without a crypto backend.
`aws-lc-rs` is the default and keeps `ring` out. Its tree pulls a few extra
permissive licenses (`Unicode-DFS-2016`, `0BSD`, `bzip2-1.0.6`), admitted because
SSH is mandatory; all three are permissive. This is the one place the
otherwise-strict allowlist is widened, and it is scoped to the transport stack.

**Implementation notes:** russh merged `russh-keys` into `russh::keys` and
re-exports `ssh-key` at a patch level distinct from the workspace's, so the two
`PrivateKey` types differ; the host key bridges them via the OpenSSH PEM text
(generate/load with the workspace `ssh-key`, parse with `russh::keys`). Identity is
by key fingerprint, not the SSH username (everyone connects as `git@`);
`channel_open_session` must explicitly `reply.accept()` in 0.62 or the channel is
rejected; exec output streams through the `Clone + Send` `Handle` from a task.

## 2026-07-25 — UI refresh: inline icons, Carbon themes, dashboard/explore split, profiles

**Decision:** Vendor UI glyphs as an inline-SVG `icons` module (Lucide, ISC) with
brand marks from Simple Icons (CC0), replacing the emoji glyphs. Rebase the default
`dark`/`light` themes on IBM Carbon (Gray 100 / White) as pure `--fb-*` token
changes. Split `/` into a signed-in dashboard and a public `/explore` landing (the
anonymous landing carries no in-content sign-in button). Give users a profile
(display name, pronouns, bio, location, website, GitHub/Mastodon handles) edited at
`/settings`, and avatars served from `/avatar/{username}`.

**Avatar storage:** the bytes live on disk at `{storage.data_dir}/avatars/{id}`;
`users.avatar_mime` (nullable TEXT, migration 0002) records the content type and its
presence means "serve the file". A NULL falls back to a deterministic FNV-derived
5×5 identicon SVG generated in-process.

**Alternatives:** an icon font or sprite sheet (extra asset, worse a11y); storing
avatar bytes in the DB (BLOB vs BYTEA is not portable across SQLite/Postgres, which
§ store portability forbids); Gravatar or any remote avatar (a network request from
a page, forbidden by §9.5); a single combined home page (the prior behaviour).

**Rationale:** inline SVG inherits `currentColor`, scales to `1em`, needs no network
request, and keeps the "no CDN / no build step" rule. Carbon is a documented, freely
usable palette and the swap touches only theme token values, proving the
structure-only `base.css` contract. On-disk avatars keep the schema in the portable
subset. Uploads are limited to raster types (PNG/JPEG/GIF/WebP, ≤ 1 MiB); SVG upload
is refused so no user-supplied markup is ever served, while our own identicons are
SVG. Both mutating routes (`POST /settings`, `POST /settings/avatar`) verify the
double-submit CSRF token; `/settings` redirects anonymous visitors to `/login`.

## 2026-07-25 — Three-level visibility, repo settings, and SSH push-to-create

**Decision:** Repositories carry a GitLab-style **visibility** — `public`
(everyone, anonymous gated by `allow_anonymous`), `internal` (any signed-in
user), or `private` (owner/collaborators/admins) — replacing the old two-state
`is_private` flag. `auth::access` decides read on visibility after the
admin/owner/collaborator rules; `instance.default_visibility` (default `private`)
sets the default for new repos. Owners/admins get a **Settings** repo tab
(rename, visibility, delete) whose mutations post to a fixed `/repo-settings/{id}`
prefix (never colliding with the `/{owner}/{*rest}` catch-all) and re-check Admin
access, returning `404` — never `403` — to non-admins. An SSH **push to a
non-existent repo** owned by the pushing user (or an admin) **auto-creates** it at
the default visibility (row + bare repo on disk, rolled back on disk failure).

**Migration:** `0004_repo_visibility` adds a `visibility TEXT NOT NULL DEFAULT
'private'` column backfilled from `is_private`; the `is_private` column is left in
place (SQLite cannot drop columns) but no longer read or written.

**Alternatives:** keeping the boolean and bolting "internal" on as a second flag
(two booleans encode four states, one nonsensical); a dedicated POST route per
repo path (impossible — repo paths are variable-length under groups); refusing
push-to-create (an extra round-trip to the CLes/UI for every new repo).

**Rationale:** three named states model real instances (internal is the common
"logged-in only" tier) and keep `access` a single exhaustively-tested function —
its matrix test now enumerates all three visibilities × viewer kinds × the anon
flag. `allow_anonymous` now gates only anonymous access to *public* repos, which
is what it always meant. The fixed `/repo-settings/{id}` prefix sidesteps the
catch-all cleanly and keys on the id (rename-safe). Push-to-create matches the
muscle memory of every other forge and stays safe: only the authenticated owner
(or an admin) can trigger it, and only on receive-pack.

## 2026-07-25 — Scope expansion: a complete forge minus CI

**Decision:** Reverse the original "issues / pull requests / self-registration are non-goals"
posture. fabrica now targets a **complete forge minus CI**: issues and pull requests with
GitHub-style **scoped labels** (`kind: value`, mutually exclusive within a scope), assignees,
comments, and open/closed state; PRs with branch compare, diff, review, and server-side
**merge machinery** (merge commit / squash / rebase) performed via the spawned `git`
subprocess (never libgit2, per §3.1); issues and PRs **toggleable per repository**; optional
web **self-registration** (`instance.allow_registration`, optional hCaptcha/reCAPTCHA)
alongside admin invites; and expanded **account settings** (username/email/password, SSH/GPG
keys, API tokens, profile). Still out of scope: orgs, forks, stars, wikis, releases, LFS,
webhooks, federation. CI stays deferred and is built last.

**Numbering:** issues and PRs share a per-repo counter (`repos.next_iid`) so `#N` is unique
across both; a PR is an `issues` row with `is_pull = 1` plus a `pull_requests` side table, so
labels/comments/numbering are shared.

**Rationale:** the maintainer wants the instance to be a full-featured forge for real use, not
just a private browser. Sharing the issue/PR numbering and tables keeps labels and comments
uniform and avoids a parallel implementation. Merge via subprocess preserves the one code path
for write operations. spec.md §§1, 18–19 and CLAUDE.md are updated to match; this is a large,
multi-phase build delivered incrementally with the gate green at each step.

## 2026-07-25 — Captcha on sign-up: an opt-in exception to "no network from pages"

**Decision:** Implement the spec §19 optional captcha (hCaptcha / reCAPTCHA v2) on the
`/register` form, off by default via a new `[captcha]` config table (`provider = none |
hcaptcha | recaptcha`, `site_key`, `secret_key`). When — and only when — an admin enables it,
the provider's widget script is loaded on the sign-up page and the solved token is verified
server-side with an outbound HTTPS POST to the provider's `siteverify` endpoint. Verification
**fails closed**: an empty token, a missing secret, a network error, or a rejected token all
reject the sign-up, so a broken verifier never admits a bot. The HTTP call uses `reqwest`
(`default-features = false`, `native-tls` + `json`) — native-tls, not rustls, so `ring` stays
out of the graph, consistent with the mail/SSH TLS decisions.

**Rationale:** captcha is fundamentally incompatible with §9.5 ("no network requests from any
page") — it cannot work without third-party JS and an out-of-band verify. The spec nonetheless
lists it as an optional feature, so the resolution is to make it a **deliberate, opt-in**
deviation: the no-network invariant holds for every page by default, and enabling captcha is an
explicit administrator choice to accept a third-party dependency on one page. No other page
loads external resources.

## 2026-07-25 — SSH/GPG key management in the web account settings

**Decision:** Surface the existing key store (CLI phase 8) in the web settings page: an "SSH
and GPG keys" section listing the viewer's keys with delete buttons and an add form (type +
optional label + pasted material), backed by `POST /settings/keys` and `/settings/keys/delete`.
The add handler reuses `git::parse_public_key` for validation and fingerprinting and rejects a
duplicate fingerprint; delete is ownership-checked against `keys_by_user`. This closes the last
account-settings gap (§19) so key management no longer requires shell access.

## 2026-07-26 — Optional S3 object storage for uploads (aws-sdk-s3, aws-lc-rs)

**Decision:** Add an optional S3-compatible backend for the three kinds of *uploads* — user
avatars, release assets, and git-LFS objects — behind a new `blob` crate exposing a `BlobStore`
enum with `Local` and `S3` variants. Bare git repositories are **not** included: git needs direct
filesystem access, so `storage.repo_dir` is always local. Selected by `storage.backend =
"local" | "s3"` (default `local`, so existing installs are unaffected) with a `[storage.s3]`
section (`bucket`, `region`, `endpoint`, `access_key_id`, `secret_access_key`, `path_style`,
`prefix`). The endpoint + path-style knobs make it work with MinIO, Cloudflare R2, Backblaze B2,
and other S3-compatible stores, not just AWS.

**Client:** `aws-sdk-s3` with a **manually constructed** config (static credentials, custom
endpoint) rather than `aws-config`'s credential-provider chain, keeping the dependency surface and
startup work small. The default HTTPS client (`default-https-client`) pulls `ring`, which the
license gate forbids; instead the HTTP client is wired explicitly via `aws-smithy-http-client`
with the `rustls-aws-lc` feature and `tls::Provider::Rustls(CryptoMode::AwsLc)`, so the crypto
provider is **aws-lc-rs** — already in the tree via russh and already on the license allow-list —
and `ring` never enters the graph (`cargo deny check licenses` stays green).

**Streaming:** LFS and release-asset uploads still stream to a **local scratch file** under
`data_dir/tmp` (LFS) / `data_dir/releases/tmp` (assets) so the sha256 (LFS) and size are computed
before the object is servable; the verified temp file is then handed to `BlobStore::put_file`,
which renames it into place (local) or uploads it and removes the temp (S3). Downloads stream
straight from the backend (`open` returns size + an `AsyncRead`). Keys are namespaced
(`avatars/`, `releases/`, `lfs/{shard}`) and validated against path traversal. The local backend
preserves the historical on-disk layout (`data_dir/avatars`, `data_dir/releases`, `lfs_dir`), so
no migration is needed to stay on local disk.