Phase 1 — Data Layer and Contracts
Goal: the database schema, roles and migrations in packages/db, the shared types in packages/types, and the API contract decisions that apps/api depends on.
Done when: migrations apply cleanly to the staging database through the pipeline, every Worker connects with its own role, and the API error contract is written down.
| ID | Task | Who | Needs | Status |
|---|---|---|---|---|
| P1.01 | Pin Better Auth and check its tables | Agent | P0.06 | merged — code #3; spec context #11 |
| P1.02 | Schema: tenancy and Better Auth | Agent | P1.01 | merged — code #4 |
| P1.03 | Schema: keys, gateway, models, rates, markup | Agent | P1.02 | merged — code #5; FX markup scope code #15 |
| P1.04 | Schema: money | Agent | P1.03 | merged — code #6 |
| P1.05 | Schema: logs |
Agent | P1.08 | merged — code #7 |
| P1.06 | Roles, grants and Hyperdrive configs | You + agent | P1.02–P1.05 | done (2026-11-01) — code #62, code #63, bindings on #64 (#37 was merged first); staging schema applied; production schema waits for the pipeline (P0.09); as-built section 17; Hyperdrive query caching turned off in all six configs 2026-11-05 |
| P1.07 | Migrations in the pipeline; staging seed | Agent | P1.06, P0.06 | in part — the migrate job is in code #38 and runs once the self-hosted runner exists (P0.09). Left: the idempotent staging seed |
| P1.08 | Decide: error contract, response extras, request-log location fields | You + agent | — | merged — context #10 (decisions), context #12 (catalogue) |
| P1.09 | Shared types and the Gateway interface |
Agent | P1.08 | merged — code #8 |
| P1.10 | Query helpers and the logs store interface | Agent | P1.06 | merged — code #9 |
P1.01 — Pin Better Auth and check its tables
Section titled “P1.01 — Pin Better Auth and check its tables”Who: Agent · Needs: P0.06
Pin Better Auth and its plugins (organization, admin, one-time-token, two-factor, passkey) to exact versions. Run @better-auth/cli generate and diff the output against db-schema.md section 4.0. Confirm:
-
the GitLab provider config
-
account-linking behaviour with an unverified provider email
-
whether stored OAuth tokens can be encrypted
-
whether cookies can be renamed to
__Host-… -
sign-up behaviour for an already-registered email
-
whether secret rotation is supported
-
Spec:
../architecture/db-schema.md4.0;../architecture/auth-security.mdsection 7; backlog #18 Auth setup -
Done when: the diff is resolved (spec updated where the library differs), and each confirmation is recorded in
auth-security.mdsection 7.
P1.02 — Schema: tenancy and Better Auth
Section titled “P1.02 — Schema: tenancy and Better Auth”Who: Agent · Needs: P1.01
Drizzle tables for db-schema.md 4.0 and 4.1: the Better Auth tables, orgs, members, invitations, workspaces, workspace members and currencies. Follow the section 1 conventions: uuid v7 from the app, timestamptz, numeric, text + CHECK enums, soft deletes for config.
- Spec:
../architecture/db-schema.md1, 3.1, 4.0, 4.1 - Done when: the migration applies to a fresh Postgres container and the ER relationships match 3.1.
P1.03 — Schema: keys, gateway, models, rates, markup
Section titled “P1.03 — Schema: keys, gateway, models, rates, markup”Who: Agent · Needs: P1.02
Tables for 4.2 and 4.3: api_keys, gateways, api_key_gateway_credentials, api_key_models, key_spend_windows, gateway_discrepancies, models, published_rates, current_rates, markup rules, FX rates, workspace discounts and the rest of 4.3. Seed the bifrost-1 gateway row.
- Spec:
../architecture/db-schema.md3.1, 3.2, 4.2, 4.3; decisions log, Gateway abstraction - Done when: the migration applies, the indexes and partial indexes in the spec exist, and
fillfactor = 70is set where specified.
P1.04 — Schema: money
Section titled “P1.04 — Schema: money”Who: Agent · Needs: P1.03
Tables for 4.4: workspace balances, holds, settlements, ledger entries, idempotency keys, top-ups, transfers, payment vendors and fees, usage discrepancies, scheduled jobs.
- Spec:
../architecture/db-schema.md3.3, 4.4, 5 - Done when: the migration applies, and the
CHECKconstraints (e.g.used >= 0, note required for adjustments) reject bad rows in a test.
P1.05 — Schema: logs
Section titled “P1.05 — Schema: logs”Who: Agent · Needs: P1.08
The logs schema: request logs, audit events, usage_hourly, content_storage_daily, job runs. Include the country and ASN columns if P1.08 decides to add them. Apply the seven logs rules: created_at in every key, no foreign keys to core, append-only.
- Spec:
../architecture/db-schema.md2, 3.4, 4.5, 6 - Done when: the migration applies, and the hooks checklist in section 6 passes item by item (listed in the PR).
P1.06 — Roles, grants and Hyperdrive configs
Section titled “P1.06 — Roles, grants and Hyperdrive configs”Who: You + agent · Needs: P1.02–P1.05
- Agent: a migration creating the roles
api,dashboard,consumerandmigrator, with grants:api: hot-path tables only, no Better Auth tablesdashboard:coreconsumer:logsmigrator: DDL
- You:
- set role passwords in each database (the cluster Postgres, staging and production)
- create one Hyperdrive config per role per environment, each connecting through that environment’s
postgresVPC Service - put the
migratorcredentials in a Kubernetes secret per environment for the self-hosted runner - fill in the inventory rows
- Spec: decisions log, Database roles;
../architecture/db-schema.md2 - Done when: each role can do exactly its job and is refused outside it (a test per role), and both Workers’ Wrangler files bind their Hyperdrive configs.
P1.07 — Migrations in the pipeline; staging seed
Section titled “P1.07 — Migrations in the pipeline; staging seed”Who: Agent · Needs: P1.06, P0.06
- Migrate step: wire it into both deploy workflows, using
migratorand running before any code. Both environments’ migrations run on the self-hosted runner, since both databases are private. The PR gates run the migrations on PGlite for the DB integration tests; deploys and manual Gates runs also run them on a Postgres 17 container (cicd.mdsection 2). - Idempotent staging seed:
- currencies, with minimum hold and rate significant figures (
rate_sig_figs; the rounding step is deprecated) - the Niobi payment vendor
- an internal test org and workspace, with a credit balance, for the canary
- currencies, with minimum hold and rate significant figures (
- Spec:
../architecture/cicd.mdsection 4; decisions log, Migrations and the staging database - Done when: a merge to
mainmigrates and seeds staging. Running the seed twice changes nothing.
P1.08 — Decide: error contract, response extras, request-log location fields
Section titled “P1.08 — Decide: error contract, response extras, request-log location fields”Who: You + agent · Needs: —
Decisions made 2026-10-26 (decisions log, API error contract and response extras): OpenRouter’s envelope with our subset; no cost or balance in responses; country and ASN logged, IP deferred. Catalogue written:
../architecture/api-errors.md(2026-10-26).
Three decisions:
- Error format: adopt OpenRouter’s
{error: {code, message, metadata}}envelope with a subset of itserror_typevalues that we can actually emit (recommended inapi-surface.mdsection 5), or define our own. Include the out-of-credit, spend-limit and account suspended codes and the rate-limit headers. - Whether cost and remaining balance appear in the response body at launch.
- Whether the request log stores country and ASN (
api-key-security.md7.2).
The agent drafts the catalogue and recommendations; you decide.
- Spec:
../product/api-surface.mdsections 4–6;../architecture/auth-security.md2.3–2.4;../architecture/api-key-security.md7.2 - Done when:
- the decisions are recorded in the decisions log
- the full error catalogue (status, code,
error_type, message, headers) is written as a section ofauth-security.mdor its own doc api-surface.mdsection 6 items 2 and 3 are closed
P1.09 — Shared types and the Gateway interface
Section titled “P1.09 — Shared types and the Gateway interface”Who: Agent · Needs: P1.08
In packages/types:
- the versioned usage event (v1)
- the niobi-callback event
- the error catalogue types from P1.08
- the
niobi-proxyrequest/response types - the
Gatewayinterface:- chat completion, streaming and not
- create/update/delete a key credential
- list models, with cost inputs
- fetch usage logs
- map errors to the catalogue
Zod schemas wherever data crosses a boundary.
- Spec: decisions log, Gateway abstraction, Log-write and audit rules;
../architecture/cicd.mdsection 3 rule 2 - Done when: the types compile, the event schemas carry a version field, and no Bifrost-specific type appears in the interface.
P1.10 — Query helpers and the logs store interface
Section titled “P1.10 — Query helpers and the logs store interface”Who: Agent · Needs: P1.06
packages/db exports:
- a connection factory per role
- typed query helpers for the hot path (key lookup by hash, current rate lookup)
- the store interface the queue consumer writes
logsthrough, so a later move to another store changes one module - Spec:
../architecture/db-schema.md2;../architecture/future-optimizations.md(analytics rows) - Done when: helpers are covered by DB integration tests on a Postgres container.