zam-core 0.9.2 → 0.9.4

package/dist/cli/commands/mcp.js

@@ -585,7 +585,12 @@ CREATE TABLE IF NOT EXISTS tokens (
   deprecated_at TEXT,
   question      TEXT,
   provider      TEXT,
-  topic_id      TEXT
+  topic_id      TEXT,
+  -- Who authored the current question ('manual' | 'llm' | 'template');
+  -- validated in code, not via CHECK. Column default is 'llm' so unlabeled
+  -- writes (pre-M013 rows, old snapshot restores) count as LLM-era content;
+  -- createToken() defaults to 'manual' for API callers instead.
+  question_source TEXT NOT NULL DEFAULT 'llm'
 );
 
 -- Prerequisite dependency graph: "to learn A, first know B"
@@ -1109,6 +1114,11 @@ async function runMigrations(db) {
   await db.exec(`
     CREATE INDEX IF NOT EXISTS idx_token_contexts_context ON token_contexts(context_id)
   `);
+  if (tokenCols.length > 0 && !tokenCols.some((c) => c.name === "question_source")) {
+    await db.exec(
+      `ALTER TABLE tokens ADD COLUMN question_source TEXT NOT NULL DEFAULT 'llm'`
+    );
+  }
 }
 var DEFAULT_DB_DIR, DEFAULT_DB_PATH, require2;
 var init_connection = __esm({
@@ -1269,7 +1279,11 @@ var init_snapshot = __esm({
       "review_logs",
       "session_syntheses",
       "user_config",
-      "agent_skills"
+      "agent_skills",
+      "sources",
+      "token_sources",
+      "contexts",
+      "token_contexts"
     ];
   }
 });
@@ -1754,6 +1768,13 @@ var init_knowledge_context = __esm({
 
 // src/kernel/models/token.ts
 import { ulid as ulid4 } from "ulid";
+function validateQuestionSource(value) {
+  if (!VALID_QUESTION_SOURCES.includes(value)) {
+    throw new Error(
+      `Invalid question_source: ${value} (expected one of ${VALID_QUESTION_SOURCES.join(", ")})`
+    );
+  }
+}
 async function createToken(db, input) {
   const id = ulid4();
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1762,9 +1783,11 @@ async function createToken(db, input) {
     throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
   }
   const title = input.title ?? "";
+  const questionSource = input.question_source ?? "manual";
+  validateQuestionSource(questionSource);
   await db.prepare(`
-    INSERT INTO tokens (id, slug, title, concept, domain, bloom_level, context, symbiosis_mode, source_link, question, provider, topic_id, created_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO tokens (id, slug, title, concept, domain, bloom_level, context, symbiosis_mode, source_link, question, question_source, provider, topic_id, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     id,
     input.slug,
@@ -1776,6 +1799,7 @@ async function createToken(db, input) {
     input.symbiosis_mode ?? null,
     input.source_link ?? null,
     input.question ?? null,
+    questionSource,
     input.provider ?? null,
     input.topic_id ?? null,
     now,
@@ -1799,6 +1823,18 @@ async function getTokenBySlug(db, slug) {
   parseTokenFallback(token);
   return token;
 }
+async function getTokensBySlugs(db, slugs) {
+  const tokens = /* @__PURE__ */ new Map();
+  const unique = [...new Set(slugs)];
+  if (unique.length === 0) return tokens;
+  const placeholders = unique.map(() => "?").join(",");
+  const rows = await db.prepare(`SELECT * FROM tokens WHERE slug IN (${placeholders})`).all(...unique);
+  for (const token of rows) {
+    parseTokenFallback(token);
+    tokens.set(token.slug, token);
+  }
+  return tokens;
+}
 async function getTokenById(db, id) {
   const token = await db.prepare("SELECT * FROM tokens WHERE id = ?").get(id);
   parseTokenFallback(token);
@@ -1852,6 +1888,12 @@ async function updateToken(db, slug, updates) {
     fields.push("question = ?");
     values.push(updates.question);
   }
+  const questionSource = updates.question_source ?? (updates.question !== void 0 ? "manual" : void 0);
+  if (questionSource !== void 0) {
+    validateQuestionSource(questionSource);
+    fields.push("question_source = ?");
+    values.push(questionSource);
+  }
   if (updates.provider !== void 0) {
     fields.push("provider = ?");
     values.push(updates.provider);
@@ -2180,6 +2222,9 @@ async function importCurriculumCards(db, userId, cards) {
           symbiosis_mode: symbiosisMode,
           source_link: card.source_link || null,
           question: card.question || null,
+          // Curriculum cards are LLM-extracted; their questions are LLM
+          // inventions, not human-authored content.
+          question_source: "llm",
           provider: card.provider || null,
           topic_id: card.topic_id || null
         });
@@ -2503,10 +2548,12 @@ async function assertPrerequisiteDoesNotCreateCycle(db, tokenId, prerequisiteId)
     throw new Error("Cannot add prerequisite: would create a cycle");
   }
 }
+var VALID_QUESTION_SOURCES;
 var init_token = __esm({
   "src/kernel/models/token.ts"() {
     "use strict";
     init_card();
+    VALID_QUESTION_SOURCES = ["manual", "llm", "template"];
   }
 });
 
@@ -3942,25 +3989,29 @@ async function cascadeBlock(db, userId, tokenSlug) {
   };
 }
 async function unblockReady(db, userId) {
-  const blockedCards = await db.prepare(
-    `SELECT c.token_id, t.slug, t.concept
-       FROM cards c
-       JOIN tokens t ON t.id = c.token_id
-       WHERE c.user_id = ? AND c.blocked = 1`
-  ).all(userId);
   const unblocked = [];
-  for (const card of blockedCards) {
-    const totalPrereqs = await db.prepare("SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?").get(card.token_id);
-    const metPrereqs = await db.prepare(
-      `SELECT COUNT(*) as n FROM cards c
-         JOIN prerequisites p ON p.requires_id = c.token_id
-         WHERE p.token_id = ? AND c.user_id = ? AND c.reps >= 1 AND c.blocked = 0`
-    ).get(card.token_id, userId);
-    if (totalPrereqs.n === 0 || metPrereqs.n === totalPrereqs.n) {
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      await db.prepare(
-        "UPDATE cards SET blocked = 0, due_at = ? WHERE token_id = ? AND user_id = ?"
-      ).run(now, card.token_id, userId);
+  for (; ; ) {
+    const readyCards = await db.prepare(
+      `SELECT c.token_id, t.slug, t.concept
+         FROM cards c
+         JOIN tokens t ON t.id = c.token_id
+         WHERE c.user_id = ? AND c.blocked = 1
+           AND (SELECT COUNT(*) FROM prerequisites p
+                WHERE p.token_id = c.token_id) =
+               (SELECT COUNT(*) FROM prerequisites p
+                JOIN cards pc ON pc.token_id = p.requires_id
+                  AND pc.user_id = c.user_id
+                WHERE p.token_id = c.token_id
+                  AND pc.reps >= 1 AND pc.blocked = 0)`
+    ).all(userId);
+    if (readyCards.length === 0) break;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const placeholders = readyCards.map(() => "?").join(",");
+    await db.prepare(
+      `UPDATE cards SET blocked = 0, due_at = ?
+         WHERE user_id = ? AND token_id IN (${placeholders})`
+    ).run(now, userId, ...readyCards.map((card) => card.token_id));
+    for (const card of readyCards) {
       unblocked.push({ slug: card.slug, concept: card.concept });
     }
   }
@@ -4137,10 +4188,14 @@ async function prepareSessionSynthesis(db, input) {
     await buildSkillPatterns(db),
     input.explicitPatterns ?? []
   );
+  const patternTokens = await getTokensBySlugs(
+    db,
+    patterns.map((pattern) => pattern.slug)
+  );
   const validPatterns = [];
   const tokens = /* @__PURE__ */ new Map();
   for (const pattern of patterns) {
-    const token = await getTokenBySlug(db, pattern.slug);
+    const token = patternTokens.get(pattern.slug);
     if (!token || token.deprecated_at) continue;
     validPatterns.push(pattern);
     tokens.set(pattern.slug, token);
@@ -4153,13 +4208,13 @@ async function prepareSessionSynthesis(db, input) {
   const minConfidence = input.minConfidence ?? "medium";
   if (session.execution_context === "ui") {
     const reports = readUiObservationLog(input.sessionId);
-    for (const report of reports) {
-      for (const candidate of report.candidateTokens) {
-        if (tokens.has(candidate.slug)) continue;
-        const token = await getTokenBySlug(db, candidate.slug);
-        if (token && !token.deprecated_at) {
-          tokens.set(candidate.slug, token);
-        }
+    const candidateTokens = await getTokensBySlugs(
+      db,
+      reports.flatMap((report) => report.candidateTokens).map((candidate) => candidate.slug).filter((slug) => !tokens.has(slug))
+    );
+    for (const [slug, token] of candidateTokens) {
+      if (!token.deprecated_at) {
+        tokens.set(slug, token);
       }
     }
     const { candidates: candidates2, skippedLowConfidence: skippedLowConfidence2 } = buildUiSynthesisCandidates(
@@ -5122,7 +5177,8 @@ async function buildReviewQueue(db, options) {
          c.state    AS state,
          c.due_at   AS due_at,
          t.source_link AS source_link,
-         t.question AS question
+         t.question AS question,
+         t.question_source AS question_source
        FROM cards c
        JOIN tokens t ON t.id = c.token_id
        WHERE c.user_id = ?
@@ -5152,7 +5208,8 @@ async function buildReviewQueue(db, options) {
          c.state    AS state,
          c.due_at   AS due_at,
          t.source_link AS source_link,
-         t.question AS question
+         t.question AS question,
+         t.question_source AS question_source
        FROM cards c
        JOIN tokens t ON t.id = c.token_id
        WHERE c.user_id = ?
@@ -5221,7 +5278,8 @@ function rowToItem(row) {
     state: row.state,
     dueAt: row.due_at,
     sourceLink: row.source_link,
-    question: row.question
+    question: row.question,
+    questionSource: row.question_source
   };
 }
 function intersperseNew(reviews, newCards, interval) {
@@ -7023,6 +7081,9 @@ async function generateQuestionViaLLM(db, input) {
   const bloom = input.bloomLevel >= 1 && input.bloomLevel <= 5 ? input.bloomLevel : 1;
   const verb = BLOOM_VERBS2[bloom];
   const langName = LANGUAGE_NAMES[cfg.locale] || "English";
+  const existingQuestion = input.existingQuestion?.trim();
+  const variationGuideline = existingQuestion ? `
+5. A canonical question for this token already exists. Generate a fresh VARIATION of it: test the same knowledge, but with different wording or from a different angle, so the learner cannot memorize the exact phrasing. Never repeat the canonical question verbatim.` : "";
   const systemPrompt = `You are ZAM, a highly precise agentic skills trainer.
 Your task is to generate a single, clear, conceptual active-recall question (flashcard front) in ${langName} for a knowledge token.
 
@@ -7030,12 +7091,13 @@ Guidelines:
 1. The question MUST match the Bloom level: ${verb} (Level ${bloom}).
 2. CRITICAL: The question MUST NOT contain or reveal the concept text itself! The concept is the answer (flashcard back) that the learner needs to recall.
 3. Keep the question concise, highly specific, and clear. Avoid generic prompts like "What is the concept of..." if possible, and ask about the core mechanism, function, or purpose of the slug/concept without giving the answer away.
-4. Output ONLY the raw question text in ${langName}. Do not include any preamble, headers, markdown fences, or conversational filler.`;
+4. Output ONLY the raw question text in ${langName}. Do not include any preamble, headers, markdown fences, or conversational filler.${variationGuideline}`;
   const userPrompt = `Domain: ${input.domain}
 Slug: ${input.slug}
 Concept to Recall (DO NOT REVEAL IN QUESTION): ${input.concept}
 Context: ${input.context || "(none)"}
-${input.sourceLinkContent ? `Source Reference:
+${existingQuestion ? `Canonical Question (vary, do not repeat verbatim): ${existingQuestion}
+` : ""}${input.sourceLinkContent ? `Source Reference:
 ${input.sourceLinkContent}` : ""}
 
 Active-Recall Question:`;
@@ -7228,7 +7290,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
 }
 async function ensureHighQualityQuestion(db, token) {
   const { enabled } = await getLlmConfig(db);
-  if (enabled) {
+  const variationEnabled = await getSetting(db, "llm.dynamic_questions") !== "false";
+  if (enabled && variationEnabled) {
     try {
       let sourceLinkContent = null;
       if (token.sourceLink) {
@@ -7244,10 +7307,10 @@ async function ensureHighQualityQuestion(db, token) {
         concept: token.concept,
         domain: token.domain,
         bloomLevel: token.bloomLevel,
-        sourceLinkContent
+        sourceLinkContent,
+        existingQuestion: token.question
       });
       if (generated.text.trim().length > 0) {
-        await updateToken(db, token.slug, { question: generated.text });
         return {
           question: generated.text,
           source: "llm",
@@ -7850,7 +7913,10 @@ async function addToken(db, params) {
     context: params.context,
     symbiosis_mode: params.symbiosisMode,
     source_link: params.sourceLink ?? null,
-    question: params.question ?? null
+    question: params.question ?? null,
+    // Bridge/MCP callers are agents: their questions are LLM-authored and
+    // stay refreshable. Humans author questions via the token CLI instead.
+    question_source: params.question ? "llm" : void 0
   });
   for (const context of assignedContexts) {
     await assignTokenToContext(db, token.id, context.id);