@thanh01.pmt/curriculum-kit 1.0.22 → 1.2.0

package/dist/workflow/index.d.cts

@@ -1,8 +1,8 @@
 import { MilestoneInput, LessonPlan, CurriculumQualityReport, ActivityLab, CodeLab, SelfLab, DiagnosticQuiz, SlideDeck, Handout, Worksheet, TeacherGuide, Extension, ProjectRoadmap } from '../schemas/index.cjs';
 import { M as ModelResolutionOptions } from '../provider-factory-DxzOVEmh.cjs';
 import { G as GitPublishOptions, a as GitPublishResult, S as SupabasePublishOptions, b as SupabasePublishResult } from '../supabasePublisher-C627qXFT.cjs';
-import { S as SingleArtifactRequest, a as SingleArtifactResult } from '../gateSettings-DKXRztJy.cjs';
-export { b as CurriculumArtifactType, C as CurriculumGateMode, D as DEFAULT_GATE_SETTINGS, G as GateSettings, R as ResolvedGateSettings, g as gateModeFor, p as parseGateSettings, r as resolveGateSettings } from '../gateSettings-DKXRztJy.cjs';
+import { S as SingleArtifactRequest, a as SingleArtifactResult } from '../gateSettings-Buk_MSML.cjs';
+export { b as CurriculumArtifactType, C as CurriculumGateMode, D as DEFAULT_GATE_SETTINGS, G as GateSettings, R as ResolvedGateSettings, g as gateModeFor, p as parseGateSettings, r as resolveGateSettings } from '../gateSettings-Buk_MSML.cjs';
 import * as workflow from 'workflow';
 import { z } from 'zod';
 import { F as FrameworkPack, C as CoverageGateReport } from '../standardsCoverageGate-CsUNzv6C.cjs';

package/dist/workflow/index.d.ts

@@ -1,8 +1,8 @@
 import { MilestoneInput, LessonPlan, CurriculumQualityReport, ActivityLab, CodeLab, SelfLab, DiagnosticQuiz, SlideDeck, Handout, Worksheet, TeacherGuide, Extension, ProjectRoadmap } from '../schemas/index.js';
 import { M as ModelResolutionOptions } from '../provider-factory-DxzOVEmh.js';
 import { G as GitPublishOptions, a as GitPublishResult, S as SupabasePublishOptions, b as SupabasePublishResult } from '../supabasePublisher-C627qXFT.js';
-import { S as SingleArtifactRequest, a as SingleArtifactResult } from '../gateSettings-DKXRztJy.js';
-export { b as CurriculumArtifactType, C as CurriculumGateMode, D as DEFAULT_GATE_SETTINGS, G as GateSettings, R as ResolvedGateSettings, g as gateModeFor, p as parseGateSettings, r as resolveGateSettings } from '../gateSettings-DKXRztJy.js';
+import { S as SingleArtifactRequest, a as SingleArtifactResult } from '../gateSettings-Buk_MSML.js';
+export { b as CurriculumArtifactType, C as CurriculumGateMode, D as DEFAULT_GATE_SETTINGS, G as GateSettings, R as ResolvedGateSettings, g as gateModeFor, p as parseGateSettings, r as resolveGateSettings } from '../gateSettings-Buk_MSML.js';
 import * as workflow from 'workflow';
 import { z } from 'zod';
 import { F as FrameworkPack, C as CoverageGateReport } from '../standardsCoverageGate-CsUNzv6C.js';

package/dist/workflow/index.mjs

@@ -68,6 +68,8 @@ function getSuggestedActionForCode(code) {
       return "N\u1ED9i dung sinh ra thi\u1EBFu c\xE1c ph\u1EA7n b\u1EAFt bu\u1ED9c [REQUIRED]. H\xE3y k\xEDch ho\u1EA1t ki\u1EC3m th\u1EED ho\u1EB7c b\u1EA5m Rerun.";
     case "ERR_STORAGE_IO_FAILED":
       return "L\u1ED7i \u0111\u1ECDc/ghi t\u1EC7p tin tr\xEAn h\u1EC7 th\u1ED1ng l\u01B0u tr\u1EEF. Ki\u1EC3m tra quy\u1EC1n ghi th\u01B0 m\u1EE5c output/projects.";
+    case "ERR_CONTEXT_MISSING":
+      return "Thi\u1EBFu ngu\u1ED3n tri th\u1EE9c b\u1EAFt bu\u1ED9c (KNOWLEDGE_EXPOSITION ho\u1EB7c CANONICAL LESSON) theo Dependency Routing Matrix. Vui l\xF2ng t\u1EA1o ho\u1EB7c \u0111\u1ED3ng b\u1ED9 t\xE0i li\u1EC7u ngu\u1ED3n tr\u01B0\u1EDBc.";
     default:
       return "B\u1EA5m Rerun \u0111\u1EC3 th\u1EED l\u1EA1i ho\u1EB7c ki\u1EC3m tra nh\u1EADt k\xFD h\u1EC7 th\u1ED1ng.";
   }
@@ -85,11 +87,23 @@ function isCodeRetryable(code) {
     case "ERR_TASK_GATE_BLOCKED":
     case "ERR_METERED_LIMIT_EXCEEDED":
     case "ERR_SCHEMA_CONTRACT_VIOLATION":
+    case "ERR_CONTEXT_MISSING":
       return false;
     default:
       return true;
   }
 }
+function createContextMissingError(params) {
+  return new CurriculumError({
+    errorCode: "ERR_CONTEXT_MISSING",
+    artifactType: params.artifactType,
+    lessonId: params.lessonId,
+    agent: params.agent,
+    message: `Required context source "${params.missingSource}" is missing for artifact "${params.artifactType}"`,
+    suggestedAction: `Generate or provide the authoritative "${params.missingSource}" source before producing "${params.artifactType}".`,
+    retryable: false
+  });
+}
 var CurriculumError;
 var init_errors = __esm({
   "src/errors/index.ts"() {
@@ -2222,9 +2236,20 @@ var SessionPlanSchema = z.object({
   differentiation: z.object({ bronze: z.string(), silver: z.string(), gold: z.string() })
 });
 var TranslationPolicySchema = z.object({
-  policy: z.enum(["after_artifact", "end_of_unit", "at_publish"]).default("at_publish"),
+  policy: z.enum(["after_artifact", "end_of_unit", "at_publish", "native"]).default("native"),
   target_language: z.string().nullable().default(null)
-});
+}).refine(
+  (data) => {
+    if (data.policy === "native") {
+      return typeof data.target_language === "string" && data.target_language.trim().length > 0;
+    }
+    return true;
+  },
+  {
+    message: "When translation policy is 'native', target_language must be a non-empty string",
+    path: ["target_language"]
+  }
+);
 var CoverageReportSchema = z.object({
   assigned_node_ids: z.array(z.string()),
   unassigned_node_ids: z.array(z.string()),
@@ -6195,6 +6220,307 @@ var LLMJudgeEngine = class {
 // src/services/lessonProductionService.ts
 init_errors();
 
+// src/services/contextBuilder.ts
+var DEFAULT_LESSON_PRIORITIES = [
+  "A. Lesson Design Plan",
+  "B. Lesson Flow",
+  "Learning Objectives & Evidence",
+  "Activity Sequence"
+];
+var DEFAULT_KX_PRIORITIES = [
+  "Key Terms",
+  "Concept Narratives",
+  "Worked Micro-Examples"
+];
+function buildSectionAwareExcerpt(markdown, opts = {}) {
+  const budget = opts.budget ?? 12e3;
+  const minContentChars = opts.minContentChars ?? 400;
+  const issues = [];
+  const source = (markdown || "").trim();
+  if (!source) {
+    return {
+      excerpt: "",
+      verified: false,
+      sectionAware: false,
+      includedSections: [],
+      issues: ["empty-source"],
+      tokenEstimate: 0
+    };
+  }
+  const slcMap = normalizeSlcContract(opts.sectionLanguageContract);
+  const sections = parseMarkdownSections(source, slcMap, opts.artifactType);
+  if (sections.length === 0) {
+    issues.push("parse:no-sections");
+    const excerpt2 = truncateByBudget(source, budget);
+    const verified2 = excerpt2.length >= minContentChars;
+    if (excerpt2.length < minContentChars) issues.push("content:insufficient");
+    return {
+      excerpt: excerpt2,
+      verified: verified2,
+      sectionAware: false,
+      includedSections: [],
+      issues,
+      tokenEstimate: Math.round(excerpt2.length / 4)
+    };
+  }
+  const byCanonical = /* @__PURE__ */ new Map();
+  const unmatched = [];
+  for (const s of sections) {
+    if (s.canonicalKey && !byCanonical.has(s.canonicalKey)) {
+      byCanonical.set(s.canonicalKey, s);
+    } else {
+      unmatched.push(s);
+    }
+  }
+  const priorities = opts.priorities ?? DEFAULT_LESSON_PRIORITIES;
+  const includedSections = [];
+  const blocks = [];
+  let used = 0;
+  const tryAdd = (heading, body, key) => {
+    const trimmedBody = body.trim();
+    if (!trimmedBody) return false;
+    const block = `## ${heading}
+
+${trimmedBody}`;
+    if (used + block.length > budget && blocks.length > 0) return false;
+    blocks.push(block);
+    used += block.length;
+    includedSections.push(key);
+    return true;
+  };
+  let sectionAware = false;
+  for (const key of priorities) {
+    const sec = byCanonical.get(key);
+    if (!sec) continue;
+    sectionAware = true;
+    if (!tryAdd(sec.cleanTitle, sec.body, key)) break;
+  }
+  for (const [key, sec] of byCanonical) {
+    if (includedSections.includes(key)) continue;
+    if (used >= budget) break;
+    if (!tryAdd(sec.cleanTitle, sec.body, key)) break;
+  }
+  for (const sec of unmatched) {
+    if (used >= budget) break;
+    if (!tryAdd(sec.cleanTitle, sec.body, sec.cleanTitle)) break;
+  }
+  if (priorities.length > 0 && !priorities.some((k) => includedSections.includes(k))) {
+    issues.push("parse:no-priority-resolution");
+  }
+  let excerpt = blocks.join("\n\n");
+  if (excerpt.length > budget) {
+    excerpt = truncateByBudget(excerpt, budget);
+  }
+  const effectiveMinChars = Math.min(minContentChars, source.length);
+  if (excerpt.length < effectiveMinChars) {
+    issues.push("content:insufficient");
+  }
+  const verified = !issues.includes("parse:no-priority-resolution") && excerpt.length >= effectiveMinChars;
+  return {
+    excerpt,
+    verified,
+    sectionAware: sectionAware || priorities.length === 0 && sections.length > 0,
+    includedSections,
+    issues,
+    tokenEstimate: Math.round(excerpt.length / 4)
+  };
+}
+function buildExpositionExcerpt(markdown, opts = {}) {
+  return buildSectionAwareExcerpt(markdown, {
+    ...opts,
+    priorities: DEFAULT_KX_PRIORITIES
+  });
+}
+function buildLessonExcerpt(markdown, opts = {}) {
+  return buildSectionAwareExcerpt(markdown, {
+    ...opts,
+    priorities: DEFAULT_LESSON_PRIORITIES
+  });
+}
+function normalizeSlcContract(slc) {
+  if (!slc) return void 0;
+  if (typeof slc !== "string") return slc;
+  const out = {};
+  const blocks = slc.split(/\n(?=#{2,3}\s+[A-Z0-9_]+)/g);
+  for (const block of blocks) {
+    const header = block.match(/^#{2,3}\s+([A-Z0-9_]+)/);
+    if (!header?.[1]) continue;
+    const mapping = {};
+    for (const line of block.split("\n")) {
+      const t = line.trim();
+      if (!t.startsWith("|") || t.includes("---")) continue;
+      const cells = t.split("|").map((c) => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1);
+      const [c0, c1] = cells;
+      if (c0 && c1 && !c0.toLowerCase().includes("canonical") && !c1.toLowerCase().includes("localized")) {
+        mapping[c0] = c1;
+      }
+    }
+    if (Object.keys(mapping).length > 0) out[header[1]] = mapping;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function parseMarkdownSections(markdown, slcMap, artifactType) {
+  const sections = [];
+  const lines = markdown.split("\n");
+  let currentHeading = "";
+  let currentBody = [];
+  const reverseMap = /* @__PURE__ */ new Map();
+  if (slcMap) {
+    const maps = artifactType && slcMap[artifactType] ? [slcMap[artifactType]] : Object.values(slcMap);
+    for (const m of maps) {
+      for (const [canonical, localized] of Object.entries(m)) {
+        reverseMap.set(normalizeHeading(localized), canonical);
+        reverseMap.set(normalizeHeading(canonical), canonical);
+      }
+    }
+  }
+  const flush = () => {
+    if (!currentHeading && currentBody.length === 0) return;
+    const cleanTitle = currentHeading.replace(/^#{1,4}\s+/, "").trim();
+    const norm = normalizeHeading(cleanTitle);
+    const canonicalKey = reverseMap.get(norm) || findCanonicalFuzzy(norm);
+    sections.push({
+      rawHeading: currentHeading,
+      cleanTitle,
+      canonicalKey,
+      body: currentBody.join("\n")
+    });
+    currentBody = [];
+  };
+  const hasH2 = lines.some((l) => /^##\s+/.test(l));
+  const headingRegex = hasH2 ? /^##\s+(.*)$/ : /^#{2,3}\s+(.*)$/;
+  for (const line of lines) {
+    const headingMatch = line.match(headingRegex);
+    if (headingMatch) {
+      flush();
+      currentHeading = line.trim();
+    } else {
+      currentBody.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+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("lesson design plan") || norm.includes("ke hoach thiet ke")) {
+    return "A. Lesson Design Plan";
+  }
+  if (norm.includes("lesson flow") || norm.includes("tien trinh giang day")) {
+    return "B. Lesson Flow";
+  }
+  if (norm.includes("learning objective") || norm.includes("muc tieu bai hoc")) {
+    return "Learning Objectives & Evidence";
+  }
+  if (norm.includes("activity sequence") || norm.includes("chuoi hoat dong")) {
+    return "Activity Sequence";
+  }
+  if (norm.includes("key term") || norm.includes("thuat ngu")) {
+    return "Key Terms";
+  }
+  if (norm.includes("concept narrative") || norm.includes("dien giai khai niem")) {
+    return "Concept Narratives";
+  }
+  if (norm.includes("worked example") || norm.includes("vi du")) {
+    return "Worked Micro-Examples";
+  }
+  return void 0;
+}
+function truncateByBudget(source, budget) {
+  if (source.length <= budget) return source;
+  let cut = source.slice(0, budget);
+  const fenceCount = (cut.match(/^```/gm) || []).length;
+  if (fenceCount % 2 === 1) cut += "\n```";
+  return cut;
+}
+init_errors();
+
+// src/services/languageDirective.ts
+function resolveTargetLanguageCode(language) {
+  const raw = String(language || "vi").trim().toLowerCase();
+  if (raw.startsWith("vi")) return "vi";
+  if (raw.startsWith("en")) return "en";
+  return raw || "vi";
+}
+function targetLanguageDisplayName(code) {
+  const map = {
+    vi: "Vietnamese (Ti\u1EBFng Vi\u1EC7t)",
+    en: "English (US)"
+  };
+  return map[code] || code;
+}
+function buildLanguageDirective(targetLanguage) {
+  const code = resolveTargetLanguageCode(targetLanguage);
+  const name = targetLanguageDisplayName(code);
+  const perLanguageExamples = {
+    vi: `- V\xED d\u1EE5 ti\xEAu \u0111\u1EC1 b\xE0i h\u1ECDc \u0111\xFAng chu\u1EA9n: "B\xE0i 1: Kh\xE1m ph\xE1 m\u1EA1ch \u0111i\u1EC7n c\u01A1 b\u1EA3n", "B\xE0i 2: \u0110i\u1EC1u khi\u1EC3n \u0111\xE8n LED nh\u1EA5p nh\xE1y" \u2014 KH\xD4NG d\xF9ng ti\xEAu \u0111\u1EC1 ti\u1EBFng Anh.`,
+    en: `- Example compliant lesson title: "Lesson 1: Exploring Basic Circuits" \u2014 natural, idiomatic English throughout.`
+  };
+  const exampleLine = perLanguageExamples[code] || "";
+  return `MANDATORY LANGUAGE DIRECTIVE (TARGET OUTPUT LANGUAGE: ${name}):
+- The TARGET OUTPUT LANGUAGE for this course is ${name}. You MUST author the ENTIRE document in ${name}.
+- All section titles, table headers, table cells, lesson names, learning objectives, pedagogical narratives, and cognitive analyses MUST be written in natural, fluent, academic ${name}.
+- Technical identifiers, code keywords (e.g. setup(), loop(), pinMode()), standard protocols (I2C, SPI, UART, GPIO), and component model numbers (ESP32, Arduino Uno) remain in standard technical notation, but all surrounding explanations MUST be in ${name}.
+- DO NOT mix in paragraphs, tables, or titles written in any other language. Strict adherence is required.${exampleLine ? `
+${exampleLine}` : ""}`;
+}
+function extractSectionHeadingsFromSLC(slcInput, artifactType) {
+  if (!slcInput) return {};
+  const upperType = artifactType.trim().toUpperCase();
+  if (typeof slcInput === "object") {
+    if (slcInput[upperType]) return slcInput[upperType];
+    for (const [key, mapping] of Object.entries(slcInput)) {
+      if (key.toUpperCase() === upperType || upperType.startsWith("LESSON") && key.toUpperCase().startsWith("LESSON")) {
+        return mapping;
+      }
+    }
+    return {};
+  }
+  const slcMarkdown = slcInput;
+  const blocks = slcMarkdown.split(/\n(?=#{2,3}\s+[A-Z0-9_]+)/g);
+  for (const block of blocks) {
+    const headerMatch = block.match(/^#{2,3}\s+([A-Z0-9_]+)/);
+    if (!headerMatch) continue;
+    const blockType = headerMatch[1].trim().toUpperCase();
+    if (blockType === upperType || upperType.startsWith("LESSON") && blockType.startsWith("LESSON")) {
+      const mapping = {};
+      const lines = block.split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("|") && !trimmed.includes("---")) {
+          const cells = trimmed.split("|").map((c) => c.trim()).filter((_, idx, arr) => idx > 0 && idx < arr.length - 1);
+          if (cells.length >= 2 && !cells[0].toLowerCase().includes("canonical") && !cells[1].toLowerCase().includes("localized")) {
+            mapping[cells[0]] = cells[1];
+          }
+        } else {
+          const bullet = line.match(/^[-*]\s+([^:]+):\s+(.+)$/);
+          if (bullet) {
+            mapping[bullet[1].trim()] = bullet[2].trim();
+          }
+        }
+      }
+      if (Object.keys(mapping).length > 0) return mapping;
+    }
+  }
+  return {};
+}
+function buildHeadingDirective(artifactType, slcMarkdown, targetLanguage = "vi") {
+  const headings = extractSectionHeadingsFromSLC(slcMarkdown, artifactType);
+  if (Object.keys(headings).length === 0) {
+    return "";
+  }
+  const lines = Object.entries(headings).map(
+    ([canonical, localized]) => `  - "${canonical}" -> Use Display Heading: "${localized}"`
+  );
+  return `MANDATORY SECTION HEADINGS FROM SECTION_LANGUAGE_CONTRACT:
+- The YAML frontmatter \`template_required_sections\` MUST preserve the exact English canonical keys.
+- In the markdown body, section headers MUST use the EXACT Localized Display Labels below (do NOT translate or paraphrase):
+${lines.join("\n")}
+- For example: if canonical section is "Computational Thinking Focus", your heading must be "## [REQUIRED] ${headings["Computational Thinking Focus"] || "Computational Thinking Focus"}".`;
+}
+
 // src/services/lessonProductionService.ts
 var __filename$1 = typeof import.meta?.url === "string" ? fileURLToPath(import.meta.url) : "";
 var _resolvedDir = __filename$1 ? path4.dirname(__filename$1) : typeof __dirname !== "undefined" ? __dirname : process.cwd();
@@ -6224,6 +6550,87 @@ function loadCurriculumTemplate(templateName) {
 
 // src/services/singleArtifactService.ts
 init_errors();
+
+// src/services/contextRouting.ts
+init_errors();
+var ARTIFACT_DEPENDENCY_ROUTING = {
+  LESSON: {
+    required: ["KNOWLEDGE_EXPOSITION", "SESSION_SLICE", "FRAMEWORK_EXCERPT"],
+    optional: ["STYLE_GUIDE", "REFERENCE_PACK"],
+    rationale: "D\u1EA1y theo ki\u1EBFn th\u1EE9c chu\u1EA9n c\u1EE7a plan, ph\xE2n b\u1ED5 m\u1EE5c ti\xEAu v\xE0 khung ch\u01B0\u01A1ng tr\xECnh"
+  },
+  HANDOUT: {
+    required: ["KNOWLEDGE_EXPOSITION"],
+    optional: ["SESSION_SLICE"],
+    rationale: "T\xE0i li\u1EC7u t\u1EF1 h\u1ECDc \u2014 b\xE1m kh\xE1i ni\u1EC7m chu\u1EA9n, kh\xF4ng c\u1EA7n activity timeline"
+  },
+  EXT: {
+    required: ["KNOWLEDGE_EXPOSITION"],
+    optional: ["SESSION_SLICE"],
+    rationale: "Th\u1EED th\xE1ch m\u1EDF r\u1ED9ng chuy\xEAn s\xE2u b\xE1m kh\xE1i ni\u1EC7m"
+  },
+  CODE: {
+    required: ["KNOWLEDGE_EXPOSITION"],
+    optional: ["LESSON_OBJECTIVES"],
+    rationale: "Code lab th\u1EF1c h\xE0nh b\xE1m kh\xE1i ni\u1EC7m k\u1EF9 thu\u1EADt v\xE0 v\xED d\u1EE5 worked examples"
+  },
+  ACT: {
+    required: ["CANONICAL_LESSON"],
+    optional: ["KNOWLEDGE_EXPOSITION", "SESSION_SLICE"],
+    rationale: "STEM Activity Lab b\u1EAFt bu\u1ED9c ph\u1EA3i kh\u1EDBp 100% Activity Sequence v\xE0 Lesson Flow c\u1EE7a LESSON"
+  },
+  WKS: {
+    required: ["CANONICAL_LESSON"],
+    optional: ["KNOWLEDGE_EXPOSITION"],
+    rationale: "Phi\u1EBFu h\u1ECDc t\u1EADp (Worksheet) luy\u1EC7n t\u1EADp theo c\xE1c ch\u1EB7ng ho\u1EA1t \u0111\u1ED9ng c\u1EE7a gi\xE1o \xE1n"
+  },
+  GUIDE: {
+    required: ["CANONICAL_LESSON"],
+    optional: ["SESSION_SLICE"],
+    rationale: "K\u1ECBch b\u1EA3n s\u01B0 ph\u1EA1m gi\xE1o vi\xEAn (Teacher Guide) b\xE1m s\xE1t timeline t\u1EEBng ph\xFAt c\u1EE7a LESSON"
+  },
+  SLIDE: {
+    required: ["CANONICAL_LESSON"],
+    optional: ["KNOWLEDGE_EXPOSITION"],
+    rationale: "Slide b\xE0i gi\u1EA3ng tr\xECnh chi\u1EBFu theo c\u1EA5u tr\xFAc ph\xE2n ph\u1ED1i n\u1ED9i dung c\u1EE7a gi\xE1o \xE1n"
+  },
+  QUIZ: {
+    required: ["KNOWLEDGE_EXPOSITION", "CANONICAL_LESSON"],
+    optional: ["SESSION_SLICE"],
+    rationale: "Ng\xE2n h\xE0ng c\xE2u h\u1ECFi \u0111\xE1nh gi\xE1 c\u1EA3 ki\u1EBFn th\u1EE9c chu\u1EA9n m\u1EF1c (KX) l\u1EABn m\u1EE5c ti\xEAu b\xE0i d\u1EA1y (LESSON)"
+  }
+};
+function validateArtifactDependencies(artifactType, availableSources, opts = {}) {
+  const normType = (artifactType || "").toUpperCase().trim();
+  const rule = ARTIFACT_DEPENDENCY_ROUTING[normType];
+  const failClosed = opts.failClosed ?? true;
+  if (!rule) {
+    return { valid: true, missing: [] };
+  }
+  const missing = [];
+  for (const req of rule.required) {
+    const val = availableSources[req];
+    const isPresent = val !== void 0 && val !== null && (typeof val === "string" ? val.trim().length > 0 : true);
+    if (!isPresent) {
+      missing.push(req);
+    }
+  }
+  if (missing.length > 0) {
+    const err = createContextMissingError({
+      artifactType: normType,
+      missingSource: missing[0],
+      lessonId: opts.lessonId,
+      agent: opts.agent
+    });
+    if (failClosed) {
+      throw err;
+    }
+    return { valid: false, missing, error: err };
+  }
+  return { valid: true, missing: [] };
+}
+
+// src/services/singleArtifactService.ts
 function getArtifactMetadata(type, lessonId, pedagogy) {
   const id = lessonId || "ON_DEMAND";
   switch (type) {
@@ -6303,9 +6710,24 @@ async function generateSingleArtifact(req) {
   const templateContent = loadedTemplate || getDefaultFallbackTemplate(artifactType, displayTitle, lessonId || "ON_DEMAND");
   const hwStr = hardwarePlatform.join(", ");
   const selectedDevices = (config?.devices || (hardwarePlatform[0]?.toLowerCase().includes("paper") ? "paper-only" : "laptop")).toLowerCase();
-  const isBilingual = language.toLowerCase().includes("bilingual") || language.toLowerCase().includes("song");
-  const isVietnamese = !isBilingual && language.toLowerCase().includes("viet");
-  const langRule = isBilingual ? `1. AUTHORING LANGUAGE: Bilingual (Vietnamese - English). Headings and core conceptual definitions should be presented in Vietnamese with English technical terms in parentheses. Explanations and instructional text are in Vietnamese. Key code terms, comments, and challenge summaries are presented bilingually.` : isVietnamese ? `1. AUTHORING LANGUAGE: Vietnamese for all instructional text, explanations, questions, rubrics, and presenter notes. Programming code, syntax keywords, and standard API identifiers remain in standard English (with Vietnamese explanation comments/notes).` : `1. AUTHORING LANGUAGE: 100% English (Plan C Canonical Specification).`;
+  language.toLowerCase().includes("bilingual") || language.toLowerCase().includes("song");
+  const targetLang = resolveTargetLanguageCode(language);
+  const langDirective = buildLanguageDirective(language);
+  const headingDirective = buildHeadingDirective(
+    artifactType.toUpperCase(),
+    req.sectionLanguageContract,
+    targetLang
+  );
+  const availableSources = {
+    KNOWLEDGE_EXPOSITION: contextSot.exposition || researchContext,
+    CANONICAL_LESSON: contextSot.lessonPlan,
+    FRAMEWORK_EXCERPT: contextSot.framework
+  };
+  validateArtifactDependencies(artifactType.toUpperCase(), availableSources, {
+    lessonId,
+    agent: meta.persona,
+    failClosed: req.failClosedContext ?? false
+  });
   const isPaperOnly = selectedDevices === "paper-only" || hwStr.toLowerCase().includes("paper") || hwStr.toLowerCase().includes("print-ready");
   const deviceRule = isPaperOnly ? `
 - \u{1F4C4} PAPER-ONLY / NO-DEVICE ENVIRONMENT: The learning space has NO computers or screens. All exercises, worksheets, task cards, exit tickets, and code analyses MUST be 100% printable. Provide write-in blank boxes, printed code snippets with line numbers, tracing tables, and physical manipulative instructions.` : selectedDevices === "tablet" || selectedDevices === "smartphone" ? `
@@ -6326,7 +6748,8 @@ async function generateSingleArtifact(req) {
 Your task is to author a canonical, publication-grade learning artifact of type "${artifactType.toUpperCase()}".
 
 ### CORE OPERATIONAL INVARIANTS:
-${langRule}
+${langDirective}
+${headingDirective}
 2. NON-MOCK CODE INVARIANT: Any code snippet provided MUST be 100% syntactically valid, idiomatic, and executable without placeholders or fake functions.
 3. PEDAGOGICAL GROUNDING: Strictly align with the ${pedagogy.toUpperCase()} model, Bloom's Revised Taxonomy, and IEEE/ACM CS2023 guidelines.
 4. SCAFFOLDING LEVEL: "${scaffoldingLevel.toUpperCase()}".${scaffoldingRule}
@@ -6335,6 +6758,11 @@ ${langRule}
 
 IMAGE PLANNING (media ledger) \u2014 QUOTA GEN: t\u1ED1i \u0111a ${mediaPolicy.maxGenImagesPerArtifact} \u1EA3nh AI cho artifact n\xE0y (\u1EA3nh search kho kh\xF4ng gi\u1EDBi h\u1EA1n).
 Khi n\u1ED9i dung c\u1EA7n minh h\u1ECDa (diagram quy tr\xECnh, s\u01A1 \u0111\u1ED3 kh\xE1i ni\u1EC7m, step-by-step visual), ch\xE8n placeholder \u0111\xFAng format [IMAGE: slug] (slug ch\u1EEF th\u01B0\u1EDDng-g\u1EA1ch ngang, unique trong b\xE0i, vd img-for-loop-diagram) T\u1EA0I \u0110\xDANG CH\u1ED6 c\u1EA7n \u1EA3nh, tr\xEAn d\xF2ng ri\xEAng. KH\xD4NG t\u1EF1 sinh \u1EA3nh, KH\xD4NG d\xF9ng markdown image \u2014 placeholder s\u1EBD \u0111\u01B0\u1EE3c thay b\u1EB1ng \u1EA3nh th\u1EADt sau khi Media Curator duy\u1EC7t. Ch\u1EC9 \u0111\u1EB7t cho \u1EA3nh TH\u1EF0C S\u1EF0 c\u1EA7n thi\u1EBFt.` : ""}`;
+  const slcContract = req.sectionLanguageContract;
+  const frameworkExcerpt = contextSot.framework ? buildSectionAwareExcerpt(contextSot.framework, { budget: 2500, sectionLanguageContract: slcContract }).excerpt : "";
+  const lessonPlanExcerpt = contextSot.lessonPlan ? buildLessonExcerpt(contextSot.lessonPlan, { budget: 8e3, sectionLanguageContract: slcContract, artifactType: "LESSON" }).excerpt : "";
+  const handoutExcerpt = contextSot.handout ? buildSectionAwareExcerpt(contextSot.handout, { budget: 2e3, sectionLanguageContract: slcContract }).excerpt : "";
+  const expositionExcerpt = contextSot.exposition ? buildExpositionExcerpt(contextSot.exposition, { budget: 6e3, sectionLanguageContract: slcContract }).excerpt : "";
   const userPrompt = `### CONTEXT GROUND TRUTH:
 - Topic / Concept Domain: "${topic}"
 - Lesson ID: "${lessonId || "ON_DEMAND"}"
@@ -6352,14 +6780,17 @@ ${selectedDevices ? `- Device Mode: "${selectedDevices}"
 ${researchContext ? `### RESEARCH GROUND TRUTH (fact-checked context \u2014 \u01B0u ti\xEAn d\xF9ng, KH\xD4NG b\u1ECBa s\u1ED1 li\u1EC7u):
 ${researchContext.slice(0, 4e3)}
 ` : ""}
-${contextSot.framework ? `### SOT CURRICULUM FRAMEWORK:
-${contextSot.framework.slice(0, 1500)}
+${expositionExcerpt ? `### SOT KNOWLEDGE EXPOSITION (CANONICAL KNOWLEDGE \u2014 teach from this, do not contradict):
+${expositionExcerpt}
+` : ""}
+${frameworkExcerpt ? `### SOT CURRICULUM FRAMEWORK:
+${frameworkExcerpt}
 ` : ""}
-${contextSot.lessonPlan ? `### SOT CANONICAL LESSON PLAN:
-${contextSot.lessonPlan.slice(0, 1500)}
+${lessonPlanExcerpt ? `### SOT CANONICAL LESSON PLAN:
+${lessonPlanExcerpt}
 ` : ""}
-${contextSot.handout ? `### SOT STUDENT HANDOUT:
-${contextSot.handout.slice(0, 1e3)}
+${handoutExcerpt ? `### SOT STUDENT HANDOUT:
+${handoutExcerpt}
 ` : ""}
 
 ### MANDATORY CANONICAL TEMPLATE CONTRACT:
@@ -6448,9 +6879,16 @@ ${yaml.trim()}
       const verdict = await LLMJudgeEngine.evaluateArtifactWithLLM({
         targetArtifactType: artifactType.toUpperCase(),
         lessonId: lessonId || "ON_DEMAND",
-        expectedLanguage: language.toLowerCase().includes("viet") ? "vietnamese" : "english",
+        expectedLanguage: targetLang || "en",
         targetObjectives: judgeObjectives,
-        generatedContentJson: JSON.stringify({ content: finalContent, artifactType, lessonId: lessonId || "ON_DEMAND", title: displayTitle })
+        generatedContentJson: JSON.stringify({
+          content: finalContent,
+          artifactType,
+          lessonId: lessonId || "ON_DEMAND",
+          title: displayTitle,
+          canonicalLessonExcerpt: lessonPlanExcerpt || void 0,
+          canonicalExposition: expositionExcerpt || void 0
+        })
       });
       const passed = Boolean(verdict.passed) && verdict.score >= 85;
       if (passed) {
@@ -6492,9 +6930,16 @@ ${finalContent}` }
         const reVerdict = await LLMJudgeEngine.evaluateArtifactWithLLM({
           targetArtifactType: artifactType.toUpperCase(),
           lessonId: lessonId || "ON_DEMAND",
-          expectedLanguage: language.toLowerCase().includes("viet") ? "vietnamese" : "english",
+          expectedLanguage: targetLang || "en",
           targetObjectives: judgeObjectives,
-          generatedContentJson: JSON.stringify({ content: repaired, artifactType, lessonId: lessonId || "ON_DEMAND", title: displayTitle })
+          generatedContentJson: JSON.stringify({
+            content: repaired,
+            artifactType,
+            lessonId: lessonId || "ON_DEMAND",
+            title: displayTitle,
+            canonicalLessonExcerpt: lessonPlanExcerpt || void 0,
+            canonicalExposition: expositionExcerpt || void 0
+          })
         });
         if (reVerdict.passed && reVerdict.score >= 85) {
           return {