@thanh01.pmt/curriculum-kit 1.4.47 → 1.4.49

package/dist/index.cjs

@@ -4019,7 +4019,25 @@ var PlanningNodeSchema = zod.z.object({
     file: zod.z.string(),
     evidence: zod.z.string().default("")
   })).default([]),
-  phase_id: zod.z.string().default("")
+  phase_id: zod.z.string().default(""),
+  // P52/T2.1: tangible user-visible outcome projected from the graph step
+  // (checkpoint candidate for session cutting). Empty = not a checkpoint.
+  user_visible_deliverable: zod.z.string().default(""),
+  // P52/T3.1 — depth-reconcile inputs (mirrored from the feed; optional so
+  // raw graphs without variants keep planning unchanged):
+  // • depth_variants: minutes to teach this node at each depth level (ULO ≤
+  //   CIO ≤ SIO) — the reconciler's price list for downgrades.
+  // • depth_scaffold_candidates: parallel to scaffold_candidates but acting
+  //   on DEPTH (SIO→CIO, CIO→ULO) instead of lesson time.
+  // • is_core: Master-Tree core concept — never downgraded; escalate instead.
+  depth_variants: zod.z.object({ ulo: zod.z.number().int().nonnegative(), cio: zod.z.number().int().nonnegative(), sio: zod.z.number().int().nonnegative() }).optional(),
+  depth_scaffold_candidates: zod.z.array(zod.z.object({
+    from_depth: DepthLevelSchema,
+    to_depth: DepthLevelSchema,
+    minutes_saved: zod.z.number().int().nonnegative(),
+    reason: zod.z.string().default("")
+  })).optional(),
+  is_core: zod.z.boolean().default(false)
 });
 var DependencyEdgeSchema = zod.z.object({
   from: zod.z.string(),
@@ -4857,9 +4875,9 @@ Evaluate the candidate artifact across these 6 dimensions:
    - 0 pts: Missing critical sections.
 
 5. **Technical & Conceptual Accuracy (15 pts):**
-   - 15 pts: Code snippets, logic flows, architectural descriptions, and Mermaid diagrams are conceptually sound and valid. If \`canonicalExposition\` or \`[KNOWLEDGE_EXPOSITION]\` is provided, content strictly adheres to canonical concepts without contradicting definitions or examples.
+   - 15 pts: Code snippets, logic flows, architectural descriptions, and Mermaid diagrams are conceptually sound and valid. Every code identifier uses the REAL standard-library/API spelling of the declared stack (grounded in REFERENCE_PACK / canonical LESSON) \u2014 internal consistency with a glossary term name is NOT evidence of correctness. If \`canonicalExposition\` or \`[KNOWLEDGE_EXPOSITION]\` is provided, content strictly adheres to canonical concepts without contradicting definitions or examples.
    - 8 pts: Minor syntax inaccuracies or unidiomatic code that does not break core concepts.
-   - 0 pts: Severe technical hallucinations, broken logic, invalid diagrams, or direct contradiction of canonical exposition knowledge.
+   - 0 pts: Severe technical hallucinations, broken logic, invalid diagrams, invented casing/spelling rules for standard-library identifiers, or direct contradiction of canonical exposition knowledge.
 
 6. **Contract Consistency & Zero-Drift (10 pts):**
    - 10 pts: Satellite artifact strictly adheres to the scope, tech stack, and objectives of Lesson ${lessonId} without introducing unrelated topics. If \`canonicalLessonExcerpt\` is present in candidate JSON, all satellite phases/activities strictly operationalize the master Lesson Flow and Activity Sequence without inventing divergent timelines.
@@ -5436,6 +5454,7 @@ var MAX_NEW_CONCEPTS_PER_SESSION_K12 = 2;
 var MAX_NEW_CONCEPTS_PER_SESSION_ADULT = 3;
 var DEFAULT_OVERHEAD_RATIO = 0.15;
 var MAX_IN_SESSION_SETUP_MINUTES = 15;
+var SESSION_CUT_TOLERANCE = 0.15;
 var ENVIRONMENT_PROVISIONING_MODELS = [
   "PRE_INSTALLED_LAB",
   "CLOUD_MANAGED",
@@ -10189,6 +10208,38 @@ function checkScopeDrift(content, scopedKeywords, tolerance = 0) {
     evidence: drift
   };
 }
+function checkIdentifierCasing(content, refPack) {
+  if (!refPack || !refPack.trim()) return null;
+  const canonical = /* @__PURE__ */ new Map();
+  const remember = (id) => {
+    if (id.length < 2) return;
+    const key = id.toLowerCase().replace(/_/g, "");
+    if (!canonical.has(key)) canonical.set(key, id);
+  };
+  for (const m of refPack.matchAll(/`([A-Za-z_][A-Za-z0-9_]*)\s*\(/g)) remember(m[1]);
+  for (const m of refPack.matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\s*\(/g)) remember(m[1]);
+  for (const m of refPack.matchAll(/`([A-Za-z_][A-Za-z0-9_]*)`/g)) remember(m[1]);
+  if (canonical.size === 0) return null;
+  const RESERVED = /* @__PURE__ */ new Set(["if", "for", "while", "switch", "func", "return", "guard", "catch", "else", "in"]);
+  const violations = [];
+  const fenceRe = /```[a-zA-Z]*\n([\s\S]*?)```/g;
+  for (const fence of content.matchAll(fenceRe)) {
+    for (const m of fence[1].matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\s*\(/g)) {
+      const tok = m[1];
+      if (RESERVED.has(tok.toLowerCase())) continue;
+      const real = canonical.get(tok.toLowerCase().replace(/_/g, ""));
+      if (real && real !== tok && !violations.includes(`${tok} \u2192 ${real}`)) {
+        violations.push(`${tok} \u2192 ${real}`);
+      }
+    }
+  }
+  if (violations.length === 0) return null;
+  return {
+    code: "identifier-casing",
+    detail: `Code d\xF9ng identifier l\u1EC7ch casing so v\u1EDBi REFERENCE_PACK (ngu\u1ED3n s\u1EF1 th\u1EADt k\u1EF9 thu\u1EADt): ${violations.join(", ")}. Identifier trong code PH\u1EA2I copy nguy\xEAn d\u1EA1ng t\u1EEB REFERENCE_PACK \u2014 KH\xD4NG suy ra casing t\u1EEB t\xEAn keyword/concept (ch\xFAng l\xE0 nh\xE3n s\u01B0 ph\u1EA1m, kh\xF4ng ph\u1EA3i API).`,
+    evidence: violations.slice(0, 5)
+  };
+}
 function validateArtifactDeterministic(input) {
   const issues = [];
   const cjk = scanCjkLeaks(input.content);
@@ -10196,6 +10247,8 @@ function validateArtifactDeterministic(input) {
   if (input.refPack) {
     const ver = checkVersionGroundTruth(input.content, input.refPack);
     if (ver) issues.push(ver);
+    const casing = checkIdentifierCasing(input.content, input.refPack);
+    if (casing) issues.push(casing);
   }
   if (input.scopedKeywords && input.scopedKeywords.length > 0) {
     const scope = checkScopeDrift(input.content, input.scopedKeywords);
@@ -10307,9 +10360,10 @@ function buildSystemPrompt(targetLanguage = "vi", techStack, hardwarePlatform) {
     "Rules:",
     "1. Cover EXACTLY the scoped keywords and concepts \u2014 nothing beyond the session scope.",
     "2. Every Key Term definition must be consistent with the glossary entry provided.",
-    "3. Respect each concept depth target (ULO/CIO/SIO) \u2014 do not overshoot.",
-    "4. Student-facing only: no teacher instructions, no classroom management text.",
-    "5. Output the full markdown document following the provided section skeleton exactly (headers and placeholders preserved).",
+    '3. IDENTIFIER GROUND TRUTH: glossary/keyword names are pedagogical concept labels \u2014 NEVER derive code identifier casing or spelling from them. In code samples, copy identifiers EXACTLY from the REFERENCE_PACK ground truth (e.g. the standard library function is `print` lowercase; "Print" as a topic label is not an API symbol).',
+    "4. Respect each concept depth target (ULO/CIO/SIO) \u2014 do not overshoot.",
+    "5. Student-facing only: no teacher instructions, no classroom management text.",
+    "6. Output the full markdown document following the provided section skeleton exactly (headers and placeholders preserved).",
     domainGuardrails,
     langDirective
   ].join("\n");
@@ -10547,6 +10601,98 @@ async function ensureExpositionForLesson(storage, projectId, lessonCode, options
   return { relPath: result.relPath, context: buildExpositionContext(result.content), reused: result.reused, rawContent: result.content };
 }
 init_errors();
+
+// src/services/depthReconciler.ts
+function tierOf(node, isLeaf) {
+  if (node.phase_id !== "" && /__ADV\d{2}$/.test(node.id)) return 1;
+  const depth = node.depth_hint ?? "cio";
+  if (depth === "sio") return isLeaf ? 2 : 3;
+  if (depth === "cio") return isLeaf ? 4 : 5;
+  return -1;
+}
+function classifyDepthCandidates(nodes, edges) {
+  const baseConcept = (id) => id.replace(/__(ADV|PREV)\d{2}$/, "");
+  const conceptIds = new Set(nodes.filter((n) => n.kind === "concept").map((n) => baseConcept(n.id)));
+  const hasDependent = /* @__PURE__ */ new Set();
+  for (const e of edges) {
+    if (e.kind !== "knowledge") continue;
+    const from = baseConcept(e.from);
+    const to = baseConcept(e.to);
+    if (conceptIds.has(from) && conceptIds.has(to)) hasDependent.add(from);
+  }
+  const isLeaf = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    if (n.kind !== "concept") continue;
+    const base = baseConcept(n.id);
+    if (!isLeaf.has(base)) isLeaf.set(base, !hasDependent.has(base));
+  }
+  return isLeaf;
+}
+function reconcilePlanDepth(nodes, edges, spec, budgetMinutes) {
+  const MAX_ROUNDS = 5;
+  const total = () => nodes.reduce((acc, n) => acc + n.estimated_minutes, 0);
+  const isLeaf = classifyDepthCandidates(nodes, edges);
+  const baseConcept = (id) => id.replace(/__(ADV|PREV)\d{2}$/, "");
+  const applied = [];
+  const mutated = /* @__PURE__ */ new Set();
+  let rounds = 0;
+  while (total() > budgetMinutes && rounds < MAX_ROUNDS) {
+    rounds++;
+    let overBy = total() - budgetMinutes;
+    const candidates = [];
+    for (let i = 0; i < nodes.length; i++) {
+      const n = nodes[i];
+      if (n.kind !== "concept") continue;
+      if (n.is_core) continue;
+      if (n.depth_hint == null) continue;
+      const base = baseConcept(n.id);
+      const leaf = isLeaf.get(base) ?? true;
+      const tier = tierOf(n, leaf);
+      if (tier < 0) continue;
+      const depth = n.depth_hint ?? "cio";
+      const toDepth = depth === "sio" ? "cio" : "ulo";
+      const variants = n.depth_variants;
+      const target = variants ? variants[toDepth] : Math.max(5, Math.round(n.estimated_minutes * 0.6));
+      const saved = n.estimated_minutes - target;
+      if (saved <= 0) continue;
+      candidates.push({
+        nodeId: n.id,
+        fromDepth: depth,
+        toDepth,
+        minutesSaved: saved,
+        reason: n.depth_scaffold_candidates?.find((c) => c.to_depth === toDepth)?.reason ?? `depth downgrade ${depth}\u2192${toDepth} (tier ${tier}${leaf ? ", leaf" : ""})`,
+        node: n,
+        tier,
+        index: i
+      });
+    }
+    if (candidates.length === 0) break;
+    candidates.sort((a, b) => a.tier - b.tier || b.minutesSaved - a.minutesSaved);
+    for (const c of candidates) {
+      if (overBy <= 0) break;
+      const n = c.node;
+      const target = n.depth_variants ? n.depth_variants[c.toDepth] : Math.max(5, Math.round(n.estimated_minutes * 0.6));
+      const saved = n.estimated_minutes - target;
+      if (saved <= 0) continue;
+      n.estimated_minutes = target;
+      n.depth_hint = c.toDepth;
+      applied.push({ nodeId: n.id, fromDepth: c.fromDepth, toDepth: c.toDepth, minutesSaved: saved, reason: c.reason });
+      mutated.add(n.id);
+      overBy -= saved;
+    }
+  }
+  const finalTotal = total();
+  const deficitMinutes = Math.max(0, finalTotal - budgetMinutes);
+  return {
+    unchanged: applied.length === 0,
+    applied,
+    mutatedNodeIds: [...mutated],
+    escalate: deficitMinutes > 0,
+    deficitMinutes
+  };
+}
+
+// src/services/curriculumPlannerService.ts
 var asArr = (v) => Array.isArray(v) ? v : [];
 var asStr = (v, dflt = "") => typeof v === "string" ? v : dflt;
 var asNum = (v, dflt) => typeof v === "number" && Number.isFinite(v) ? v : dflt;
@@ -10586,7 +10732,20 @@ function normalizePlanningGraph(raw) {
           suggest: asStr(c.suggest, "provide_full")
         })),
         references: asArr(n.references).map((ref) => ({ file: asStr(ref.file), evidence: asStr(ref.evidence) })).filter((ref) => ref.file),
-        phase_id: asStr(n.phase_id)
+        phase_id: asStr(n.phase_id),
+        user_visible_deliverable: asStr(n.user_visible_deliverable),
+        depth_variants: (() => {
+          const dv = n.depth_variants;
+          if (!dv) return void 0;
+          return { ulo: Math.max(0, Math.round(asNum(dv.ulo, 0))), cio: Math.max(0, Math.round(asNum(dv.cio, 0))), sio: Math.max(0, Math.round(asNum(dv.sio, 0))) };
+        })(),
+        depth_scaffold_candidates: asArr(n.depth_scaffold_candidates).map((c) => ({
+          from_depth: asStr(c.from_depth, "sio"),
+          to_depth: asStr(c.to_depth, "cio"),
+          minutes_saved: Math.max(0, Math.round(asNum(c.minutes_saved, 0))),
+          reason: asStr(c.reason)
+        })),
+        is_core: n.is_core === true
       });
     }
     for (const e of asArr(r.dependency_edges)) {
@@ -10630,7 +10789,9 @@ function normalizePlanningGraph(raw) {
           completion_level: "standard",
           scaffold_candidates: [],
           references: [],
-          phase_id: ""
+          phase_id: "",
+          user_visible_deliverable: "",
+          is_core: false
         });
         for (const p of asStrArr(c.prerequisites)) {
           edges.push({ from: p, to: asStr(c.id), kind: "knowledge", reason: "concept prerequisite" });
@@ -10667,7 +10828,9 @@ function normalizePlanningGraph(raw) {
             completion_level: "standard",
             scaffold_candidates: [],
             references: [],
-            phase_id: ""
+            phase_id: "",
+            user_visible_deliverable: "",
+            is_core: false
           });
           if (prev) edges.push({ from: prev, to: id, kind: "task", reason: "roadmap sequence" });
           prev = id;
@@ -10703,13 +10866,15 @@ function normalizePlanningGraph(raw) {
             completion_level: "standard",
             scaffold_candidates: [],
             references: [],
-            phase_id: ""
+            phase_id: "",
+            user_visible_deliverable: "",
+            is_core: false
           });
           if (prev) edges.push({ from: prev, to: id, kind: "task", reason: "feature build order" });
           prev = id;
         }
         if (stepCount === 0 && fid) {
-          nodes.push({ id: fid, kind: "skill", name: asStr(f.name, fid), concept_codes: [], keywords: [], new_keywords: [], prerequisite_keywords: [], estimated_minutes: 45, bloom_hint: "Apply", depth_hint: null, completion_level: "standard", scaffold_candidates: [], references: [], phase_id: "" });
+          nodes.push({ id: fid, kind: "skill", name: asStr(f.name, fid), concept_codes: [], keywords: [], new_keywords: [], prerequisite_keywords: [], estimated_minutes: 45, bloom_hint: "Apply", depth_hint: null, completion_level: "standard", scaffold_candidates: [], references: [], phase_id: "", user_visible_deliverable: "", is_core: false });
         }
       }
     }
@@ -10871,6 +11036,39 @@ function computePackingSpec(constraints) {
     sessionDurationMinutes: constraints.session_duration_minutes
   };
 }
+var filledOf = (s) => s.knowledgeMinutes + s.practiceMinutes;
+function cutBackToCheckpoint(current, nodeById, spec, warnings) {
+  const budget = spec.contentBudget;
+  const minFill = budget * (1 - SESSION_CUT_TOLERANCE);
+  const hasPartAfter = new Array(current.entries.length).fill(false);
+  let seenPart = false;
+  for (let i = current.entries.length - 1; i >= 0; i--) {
+    hasPartAfter[i] = seenPart;
+    if (current.entries[i].totalParts > 1) seenPart = true;
+  }
+  let bestIdx = -1;
+  let cumulative = 0;
+  for (let i = 0; i < current.entries.length; i++) {
+    const e = current.entries[i];
+    cumulative += e.minutes;
+    if (hasPartAfter[i] || e.totalParts > 1) continue;
+    const n = nodeById.get(e.id);
+    if (!n || n.user_visible_deliverable.trim().length === 0) continue;
+    if (cumulative > budget || cumulative < minFill) continue;
+    bestIdx = i;
+  }
+  if (bestIdx < 0) {
+    warnings.push("no-checkpoint-within-tolerance: session cut at " + filledOf(current) + "m without a user-visible deliverable");
+    return [];
+  }
+  const displacedEntries = current.entries.splice(bestIdx + 1);
+  for (const e of displacedEntries) {
+    if (nodeById.get(e.id)?.kind === "concept") current.knowledgeMinutes -= e.minutes;
+    else current.practiceMinutes -= e.minutes;
+  }
+  current.nodeIds = current.entries.map((e) => e.id);
+  return displacedEntries.map((e) => nodeById.get(e.id)).filter((n) => n != null);
+}
 function packUnitSessions(group, nodeById, spec, warnings) {
   const sessions = [];
   const fresh = () => ({ groupId: group.key, nodeIds: [], entries: [], knowledgeMinutes: 0, practiceMinutes: 0, oversized: false });
@@ -10880,7 +11078,9 @@ function packUnitSessions(group, nodeById, spec, warnings) {
     current = fresh();
   };
   const filled = () => current.knowledgeMinutes + current.practiceMinutes;
-  for (const id of group.orderedIds) {
+  const ids = [...group.orderedIds];
+  while (ids.length > 0) {
+    const id = ids.shift();
     const node = nodeById.get(id);
     const isKnowledge = node.kind === "concept";
     if (node.estimated_minutes > spec.contentBudget) {
@@ -10916,7 +11116,16 @@ function packUnitSessions(group, nodeById, spec, warnings) {
       continue;
     }
     const minutes = node.estimated_minutes;
-    if (current.entries.length > 0 && filled() + minutes > spec.contentBudget) flush();
+    if (current.entries.length > 0 && filled() + minutes > spec.contentBudget) {
+      const displaced = cutBackToCheckpoint(current, nodeById, spec, warnings);
+      if (displaced.length > 0) {
+        ids.unshift(id);
+        for (let di = displaced.length - 1; di >= 0; di--) ids.unshift(displaced[di].id);
+        flush();
+        continue;
+      }
+      flush();
+    }
     if (isKnowledge) current.knowledgeMinutes += minutes;
     else current.practiceMinutes += minutes;
     current.entries.push({ id, minutes, part: 1, totalParts: 1 });
@@ -11226,6 +11435,19 @@ async function buildCurriculumPlan(rawGraph, options) {
   const graph = normalizePlanningGraph(rawGraph);
   warnings.push(...graph.warnings);
   assertAcyclic(graph.nodes, graph.edges);
+  let reconcileSummary = null;
+  if (typeof constraints.total_sessions === "number" && constraints.total_sessions > 0) {
+    const spec0 = computePackingSpec(constraints);
+    const budgetMinutes = constraints.total_sessions * spec0.contentBudget;
+    reconcileSummary = reconcilePlanDepth(graph.nodes, graph.edges, spec0, budgetMinutes);
+    if (!reconcileSummary.unchanged) {
+      const saved = reconcileSummary.applied.reduce((a, x) => a + x.minutesSaved, 0);
+      warnings.push(`depth reconcile: ${reconcileSummary.applied.length} downgrade(s), saved ${saved}m across ${reconcileSummary.mutatedNodeIds.length} node(s)`);
+    }
+    if (reconcileSummary.escalate) {
+      warnings.push(`budget_escalation: deficit ${reconcileSummary.deficitMinutes}m after exhausting non-core depth candidates (budget ${constraints.total_sessions * computePackingSpec(constraints).contentBudget}m) \u2014 human review required`);
+    }
+  }
   const orderedIds = topoSort(graph.nodes, graph.edges);
   const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
   const spec = computePackingSpec(constraints);
@@ -27169,6 +27391,7 @@ Your task is to author a canonical, publication-grade learning artifact of type
 ${langDirective}
 ${headingDirective}
 2. NON-MOCK CODE INVARIANT: Any code snippet provided MUST be 100% syntactically valid, idiomatic, and executable without placeholders or fake functions.
+2b. IDENTIFIER GROUND TRUTH: Never derive identifier casing/spelling from glossary term or concept names (they are pedagogical labels). Copy identifiers EXACTLY from the canonical LESSON and REFERENCE_PACK ground truth present in the context.
 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}
 5. TARGET AUDIENCE: ${gradeLevel ? `Grade ${gradeLevel}, ` : ""}${targetAge} on ${hwStr}.${deviceRule}${classDynamicsRule}${extraContextRule}
@@ -31673,6 +31896,7 @@ exports.RotationStationSchema = RotationStationSchema;
 exports.RubricCriteriaSchema = RubricCriteriaSchema;
 exports.RubricSchema = RubricSchema;
 exports.SATELLITE_LESSON_PRIORITIES = SATELLITE_LESSON_PRIORITIES;
+exports.SESSION_CUT_TOLERANCE = SESSION_CUT_TOLERANCE;
 exports.SLIDE_CANONICAL_METHODOLOGY = SLIDE_CANONICAL_METHODOLOGY;
 exports.STANDARD_REF_REGEX = STANDARD_REF_REGEX;
 exports.STANDARD_SOT_FILES = STANDARD_SOT_FILES;
@@ -31762,6 +31986,7 @@ exports.buildTeacherGuidePrompt = buildTeacherGuidePrompt;
 exports.buildWalkingSkeleton = buildWalkingSkeleton;
 exports.buildWorksheetPrompt = buildWorksheetPrompt;
 exports.checkSessionZpd = checkSessionZpd;
+exports.classifyDepthCandidates = classifyDepthCandidates;
 exports.closeTruncatedJson = closeTruncatedJson;
 exports.computeConceptSpiralProgression = computeConceptSpiralProgression;
 exports.computeContentHash = computeContentHash;
@@ -31855,6 +32080,7 @@ exports.loadAuthoringTemplate = loadAuthoringTemplate;
 exports.loadCurriculumTemplate = loadCurriculumTemplate;
 exports.loadSotTemplate = loadSotTemplate;
 exports.normalizePlanningGraph = normalizePlanningGraph;
+exports.packUnitSessions = packUnitSessions;
 exports.packagerTools = packagerTools;
 exports.parseAllSessions = parseAllSessions;
 exports.parseGateSettings = parseGateSettings;
@@ -31865,6 +32091,7 @@ exports.produceSingleLesson = produceSingleLesson;
 exports.publishToGitHub = publishToGitHub;
 exports.publishToSupabase = publishToSupabase;
 exports.rankGenCandidates = rankGenCandidates;
+exports.reconcilePlanDepth = reconcilePlanDepth;
 exports.renderAssignedRowsTable = renderAssignedRowsTable;
 exports.renderEntitySlotsForType = renderEntitySlotsForType;
 exports.renderFrameworkFromPlan = renderFrameworkFromPlan;