@thanh01.pmt/curriculum-kit 1.4.46 → 1.4.48

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(),
@@ -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",
@@ -10547,6 +10566,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 +10697,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 +10754,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 +10793,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 +10831,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 +11001,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 +11043,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 +11081,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 +11400,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);
@@ -31673,6 +31860,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 +31950,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 +32044,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 +32055,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;