@intelligo-dev/core 1.0.0-beta.1

package/src/db/migrations/0015_new_v1_tables.sql

@@ -0,0 +1,149 @@
+-- NOTE (2026-08-26): every table below is also created by
+-- 0011_ambiguous_otto_octavius.sql, which runs first and whose
+-- shared_reports definition is the fuller one (it has conversation_id
+-- and parent_report_id; this file's does not). Replaying the chain
+-- against an empty database therefore failed here with
+-- `relation "knowledge_articles" already exists`.
+--
+-- Guarded rather than deleted: the file is in the journal, and on any
+-- database where it did run first its statements are the ones that
+-- created these tables. IF NOT EXISTS makes both orders converge on
+-- 0011's schema.
+
+-- Migration: 0015_new_v1_tables
+-- Description: Add 6 new tables for v1.0 features (knowledge, competition, referral, shared reports)
+-- Phase: 72-02
+
+CREATE TABLE IF NOT EXISTS "knowledge_articles" (
+	"id" text PRIMARY KEY NOT NULL,
+	"slug" text NOT NULL,
+	"category" text NOT NULL,
+	"title" jsonb NOT NULL,
+	"description" jsonb NOT NULL,
+	"content" jsonb NOT NULL,
+	"tags" text[],
+	"reading_time_minutes" integer DEFAULT 5 NOT NULL,
+	"sort_order" integer DEFAULT 0 NOT NULL,
+	"is_published" boolean DEFAULT false NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "competitions" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" jsonb NOT NULL,
+	"description" jsonb NOT NULL,
+	"start_date" timestamp NOT NULL,
+	"end_date" timestamp NOT NULL,
+	"is_active" boolean DEFAULT false NOT NULL,
+	"prize_description" jsonb,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "competition_entries" (
+	"id" text PRIMARY KEY NOT NULL,
+	"competition_id" text NOT NULL,
+	"workspace_id" text NOT NULL,
+	"school_name" text NOT NULL,
+	"class_name" text NOT NULL,
+	"assessment_count" integer DEFAULT 0 NOT NULL,
+	"total_score" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "referral_codes" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"code" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "referrals" (
+	"id" text PRIMARY KEY NOT NULL,
+	"referrer_id" text NOT NULL,
+	"referred_user_id" text NOT NULL,
+	"referral_code_id" text NOT NULL,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"completed_at" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "shared_reports" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"workspace_id" text NOT NULL,
+	"report_type" text DEFAULT 'career' NOT NULL,
+	"report_data" jsonb NOT NULL,
+	"is_public" boolean DEFAULT true NOT NULL,
+	"view_count" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "competition_entries" ADD CONSTRAINT "competition_entries_competition_id_competitions_id_fk" FOREIGN KEY ("competition_id") REFERENCES "public"."competitions"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "competition_entries" ADD CONSTRAINT "competition_entries_workspace_id_organization_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "referral_codes" ADD CONSTRAINT "referral_codes_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "referrals" ADD CONSTRAINT "referrals_referrer_id_users_id_fk" FOREIGN KEY ("referrer_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "referrals" ADD CONSTRAINT "referrals_referred_user_id_users_id_fk" FOREIGN KEY ("referred_user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "referrals" ADD CONSTRAINT "referrals_referral_code_id_referral_codes_id_fk" FOREIGN KEY ("referral_code_id") REFERENCES "public"."referral_codes"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "shared_reports" ADD CONSTRAINT "shared_reports_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "shared_reports" ADD CONSTRAINT "shared_reports_workspace_id_organization_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "knowledge_articles_slug_idx" ON "knowledge_articles" USING btree ("slug");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "knowledge_articles_category_idx" ON "knowledge_articles" USING btree ("category");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "competitions_is_active_idx" ON "competitions" USING btree ("is_active");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "competition_entries_competition_id_idx" ON "competition_entries" USING btree ("competition_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "competition_entries_workspace_id_idx" ON "competition_entries" USING btree ("workspace_id");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "competition_entries_competition_workspace_idx" ON "competition_entries" USING btree ("competition_id","workspace_id");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "referral_codes_code_idx" ON "referral_codes" USING btree ("code");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "referral_codes_user_id_idx" ON "referral_codes" USING btree ("user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "referrals_referrer_id_idx" ON "referrals" USING btree ("referrer_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "referrals_referred_user_id_idx" ON "referrals" USING btree ("referred_user_id");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "referrals_referred_user_id_unique_idx" ON "referrals" USING btree ("referred_user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "shared_reports_user_id_idx" ON "shared_reports" USING btree ("user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "shared_reports_workspace_id_idx" ON "shared_reports" USING btree ("workspace_id");

package/src/db/migrations/0016_document_types.sql

@@ -0,0 +1,30 @@
+-- Document Types reference table
+CREATE TABLE IF NOT EXISTS "document_types" (
+  "id" text PRIMARY KEY,
+  "name" text NOT NULL,
+  "name_mn" text NOT NULL,
+  "description" text,
+  "icon" text,
+  "sort_order" integer NOT NULL DEFAULT 0,
+  "is_active" boolean NOT NULL DEFAULT true,
+  "created_at" timestamp DEFAULT now() NOT NULL
+);
+
+-- Add type_id column to documents
+ALTER TABLE "documents" ADD COLUMN IF NOT EXISTS "type_id" text REFERENCES "document_types"("id") ON DELETE SET NULL;
+
+-- Index for type lookups
+CREATE INDEX IF NOT EXISTS "documents_type_id_idx" ON "documents" ("type_id");
+
+-- Seed 5 career document types
+INSERT INTO "document_types" ("id", "name", "name_mn", "description", "icon", "sort_order") VALUES
+  ('career-report', 'Career Report', 'Карьерын тайлан', 'Full career assessment report with recommendations', 'file-text', 0),
+  ('deep-dive-report', 'Deep Dive Report', 'Гүнзгий шинжилгээ', 'Detailed analysis of a specific career path', 'search', 1),
+  ('scholarship-report', 'Scholarship Report', 'Тэтгэлгийн тайлан', 'Scholarship matching and financial aid report', 'gift', 2),
+  ('comparison-report', 'Comparison Report', 'Харьцуулалт', 'Side-by-side career or university comparison', 'columns', 3),
+  ('skills-report', 'Skills Report', 'Ур чадварын тайлан', 'Skills gap analysis and development plan', 'target', 4)
+ON CONFLICT ("id") DO NOTHING;
+
+-- Backfill existing career report documents
+UPDATE "documents" SET "type_id" = 'career-report'
+WHERE "kind" = 'text' AND ("title" LIKE '%Карьерын Тайлан%' OR "title" LIKE '%Career Report%');

package/src/db/migrations/0017_document_metadata.sql

@@ -0,0 +1,2 @@
+-- Add metadata JSONB column to documents for structured data storage
+ALTER TABLE "documents" ADD COLUMN IF NOT EXISTS "metadata" jsonb;

package/src/db/migrations/0018_identity_graph.sql

@@ -0,0 +1,200 @@
+-- AI-ARCHITECTURE Phase B: User Identity Graph
+--
+-- Adds the four tables that back the cross-product memory system.
+-- See packages/core/src/db/schema/identity.ts for the Drizzle schema
+-- and docs/AI-ARCHITECTURE.md §2 for the design rationale.
+--
+-- Numbering note: this file is named 0018 to slot after the existing
+-- 0017_document_metadata. The project mixes two migration patterns —
+-- 0000–0011 are tracked by drizzle's _journal.json (auto-generated by
+-- `drizzle-kit generate`), while 0012–0018 are hand-rolled SQL applied
+-- via `pnpm --filter @intelligo-dev/core db:push` and have no journal
+-- entry. Future hand-rolled migrations should continue the 0019,
+-- 0020, ... sequence and stay out of _journal.json.
+--
+-- This migration is hand-crafted (not produced by `drizzle-kit generate`)
+-- because the auto-generator also picks up unrelated drift between the
+-- current schema files and the last applied migration. Keeping the
+-- diff narrow lets this PR ship the identity layer without dragging in
+-- those unrelated alterations.
+
+-- ---------------------------------------------------------------------------
+-- 1. user_facts — structured, evidence-backed facts
+-- ---------------------------------------------------------------------------
+CREATE TABLE "user_facts" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"workspace_id" text NOT NULL,
+	"category" text NOT NULL,
+	"key" text NOT NULL,
+	"value" jsonb NOT NULL,
+	"confidence" double precision NOT NULL,
+	"importance" integer DEFAULT 5 NOT NULL,
+	"source_product" text,
+	"source_session_id" text,
+	"source_message_id" text,
+	"extraction_method" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"last_confirmed_at" timestamp,
+	"expires_at" timestamp
+);
+--> statement-breakpoint
+ALTER TABLE "user_facts" ADD CONSTRAINT "user_facts_user_id_users_id_fk"
+	FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade;
+--> statement-breakpoint
+ALTER TABLE "user_facts" ADD CONSTRAINT "user_facts_workspace_id_organization_id_fk"
+	FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade;
+--> statement-breakpoint
+CREATE INDEX "user_facts_user_idx" ON "user_facts" USING btree ("user_id");
+--> statement-breakpoint
+CREATE INDEX "user_facts_workspace_idx" ON "user_facts" USING btree ("workspace_id");
+--> statement-breakpoint
+CREATE INDEX "user_facts_category_idx" ON "user_facts" USING btree ("workspace_id", "category");
+--> statement-breakpoint
+CREATE UNIQUE INDEX "user_facts_workspace_category_key_uniq"
+	ON "user_facts" USING btree ("workspace_id", "category", "key");
+--> statement-breakpoint
+
+-- ---------------------------------------------------------------------------
+-- 2. user_memories — episodic memories with pgvector embedding
+-- ---------------------------------------------------------------------------
+CREATE TABLE "user_memories" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"workspace_id" text NOT NULL,
+	"kind" text NOT NULL,
+	"content" text NOT NULL,
+	-- 1536 dimensions matches OpenAI text-embedding-3-small (the default
+	-- embedding model used across @intelligo-dev/ai). If the embedding model
+	-- ever changes the dimension constraint will need a new migration —
+	-- pgvector cannot resize a vector column in place. Search for
+	-- "vector(1536)" in apps/* before editing.
+	"embedding" vector(1536),
+	"source_product" text,
+	"source_session_id" text,
+	"source_message_ids" text[],
+	"importance" integer DEFAULT 5 NOT NULL,
+	"decay_factor" double precision DEFAULT 1 NOT NULL,
+	"metadata" jsonb,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "user_memories" ADD CONSTRAINT "user_memories_user_id_users_id_fk"
+	FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade;
+--> statement-breakpoint
+ALTER TABLE "user_memories" ADD CONSTRAINT "user_memories_workspace_id_organization_id_fk"
+	FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade;
+--> statement-breakpoint
+CREATE INDEX "user_memories_user_idx" ON "user_memories" USING btree ("user_id");
+--> statement-breakpoint
+CREATE INDEX "user_memories_workspace_idx" ON "user_memories" USING btree ("workspace_id");
+--> statement-breakpoint
+CREATE INDEX "user_memories_kind_idx" ON "user_memories" USING btree ("workspace_id", "kind");
+--> statement-breakpoint
+-- IVFFlat vector index for cosine-similarity recall. Drizzle-orm
+-- doesn't expose this syntax natively, so it lives in the migration.
+--
+-- `lists = 100` is a starter value tuned for ~100k–1M rows
+-- (rule of thumb: rows / 1000). IVFFlat performance degrades when the
+-- table grows past `lists * sqrt(rows)`, so once Phase F starts
+-- ingesting real memories at scale this should be either:
+--   (a) raised to ~sqrt(actual_rows), then REINDEX, or
+--   (b) replaced with HNSW (`USING hnsw (...) WITH (m=16, ef_construction=64)`),
+-- which doesn't have IVFFlat's tuning sensitivity but uses more memory.
+-- See docs/AI-ARCHITECTURE.md §2.2 for the recall path that uses this.
+CREATE INDEX "user_memories_embedding_ivfflat"
+	ON "user_memories" USING ivfflat ("embedding" vector_cosine_ops) WITH (lists = 100);
+--> statement-breakpoint
+
+-- ---------------------------------------------------------------------------
+-- 3. user_profile_snapshots — synthesized, fast-read profile cache
+-- ---------------------------------------------------------------------------
+CREATE TABLE "user_profile_snapshots" (
+	"user_id" text PRIMARY KEY NOT NULL,
+	"workspace_id" text NOT NULL,
+	"version" integer NOT NULL,
+	"summary" text NOT NULL,
+	"summary_en" text,
+	"summary_mn" text,
+	"facts_digest" jsonb NOT NULL,
+	"active_goals" jsonb,
+	"personality_signals" jsonb,
+	"relationship_notes" jsonb,
+	"synthesized_by_model" text,
+	"synthesized_at" timestamp DEFAULT now() NOT NULL,
+	"next_synthesis_at" timestamp,
+	"trigger_reason" text
+);
+--> statement-breakpoint
+ALTER TABLE "user_profile_snapshots" ADD CONSTRAINT "user_profile_snapshots_user_id_users_id_fk"
+	FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade;
+--> statement-breakpoint
+ALTER TABLE "user_profile_snapshots" ADD CONSTRAINT "user_profile_snapshots_workspace_id_organization_id_fk"
+	FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade;
+--> statement-breakpoint
+CREATE INDEX "user_profile_snapshots_workspace_idx"
+	ON "user_profile_snapshots" USING btree ("workspace_id");
+--> statement-breakpoint
+
+-- ---------------------------------------------------------------------------
+-- 4. user_memory_audit — append-only audit log
+-- ---------------------------------------------------------------------------
+CREATE TABLE "user_memory_audit" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"workspace_id" text NOT NULL,
+	"target_kind" text NOT NULL,
+	"target_id" text NOT NULL,
+	"action" text NOT NULL,
+	"actor_kind" text NOT NULL,
+	"actor_id" text,
+	"before_value" jsonb,
+	"after_value" jsonb,
+	"reason" text,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "user_memory_audit" ADD CONSTRAINT "user_memory_audit_user_id_users_id_fk"
+	FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade;
+--> statement-breakpoint
+ALTER TABLE "user_memory_audit" ADD CONSTRAINT "user_memory_audit_workspace_id_organization_id_fk"
+	FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade;
+--> statement-breakpoint
+CREATE INDEX "user_memory_audit_user_idx" ON "user_memory_audit" USING btree ("user_id");
+--> statement-breakpoint
+CREATE INDEX "user_memory_audit_workspace_idx" ON "user_memory_audit" USING btree ("workspace_id");
+--> statement-breakpoint
+CREATE INDEX "user_memory_audit_target_idx"
+	ON "user_memory_audit" USING btree ("target_kind", "target_id");
+--> statement-breakpoint
+
+-- Append-only enforcement: facts/memories/snapshots can be updated and
+-- deleted via the application layer, but their audit trail must not.
+-- A future PR can replace this with a row-level revoke if RLS is wired
+-- up; the trigger guard is the smaller change for now.
+--
+-- The function is fully qualified as `public.user_memory_audit_block_mutation`
+-- so a future schema split (e.g., moving identity tables into an
+-- "identity" schema) won't shadow it.
+--
+-- The exception message deliberately omits NEW.* / OLD.* — Postgres
+-- writes RAISE EXCEPTION strings to the server log by default, and the
+-- audit row's before/after values can contain user PII (interest,
+-- skill, etc. extracted by an LLM). ERRCODE 25006 = read_only_sql_transaction;
+-- close enough for upstream callers to recognize the class without
+-- needing a custom code.
+CREATE OR REPLACE FUNCTION public.user_memory_audit_block_mutation()
+	RETURNS trigger AS $$
+BEGIN
+	RAISE EXCEPTION 'user_memory_audit is append-only'
+		USING ERRCODE = '25006', HINT = 'INSERT new audit rows; do not UPDATE or DELETE existing ones.';
+END;
+$$ LANGUAGE plpgsql;
+--> statement-breakpoint
+CREATE TRIGGER user_memory_audit_no_update
+	BEFORE UPDATE ON "user_memory_audit"
+	FOR EACH ROW EXECUTE FUNCTION public.user_memory_audit_block_mutation();
+--> statement-breakpoint
+CREATE TRIGGER user_memory_audit_no_delete
+	BEFORE DELETE ON "user_memory_audit"
+	FOR EACH ROW EXECUTE FUNCTION public.user_memory_audit_block_mutation();

package/src/db/migrations/0019_db_driven_prompts.sql

@@ -0,0 +1,20 @@
+-- Phase C — DB-driven prompts and model config.
+--
+-- Adds two columns to the agents table that turn the database into the
+-- single source of truth for prompts and per-agent model selection. Both
+-- columns are nullable so the migration is safe to apply before the seed
+-- backfill runs; once the seed has populated the new fields, application
+-- code reads only from the database (the legacy
+-- apps/app/lib/prompts/career-advisor.ts file is removed in the same
+-- phase).
+--
+-- system_prompt is shaped as the BilingualText JSON {"en": "...", "mn": "..."},
+-- matching the existing `name` and `description` columns. model_config is a
+-- forward-looking JSONB blob that will eventually replace `default_model`
+-- with full routing rules; for now it stores at minimum { primary: "..." }.
+--
+-- Apply with: psql $DATABASE_URL -f packages/core/src/db/migrations/0019_db_driven_prompts.sql
+
+ALTER TABLE "agents"
+  ADD COLUMN IF NOT EXISTS "system_prompt" jsonb,
+  ADD COLUMN IF NOT EXISTS "model_config" jsonb;

package/src/db/migrations/0020_pending_extractions.sql

@@ -0,0 +1,35 @@
+-- Phase F — pending_extractions queue.
+--
+-- Background-job queue for fact extraction. The chat handler enqueues
+-- one row per ended conversation; the worker (in @intelligo-dev/agents)
+-- polls 'pending' rows, transitions them through 'processing' →
+-- ('completed' | 'failed'), and the conversation_id uniqueness
+-- constraint guarantees a conversation is never enqueued twice.
+--
+-- Cron poller wiring lands in a follow-up; this migration only
+-- creates the storage layer so the worker has somewhere to read from.
+--
+-- Apply with: psql $DATABASE_URL -f packages/core/src/db/migrations/0020_pending_extractions.sql
+
+CREATE TABLE IF NOT EXISTS "pending_extractions" (
+  "id" text PRIMARY KEY,
+  "conversation_id" text NOT NULL,
+  "workspace_id" text NOT NULL REFERENCES "organization"("id") ON DELETE CASCADE,
+  "user_id" text NOT NULL REFERENCES "users"("id") ON DELETE CASCADE,
+  "product_slug" text NOT NULL,
+
+  "status" text NOT NULL DEFAULT 'pending',
+  "attempts" integer NOT NULL DEFAULT 0,
+  "max_attempts" integer NOT NULL DEFAULT 3,
+
+  "last_error" text,
+  "next_retry_at" timestamp,
+
+  "enqueued_at" timestamp NOT NULL DEFAULT NOW(),
+  "started_at" timestamp,
+  "completed_at" timestamp
+);
+
+CREATE INDEX IF NOT EXISTS "pending_extractions_status_idx" ON "pending_extractions" ("status");
+CREATE INDEX IF NOT EXISTS "pending_extractions_workspace_idx" ON "pending_extractions" ("workspace_id");
+CREATE UNIQUE INDEX IF NOT EXISTS "pending_extractions_conversation_uniq" ON "pending_extractions" ("conversation_id");

package/src/db/migrations/0021_rag_documents.sql

@@ -0,0 +1,39 @@
+-- Phase H — rag_documents table.
+--
+-- One shared table that backs every collection in
+-- @intelligo-dev/agents/rag. Each typed Collection wrapper in a product
+-- package writes through this table with its own `collection` slug
+-- and Zod-validated metadata, so adding a new collection means
+-- adding a TS file, not running a migration.
+--
+-- The pgvector index uses IVFFlat with cosine ops; the lists
+-- parameter starts conservative for early-launch traffic and can be
+-- tuned upward via REINDEX once we measure real recall vs. query
+-- latency. The composite (collection, embedding) layout means a
+-- per-collection ANN search filters first then ranks.
+--
+-- Apply with: psql $DATABASE_URL -f packages/core/src/db/migrations/0021_rag_documents.sql
+
+CREATE TABLE IF NOT EXISTS "rag_documents" (
+  "id" text PRIMARY KEY,
+  "collection" text NOT NULL,
+  "external_id" text,
+
+  "content" text NOT NULL,
+  "metadata" jsonb NOT NULL DEFAULT '{}'::jsonb,
+  "embedding" vector(1536),
+
+  "created_at" timestamp NOT NULL DEFAULT NOW(),
+  "updated_at" timestamp NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS "rag_documents_collection_idx" ON "rag_documents" ("collection");
+CREATE UNIQUE INDEX IF NOT EXISTS "rag_documents_collection_external_uniq" ON "rag_documents" ("collection", "external_id");
+
+-- IVFFlat index for cosine similarity. lists=100 is a reasonable
+-- starting point for ~10k documents per collection; bump after
+-- measuring recall.
+CREATE INDEX IF NOT EXISTS "rag_documents_embedding_idx"
+  ON "rag_documents"
+  USING ivfflat ("embedding" vector_cosine_ops)
+  WITH (lists = 100);

package/src/db/migrations/0022_user_quotas_usage_jsonb.sql

@@ -0,0 +1,70 @@
+-- NOTE (2026-08-26): user_quotas is created here.
+--
+-- No migration ever created it — the table existed only in schema.ts,
+-- so every environment got it from `drizzle-kit push` and replaying
+-- the chain against an empty database died on the ALTER below. Of the
+-- 49 tables in the schema it was the only one missing from the chain.
+--
+-- Created in this file rather than a new earlier one because this is
+-- the first migration that touches the table; a repair migration would
+-- have needed a number that sorts between 0021 and 0022. Guarded, so
+-- databases that already have it are unaffected.
+CREATE TABLE IF NOT EXISTS "user_quotas" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" text NOT NULL,
+	"workspace_id" text NOT NULL,
+	"plan" text DEFAULT 'free' NOT NULL,
+	"chat_messages_used" integer DEFAULT 0 NOT NULL,
+	"assessments_used" integer DEFAULT 0 NOT NULL,
+	"reports_used" integer DEFAULT 0 NOT NULL,
+	"total_cost_usd" real DEFAULT 0 NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "user_quotas_user_id_unique" UNIQUE("user_id")
+);
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "user_quotas" ADD CONSTRAINT "user_quotas_user_id_users_id_fk"
+    FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+  ALTER TABLE "user_quotas" ADD CONSTRAINT "user_quotas_workspace_id_organization_id_fk"
+    FOREIGN KEY ("workspace_id") REFERENCES "public"."organization"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "user_quotas_user_id_idx" ON "user_quotas" USING btree ("user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "user_quotas_workspace_id_idx" ON "user_quotas" USING btree ("workspace_id");
+--> statement-breakpoint
+
+-- Wave 4 — userQuotas.usage JSONB column for generic per-action counters.
+--
+-- Adds a generic `usage` JSONB column alongside the legacy career-only
+-- chat_messages_used / assessments_used / reports_used integer columns.
+-- The new column starts at '{}' for every row; recordFeatureUsage in
+-- @intelligo-dev/billing/feature-quota.ts dual-writes both the legacy
+-- column AND the corresponding `usage[action]` slot so the read path
+-- can be flipped atomically in a follow-up commit once production
+-- soak confirms the JSONB pathway is reliable.
+--
+-- Backfill query (optional, for any rows that already have legacy
+-- counts that need to be reflected in the JSONB shape):
+--
+--   UPDATE user_quotas
+--   SET usage = jsonb_build_object(
+--     'chat', chat_messages_used,
+--     'assessment', assessments_used,
+--     'report', reports_used
+--   )
+--   WHERE usage = '{}'::jsonb;
+--
+-- Run the backfill once after the deploy and verify counts match
+-- before flipping the read path.
+--
+-- Apply with: psql $DATABASE_URL -f packages/core/src/db/migrations/0022_user_quotas_usage_jsonb.sql
+
+ALTER TABLE "user_quotas"
+  ADD COLUMN IF NOT EXISTS "usage" jsonb NOT NULL DEFAULT '{}'::jsonb;

package/src/db/migrations/0023_user_facts_user_scoped_unique.sql

@@ -0,0 +1,17 @@
+-- AI-ARCHITECTURE follow-up: user_facts uniqueness must include user_id.
+--
+-- The original 0018 migration scoped the unique index to
+-- (workspace_id, category, key), which made it impossible for two
+-- members of the same org (family, classroom, team) to hold the
+-- same fact key — e.g. two students both with `interest: mathematics`.
+-- The second upsert would collide on the unique index and either
+-- fail or silently overwrite the first user's fact.
+--
+-- Drop the old index and replace it with a (user_id, workspace_id,
+-- category, key) unique index so facts are always scoped to the
+-- owning user.
+
+DROP INDEX IF EXISTS "user_facts_workspace_category_key_uniq";
+--> statement-breakpoint
+CREATE UNIQUE INDEX "user_facts_user_workspace_category_key_uniq"
+	ON "user_facts" USING btree ("user_id", "workspace_id", "category", "key");

package/src/db/migrations/0024_user_memories_hnsw.sql

@@ -0,0 +1,23 @@
+-- AI-ARCHITECTURE follow-up: switch user_memories embedding index to HNSW.
+--
+-- The original 0018 migration used IVFFlat with `lists = 100`, a value
+-- tuned for ~100k–1M rows. At launch the table starts empty, so for
+-- the first several months IVFFlat recall will be degraded: with
+-- rows << lists the probe count dominates and approximation quality
+-- drops.
+--
+-- HNSW (available in pgvector >= 0.5.0) has no such tuning cliff —
+-- recall is good from a handful of rows up through tens of millions,
+-- at the cost of somewhat higher build time and ~2x memory per vector.
+-- For this workload (synthesis-time recall, not per-request search)
+-- that tradeoff is clearly worth it.
+--
+-- m / ef_construction values follow the pgvector docs' defaults
+-- tuned for text embeddings; we can raise ef_construction later via
+-- REINDEX if recall needs tightening.
+
+DROP INDEX IF EXISTS "user_memories_embedding_ivfflat";
+--> statement-breakpoint
+CREATE INDEX "user_memories_embedding_hnsw"
+	ON "user_memories" USING hnsw ("embedding" vector_cosine_ops)
+	WITH (m = 16, ef_construction = 64);

package/src/db/migrations/0025_audit_trigger_errcode.sql

@@ -0,0 +1,21 @@
+-- AI-ARCHITECTURE follow-up: fix audit trigger exception class.
+--
+-- 0018 used ERRCODE 25006 (read_only_sql_transaction) for the
+-- append-only guard on user_memory_audit. That code is documented
+-- for "SQL transaction is read-only" and is semantically wrong for
+-- "this table rejects UPDATE/DELETE" — a Sentry filter or pg error
+-- class handler could misroute the exception into the transient
+-- retry bucket.
+--
+-- P0001 (raise_exception) is the correct generic class for
+-- application-level invariants raised via RAISE EXCEPTION. The
+-- trigger still fires on BEFORE UPDATE and BEFORE DELETE and the
+-- hint stays PII-free.
+
+CREATE OR REPLACE FUNCTION public.user_memory_audit_block_mutation()
+	RETURNS trigger AS $$
+BEGIN
+	RAISE EXCEPTION 'user_memory_audit is append-only'
+		USING ERRCODE = 'P0001', HINT = 'INSERT new audit rows; do not UPDATE or DELETE existing ones.';
+END;
+$$ LANGUAGE plpgsql;

package/src/db/migrations/0026_user_profile_snapshots_composite_pk.sql

@@ -0,0 +1,17 @@
+-- AI-ARCHITECTURE follow-up: user_profile_snapshots composite primary key.
+--
+-- 0018 used user_id alone as the PK, which hardcoded "one snapshot per
+-- user globally". The moment a user belongs to more than one workspace
+-- (family + classroom, personal + team, etc.) those workspaces would
+-- be forced to share a single synthesized profile — collapsing
+-- context that should stay separate.
+--
+-- Switch to a composite PK on (user_id, workspace_id). Existing rows
+-- already have workspace_id populated, so the migration is a straight
+-- PK drop + re-add.
+
+ALTER TABLE "user_profile_snapshots" DROP CONSTRAINT "user_profile_snapshots_pkey";
+--> statement-breakpoint
+ALTER TABLE "user_profile_snapshots"
+	ADD CONSTRAINT "user_profile_snapshots_user_id_workspace_id_pk"
+	PRIMARY KEY ("user_id", "workspace_id");