@thanh01.pmt/domain-kit 0.2.1 → 0.4.0

package/dist/{curriculumFeedSchema-TEeQg2bY.d.cts → curriculumFeedSchema-B66H3gEV.d.ts}

@@ -105,8 +105,39 @@ declare const FeedNodeSchema: z.ZodObject<{
     }>, "many">>;
     feature_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     concept_ref: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    user_visible_deliverable: z.ZodDefault<z.ZodString>;
+    depth_variants: z.ZodOptional<z.ZodObject<{
+        ulo: z.ZodNumber;
+        cio: z.ZodNumber;
+        sio: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        ulo: number;
+        cio: number;
+        sio: number;
+    }, {
+        ulo: number;
+        cio: number;
+        sio: number;
+    }>>;
+    depth_scaffold_candidates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        from_depth: z.ZodEnum<["ulo", "cio", "sio"]>;
+        to_depth: z.ZodEnum<["ulo", "cio", "sio"]>;
+        minutes_saved: z.ZodNumber;
+        reason: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        reason: string;
+        minutes_saved: number;
+        from_depth: "ulo" | "cio" | "sio";
+        to_depth: "ulo" | "cio" | "sio";
+    }, {
+        minutes_saved: number;
+        from_depth: "ulo" | "cio" | "sio";
+        to_depth: "ulo" | "cio" | "sio";
+        reason?: string | undefined;
+    }>, "many">>;
+    is_core: z.ZodDefault<z.ZodBoolean>;
     phase_id: z.ZodDefault<z.ZodString>;
-    introduce_aspect: z.ZodDefault<z.ZodNullable<z.ZodEnum<["new", "advanced"]>>>;
+    introduce_aspect: z.ZodDefault<z.ZodNullable<z.ZodEnum<["new", "advanced", "preview"]>>>;
 }, "strip", z.ZodTypeAny, {
     estimated_minutes: number;
     id: string;
@@ -137,7 +168,20 @@ declare const FeedNodeSchema: z.ZodObject<{
         file: string;
     }[];
     concept_ref: string | null;
-    introduce_aspect: "new" | "advanced" | null;
+    user_visible_deliverable: string;
+    is_core: boolean;
+    introduce_aspect: "new" | "advanced" | "preview" | null;
+    depth_variants?: {
+        ulo: number;
+        cio: number;
+        sio: number;
+    } | undefined;
+    depth_scaffold_candidates?: {
+        reason: string;
+        minutes_saved: number;
+        from_depth: "ulo" | "cio" | "sio";
+        to_depth: "ulo" | "cio" | "sio";
+    }[] | undefined;
 }, {
     estimated_minutes: number;
     id: string;
@@ -168,7 +212,20 @@ declare const FeedNodeSchema: z.ZodObject<{
         evidence?: string | undefined;
     }[] | undefined;
     concept_ref?: string | null | undefined;
-    introduce_aspect?: "new" | "advanced" | null | undefined;
+    user_visible_deliverable?: string | undefined;
+    depth_variants?: {
+        ulo: number;
+        cio: number;
+        sio: number;
+    } | undefined;
+    depth_scaffold_candidates?: {
+        minutes_saved: number;
+        from_depth: "ulo" | "cio" | "sio";
+        to_depth: "ulo" | "cio" | "sio";
+        reason?: string | undefined;
+    }[] | undefined;
+    is_core?: boolean | undefined;
+    introduce_aspect?: "new" | "advanced" | "preview" | null | undefined;
 }>;
 declare const FeedEdgeSchema: z.ZodObject<{
     from: z.ZodString;
@@ -306,8 +363,39 @@ declare const CurriculumFeedSchema: z.ZodObject<{
         }>, "many">>;
         feature_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         concept_ref: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        user_visible_deliverable: z.ZodDefault<z.ZodString>;
+        depth_variants: z.ZodOptional<z.ZodObject<{
+            ulo: z.ZodNumber;
+            cio: z.ZodNumber;
+            sio: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            ulo: number;
+            cio: number;
+            sio: number;
+        }, {
+            ulo: number;
+            cio: number;
+            sio: number;
+        }>>;
+        depth_scaffold_candidates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            from_depth: z.ZodEnum<["ulo", "cio", "sio"]>;
+            to_depth: z.ZodEnum<["ulo", "cio", "sio"]>;
+            minutes_saved: z.ZodNumber;
+            reason: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            reason: string;
+            minutes_saved: number;
+            from_depth: "ulo" | "cio" | "sio";
+            to_depth: "ulo" | "cio" | "sio";
+        }, {
+            minutes_saved: number;
+            from_depth: "ulo" | "cio" | "sio";
+            to_depth: "ulo" | "cio" | "sio";
+            reason?: string | undefined;
+        }>, "many">>;
+        is_core: z.ZodDefault<z.ZodBoolean>;
         phase_id: z.ZodDefault<z.ZodString>;
-        introduce_aspect: z.ZodDefault<z.ZodNullable<z.ZodEnum<["new", "advanced"]>>>;
+        introduce_aspect: z.ZodDefault<z.ZodNullable<z.ZodEnum<["new", "advanced", "preview"]>>>;
     }, "strip", z.ZodTypeAny, {
         estimated_minutes: number;
         id: string;
@@ -338,7 +426,20 @@ declare const CurriculumFeedSchema: z.ZodObject<{
             file: string;
         }[];
         concept_ref: string | null;
-        introduce_aspect: "new" | "advanced" | null;
+        user_visible_deliverable: string;
+        is_core: boolean;
+        introduce_aspect: "new" | "advanced" | "preview" | null;
+        depth_variants?: {
+            ulo: number;
+            cio: number;
+            sio: number;
+        } | undefined;
+        depth_scaffold_candidates?: {
+            reason: string;
+            minutes_saved: number;
+            from_depth: "ulo" | "cio" | "sio";
+            to_depth: "ulo" | "cio" | "sio";
+        }[] | undefined;
     }, {
         estimated_minutes: number;
         id: string;
@@ -369,7 +470,20 @@ declare const CurriculumFeedSchema: z.ZodObject<{
             evidence?: string | undefined;
         }[] | undefined;
         concept_ref?: string | null | undefined;
-        introduce_aspect?: "new" | "advanced" | null | undefined;
+        user_visible_deliverable?: string | undefined;
+        depth_variants?: {
+            ulo: number;
+            cio: number;
+            sio: number;
+        } | undefined;
+        depth_scaffold_candidates?: {
+            minutes_saved: number;
+            from_depth: "ulo" | "cio" | "sio";
+            to_depth: "ulo" | "cio" | "sio";
+            reason?: string | undefined;
+        }[] | undefined;
+        is_core?: boolean | undefined;
+        introduce_aspect?: "new" | "advanced" | "preview" | null | undefined;
     }>, "many">;
     dependency_edges: z.ZodDefault<z.ZodArray<z.ZodObject<{
         from: z.ZodString;
@@ -466,7 +580,20 @@ declare const CurriculumFeedSchema: z.ZodObject<{
             file: string;
         }[];
         concept_ref: string | null;
-        introduce_aspect: "new" | "advanced" | null;
+        user_visible_deliverable: string;
+        is_core: boolean;
+        introduce_aspect: "new" | "advanced" | "preview" | null;
+        depth_variants?: {
+            ulo: number;
+            cio: number;
+            sio: number;
+        } | undefined;
+        depth_scaffold_candidates?: {
+            reason: string;
+            minutes_saved: number;
+            from_depth: "ulo" | "cio" | "sio";
+            to_depth: "ulo" | "cio" | "sio";
+        }[] | undefined;
     }[];
     dependency_edges: {
         from: string;
@@ -517,7 +644,20 @@ declare const CurriculumFeedSchema: z.ZodObject<{
             evidence?: string | undefined;
         }[] | undefined;
         concept_ref?: string | null | undefined;
-        introduce_aspect?: "new" | "advanced" | null | undefined;
+        user_visible_deliverable?: string | undefined;
+        depth_variants?: {
+            ulo: number;
+            cio: number;
+            sio: number;
+        } | undefined;
+        depth_scaffold_candidates?: {
+            minutes_saved: number;
+            from_depth: "ulo" | "cio" | "sio";
+            to_depth: "ulo" | "cio" | "sio";
+            reason?: string | undefined;
+        }[] | undefined;
+        is_core?: boolean | undefined;
+        introduce_aspect?: "new" | "advanced" | "preview" | null | undefined;
     }[];
     phases?: {
         id: string;

package/dist/feed/index.cjs

@@ -31,11 +31,33 @@ var FeedNodeSchema = zod.z.object({
   references: zod.z.array(zod.z.object({ file: zod.z.string().min(1), evidence: zod.z.string().default("") })).default([]),
   feature_id: zod.z.string().nullable().default(null),
   concept_ref: zod.z.string().nullable().default(null),
+  // P52/T2.1: outcome.user_visible projected from the ProjectGraph step — the
+  // tangible checkpoint the session-cutting planner aims for (empty when the
+  // step declares no user-visible result). Concepts carry '' by default.
+  user_visible_deliverable: zod.z.string().default(""),
+  // P52/T3.1 — depth-reconcile inputs (optional/defaulted so old feeds
+  // validate unchanged):
+  // • depth_variants: minutes to teach this node at each depth level.
+  //  ULO (know-it-exists) ≤ CIO (mechanism) ≤ SIO (implementation). All 3
+  //   required so a downgrade never turns an anchor teach into a zero.
+  // • depth_scaffold_candidates: parallel to scaffold_candidates but
+  //   acts on DEPTH (e.g. SIO→CIO) instead of lesson time.
+  // • is_core: concept is a Master-Tree core concept — reconciler must
+  //   never downgrade it; 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: zod.z.enum(["ulo", "cio", "sio"]),
+    to_depth: zod.z.enum(["ulo", "cio", "sio"]),
+    minutes_saved: zod.z.number().int().nonnegative(),
+    reason: zod.z.string().default("")
+  })).optional(),
+  is_core: zod.z.boolean().default(false),
   // Progressive-completion bookkeeping (feed v2, additive):
   // phase_id = development phase that introduces/uses this node;
-  // introduce_aspect = how the phase teaches a concept node (first intro vs advanced revisit).
+  // introduce_aspect = how the phase teaches a concept node (first intro, advanced
+  // revisit, or preview — a light ULO awareness pass that is NOT the introduction).
   phase_id: zod.z.string().default(""),
-  introduce_aspect: zod.z.enum(["new", "advanced"]).nullable().default(null)
+  introduce_aspect: zod.z.enum(["new", "advanced", "preview"]).nullable().default(null)
 });
 var FeedEdgeSchema = zod.z.object({
   from: zod.z.string().min(1),
@@ -94,6 +116,22 @@ function validateCurriculumFeed(feed) {
   }
   const phaseIds = parsed.phases.map((p) => p.id);
   if (new Set(phaseIds).size !== phaseIds.length) throw new Error("curriculum feed contains duplicate phase ids");
+  if (parsed.phases.length > 0) {
+    const phaseIndexOf = /* @__PURE__ */ new Map();
+    parsed.phases.forEach((p, i) => {
+      for (const id of p.node_ids) phaseIndexOf.set(id, i);
+    });
+    for (const e of parsed.dependency_edges) {
+      const fromIdx = phaseIndexOf.get(e.from);
+      const toIdx = phaseIndexOf.get(e.to);
+      if (fromIdx === void 0 || toIdx === void 0) continue;
+      if (fromIdx > toIdx) {
+        throw new Error(
+          "curriculum feed teaching-order violation: prerequisite " + e.from + " (phase " + (fromIdx + 1) + ") is scheduled AFTER its consumer " + e.to + " (phase " + (toIdx + 1) + ")"
+        );
+      }
+    }
+  }
   return parsed;
 }
 
@@ -108,6 +146,9 @@ function stepMinutes(step) {
   const effort = step.effort ?? {};
   return Math.max(0, Math.round(num(effort.estimated_minutes, num(step.estimated_minutes, 45))));
 }
+function pushWarning(opts, message) {
+  (opts.warnings ?? (opts.warnings = [])).push(message);
+}
 function newKeywordsInOrder(nodes) {
   const seen = /* @__PURE__ */ new Set();
   for (const n of nodes) {
@@ -137,6 +178,10 @@ function feedNodeFromStep(step, featureId) {
     references: arr(step.files).map((f) => ({ file: str(f), evidence: "step file" })).filter((f) => f.file),
     feature_id: featureId,
     concept_ref: null,
+    // P52/T2.1: carry the step's tangible outcome so the planner can cut
+    // sessions at user-visible checkpoints instead of raw minute counts.
+    user_visible_deliverable: str(step.outcome?.user_visible),
+    is_core: false,
     phase_id: "",
     introduce_aspect: null
   };
@@ -155,6 +200,20 @@ function deriveConceptDepthHint(concept) {
   if (str(concept.cio) || prereqs.length >= 1) return "cio";
   return "ulo";
 }
+function deriveDepthInputs(minutes, depth) {
+  const ulo = Math.max(5, Math.round(minutes * 0.35));
+  const cio = Math.max(ulo + 5, Math.round(minutes * 0.65));
+  const sio = Math.max(cio + 5, minutes);
+  const variants = { ulo, cio, sio };
+  const candidates = [];
+  if (depth === "sio") {
+    candidates.push({ from_depth: "sio", to_depth: "cio", minutes_saved: sio - cio, reason: "SIO implementation practice deferred \u2014 CIO mechanism suffices for downstream consumers" });
+  }
+  if (depth === "cio" || depth === "sio") {
+    candidates.push({ from_depth: depth, to_depth: "ulo", minutes_saved: (depth === "sio" ? sio : cio) - ulo, reason: "Mechanism deferred \u2014 ULO awareness suffices (know-it-exists); never below the ULO floor" });
+  }
+  return { depth_variants: variants, depth_scaffold_candidates: candidates };
+}
 function feedNodeFromConcept(concept) {
   const id = str(concept.id);
   const pts = arr(concept.problem_types).map((p) => str(p.bloom_level, "Understand")).filter((b) => b in BLOOM_RANK).sort((a, b) => BLOOM_RANK[a] - BLOOM_RANK[b]);
@@ -184,6 +243,10 @@ function feedNodeFromConcept(concept) {
     references,
     feature_id: null,
     concept_ref: id,
+    user_visible_deliverable: "",
+    // concepts are taught, not shipped — checkpoints live on product steps
+    ...deriveDepthInputs(Math.max(0, Math.round(num(concept.estimated_minutes, 15))), deriveConceptDepthHint(concept)),
+    is_core: false,
     phase_id: "",
     introduce_aspect: null
   };
@@ -244,6 +307,7 @@ function emitFromHybrid(hybrid, opts) {
   }
   const emitCtx = [];
   const emittedConcepts = /* @__PURE__ */ new Set();
+  const previewsEmitted = /* @__PURE__ */ new Set();
   const linkList = arr(hybrid.links);
   for (const rp of rawPhases) {
     const pid = str(rp.id);
@@ -252,7 +316,8 @@ function emitFromHybrid(hybrid, opts) {
     const intros = arr(rp.introduces);
     const news = intros.filter((i) => str(i.aspect, "new") === "new");
     const advanced = intros.filter((i) => str(i.aspect) === "advanced");
-    for (const intro of [...news, ...advanced]) {
+    const previews = intros.filter((i) => str(i.aspect) === "preview");
+    for (const intro of [...news, ...advanced, ...previews]) {
       const cid = str(intro.concept_id);
       const c = conceptById.get(cid);
       if (!c) {
@@ -261,6 +326,39 @@ function emitFromHybrid(hybrid, opts) {
       if (str(intro.aspect, "new") === "advanced" && !emittedConcepts.has(cid)) {
         throw new Error("Phase " + pid + " advanced-revisits concept " + cid + " that was never emitted - fail-closed");
       }
+      if (str(intro.aspect, "new") === "preview") {
+        if (emittedConcepts.has(cid)) {
+          throw new Error("Phase " + pid + " previews concept " + cid + " that was already introduced - preview must precede the anchor teach - fail-closed");
+        }
+        if (previewsEmitted.has(cid)) {
+          throw new Error("Phase " + pid + " duplicate preview of concept " + cid + " - fail-closed");
+        }
+        const pidIdx = rawPhases.findIndex((rp2) => str(rp2.id) === pid);
+        const anchorIdx = rawPhases.findIndex((rp2) => arr(rp2.introduces).some((i2) => str(i2.concept_id) === cid && str(i2.aspect, "new") !== "preview"));
+        if (anchorIdx < 0) {
+          throw new Error("Phase " + pid + " previews concept " + cid + " that is never fully introduced in any phase - fail-closed");
+        }
+        if (pidIdx >= anchorIdx) {
+          throw new Error("Phase " + pid + " previews concept " + cid + " whose anchor introduction is not in a LATER phase - fail-closed");
+        }
+        previewsEmitted.add(cid);
+        const prevNode = feedNodeFromConcept(c);
+        prevNode.id = cid + "__PREV" + pad2(order);
+        prevNode.name = str(c.name, cid) + " (preview)";
+        prevNode.phase_id = pid;
+        prevNode.introduce_aspect = "preview";
+        prevNode.estimated_minutes = Math.max(5, Math.round(prevNode.estimated_minutes * 0.25));
+        prevNode.depth_hint = "ulo";
+        prevNode.bloom_hint = "Understand";
+        prevNode.concept_codes = [str(c.code) || cid];
+        prevNode.keywords = { all: strs(c.keywords), new: [], prerequisite: [] };
+        prevNode.scaffolding = { scaffold_candidates: [], core_value_minutes: 0 };
+        prevNode.depth_variants = { ulo: prevNode.estimated_minutes, cio: prevNode.estimated_minutes, sio: prevNode.estimated_minutes };
+        prevNode.depth_scaffold_candidates = [];
+        nodes.push(prevNode);
+        conceptOrder.push(prevNode.id);
+        continue;
+      }
       if (!emittedConcepts.has(cid)) {
         const node = feedNodeFromConcept(c);
         node.phase_id = pid;
@@ -281,6 +379,7 @@ function emitFromHybrid(hybrid, opts) {
         node.name = str(c.name, cid) + " (advanced)";
         node.phase_id = pid;
         node.introduce_aspect = "advanced";
+        node.depth_scaffold_candidates = [{ from_depth: "sio", to_depth: "cio", minutes_saved: Math.round(node.estimated_minutes * 0.3), reason: "advanced revisit may drop to CIO recap without breaking first-teach chain" }];
         node.estimated_minutes = Math.max(15, Math.round(node.estimated_minutes * 0.5));
         node.concept_codes = [str(c.code) || cid];
         edges.push({ from: cid, to: revisitId, kind: "knowledge", reason: "advanced revisit of " + cid + " at phase " + pid });
@@ -316,6 +415,17 @@ function emitFromHybrid(hybrid, opts) {
     }
     phaseNodeIds.push(ids);
   }
+  const placed = new Set(phaseNodeIds.flat());
+  const orderedNodes = [];
+  for (const ids of phaseNodeIds) {
+    for (const id of ids) {
+      const n = nodes.find((x) => x.id === id);
+      if (n) orderedNodes.push(n);
+    }
+  }
+  for (const n of nodes) if (!placed.has(n.id)) orderedNodes.push(n);
+  nodes.length = 0;
+  nodes.push(...orderedNodes);
   const edgeSeen = new Set(edges.map((e) => e.from + ">" + e.to));
   const pushEdge = (from, to, reason) => {
     const key = from + ">" + to;
@@ -330,6 +440,14 @@ function emitFromHybrid(hybrid, opts) {
     const firstStep = (stepIdsByFeature.get(fid) || [])[0];
     if (!firstStep) continue;
     const depth = str(l.depth, "cio");
+    const anchorNode = nodes.find((n2) => n2.kind === "concept" && n2.concept_ref === cid && n2.introduce_aspect === "new");
+    const stepNode = nodes.find((n2) => n2.id === firstStep);
+    const anchorPhaseIdx = anchorNode ? emitCtx.findIndex((c2) => c2.id === anchorNode.phase_id) : -1;
+    const stepPhaseIdx = stepNode ? emitCtx.findIndex((c2) => c2.id === stepNode.phase_id) : -1;
+    if (emitCtx.length > 0 && anchorPhaseIdx > stepPhaseIdx) {
+      pushWarning(opts, "hybrid link drift: concept " + cid + " is fully taught in a later phase than consumer " + firstStep + " (a preview covers the dependency)");
+      continue;
+    }
     pushEdge(cid, firstStep, str(l.relationship, "hybrid link") + " [" + depth + "]");
     for (const n of nodes) {
       if (n.kind === "concept" && n.concept_ref === cid && n.introduce_aspect === "advanced" && n.phase_id === str(l.phase_id)) {
@@ -348,6 +466,21 @@ function emitFromHybrid(hybrid, opts) {
     for (const k of n.keywords?.prerequisite ?? []) {
       const src = introducer.get(k.toLowerCase());
       if (!src || src === n.id) continue;
+      const srcNode = nodes.find((x) => x.id === src);
+      const phaseOf = (id) => {
+        const n2 = nodes.find((x) => x.id === id);
+        return n2 ? emitCtx.findIndex((c) => c.id === n2.phase_id) : -1;
+      };
+      const conceptOvertaken = n.kind === "concept" && srcNode?.kind === "product_step";
+      const fromPhase = phaseOf(src);
+      const toPhase = phaseOf(n.id);
+      if (conceptOvertaken || emitCtx.length > 0 && fromPhase > toPhase) {
+        pushWarning(
+          opts,
+          "keyword-order drift: introducer " + src + " sits in a later phase than consumer " + n.id + ' (keyword "' + k + '") \u2014 host should move the introducer earlier'
+        );
+        continue;
+      }
       if (feedOrder.get(src) < feedOrder.get(n.id)) pushEdge(src, n.id, "keyword prerequisite [" + k + "]");
     }
   }