First milestone of the mesh-level account/authorization authority (#59).
New workspace crate `crates/helexa-upstream` (binary + lib), mirroring the
helexa-router skeleton: axum `build_app`/`run`, clap `serve --config`,
figment `UPSTREAM_`-prefixed config.
- **Storage:** PostgreSQL via sqlx (runtime query API — builds in CI with no
DB or offline cache; correctness covered by gated integration tests).
`migrations/0001_init.sql` is the full schema: users (argon2 hash slot,
email_verified, registration_fingerprint), email_tokens, accounts
(allocation total/spent/reserved + `accounts_no_overshoot` CHECK, silent
`status` deactivation flag, fingerprint_flagged), api_keys (sha256 hash,
percent|hardcap limit, cap_window, per-key ledger), reservations
(BIGSERIAL id → maps to cortex Reservation.id u64), top_up_codes,
served_usage, sessions. Migrations run on startup.
- **Ledger (no-overshoot core):** `ledger::{reserve,settle,release}` —
reserve takes `SELECT … FOR UPDATE` on the account + key rows so
concurrent reserves serialize and spent+reserved can never exceed the
effective cap (= min(resolved key cap, remaining account allocation));
the CHECK is the DB backstop. Settle clamps actual to [0,reserved] and is
idempotent; release is idempotent. `resolve_abs_cap` (percent/hardcap,
i128 math) is pure + unit-tested. Balance semantics here; rolling-window
sub-caps + RateLimited land with the authz API (B2).
- `/health` does a DB round-trip.
- Config + example TOML ([server]/[db]/[grant] free grant/[abuse]
fingerprint threshold).
Validated end-to-end against a throwaway Postgres 16: migration applies,
20 concurrent reserves of 100 against a 500 cap admit exactly 5 (reserved
== 500, never over), settle/release idempotent, hardcap key sub-cap binds
below the account, `/health` → db ok. CI runs the cap-math + config unit
tests; the DB integration tests skip cleanly when UPSTREAM_TEST_DATABASE_URL
is unset.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F6o3ddqmYNh9kzdwq6eowh
