Skip to content

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.md 4.0; ../architecture/auth-security.md section 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.md section 7.

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.md 1, 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.md 3.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 = 70 is set where specified.

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.md 3.3, 4.4, 5
  • Done when: the migration applies, and the CHECK constraints (e.g. used >= 0, note required for adjustments) reject bad rows in a test.

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.md 2, 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, consumer and migrator, with grants:
    • api: hot-path tables only, no Better Auth tables
    • dashboard: core
    • consumer: logs
    • migrator: 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 postgres VPC Service
    • put the migrator credentials in a Kubernetes secret per environment for the self-hosted runner
    • fill in the inventory rows
  • Spec: decisions log, Database roles; ../architecture/db-schema.md 2
  • 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 migrator and 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.md section 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
  • Spec: ../architecture/cicd.md section 4; decisions log, Migrations and the staging database
  • Done when: a merge to main migrates 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:

  1. Error format: adopt OpenRouter’s {error: {code, message, metadata}} envelope with a subset of its error_type values that we can actually emit (recommended in api-surface.md section 5), or define our own. Include the out-of-credit, spend-limit and account suspended codes and the rate-limit headers.
  2. Whether cost and remaining balance appear in the response body at launch.
  3. Whether the request log stores country and ASN (api-key-security.md 7.2).

The agent drafts the catalogue and recommendations; you decide.

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-proxy request/response types
  • the Gateway interface:
    • 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.md section 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 logs through, so a later move to another store changes one module
  • Spec: ../architecture/db-schema.md 2; ../architecture/future-optimizations.md (analytics rows)
  • Done when: helpers are covered by DB integration tests on a Postgres container.