zam-core 0.9.3 → 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,
@@ -1864,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);
@@ -2192,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
         });
@@ -2515,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"];
   }
 });
 
@@ -5142,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 = ?
@@ -5172,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 = ?
@@ -5241,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) {
@@ -7043,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.
 
@@ -7050,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:`;
@@ -7248,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) {
@@ -7264,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",
@@ -7870,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);