@thanh01.pmt/curriculum-kit 1.4.21 → 1.4.23

package/dist/index.cjs

@@ -11519,6 +11519,21 @@ function normalizeHeading(str) {
   return str.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/[^\w\s]/g, " ").replace(/\s+/g, " ").trim();
 }
 function findCanonicalFuzzy(norm) {
+  if (norm.includes("toolchain") || norm.includes("moi truong phat trien") || norm.includes("cong cu") || norm.includes("version") || norm.includes("phan mem") || norm.includes("development environment") || norm.includes("technical overview") || norm.includes("kien truc")) {
+    return "Technical Overview & Architecture Blueprint";
+  }
+  if (norm.includes("pinout") || norm.includes("phan cung") || norm.includes("hardware") || norm.includes("wiring") || norm.includes("ket noi")) {
+    return "Hardware Pinout & Wiring Configuration Matrix";
+  }
+  if (norm.includes("pedagog") || norm.includes("phuong phap") || norm.includes("day hoc") || norm.includes("su pham")) {
+    return "Core Pedagogical Concept Anchor & Real-World Domain Bridge";
+  }
+  if (norm.includes("standard") || norm.includes("tieu chuan") || norm.includes("csta") || norm.includes("cs2023") || norm.includes("chuan academic")) {
+    return "Standards Alignment";
+  }
+  if (norm.includes("roadmap") || norm.includes("lo trinh") || norm.includes("milestone") || norm.includes("giai doan")) {
+    return void 0;
+  }
   if (norm.includes("symbol") || norm.includes("identifier ledger") || norm.includes("dinh danh")) {
     return "Symbol & Identifier Ledger";
   }
@@ -11609,6 +11624,137 @@ function extractSymbolLedger(lessonMarkdown) {
   return result;
 }
 
+// src/services/artifactValidators.ts
+var CJK_RE = /[\u3400-\u4DBF\u4E00-\u9FFF\u3040-\u30FF\uAC00-\uD7AF]/g;
+function scanCjkLeaks(content) {
+  const matches = content.match(CJK_RE);
+  if (!matches || matches.length === 0) return null;
+  const lines = [];
+  for (const line of content.split("\n")) {
+    if (CJK_RE.test(line)) lines.push(line.trim().slice(0, 160));
+  }
+  return {
+    code: "cjk-leak",
+    detail: `Ph\xE1t hi\u1EC7n ${matches.length} k\xFD t\u1EF1 CJK (Trung/Nh\u1EADt/H\xE0n) trong artifact ng\xF4n ng\u1EEF Vi\u1EC7t/Anh. B\u1ECB c\u1EA5m tuy\u1EC7t \u0111\u1ED1i.`,
+    evidence: lines.slice(0, 5)
+  };
+}
+var VERSION_CLAIM_RE = /\b([A-Z][A-Za-z+#.\-]{1,24})\s+(\d{1,2}(?:\.\d{1,2})?)\b/g;
+function checkVersionGroundTruth(content, refPack) {
+  if (!refPack || !refPack.trim()) return null;
+  const packLower = refPack.toLowerCase();
+  const claims = /* @__PURE__ */ new Map();
+  for (const m of content.matchAll(VERSION_CLAIM_RE)) {
+    const tool = m[1];
+    if (claims.size === 0 || !claims.has(tool)) claims.set(tool, m[2]);
+  }
+  const contradictions = [];
+  for (const [tool, claimed] of claims) {
+    const toolRe = new RegExp(`\\b${tool.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+(\\d{1,2}(?:\\.\\d{1,2})?)\\b`, "i");
+    const packMatch = packLower.match(toolRe);
+    if (packMatch && packMatch[1] !== claimed) {
+      contradictions.push(`${tool}: artifact n\xF3i ${claimed}, REFERENCE_PACK ch\u1ED1t ${packMatch[1]}`);
+    }
+  }
+  if (contradictions.length === 0) return null;
+  return {
+    code: "version-contradiction",
+    detail: `Version m\xE2u thu\u1EABn v\u1EDBi ground truth REFERENCE_PACK: ${contradictions.join("; ")}. S\u1EEDa theo b\u1EA3n trong REFERENCE_PACK.`,
+    evidence: contradictions
+  };
+}
+function checkScopeDrift(content, scopedKeywords, tolerance = 0) {
+  const conceptHeaders = /* @__PURE__ */ new Set();
+  for (const m of content.matchAll(/\*\*([^*\n]{3,60}?)\s*\((?:WHAT|CIO|SIO|ULO)[^)]*\):\*\*/g)) {
+    conceptHeaders.add(m[1].toLowerCase());
+  }
+  if (conceptHeaders.size === 0) return null;
+  const drift = [];
+  for (const header of conceptHeaders) {
+    const hit = scopedKeywords.some((kw) => {
+      const k = kw.toLowerCase().trim();
+      if (!k) return false;
+      const tokens = k.split(/\s+/);
+      const present = tokens.filter((t) => header.includes(t)).length;
+      return present >= Math.max(1, tokens.length - tolerance);
+    });
+    if (!hit) drift.push(header);
+  }
+  if (drift.length === 0) return null;
+  return {
+    code: "scope-drift",
+    detail: `C\xE1c kh\xE1i ni\u1EC7m sau KH\xD4NG thu\u1ED9c scope c\u1EE7a bu\u1ED5i h\u1ECDc (kh\xF4ng c\xF3 trong new_keywords/graph node keywords): ${drift.join(" | ")}. Xo\xE1 ho\xE0n to\xE0n ho\u1EB7c thay b\u1EB1ng kh\xE1i ni\u1EC7m trong scope.`,
+    evidence: drift
+  };
+}
+function validateArtifactDeterministic(input) {
+  const issues = [];
+  const cjk = scanCjkLeaks(input.content);
+  if (cjk) issues.push(cjk);
+  if (input.refPack) {
+    const ver = checkVersionGroundTruth(input.content, input.refPack);
+    if (ver) issues.push(ver);
+  }
+  if (input.scopedKeywords && input.scopedKeywords.length > 0) {
+    const scope = checkScopeDrift(input.content, input.scopedKeywords);
+    if (scope) issues.push(scope);
+  }
+  return { ok: issues.length === 0, issues };
+}
+function validatorRepairPrompt(issues) {
+  return [
+    "DETERMINISTIC VALIDATOR FAILURES (mechanically detected \u2014 non-negotiable, fix ALL):",
+    ...issues.map((i, n) => `${n + 1}. [${i.code}] ${i.detail}${i.evidence.length ? `
+   Evidence: ${i.evidence.join(" | ").slice(0, 400)}` : ""}`)
+  ].join("\n");
+}
+
+// src/services/productSpec.ts
+function extractToolchainFacts(refPack) {
+  const { excerpt } = buildSectionAwareExcerpt(refPack, {
+    priorities: ["Technical Overview & Architecture Blueprint", "Hardware Pinout & Wiring Configuration Matrix"],
+    budget: 4e3
+  });
+  if (!excerpt) return [];
+  const factLines = [];
+  for (const rawLine of excerpt.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (/\d{1,2}(?:\.\d{1,2})?/.test(line) || /Xcode|Swift|macOS|iOS|SDK|Node|Python|JDK|\.NET/i.test(line)) {
+      factLines.push(line.replace(/^[-*•]\s*/, "- "));
+    }
+    if (factLines.length >= 8) break;
+  }
+  return factLines;
+}
+function buildProductSpecBlock(input) {
+  const b = input.briefing || {};
+  const platform = (input.overrides?.primaryLanguage || b.coreTechnology || b.techStack || b.topic || "").trim();
+  const hardware = (b.hardwarePlatform || b.studentEquipment || b.classDynamic || "").trim();
+  const toolchainFacts = input.refPack ? extractToolchainFacts(input.refPack) : [];
+  const lines = [];
+  lines.push("[PRODUCT SPEC \u2014 CANONICAL, BINDING FOR EVERY ARTIFACT OF THIS PROJECT]:");
+  lines.push("All decisions below are PROJECT-WIDE. Every artifact (LESSON, satellites, KX)");
+  lines.push("must describe the SAME product. Contradicting or re-deciding any line here is a");
+  lines.push("consistency failure \u2014 if a needed decision is absent, stay GENERIC, never invent.");
+  lines.push("");
+  if (platform) {
+    lines.push(`- Primary technology: ${platform}`);
+  }
+  if (hardware) {
+    lines.push(`- Hardware / classroom setup: ${hardware}`);
+  }
+  if (input.overrides?.deliverableTemplate) {
+    lines.push(`- Deliverable template: ${input.overrides.deliverableTemplate}`);
+  }
+  if (toolchainFacts.length > 0) {
+    lines.push("- Toolchain & versions (ground truth):");
+    for (const f of toolchainFacts) lines.push(`  ${f}`);
+  }
+  if (lines.length <= 5) return "";
+  return lines.join("\n");
+}
+
 // src/services/knowledgeExpositionService.ts
 var EXPOSITION_REL = (lessonCode) => "_sot/expositions/" + lessonCode + ".md";
 var ExpositionApprovalError = class extends Error {
@@ -11655,7 +11801,7 @@ function buildSystemPrompt(targetLanguage = "vi", techStack, hardwarePlatform) {
     langDirective
   ].join("\n");
 }
-function buildUserPrompt(session, plan, glossary, targetLanguage = "vi", slcMarkdown) {
+function buildUserPrompt(session, plan, glossary, targetLanguage = "vi", slcMarkdown, refPack) {
   const depthLines = session.depth_assignments.map((d) => "- " + d.node_id + " [" + d.depth.toUpperCase() + "]: " + DEPTH_RULES[d.depth]).join("\n");
   const termLines = glossary.map((g) => "- " + g.term + (g.definition ? " \u2014 " + g.definition : "") + (g.example ? " (example: " + g.example + ")" : "")).join("\n");
   const langCode = resolveTargetLanguageCode(targetLanguage);
@@ -11668,6 +11814,28 @@ function buildUserPrompt(session, plan, glossary, targetLanguage = "vi", slcMark
   const hQuestions = headings["Self-Check Questions"] || (langCode === "vi" ? "C\xE2u h\u1ECFi T\u1EF1 ki\u1EC3m tra" : "Self-Check Questions");
   const skeleton = `## ${hScope} / ## ${hTerms} / ## ${hNarratives} / ## ${hExamples} / ## ${hMistakes} / ## ${hQuestions}`;
   const headingDirective = buildHeadingDirective("KNOWLEDGE_EXPOSITION", slcMarkdown, targetLanguage);
+  let refPackBlock = "";
+  if (refPack && refPack.trim()) {
+    const refExcerpt = buildSectionAwareExcerpt(refPack, {
+      priorities: [
+        "Technical Overview & Architecture Blueprint",
+        "Hardware Pinout & Wiring Configuration Matrix",
+        "Standards Alignment"
+      ],
+      budget: 2500
+    }).excerpt;
+    if (refExcerpt) {
+      refPackBlock = [
+        "",
+        "[GROUND TRUTH \u2014 BINDING, from REFERENCE_PACK.md]:",
+        "Tool versions, APIs, and platform facts below are CANONICAL. Do NOT",
+        "contradict them; do NOT substitute versions from memory. If a fact you",
+        "need is not stated here, stay generic rather than inventing specifics.",
+        "",
+        refExcerpt
+      ].join("\n");
+    }
+  }
   return [
     "Session: " + session.id + " \u2014 " + session.title,
     "Objective: " + session.prose_objective,
@@ -11680,6 +11848,7 @@ function buildUserPrompt(session, plan, glossary, targetLanguage = "vi", slcMark
     "",
     "Glossary terms (definitions are canonical):",
     termLines || "(none provided \u2014 write definitions and mark them for glossary sync)",
+    refPackBlock,
     "",
     "Section skeleton to fill (replace ONLY the {{placeholders}}):",
     skeleton,
@@ -11688,7 +11857,7 @@ function buildUserPrompt(session, plan, glossary, targetLanguage = "vi", slcMark
   ].filter(Boolean).join("\n");
 }
 async function ensureKnowledgeExposition(options) {
-  const { projectId, lessonCode, plan, glossary, llmFn, storage, techStack, hardwarePlatform } = options;
+  const { projectId, lessonCode, plan, glossary, llmFn, storage, techStack, hardwarePlatform, refPack } = options;
   const session = plan.sessions.find((s) => s.id === lessonCode);
   if (!session) throw new Error("Session " + lessonCode + " not found in plan " + plan.plan_id);
   const existing = await storage.readArtifact(projectId, EXPOSITION_REL(lessonCode));
@@ -11702,9 +11871,16 @@ async function ensureKnowledgeExposition(options) {
     throw new ExpositionApprovalError("Approval hash " + plan.approval.plan_hash + " does not match current plan hash " + plan.plan_hash + " \u2014 re-approve after plan changes");
   }
   const targetLanguage = options.targetLanguage || plan.translation?.target_language || "vi";
+  const originalSystemPrompt = buildSystemPrompt(targetLanguage, techStack, hardwarePlatform);
+  const productSpecBlock = buildProductSpecBlock({
+    refPack,
+    briefing: techStack || hardwarePlatform ? { techStack, hardwarePlatform } : void 0,
+    overrides: options.productSpec
+  });
+  const originalUserPrompt = buildUserPrompt(session, plan, glossary, targetLanguage, options.slcMarkdown, refPack) + (productSpecBlock ? "\n\n" + productSpecBlock : "");
   const content = (await llmFn(
-    buildSystemPrompt(targetLanguage, techStack, hardwarePlatform),
-    buildUserPrompt(session, plan, glossary, targetLanguage, options.slcMarkdown)
+    originalSystemPrompt,
+    originalUserPrompt
   )).trim();
   if (content.length < 200) {
     throw new Error("EXPOSITION too short for " + lessonCode + " (" + content.length + " chars) \u2014 refusing to save");
@@ -11735,11 +11911,30 @@ async function ensureKnowledgeExposition(options) {
       const parsed = JSON.parse(match[0]);
       return { verdict: parsed.verdict ?? "NEEDS_REVISION", score: parsed.score ?? 0, critique: parsed.critique ?? "" };
     };
-    let verdict = await judgeOnce(finalContent);
+    const scopedKeywords = [
+      ...session.new_keywords,
+      ...glossary.map((g) => g.term)
+    ];
+    const runDeterministic = (candidate) => validateArtifactDeterministic({
+      content: candidate,
+      refPack,
+      scopedKeywords
+    });
+    let det = runDeterministic(finalContent);
+    let verdict = det.ok ? await judgeOnce(finalContent) : { verdict: "NEEDS_REVISION", score: 0, critique: validatorRepairPrompt(det.issues) };
     if (verdict.verdict !== "APPROVED") {
-      const repairPrompt = finalContent + "\n\nJUDGE CRITIQUE (fix ALL issues, output the COMPLETE corrected document):\n" + verdict.critique;
-      finalContent = (await llmFn(buildSystemPrompt(), repairPrompt)).trim();
-      verdict = await judgeOnce(finalContent);
+      const repairPrompt = [
+        originalUserPrompt,
+        "",
+        "--- YOUR PREVIOUS DRAFT (REJECTED, fix ALL issues below) ---",
+        finalContent,
+        "",
+        "--- CRITIQUE (fix ALL issues, output the COMPLETE corrected document) ---",
+        verdict.critique
+      ].join("\n");
+      finalContent = (await llmFn(originalSystemPrompt, repairPrompt)).trim();
+      det = runDeterministic(finalContent);
+      verdict = det.ok ? await judgeOnce(finalContent) : { verdict: "NEEDS_REVISION", score: 0, critique: validatorRepairPrompt(det.issues) };
     }
     if (verdict.verdict !== "APPROVED") {
       throw new Error("EXPOSITION failed judge for " + lessonCode + " (verdict " + verdict.verdict + ", score " + verdict.score + "): " + verdict.critique);
@@ -11779,12 +11974,27 @@ async function ensureExpositionForLesson(storage, projectId, lessonCode, options
     try {
       const lpRaw = await storage.readSotDocument(projectId, "LEARNER_PROFILE.md");
       if (lpRaw) {
-        const hwMatch = lpRaw.match(/(?:Student Equipment|Hardware|Platform|Thiết bị)[:\s*`]+([^\n\r]+)/i);
-        if (hwMatch && !hw) hw = hwMatch[1].trim();
+        const hwPatterns = [
+          /(?:Student Equipment|Hardware|Platform|Thiết bị|Thiết bị học tập)\s*(?:\(|:|\*)*\s*([^\n\r]+?)(?:\s*\*\*|[.).]?\s*$)/i,
+          /(?:máy|device|machine)\s+([^,.;\n]{4,60}(?:M\d|Intel|PC|computer|mini)[^,.;\n]{0,30})/i
+        ];
+        for (const p of hwPatterns) {
+          const m = lpRaw.match(p);
+          if (m && !hw) {
+            hw = m[1].trim();
+            break;
+          }
+        }
       }
     } catch {
     }
   }
+  let refPackContent;
+  try {
+    refPackContent = await storage.readSotDocument(projectId, "REFERENCE_PACK.md") || void 0;
+  } catch {
+    refPackContent = void 0;
+  }
   const { runCurriculumAIInference: runCurriculumAIInference2 } = await Promise.resolve().then(() => (init_streamRunner(), streamRunner_exports));
   const targetLang = options.targetLanguage || plan.translation?.target_language || "vi";
   const result = await ensureKnowledgeExposition({
@@ -11796,6 +12006,7 @@ async function ensureExpositionForLesson(storage, projectId, lessonCode, options
     slcMarkdown: options.slcMarkdown,
     techStack: tech,
     hardwarePlatform: hw,
+    refPack: refPackContent,
     llmFn: async (systemPrompt, userPrompt) => {
       const runnerOpts = options.customInference ? { customInference: options.customInference } : {};
       const out = await runCurriculumAIInference2(
@@ -26094,11 +26305,16 @@ async function produceSingleLesson(storage, projectId, lessonId, options = {}) {
   }).excerpt : "";
   let effectiveRefPack = refPack ? buildSectionAwareExcerpt(refPack, {
     priorities: [
+      // Toolchain/version matrix FIRST — the most-frequently-hallucinated
+      // facts are tool versions ("Xcode 15" vs ground truth "Xcode 16").
+      // The bilingual fuzzy matcher in contextBuilder resolves these keys
+      // even when the generated RefPack headings are Vietnamese.
       "Technical Overview & Architecture Blueprint",
       "Hardware Pinout & Wiring Configuration Matrix",
+      "Standards Alignment",
       "Core Pedagogical Concept Anchor & Real-World Domain Bridge"
     ],
-    budget: 2500
+    budget: 3500
   }).excerpt : "";
   const baseContextPrefix = `PROJECT & ACADEMIC CONTEXT:
 - Project ID: ${projectId}
@@ -26147,6 +26363,10 @@ ${expositionContext}`);
       parts.push(`### REFERENCE PACK GROUND TRUTH
 ${effectiveRefPack}`);
     }
+    const productSpec = buildProductSpecBlock({ refPack, briefing: options.briefing });
+    if (productSpec) {
+      parts.push(productSpec);
+    }
     return parts.length > 0 ? `
 
 [GROUND TRUTH]:
@@ -26305,6 +26525,23 @@ ${yamlBlock.trim()}
 `);
       };
       var injectYamlReviewMetadata = injectYamlReviewMetadata2;
+      const lessonDet = validateArtifactDeterministic({ content: lessonContent, refPack });
+      if (!lessonDet.ok) {
+        const detCritique = validatorRepairPrompt(lessonDet.issues);
+        onProgress?.("@reviewer", `\u26D4 LESSON deterministic validator FAIL: ${detCritique.slice(0, 200)}`);
+        await storage.updateArtifactState(projectId, lessonCode, "LESSON", {
+          state: "rejected",
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          contentHash: computeContentHash(lessonContent),
+          review: {
+            decision: "NEEDS_REVISION",
+            reviewedBy: "@heuristic-linter",
+            reviewedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            score: 0,
+            critique: detCritique
+          }
+        });
+      }
       const judgeObjectives = parseLessonObjectives(lessonContent, concept, bloomLevel);
       const judgeExpositionExcerpt = expositionContext ? buildExpositionExcerpt(expositionContext, { budget: 3e3, sectionLanguageContract: slcMarkdown, artifactType: "KNOWLEDGE_EXPOSITION" }).excerpt : void 0;
       const judgeResult = await LLMJudgeEngine.evaluateArtifactWithLLM({
@@ -26560,6 +26797,23 @@ ${currentContent}` }],
 ${lessonExcerpt}${symbolLedgerBlock}`;
   const judgeSat = (sat, content) => {
     if (gateModeFor(gates, sat) !== "LLM_JUDGE") return Promise.resolve();
+    const det = validateArtifactDeterministic({ content, refPack });
+    if (!det.ok) {
+      const critique = validatorRepairPrompt(det.issues);
+      onProgress?.("@reviewer", `\u26D4 ${sat} deterministic validator FAIL: ${critique.slice(0, 200)}`);
+      return storage.updateArtifactState(projectId, lessonCode, sat, {
+        state: "rejected",
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        contentHash: computeContentHash(content),
+        review: {
+          decision: "NEEDS_REVISION",
+          reviewedBy: "@heuristic-linter",
+          reviewedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          score: 0,
+          critique
+        }
+      });
+    }
     return judgeSatelliteArtifact({
       storage,
       projectId,