@thanh01.pmt/domain-kit 0.5.0 → 0.6.1

package/dist/{conceptEscalator-YfMKIKCZ.d.ts → conceptEscalator-DMsehscs.d.ts}

@@ -1,4 +1,4 @@
-import { L as LlmClientConfig } from './llmClient-ysPhLjcH.js';
+import { LlmClientConfig, LlmClient } from './utils/llmClient.js';
 import { u as ProjectGraph } from './projectGraphSchema-DnD7orZV.js';
 
 /**
@@ -19,6 +19,12 @@ interface ConceptMapping {
     keyword: string;
     depth: 'ulo' | 'cio' | 'sio';
     depth_rationale: string;
+    /**
+     * Who decided `depth`. The regex fallback (comment → ulo, import → sio) has no
+     * pedagogical basis — without this marker a degraded run is indistinguishable
+     * from a considered one, because both write the same field.
+     */
+    depth_source: 'llm' | 'heuristic' | 'override';
     evidence_files: string[];
 }
 interface EscalateOptions {
@@ -31,6 +37,9 @@ interface EscalateOptions {
         depth?: string;
     }>;
     llmConfig?: LlmClientConfig;
+    /** Pre-built client from the calling pipeline — reused so every step of one run
+     *  lands in ONE callLog and the feed can report real provenance. */
+    sharedClient?: LlmClient;
 }
 /**
  * Escalate keywords/api_usage to neutral concepts with ULO/CIO/SIO depth and join evidence files.

package/dist/concepts/index.d.cts

@@ -1,6 +1,7 @@
-import { L as LlmClientConfig } from '../llmClient-ysPhLjcH.cjs';
-import { K as Keyword } from '../keywordExtractor-BxlGRMHC.cjs';
-import '../cpp-CZUPqJt9.cjs';
+import { LlmClientConfig } from '../utils/llmClient.cjs';
+import { K as Keyword } from '../keywordExtractor-1YAFntsn.cjs';
+import '../utils/llmTransportResult.cjs';
+import '../cpp-vlDl6pCL.cjs';
 
 /**
  * Concept resolution — maps keywords to Master Tree concepts.

package/dist/concepts/index.d.ts

@@ -1,6 +1,7 @@
-import { L as LlmClientConfig } from '../llmClient-ysPhLjcH.js';
-import { K as Keyword } from '../keywordExtractor-DU5XRN8-.js';
-import '../cpp-CZUPqJt9.js';
+import { LlmClientConfig } from '../utils/llmClient.js';
+import { K as Keyword } from '../keywordExtractor-DWw8z_AF.js';
+import '../utils/llmTransportResult.js';
+import '../cpp-vlDl6pCL.js';
 
 /**
  * Concept resolution — maps keywords to Master Tree concepts.

package/dist/{cpp-CZUPqJt9.d.cts → cpp-vlDl6pCL.d.cts}

@@ -1,5 +1,5 @@
 /**
- * Swift AST-level parser — extracts imports, types, functions, property wrappers,
+ * Swift regex-based parser (heuristic) — extracts imports, types, functions, property wrappers,
  * error handling patterns, and framework usage from Swift source files.
  *
  * Ported from knowledge-tree/extract_project_keywords.py parse_swift_file()
@@ -26,7 +26,7 @@ declare function parseSwiftFile(filepath: string, content: string): SwiftParseRe
 declare function mergeSwiftResults(results: SwiftParseResult[]): SwiftParseResult;
 
 /**
- * TypeScript/JavaScript AST-level parser — extracts imports, types, functions,
+ * TypeScript/JavaScript regex-based parser (heuristic) — extracts imports, types, functions,
  * and error handling patterns.
  *
  * Ported from knowledge-tree/extract_project_keywords.py parse_ts_file()
@@ -49,7 +49,7 @@ declare function parseTsFile(filepath: string, content: string): TsParseResult;
 declare function mergeTsResults(results: TsParseResult[]): TsParseResult;
 
 /**
- * Python AST-level parser — extracts imports, classes, functions, docstrings,
+ * Python regex-based parser (heuristic) — extracts imports, classes, functions, docstrings,
  * and error handling patterns.
  *
  * Ported from knowledge-tree/extract_project_keywords.py parse_python_file()
@@ -74,7 +74,7 @@ declare function parsePythonFile(filepath: string, content: string): PythonParse
 declare function mergePythonResults(results: PythonParseResult[]): PythonParseResult;
 
 /**
- * C++/Arduino AST-level parser — extracts #include, types, functions,
+ * C++/Arduino regex-based parser (heuristic) — extracts #include, types, functions,
  * and error handling patterns.
  *
  * Ported from knowledge-tree/extract_project_keywords.py parse_cpp_file()

package/dist/{cpp-CZUPqJt9.d.ts → cpp-vlDl6pCL.d.ts}

@@ -1,5 +1,5 @@
 /**
- * Swift AST-level parser — extracts imports, types, functions, property wrappers,
+ * Swift regex-based parser (heuristic) — extracts imports, types, functions, property wrappers,
  * error handling patterns, and framework usage from Swift source files.
  *
  * Ported from knowledge-tree/extract_project_keywords.py parse_swift_file()
@@ -26,7 +26,7 @@ declare function parseSwiftFile(filepath: string, content: string): SwiftParseRe
 declare function mergeSwiftResults(results: SwiftParseResult[]): SwiftParseResult;
 
 /**
- * TypeScript/JavaScript AST-level parser — extracts imports, types, functions,
+ * TypeScript/JavaScript regex-based parser (heuristic) — extracts imports, types, functions,
  * and error handling patterns.
  *
  * Ported from knowledge-tree/extract_project_keywords.py parse_ts_file()
@@ -49,7 +49,7 @@ declare function parseTsFile(filepath: string, content: string): TsParseResult;
 declare function mergeTsResults(results: TsParseResult[]): TsParseResult;
 
 /**
- * Python AST-level parser — extracts imports, classes, functions, docstrings,
+ * Python regex-based parser (heuristic) — extracts imports, classes, functions, docstrings,
  * and error handling patterns.
  *
  * Ported from knowledge-tree/extract_project_keywords.py parse_python_file()
@@ -74,7 +74,7 @@ declare function parsePythonFile(filepath: string, content: string): PythonParse
 declare function mergePythonResults(results: PythonParseResult[]): PythonParseResult;
 
 /**
- * C++/Arduino AST-level parser — extracts #include, types, functions,
+ * C++/Arduino regex-based parser (heuristic) — extracts #include, types, functions,
  * and error handling patterns.
  *
  * Ported from knowledge-tree/extract_project_keywords.py parse_cpp_file()

package/dist/{curriculumFeedSchema-DUFwFyr2.d.ts → curriculumFeedSchema-DK-TUAJZ.d.cts}

@@ -26,8 +26,8 @@ declare const FeedScaffoldCandidateSchema: z.ZodObject<{
     minutes_saved: z.ZodDefault<z.ZodNumber>;
     suggest: z.ZodDefault<z.ZodEnum<["provide_full", "provide_partial", "provide_reference"]>>;
 }, "strip", z.ZodTypeAny, {
-    item: string;
     reason: string;
+    item: string;
     minutes_saved: number;
     suggest: "provide_full" | "provide_partial" | "provide_reference";
 }, {
@@ -65,8 +65,8 @@ declare const FeedNodeSchema: z.ZodObject<{
             minutes_saved: z.ZodDefault<z.ZodNumber>;
             suggest: z.ZodDefault<z.ZodEnum<["provide_full", "provide_partial", "provide_reference"]>>;
         }, "strip", z.ZodTypeAny, {
-            item: string;
             reason: string;
+            item: string;
             minutes_saved: number;
             suggest: "provide_full" | "provide_partial" | "provide_reference";
         }, {
@@ -78,8 +78,8 @@ declare const FeedNodeSchema: z.ZodObject<{
         core_value_minutes: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         scaffold_candidates: {
-            item: string;
             reason: string;
+            item: string;
             minutes_saved: number;
             suggest: "provide_full" | "provide_partial" | "provide_reference";
         }[];
@@ -136,6 +136,14 @@ declare const FeedNodeSchema: z.ZodObject<{
         reason?: string | undefined;
     }>, "many">>;
     is_core: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Prerequisite concept ids this node needs that NO node in this feed provides —
+     * i.e. the learner must already know them before starting. Previously these were
+     * silently dropped (knowledge path) or crashed emission (both hybrid paths), so a
+     * course silently lost its entry requirements. Kept on the node so the mapping
+     * "concept X needs prior knowledge Y" survives; a course-level roll-up is derivable.
+     */
+    external_prerequisites: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     depth_context: z.ZodOptional<z.ZodObject<{
         ulo: z.ZodDefault<z.ZodString>;
         cio: z.ZodDefault<z.ZodString>;
@@ -169,8 +177,8 @@ declare const FeedNodeSchema: z.ZodObject<{
     depth_hint: "ulo" | "cio" | "sio" | null;
     scaffolding: {
         scaffold_candidates: {
-            item: string;
             reason: string;
+            item: string;
             minutes_saved: number;
             suggest: "provide_full" | "provide_partial" | "provide_reference";
         }[];
@@ -183,6 +191,7 @@ declare const FeedNodeSchema: z.ZodObject<{
     concept_ref: string | null;
     user_visible_deliverable: string;
     is_core: boolean;
+    external_prerequisites: string[];
     introduce_aspect: "new" | "advanced" | "preview" | null;
     depth_variants?: {
         ulo: number;
@@ -243,6 +252,7 @@ declare const FeedNodeSchema: z.ZodObject<{
         reason?: string | undefined;
     }[] | undefined;
     is_core?: boolean | undefined;
+    external_prerequisites?: string[] | undefined;
     depth_context?: {
         ulo?: string | undefined;
         cio?: string | undefined;
@@ -302,20 +312,127 @@ declare const FeedPhaseSchema: z.ZodObject<{
     node_ids: string[];
 }>;
 type FeedPhase = z.infer<typeof FeedPhaseSchema>;
+/**
+ * Machine-readable diagnostic. `warnings` in `source` is the DERIVED text view of
+ * these (every diagnostic whose severity is not 'info'), so there is exactly one
+ * source of truth and the host can gate on `code`/`severity` instead of substring
+ * matching free text — the 2026-09-17 class of incident was a drift that was only
+ * ever a warning string.
+ */
+declare const FeedDiagnosticSchema: z.ZodObject<{
+    code: z.ZodString;
+    severity: z.ZodEnum<["info", "warning", "error"]>;
+    message: z.ZodString;
+    node_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    severity: "info" | "warning" | "error";
+    node_ids: string[];
+}, {
+    code: string;
+    message: string;
+    severity: "info" | "warning" | "error";
+    node_ids?: string[] | undefined;
+}>;
+type FeedDiagnostic = z.infer<typeof FeedDiagnosticSchema>;
+/** Which LLM providers actually served this graph, and whether any call fell over. */
+declare const FeedProvenanceSchema: z.ZodObject<{
+    providers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    models: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    calls: z.ZodDefault<z.ZodNumber>;
+    failed_calls: z.ZodDefault<z.ZodNumber>;
+    degraded: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    models: string[];
+    providers: string[];
+    calls: number;
+    failed_calls: number;
+    degraded: boolean;
+}, {
+    models?: string[] | undefined;
+    providers?: string[] | undefined;
+    calls?: number | undefined;
+    failed_calls?: number | undefined;
+    degraded?: boolean | undefined;
+}>;
+type FeedProvenance = z.infer<typeof FeedProvenanceSchema>;
 declare const CurriculumFeedSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<2>;
     source: z.ZodObject<{
         graph_type: z.ZodEnum<["project_graph", "knowledge_graph", "hybrid_graph"]>;
+        /** DERIVED from diagnostics — do not write to it directly. */
         warnings: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         hallucination_count: z.ZodDefault<z.ZodNumber>;
+        diagnostics: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            severity: z.ZodEnum<["info", "warning", "error"]>;
+            message: z.ZodString;
+            node_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            message: string;
+            severity: "info" | "warning" | "error";
+            node_ids: string[];
+        }, {
+            code: string;
+            message: string;
+            severity: "info" | "warning" | "error";
+            node_ids?: string[] | undefined;
+        }>, "many">>;
+        provenance: z.ZodOptional<z.ZodObject<{
+            providers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            models: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            calls: z.ZodDefault<z.ZodNumber>;
+            failed_calls: z.ZodDefault<z.ZodNumber>;
+            degraded: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            models: string[];
+            providers: string[];
+            calls: number;
+            failed_calls: number;
+            degraded: boolean;
+        }, {
+            models?: string[] | undefined;
+            providers?: string[] | undefined;
+            calls?: number | undefined;
+            failed_calls?: number | undefined;
+            degraded?: boolean | undefined;
+        }>>;
     }, "strip", z.ZodTypeAny, {
         graph_type: "knowledge_graph" | "hybrid_graph" | "project_graph";
         warnings: string[];
         hallucination_count: number;
+        diagnostics: {
+            code: string;
+            message: string;
+            severity: "info" | "warning" | "error";
+            node_ids: string[];
+        }[];
+        provenance?: {
+            models: string[];
+            providers: string[];
+            calls: number;
+            failed_calls: number;
+            degraded: boolean;
+        } | undefined;
     }, {
         graph_type: "knowledge_graph" | "hybrid_graph" | "project_graph";
         warnings?: string[] | undefined;
         hallucination_count?: number | undefined;
+        diagnostics?: {
+            code: string;
+            message: string;
+            severity: "info" | "warning" | "error";
+            node_ids?: string[] | undefined;
+        }[] | undefined;
+        provenance?: {
+            models?: string[] | undefined;
+            providers?: string[] | undefined;
+            calls?: number | undefined;
+            failed_calls?: number | undefined;
+            degraded?: boolean | undefined;
+        } | undefined;
     }>;
     learning_nodes: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -346,8 +463,8 @@ declare const CurriculumFeedSchema: z.ZodObject<{
                 minutes_saved: z.ZodDefault<z.ZodNumber>;
                 suggest: z.ZodDefault<z.ZodEnum<["provide_full", "provide_partial", "provide_reference"]>>;
             }, "strip", z.ZodTypeAny, {
-                item: string;
                 reason: string;
+                item: string;
                 minutes_saved: number;
                 suggest: "provide_full" | "provide_partial" | "provide_reference";
             }, {
@@ -359,8 +476,8 @@ declare const CurriculumFeedSchema: z.ZodObject<{
             core_value_minutes: z.ZodDefault<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
             scaffold_candidates: {
-                item: string;
                 reason: string;
+                item: string;
                 minutes_saved: number;
                 suggest: "provide_full" | "provide_partial" | "provide_reference";
             }[];
@@ -417,6 +534,14 @@ declare const CurriculumFeedSchema: z.ZodObject<{
             reason?: string | undefined;
         }>, "many">>;
         is_core: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Prerequisite concept ids this node needs that NO node in this feed provides —
+         * i.e. the learner must already know them before starting. Previously these were
+         * silently dropped (knowledge path) or crashed emission (both hybrid paths), so a
+         * course silently lost its entry requirements. Kept on the node so the mapping
+         * "concept X needs prior knowledge Y" survives; a course-level roll-up is derivable.
+         */
+        external_prerequisites: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         depth_context: z.ZodOptional<z.ZodObject<{
             ulo: z.ZodDefault<z.ZodString>;
             cio: z.ZodDefault<z.ZodString>;
@@ -450,8 +575,8 @@ declare const CurriculumFeedSchema: z.ZodObject<{
         depth_hint: "ulo" | "cio" | "sio" | null;
         scaffolding: {
             scaffold_candidates: {
-                item: string;
                 reason: string;
+                item: string;
                 minutes_saved: number;
                 suggest: "provide_full" | "provide_partial" | "provide_reference";
             }[];
@@ -464,6 +589,7 @@ declare const CurriculumFeedSchema: z.ZodObject<{
         concept_ref: string | null;
         user_visible_deliverable: string;
         is_core: boolean;
+        external_prerequisites: string[];
         introduce_aspect: "new" | "advanced" | "preview" | null;
         depth_variants?: {
             ulo: number;
@@ -524,6 +650,7 @@ declare const CurriculumFeedSchema: z.ZodObject<{
             reason?: string | undefined;
         }[] | undefined;
         is_core?: boolean | undefined;
+        external_prerequisites?: string[] | undefined;
         depth_context?: {
             ulo?: string | undefined;
             cio?: string | undefined;
@@ -587,6 +714,19 @@ declare const CurriculumFeedSchema: z.ZodObject<{
         graph_type: "knowledge_graph" | "hybrid_graph" | "project_graph";
         warnings: string[];
         hallucination_count: number;
+        diagnostics: {
+            code: string;
+            message: string;
+            severity: "info" | "warning" | "error";
+            node_ids: string[];
+        }[];
+        provenance?: {
+            models: string[];
+            providers: string[];
+            calls: number;
+            failed_calls: number;
+            degraded: boolean;
+        } | undefined;
     };
     schema_version: 2;
     phases: {
@@ -614,8 +754,8 @@ declare const CurriculumFeedSchema: z.ZodObject<{
         depth_hint: "ulo" | "cio" | "sio" | null;
         scaffolding: {
             scaffold_candidates: {
-                item: string;
                 reason: string;
+                item: string;
                 minutes_saved: number;
                 suggest: "provide_full" | "provide_partial" | "provide_reference";
             }[];
@@ -628,6 +768,7 @@ declare const CurriculumFeedSchema: z.ZodObject<{
         concept_ref: string | null;
         user_visible_deliverable: string;
         is_core: boolean;
+        external_prerequisites: string[];
         introduce_aspect: "new" | "advanced" | "preview" | null;
         depth_variants?: {
             ulo: number;
@@ -663,6 +804,19 @@ declare const CurriculumFeedSchema: z.ZodObject<{
         graph_type: "knowledge_graph" | "hybrid_graph" | "project_graph";
         warnings?: string[] | undefined;
         hallucination_count?: number | undefined;
+        diagnostics?: {
+            code: string;
+            message: string;
+            severity: "info" | "warning" | "error";
+            node_ids?: string[] | undefined;
+        }[] | undefined;
+        provenance?: {
+            models?: string[] | undefined;
+            providers?: string[] | undefined;
+            calls?: number | undefined;
+            failed_calls?: number | undefined;
+            degraded?: boolean | undefined;
+        } | undefined;
     };
     schema_version: 2;
     learning_nodes: {
@@ -708,6 +862,7 @@ declare const CurriculumFeedSchema: z.ZodObject<{
             reason?: string | undefined;
         }[] | undefined;
         is_core?: boolean | undefined;
+        external_prerequisites?: string[] | undefined;
         depth_context?: {
             ulo?: string | undefined;
             cio?: string | undefined;
@@ -742,4 +897,4 @@ type FeedGrouping = z.infer<typeof FeedGroupingSchema>;
 /** Strict pre-save resolution validation — fail-closed, no defaulted-empty graphs. */
 declare function validateCurriculumFeed(feed: unknown): CurriculumFeed;
 
-export { CurriculumFeedSchema as C, FeedKeywordsSchema as F, FeedScaffoldCandidateSchema as a, FeedNodeSchema as b, FeedEdgeSchema as c, FeedGroupingSchema as d, FeedPhaseSchema as e, type FeedPhase as f, type CurriculumFeed as g, type FeedNode as h, type FeedEdge as i, type FeedGrouping as j, validateCurriculumFeed as v };
+export { CurriculumFeedSchema as C, FeedKeywordsSchema as F, FeedScaffoldCandidateSchema as a, FeedNodeSchema as b, FeedEdgeSchema as c, FeedGroupingSchema as d, FeedPhaseSchema as e, type FeedPhase as f, FeedDiagnosticSchema as g, type FeedDiagnostic as h, FeedProvenanceSchema as i, type FeedProvenance as j, type CurriculumFeed as k, type FeedNode as l, type FeedEdge as m, type FeedGrouping as n, validateCurriculumFeed as v };