@intelligo-dev/core 1.0.0-beta.1

package/src/db/migrations/0027_billing_settings_mnt_columns.sql

@@ -0,0 +1,54 @@
+-- Wave 4 — MNT-denominated billing + live settings row.
+--
+-- Adds the authoritative MNT columns that `packages/billing/src/quota.ts`
+-- reads on every chat turn (chargedMnt, balanceMnt, credits*Mnt) and the
+-- singleton `billing_settings` row that holds the current FX rate and
+-- margin multiplier. The application reads these in-process with a 60s
+-- TTL cache so prices can be tuned without a code push.
+--
+-- Safe to re-run: all statements use IF NOT EXISTS.
+--
+-- Apply with:
+--   psql $DATABASE_URL -f packages/core/src/db/migrations/0027_billing_settings_mnt_columns.sql
+
+-- billing_settings — singleton config row (id = 'default').
+CREATE TABLE IF NOT EXISTS "billing_settings" (
+  "id" text PRIMARY KEY NOT NULL,
+  "usd_to_mnt_rate" integer NOT NULL DEFAULT 3450,
+  "margin_multiplier_bp" integer NOT NULL DEFAULT 400,
+  "updated_at" timestamp NOT NULL DEFAULT now()
+);
+--> statement-breakpoint
+
+-- Seed the singleton row so getBillingSettings() has a hit on fresh installs.
+INSERT INTO "billing_settings" ("id", "usd_to_mnt_rate", "margin_multiplier_bp")
+VALUES ('default', 3450, 400)
+ON CONFLICT ("id") DO NOTHING;
+--> statement-breakpoint
+
+-- credit_balances — MNT balance columns (legacy `balance` column left intact).
+ALTER TABLE "credit_balances"
+  ADD COLUMN IF NOT EXISTS "balance_mnt" integer NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS "total_purchased_mnt" integer NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS "total_used_mnt" integer NOT NULL DEFAULT 0;
+--> statement-breakpoint
+
+-- usage_records — per-request MNT + trace fields.
+ALTER TABLE "usage_records"
+  ADD COLUMN IF NOT EXISTS "margin_multiplier" real NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS "fx_rate" real NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS "charged_mnt" integer NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS "request_id" text,
+  ADD COLUMN IF NOT EXISTS "conversation_id" text;
+--> statement-breakpoint
+
+-- monthly_usage — MNT aggregate for O(1) plan quota checks.
+ALTER TABLE "monthly_usage"
+  ADD COLUMN IF NOT EXISTS "charged_mnt" integer NOT NULL DEFAULT 0;
+--> statement-breakpoint
+
+-- trial_credits — MNT-denominated grant replaces token counters.
+ALTER TABLE "trial_credits"
+  ADD COLUMN IF NOT EXISTS "initial_credits_mnt" integer NOT NULL DEFAULT 5000,
+  ADD COLUMN IF NOT EXISTS "credits_used_mnt" integer NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS "credits_remaining_mnt" integer NOT NULL DEFAULT 5000;

package/src/db/migrations/0028_trial_credits_normalized_email.sql

@@ -0,0 +1,37 @@
+-- Indexed per-email trial abuse check.
+--
+-- checkTrialAbuse() previously did `SELECT created_by_email FROM
+-- trial_credits` (no WHERE, no LIMIT) and filtered in JS. That's a
+-- full-table scan on every signup. Adding a normalized_email column
+-- (populated at provisioning time) plus a btree index lets the same
+-- check become `SELECT count(*) WHERE normalized_email = ?` — O(log n)
+-- with index-only scan.
+--
+-- Apply with:
+--   psql $DATABASE_URL -f packages/core/src/db/migrations/0028_trial_credits_normalized_email.sql
+
+ALTER TABLE "trial_credits"
+  ADD COLUMN IF NOT EXISTS "normalized_email" text;
+--> statement-breakpoint
+
+-- Backfill existing rows so the abuse check behaves consistently for
+-- trials provisioned before this migration. Mirrors the JS rule in
+-- normalizeEmailForAbuseCheck: lowercase, drop +aliases, collapse dots
+-- on gmail/googlemail, rewrite googlemail.com → gmail.com.
+UPDATE "trial_credits"
+SET "normalized_email" = (
+  CASE
+    WHEN split_part(lower(trim("created_by_email")), '@', 2) IN ('gmail.com', 'googlemail.com')
+      THEN replace(split_part(split_part(lower(trim("created_by_email")), '@', 1), '+', 1), '.', '')
+           || '@gmail.com'
+    ELSE split_part(split_part(lower(trim("created_by_email")), '@', 1), '+', 1)
+         || '@'
+         || split_part(lower(trim("created_by_email")), '@', 2)
+  END
+)
+WHERE "created_by_email" IS NOT NULL
+  AND "normalized_email" IS NULL;
+--> statement-breakpoint
+
+CREATE INDEX IF NOT EXISTS "trial_credits_normalized_email_idx"
+  ON "trial_credits" ("normalized_email");

package/src/db/migrations/0029_usage_records_conversation_idx.sql

@@ -0,0 +1,13 @@
+-- Cover the conversation deep-link path on the usage dashboard.
+--
+-- usage_table.tsx renders a per-row link to /chat/<conversationId>;
+-- once traffic grows, any reverse lookup (e.g. "all usage for this
+-- conversation") has to seq-scan on the nullable conversation_id
+-- column. Adding the index now while the table is still small is
+-- cheap and future-proofs the lookup path.
+--
+-- Apply with:
+--   psql $DATABASE_URL -f packages/core/src/db/migrations/0029_usage_records_conversation_idx.sql
+
+CREATE INDEX IF NOT EXISTS "usage_records_conversation_id_idx"
+  ON "usage_records" ("conversation_id");

package/src/db/migrations/0030_pending_extractions_composite_idx.sql

@@ -0,0 +1,11 @@
+-- DB-02: Composite index for efficient workspace-scoped extraction polling.
+--
+-- The worker queries "status = 'pending'" filtered by workspaceId, but the
+-- existing index is on status alone. A scan across all workspaces is
+-- expensive as the queue grows. This composite index allows index-only
+-- scan for workspace-scoped pending-extraction queries.
+--
+-- Apply with: psql $DATABASE_URL -f packages/core/src/db/migrations/0030_pending_extractions_composite_idx.sql
+
+CREATE INDEX IF NOT EXISTS "pending_extractions_status_workspace_idx"
+  ON "pending_extractions" ("status", "workspace_id");

package/src/db/migrations/0031_rag_documents_hnsw.sql

@@ -0,0 +1,16 @@
+-- DB-04: Migrate rag_documents vector index from IVFFlat to HNSW.
+--
+-- IVFFlat with lists=100 degrades at < 100k docs (probe count dominates,
+-- approximation quality drops). HNSW has no tuning cliff — recall is good
+-- from a handful of rows through tens of millions.
+--
+-- Template: 0011_hnsw_vector_index.sql + 0024_user_memories_hnsw.sql
+-- m / ef_construction follow pgvector docs defaults for text embeddings.
+--
+-- Apply with: psql $DATABASE_URL -f packages/core/src/db/migrations/0031_rag_documents_hnsw.sql
+
+DROP INDEX IF EXISTS "rag_documents_embedding_idx";
+--> statement-breakpoint
+CREATE INDEX "rag_documents_embedding_hnsw_idx"
+  ON "rag_documents" USING hnsw ("embedding" vector_cosine_ops)
+  WITH (m = 16, ef_construction = 64);

package/src/db/migrations/0032_rate_limit_unique_idx.sql

@@ -0,0 +1,16 @@
+-- DB-06: Unique constraint for rate limit deduplication.
+--
+-- Enables INSERT ... ON CONFLICT DO NOTHING as the authoritative rate limit
+-- check instead of pre-count + insert (which allows 2× concurrent requests through).
+-- The composite unique index is on (workspaceId, endpoint, minute_bucket).
+-- minute_bucket floors requestedAt to the minute, so entries within the same
+-- minute window conflict and only the first is inserted.
+--
+-- Apply with: psql $DATABASE_URL -f packages/core/src/db/migrations/0032_rate_limit_unique_idx.sql
+
+CREATE UNIQUE INDEX IF NOT EXISTS "rate_limit_entries_unique_bucket_idx"
+  ON "rate_limit_entries" (
+    "workspace_id",
+    "endpoint",
+    date_trunc('minute', "requested_at")
+  );

package/src/db/migrations/0033_pending_extractions_partial_idx.sql

@@ -0,0 +1,18 @@
+-- DB-01: Partial index for workspace-scoped pending extraction polling.
+--
+-- Workers claim rows by: WHERE status = 'pending' AND workspace_id = ?
+-- The existing composite index (status, workspace_id) forces a scan of
+-- ALL pending rows across all workspaces before filtering by workspace.
+-- This partial index narrows the scan to just pending rows for the target
+-- workspace — an index-only scan at O(log n) per workspace instead of
+-- O(pending_rows_total).
+--
+-- Applies to: claimNextExtraction() and listPendingExtractions() in
+-- packages/agents/src/extraction/queue.ts
+--
+-- Run with: psql $DATABASE_URL -f packages/core/src/db/migrations/0033_pending_extractions_partial_idx.sql
+-- Or via: cd packages/core && pnpm drizzle-kit push
+
+CREATE INDEX IF NOT EXISTS pending_extractions_workspace_pending_idx
+  ON pending_extractions (workspace_id)
+  WHERE status = 'pending';

package/src/db/migrations/0034_rate_limit_count.sql

@@ -0,0 +1,9 @@
+-- B-05b: Rate limiter admits only ONE request per minute bucket.
+--
+-- The B-05 fix replaced check-then-insert with a unique constraint on
+-- (workspace_id, endpoint, minute_bucket) + ON CONFLICT DO NOTHING, but
+-- that admits exactly one request per bucket — the per-plan limit
+-- (10/60/300 rpm) was never consulted. Add a counter column so the
+-- upsert becomes DO UPDATE SET count = count + 1 RETURNING count, and
+-- admission is count <= limit.
+ALTER TABLE "rate_limit_entries" ADD COLUMN IF NOT EXISTS "count" integer DEFAULT 1 NOT NULL;

package/src/db/migrations/0035_credit_reservations.sql

@@ -0,0 +1,24 @@
+-- B-06: Close the checkQuota → recordTokenUsage TOCTOU window.
+--
+-- checkQuota was a pure read; the debit happened minutes later in
+-- recordTokenUsage, so N concurrent requests could all pass admission
+-- against the same balance. Admission now inserts a reservation for the
+-- worst-case MNT estimate in the same transaction that sums the other
+-- active reservations. recordTokenUsage settles it; abandoned rows
+-- expire via expires_at (TTL >= chat route maxDuration) and are cleaned
+-- by the cleanup cron.
+CREATE TABLE IF NOT EXISTS "credit_reservations" (
+	"id" text PRIMARY KEY NOT NULL,
+	"workspace_id" text NOT NULL,
+	"request_id" text NOT NULL,
+	"estimated_mnt" integer NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"settled_at" timestamp,
+	CONSTRAINT "credit_reservations_request_id_unique" UNIQUE("request_id")
+);
+--> statement-breakpoint
+ALTER TABLE "credit_reservations" ADD CONSTRAINT "credit_reservations_workspace_id_organization_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "credit_reservations_active_idx" ON "credit_reservations" USING btree ("workspace_id","status","expires_at");

package/src/db/migrations/0036_executions_audit_jobs.sql

@@ -0,0 +1,96 @@
+-- Phase 2: the SaaS execution boundary (ADR-0003, ADR-0004).
+--
+-- Three tables, three owning packages:
+--   executions   → @intelligo-dev/executions — one row per AI run: actor,
+--                  workspace, capability, entitlement outcome, status,
+--                  usage, cost. Records nothing about agents/tools/
+--                  messages, which stay native to the AI framework.
+--   audit_events → @intelligo-dev/audit — append-only who-did-what.
+--   jobs         → @intelligo-dev/jobs — Postgres-backed queue (claimed
+--                  with FOR UPDATE SKIP LOCKED).
+--
+-- usage_records gains execution_id rather than being duplicated into a
+-- new usage_events table: it already IS the per-request usage/cost
+-- detail. The rename happens with the Phase 4 package split.
+
+CREATE TABLE IF NOT EXISTS "executions" (
+	"id" text PRIMARY KEY NOT NULL,
+	"workspace_id" text NOT NULL,
+	"user_id" text,
+	"capability" text NOT NULL,
+	"request_id" text NOT NULL,
+	"status" text DEFAULT 'running' NOT NULL,
+	"model" text,
+	"input_tokens" integer,
+	"output_tokens" integer,
+	"total_tokens" integer,
+	"charged_mnt" integer,
+	"reserved_mnt" integer,
+	"refusal_reason" text,
+	"error_message" text,
+	"started_at" timestamp DEFAULT now() NOT NULL,
+	"finished_at" timestamp,
+	"duration_ms" integer,
+	"metadata" jsonb,
+	CONSTRAINT "executions_request_id_unique" UNIQUE("request_id")
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "audit_events" (
+	"id" text PRIMARY KEY NOT NULL,
+	"workspace_id" text,
+	"actor_id" text,
+	"actor_kind" text DEFAULT 'user' NOT NULL,
+	"action" text NOT NULL,
+	"resource_kind" text NOT NULL,
+	"resource_id" text,
+	"outcome" text DEFAULT 'ok' NOT NULL,
+	"metadata" jsonb,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "jobs" (
+	"id" text PRIMARY KEY NOT NULL,
+	"workspace_id" text,
+	"kind" text NOT NULL,
+	"payload" jsonb,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"attempts" integer DEFAULT 0 NOT NULL,
+	"max_attempts" integer DEFAULT 3 NOT NULL,
+	"run_at" timestamp DEFAULT now() NOT NULL,
+	"started_at" timestamp,
+	"finished_at" timestamp,
+	"last_error" text,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "usage_records" ADD COLUMN IF NOT EXISTS "execution_id" text;
+--> statement-breakpoint
+ALTER TABLE "executions" ADD CONSTRAINT "executions_workspace_id_organization_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "executions" ADD CONSTRAINT "executions_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "audit_events" ADD CONSTRAINT "audit_events_workspace_id_organization_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "audit_events" ADD CONSTRAINT "audit_events_actor_id_users_id_fk" FOREIGN KEY ("actor_id") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "jobs" ADD CONSTRAINT "jobs_workspace_id_organization_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "executions_workspace_started_idx" ON "executions" USING btree ("workspace_id","started_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "executions_status_idx" ON "executions" USING btree ("status","started_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "executions_capability_idx" ON "executions" USING btree ("capability","started_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "audit_events_workspace_created_idx" ON "audit_events" USING btree ("workspace_id","created_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "audit_events_action_idx" ON "audit_events" USING btree ("action","created_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "audit_events_resource_idx" ON "audit_events" USING btree ("resource_kind","resource_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "jobs_claim_idx" ON "jobs" USING btree ("status","run_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "jobs_kind_idx" ON "jobs" USING btree ("kind","status");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "jobs_workspace_idx" ON "jobs" USING btree ("workspace_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "usage_records_execution_id_idx" ON "usage_records" USING btree ("execution_id");

package/src/db/migrations/0037_rate_limit_minute_bucket.sql

@@ -0,0 +1,46 @@
+-- Repair the rate-limit schema so a fresh database matches the code.
+--
+-- 0032 documented a unique constraint on (workspace_id, endpoint,
+-- minute_bucket) but created an EXPRESSION index on
+-- date_trunc('minute', requested_at) instead, and no migration ever
+-- added the minute_bucket column. checkRateLimit's
+-- `ON CONFLICT (workspace_id, endpoint, minute_bucket)` can only
+-- resolve against a constraint on those literal columns, so replaying
+-- the committed history against an empty database produced a
+-- rate_limit_entries table that throws
+-- `column "minute_bucket" does not exist` on every chat request.
+-- Production only worked because the live database had been synced
+-- with `drizzle-kit push` straight from schema.ts, bypassing these
+-- files entirely.
+
+ALTER TABLE "rate_limit_entries"
+  ADD COLUMN IF NOT EXISTS "minute_bucket" timestamp;
+--> statement-breakpoint
+
+-- Backfill so the NOT NULL below can be applied to existing rows.
+UPDATE "rate_limit_entries"
+  SET "minute_bucket" = date_trunc('minute', "requested_at")
+  WHERE "minute_bucket" IS NULL;
+--> statement-breakpoint
+
+ALTER TABLE "rate_limit_entries"
+  ALTER COLUMN "minute_bucket" SET NOT NULL;
+--> statement-breakpoint
+
+-- The expression index carries the name the constraint needs.
+DROP INDEX IF EXISTS "rate_limit_entries_unique_bucket_idx";
+--> statement-breakpoint
+
+-- Collapse any duplicate buckets the expression index allowed through
+-- before the real constraint can be created.
+DELETE FROM "rate_limit_entries" a
+  USING "rate_limit_entries" b
+  WHERE a.ctid < b.ctid
+    AND a."workspace_id" = b."workspace_id"
+    AND a."endpoint" = b."endpoint"
+    AND a."minute_bucket" = b."minute_bucket";
+--> statement-breakpoint
+
+ALTER TABLE "rate_limit_entries"
+  ADD CONSTRAINT "rate_limit_entries_unique_bucket_idx"
+  UNIQUE ("workspace_id", "endpoint", "minute_bucket");

package/src/db/migrations/0038_user_quotas_generic_usage.sql

@@ -0,0 +1,25 @@
+-- Finish the user_quotas cutover to a generic usage map (B6).
+--
+-- The table carried three career-specific counters — chat_messages_used,
+-- assessments_used, reports_used — alongside the generic `usage` JSONB
+-- added in migration 0022. Since then recordFeatureUsage dual-wrote both
+-- while reads still preferred the columns, so a public package's schema
+-- named a vertical's actions and no vertical could add a fourth counter
+-- without a migration to Intelligo (ADR-0004, ADR-0006).
+--
+-- Backfill first: rows written since the dual-write started already have
+-- the keys in `usage`, and those values win. Rows that predate it have a
+-- non-zero column and no key, so the built object supplies them. `||` is
+-- right-biased, hence usage on the right.
+
+UPDATE user_quotas
+   SET usage = jsonb_build_object(
+                 'chat',       COALESCE(chat_messages_used, 0),
+                 'assessment', COALESCE(assessments_used, 0),
+                 'report',     COALESCE(reports_used, 0)
+               ) || COALESCE(usage, '{}'::jsonb);
+
+ALTER TABLE user_quotas
+  DROP COLUMN IF EXISTS chat_messages_used,
+  DROP COLUMN IF EXISTS assessments_used,
+  DROP COLUMN IF EXISTS reports_used;

package/src/db/migrations/0039_platform_admin_impersonation.sql

@@ -0,0 +1,27 @@
+-- Platform role and impersonation support.
+--
+-- `users.role` makes platform admin a property of the user rather than
+-- of the environment. PLATFORM_ADMIN_EMAILS stays as the bootstrap —
+-- requirePlatformAdmin promotes an allowlisted user into this column on
+-- first use — so a fresh deployment still has a way in, but the runtime
+-- authority is a row, which Better-Auth's admin plugin can read and
+-- which survives someone editing the env.
+--
+-- The ban columns are unused by the product; the admin plugin's schema
+-- expects them and Better-Auth errors on a missing column rather than
+-- degrading.
+--
+-- `sessions.impersonated_by` is what makes an impersonated session
+-- recognisable as one after the fact, at the session itself and not
+-- only in the audit trail.
+
+ALTER TABLE users
+  ADD COLUMN IF NOT EXISTS role text,
+  ADD COLUMN IF NOT EXISTS banned boolean NOT NULL DEFAULT false,
+  ADD COLUMN IF NOT EXISTS ban_reason text,
+  ADD COLUMN IF NOT EXISTS ban_expires timestamp;
+
+ALTER TABLE sessions
+  ADD COLUMN IF NOT EXISTS impersonated_by text;
+
+CREATE INDEX IF NOT EXISTS users_role_idx ON users (role) WHERE role IS NOT NULL;

package/src/db/migrations/0040_ee_audit_chain.sql

@@ -0,0 +1,23 @@
+-- Tamper-evidence chain over the audit trail.
+--
+-- Owned by @intelligo-dev/ee-governance, a package outside the public
+-- allowlist. It appears in this shared history because Core owns the
+-- migration chain for the whole database (ADR-0004) — but no public
+-- package declares the table, imports the module, or knows the feature
+-- exists. Removing the module removes the capability and nothing else.
+--
+-- No foreign key to audit_events on purpose: audit is append-only and
+-- owned elsewhere, and a cascade from there would erase the evidence
+-- that something was erased, which is the one thing this table is for.
+
+CREATE TABLE IF NOT EXISTS ee_audit_chain (
+  event_id      text PRIMARY KEY,
+  workspace_id  text,
+  sequence      integer NOT NULL,
+  previous_hash text NOT NULL,
+  hash          text NOT NULL,
+  created_at    timestamp NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS ee_audit_chain_workspace_seq_idx
+  ON ee_audit_chain (workspace_id, sequence);

package/src/db/migrations/README.md

@@ -0,0 +1,57 @@
+# Migrations
+
+`drizzle-kit migrate` applies the `.sql` files listed in
+`meta/_journal.json`, in journal order. Both halves have to agree, and
+for most of this repository's life they did not: the journal stopped at
+entry 11 while the directory grew to 39 files, so `migrate` silently
+applied a quarter of the chain and every environment was really
+provisioned by `drizzle-kit push` from `schema.ts`.
+
+That is how `0032` shipped documenting a unique constraint on a
+`minute_bucket` column no migration ever created — the rate limiter's
+`ON CONFLICT` could not have resolved on a database built from these
+files. `0037` repairs it, and `intelligo doctor` now fails CI if the
+journal and the directory drift apart again.
+
+## Adding a migration
+
+Prefer `pnpm --filter @intelligo-dev/core db:generate`, which writes both
+the `.sql` file and its journal entry. A hand-written file needs its
+tag added to `meta/_journal.json` by hand — `doctor` will tell you if
+you forget.
+
+Note that `db:generate` diffs against `meta/NNNN_snapshot.json`, and
+snapshots exist only up to `0011`. Until the snapshots are rebuilt,
+generate produces a full-schema diff rather than an incremental one;
+hand-write the file and add the journal entry instead.
+
+## Baselining an existing database
+
+Because the journal previously listed only 12 of the 39 files, a
+database provisioned with `push` has the schema but no record of the
+migrations. Running `migrate` against it now would try to apply all 39.
+Most are `IF NOT EXISTS`-guarded, but not all.
+
+Mark them as already applied before the first `migrate` on such a
+database:
+
+```sql
+-- One row per journal entry, in journal order. hash is the sha256 of
+-- the .sql file contents; drizzle compares it on subsequent runs.
+CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (
+  id SERIAL PRIMARY KEY,
+  hash text NOT NULL,
+  created_at bigint
+);
+```
+
+Generate the rows with the file hashes and the `when` values from the
+journal, then verify with `intelligo doctor` and a `migrate` run that
+reports nothing to apply. Do this on a restored copy first.
+
+## Verifying the chain
+
+CI replays every file against an empty database on each run (see the
+`e2e` job) and then asserts the columns the running code depends on.
+That check is what proves these files are a provisioning mechanism
+rather than documentation.