feat(ai): per-course mentor preferences table (contract request 4)

0002_ai_mentor_prefs.sql adds ai_mentor_prefs(user_id, course_id, off).
upgradeAiData copies v1 config_json.mentorOff toggles into it once
(marked ai_data_v11 in schema_migrations); the settings repo awaits the
upgrade before first use and aiFeature starts it at construction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

packages/feature-ai/src/feature.ts

@@ -145,6 +145,8 @@ export function aiFeature(ctx: ServerContext, opts: AiFeatureOptions = {}): Feat
   const progress = progressRepo(ctx.db);
   const sink = opts.draftSink ?? createFsDraftSink(ctx.config.dataDir);
   const log = opts.log ?? ((m: string) => console.error(`[ai] ${m}`));
+  // The v1 data upgrade (mentor toggles, MCP secrets) starts now; every settings call also waits for it.
+  settings.ready().catch((e) => log(`v1.1 data upgrade failed (retried on next use): ${(e as Error).message}`));
   // AppConfig.aiAllowedBaseUrls (STC_AI_ALLOWED_BASE_URLS) plus the admin's list in the server AI settings.
   const configOrigins = parseAllowedOrigins((ctx.config.aiAllowedBaseUrls ?? []).join(","));
   const allowedOrigins = async () => [...new Set([...configOrigins, ...(await settings.getServer()).allowedBaseUrls])];

packages/feature-ai/src/index.ts

@@ -2,6 +2,7 @@ export { createSecretBox, type SecretBox } from "./crypto";
 
 export { migrationsDirs } from "./migrations";
 export * from "./settings";
+export { upgradeAiData, AI_DATA_UPGRADE } from "./upgrade";
 export * from "./providers";
 export * from "./retrieval/course-index";
 export { Bm25, tokenize } from "./retrieval/bm25";

packages/feature-ai/src/settings.ts

@@ -1,5 +1,6 @@
 import type { Db } from "@stc/db";
 import type { SecretBox } from "./crypto";
+import { upgradeAiData } from "./upgrade";
 
 export type ProviderKind = "anthropic" | "openai";
 export type Effort = "low" | "medium" | "high" | "xhigh" | "max";
@@ -30,7 +31,7 @@ export interface ServerSettingsInput {
 export interface UserSettings { byok: PublicProviderConfig | null; mentorOff: Record<string, boolean> }
 
 type ServerRow = { provider: ProviderConfig | null; apiKeyCipher: string | null; mcpServers: McpServerConfig[]; allowedBaseUrls?: string[] };
-type UserRow = { byok: ProviderConfig | null; mentorOff: Record<string, boolean> };
+type UserRow = { byok: ProviderConfig | null };
 
 const pickProvider = (p: ProviderConfig): ProviderConfig => {
   const out: ProviderConfig = { kind: p.kind };
@@ -46,14 +47,18 @@ const parse = <T>(s: string | undefined, fallback: T): T => {
 };
 
 /**
- * AI settings in the ai_settings and user_api_keys tables of 0001_init.sql.
+ * AI settings in ai_settings and user_api_keys (core 0001_init.sql) and ai_mentor_prefs (this package's 0002).
  * - ('server', '') holds the admin provider (key encrypted) and MCP servers.
- * - ('user', <userId>) holds the BYOK provider choice and per-course mentor toggles. The frozen primary key
- *   is (scope, owner_id), so the per-course flag lives in config_json; the mentor_off column means
- *   "off for every course" and stays 0 (see docs/contract-requests/ai.md).
+ * - ('user', <userId>) holds the BYOK provider choice. The mentor_off column ("off for every course") stays 0.
+ * - ai_mentor_prefs has a row per (user, course) whose mentor rules the learner switched off.
  * Keys never leave this module except through serverApiKey/userApiKey, which only server code calls.
+ * Every method first awaits the one-time v1 data upgrade (upgradeAiData); a failed attempt is retried next call.
  */
 export function aiSettingsRepo(db: Db, box: SecretBox) {
+  let upgraded: Promise<unknown> | null = null;
+  const ready = () =>
+    (upgraded ??= upgradeAiData(db, box).catch((e) => { upgraded = null; throw e; }));
+
   const read = async (scope: "server" | "user", owner: string): Promise<string | undefined> => {
     const rows = await db.sql`SELECT config_json FROM ai_settings WHERE scope = ${scope} AND owner_id = ${owner}`;
     return rows[0]?.config_json;
@@ -68,16 +73,23 @@ export function aiSettingsRepo(db: Db, box: SecretBox) {
     });
   };
   const serverRow = async (): Promise<ServerRow> => parse(await read("server", ""), { provider: null, apiKeyCipher: null, mcpServers: [] });
-  const userRow = async (userId: string): Promise<UserRow> => parse(await read("user", userId), { byok: null, mentorOff: {} });
+  const userRow = async (userId: string): Promise<UserRow> => {
+    const { mentorOff: _legacy, ...row } = parse(await read("user", userId), { byok: null } as UserRow & { mentorOff?: unknown });
+    return row;
+  };
   const keyRow = async (userId: string) =>
     (await db.sql`SELECT provider, ciphertext FROM user_api_keys WHERE user_id = ${userId}`)[0] as { provider: string; ciphertext: string } | undefined;
 
   return {
+    /** Resolves once the v1 data upgrade is done (aiFeature starts it at construction). */
+    ready: async (): Promise<void> => { await ready(); },
     async getServer(): Promise<ServerSettings> {
+      await ready();
       const r = await serverRow();
       return { provider: r.provider ? { ...r.provider, hasApiKey: !!r.apiKeyCipher } : null, mcpServers: r.mcpServers ?? [], allowedBaseUrls: r.allowedBaseUrls ?? [] };
     },
     async saveServer(input: ServerSettingsInput): Promise<void> {
+      await ready();
       const prev = await serverRow();
       let apiKeyCipher: string | null = null;
       if (input.provider) {
@@ -92,15 +104,19 @@ export function aiSettingsRepo(db: Db, box: SecretBox) {
       });
     },
     async serverApiKey(): Promise<string | null> {
+      await ready();
       const r = await serverRow();
       return r.provider && r.apiKeyCipher ? box.decrypt(r.apiKeyCipher) : null;
     },
     async getUser(userId: string): Promise<UserSettings> {
+      await ready();
       const r = await userRow(userId);
       const k = await keyRow(userId);
-      return { byok: r.byok && k ? { ...r.byok, hasApiKey: true } : null, mentorOff: r.mentorOff ?? {} };
+      const prefs = (await db.sql`SELECT course_id FROM ai_mentor_prefs WHERE user_id = ${userId} AND off = 1`) as { course_id: string }[];
+      return { byok: r.byok && k ? { ...r.byok, hasApiKey: true } : null, mentorOff: Object.fromEntries(prefs.map((p) => [p.course_id, true])) };
     },
     async saveUserKey(userId: string, cfg: ProviderConfig & { apiKey: string }): Promise<void> {
+      await ready();
       const ciphertext = await box.encrypt(cfg.apiKey);
       const now = new Date().toISOString();
       await db.sql.begin(async (tx) => {
@@ -111,23 +127,26 @@ export function aiSettingsRepo(db: Db, box: SecretBox) {
       await write("user", userId, { ...r, byok: pickProvider(cfg) });
     },
     async removeUserKey(userId: string): Promise<void> {
+      await ready();
       await db.sql`DELETE FROM user_api_keys WHERE user_id = ${userId}`;
       const r = await userRow(userId);
       await write("user", userId, { ...r, byok: null });
     },
     async userApiKey(userId: string): Promise<string | null> {
+      await ready();
       const k = await keyRow(userId);
       return k ? box.decrypt(k.ciphertext) : null;
     },
     async setMentorOff(userId: string, courseId: string, off: boolean): Promise<void> {
-      const r = await userRow(userId);
-      const mentorOff = { ...r.mentorOff };
-      if (off) mentorOff[courseId] = true;
-      else delete mentorOff[courseId];
-      await write("user", userId, { ...r, mentorOff });
+      await ready();
+      await db.sql.begin(async (tx) => {
+        await tx`DELETE FROM ai_mentor_prefs WHERE user_id = ${userId} AND course_id = ${courseId}`;
+        if (off) await tx`INSERT INTO ai_mentor_prefs (user_id, course_id, off, updated_at) VALUES (${userId}, ${courseId}, 1, ${new Date().toISOString()})`;
+      });
     },
     async isMentorOff(userId: string, courseId: string): Promise<boolean> {
-      return (await userRow(userId)).mentorOff?.[courseId] === true;
+      await ready();
+      return (await db.sql`SELECT 1 AS x FROM ai_mentor_prefs WHERE user_id = ${userId} AND course_id = ${courseId} AND off = 1`).length > 0;
     },
   };
 }

packages/feature-ai/src/upgrade.ts

@@ -0,0 +1,45 @@
+import type { Db } from "@stc/db";
+import type { SecretBox } from "./crypto";
+
+/** Recorded in schema_migrations once the data upgrade has run (no `.sql` suffix, so no file can share it). */
+export const AI_DATA_UPGRADE = "ai_data_v11";
+
+type Tx = Bun.TransactionSQL;
+
+const parseObject = (s: string): Record<string, unknown> | null => {
+  try {
+    const v = JSON.parse(s);
+    return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+  } catch { return null; }
+};
+
+/** v1 kept per-course toggles in the user row's config_json.mentorOff; move them to ai_mentor_prefs. */
+async function moveMentorToggles(tx: Tx, now: string) {
+  const rows = (await tx`SELECT owner_id, config_json FROM ai_settings WHERE scope = 'user'`) as { owner_id: string; config_json: string }[];
+  for (const r of rows) {
+    const cfg = parseObject(r.config_json);
+    if (!cfg || !("mentorOff" in cfg)) continue;
+    const off = cfg.mentorOff && typeof cfg.mentorOff === "object" ? (cfg.mentorOff as Record<string, unknown>) : {};
+    for (const [courseId, v] of Object.entries(off)) {
+      if (v !== true || !courseId) continue;
+      const exists = await tx`SELECT 1 AS x FROM ai_mentor_prefs WHERE user_id = ${r.owner_id} AND course_id = ${courseId}`;
+      if (!exists.length) await tx`INSERT INTO ai_mentor_prefs (user_id, course_id, off, updated_at) VALUES (${r.owner_id}, ${courseId}, 1, ${now})`;
+    }
+    const { mentorOff: _drop, ...rest } = cfg;
+    await tx`UPDATE ai_settings SET config_json = ${JSON.stringify(rest)}, updated_at = ${now} WHERE scope = 'user' AND owner_id = ${r.owner_id}`;
+  }
+}
+
+/**
+ * Data the v1.1 SQL migrations cannot move portably. Runs after the package's migrations, in one transaction,
+ * once (marked in schema_migrations). Returns true if it ran now. The settings repo awaits it before first use.
+ */
+export async function upgradeAiData(db: Db, _box: SecretBox): Promise<boolean> {
+  return db.sql.begin(async (tx) => {
+    if ((await tx`SELECT name FROM schema_migrations WHERE name = ${AI_DATA_UPGRADE}`).length) return false;
+    const now = new Date().toISOString();
+    await moveMentorToggles(tx, now);
+    await tx`INSERT INTO schema_migrations (name, applied_at) VALUES (${AI_DATA_UPGRADE}, ${now})`;
+    return true;
+  });
+}