@thanh01.pmt/domain-kit 0.5.0 → 0.6.1

package/dist/graph/index.cjs

@@ -4,7 +4,56 @@ var fs = require('fs');
 var os = require('os');
 var path = require('path');
 
+// src/utils/llmTransportResult.ts
+function transportResultFrom(provider, model, options) {
+  return {
+    provider,
+    model,
+    framingStripped: !!options?.framingStripped,
+    upstreamError: options?.upstreamError,
+    usage: options?.usage
+  };
+}
+
 // src/utils/llmClient.ts
+async function responseJsonCompat(response) {
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    const start = text.indexOf("{");
+    if (start < 0) {
+      throw new LlmClientError(`LLM API returned a non-JSON body: ${text.slice(0, 200)}`);
+    }
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = start; i < text.length; i++) {
+      const ch = text[i];
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escape = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = !inString;
+        continue;
+      }
+      if (inString) continue;
+      if (ch === "{") depth++;
+      if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          return JSON.parse(text.slice(start, i + 1));
+        }
+      }
+    }
+    throw new LlmClientError(`LLM API returned an unterminated JSON body: ${text.slice(0, 200)}`);
+  }
+}
 var LlmClientError = class extends Error {
   constructor(message, status, cause) {
     super(message);
@@ -13,47 +62,46 @@ var LlmClientError = class extends Error {
     this.name = "LlmClientError";
   }
 };
-function resolveProviderChain(config) {
-  const chain = [];
-  const push = (label, baseUrl, apiKey, model) => {
-    if (apiKey && baseUrl && model && !chain.some((c) => c.baseUrl === baseUrl && c.model === model)) {
-      chain.push({ label, baseUrl, apiKey, model });
-    }
-  };
-  if (config?.apiKey) {
-    push("config", config.baseUrl || "https://api.openai.com/v1", config.apiKey, config.model || "gpt-4o-mini");
-  }
-  push("legacy", process.env.LLM_BASE_URL || process.env.OPENAI_BASE_URL || "", process.env.LLM_API_KEY || process.env.OPENAI_API_KEY || "", process.env.LLM_MODEL || process.env.LLM_TIER_FAST || "");
-  push("dashscope", process.env.DASHSCOPE_BASE_URL || process.env.ALIBABA_BASE_URL || "", process.env.DASHSCOPE_API_KEY || process.env.ALIBABA_API_KEY || "", process.env.DASHSCOPE_MODEL || process.env.DEFAULT_AI_MODEL || "");
-  push("nvidia", "https://integrate.api.nvidia.com/v1", process.env.NVIDIA_API_KEY || "", process.env.NVIDIA_MODEL || "nvidia/nemotron-3-ultra-550b-a55b:free");
-  push("openrouter", "https://openrouter.ai/api/v1", process.env.OPENROUTER_API_KEY || "", process.env.OPENROUTER_MODEL || "nvidia/nemotron-3-ultra-550b-a55b:free");
-  if (process.env.OPENROUTER_MODEL) {
-    const or = chain.find((c) => c.label === "openrouter");
-    if (or) {
-      const rest = chain.filter((c) => c !== or);
-      return [or, ...rest];
-    }
-  }
-  return chain;
+function build9routerProvider(model) {
+  const apiKey = process.env.NINEROUTER_API_KEY;
+  if (!apiKey) return null;
+  const baseUrl = (process.env.NINEROUTER_BASE_URL || "https://ai-router.orchable.app/v1").replace(/^["']|["']$/g, "").trim();
+  const label = "9router";
+  const modelName = (model || process.env.NINEROUTER_MODEL || "laguna-s-2.1").trim();
+  return { label, baseUrl, apiKey, model: modelName };
+}
+function resolve9routerChain(configModel) {
+  const primary = build9routerProvider(configModel);
+  if (!primary) return [];
+  const alt = process.env.NINEROUTER_MODEL_ALT && process.env.NINEROUTER_MODEL_ALT.trim();
+  if (!alt) return [primary];
+  const secondary = build9routerProvider(alt);
+  if (!secondary) return [primary];
+  return primary.model === secondary.model ? [primary] : [primary, secondary];
 }
 var MIN_REQUEST_INTERVAL_MS = 2500;
+var requestIntervalMs = Number(process.env.LLM_MIN_REQUEST_INTERVAL_MS || MIN_REQUEST_INTERVAL_MS);
 var lastRequestAt = 0;
 async function pacedDelay() {
-  const wait = lastRequestAt + MIN_REQUEST_INTERVAL_MS - Date.now();
+  const wait = lastRequestAt + requestIntervalMs - Date.now();
   if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
   lastRequestAt = Date.now();
 }
 function createLlmClient(config) {
-  const chain = resolveProviderChain(config);
+  const chain = resolve9routerChain(config?.model);
   const primary = chain[0];
   if (!primary) {
     throw new LlmClientError(
-      "No LLM provider configured. Set NVIDIA_API_KEY (primary) and/or OPENROUTER_API_KEY (fallback), or pass llmConfig."
+      "No 9router provider configured. Set NINEROUTER_API_KEY and NINEROUTER_MODEL (or the NINEROUTER_* env defaults expected by the kit)."
     );
   }
   primary.apiKey;
   primary.baseUrl;
   const model = primary.model;
+  if (config?.minRequestIntervalMs !== void 0) {
+    requestIntervalMs = Math.max(0, config.minRequestIntervalMs);
+  }
+  const callLog = [];
   async function chat(messages, options) {
     const temperature = options?.temperature ?? config?.temperature ?? 0.1;
     const maxTokens = options?.maxTokens ?? config?.maxTokens ?? parseInt(process.env.LLM_MAX_TOKENS || "65536", 10);
@@ -68,6 +116,7 @@ function createLlmClient(config) {
         await new Promise((resolve) => setTimeout(resolve, 2e4));
       }
       for (const provider of chain) {
+        const recIdx = callLog.push({ provider: provider.label, model: provider.model, ok: false }) - 1;
         try {
           const headers = {
             "Content-Type": "application/json",
@@ -125,16 +174,22 @@ function createLlmClient(config) {
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
               });
               if (!retry.ok) throw err;
-              const retryData = await retry.json();
+              const retryData = await responseJsonCompat(retry);
               const retryContent2 = retryData.choices?.[0]?.message?.content || "";
               if (!retryContent2.trim()) throw err;
+              callLog[recIdx] = { ...callLog[recIdx], ok: true };
+              const transport2 = transportResultFrom(provider.label, retryData.model || provider.model, {
+                usage: retryData.usage,
+                framingStripped: true
+              });
               return {
                 content: retryContent2,
                 model: retryData.model || provider.model,
                 provider: provider.label,
                 attempts: attempts.slice(),
                 usage: retryData.usage,
-                finishReason: retryData.choices?.[0]?.finish_reason
+                finishReason: retryData.choices?.[0]?.finish_reason,
+                _transport: transport2
               };
             }
             if (TRANSIENT.has(response.status)) {
@@ -154,20 +209,26 @@ function createLlmClient(config) {
                 })
               });
               if (!retry.ok) throw err;
-              const retryData = await retry.json();
+              const retryData = await responseJsonCompat(retry);
               const retryContent = retryData.choices?.[0]?.message?.content || "";
+              callLog[recIdx] = { ...callLog[recIdx], ok: true };
+              const transport2 = transportResultFrom(provider.label, retryData.model || provider.model, {
+                usage: retryData.usage,
+                framingStripped: true
+              });
               return {
                 content: retryContent,
                 model: retryData.model || provider.model,
                 provider: provider.label,
                 attempts: attempts.slice(),
                 usage: retryData.usage,
-                finishReason: retryData.choices?.[0]?.finish_reason
+                finishReason: retryData.choices?.[0]?.finish_reason,
+                _transport: transport2
               };
             }
             throw err;
           }
-          const data = await response.json();
+          const data = await responseJsonCompat(response);
           const wrappedError = data.error;
           if (wrappedError) {
             throw new LlmClientError("[" + provider.label + "] upstream error " + (wrappedError.code ?? "") + ": " + (wrappedError.message ?? "unknown"));
@@ -176,16 +237,22 @@ function createLlmClient(config) {
           if (!content.trim()) {
             throw new LlmClientError("[" + provider.label + "] empty completion returned");
           }
+          const transport = transportResultFrom(provider.label, data.model || provider.model, {
+            usage: data.usage,
+            framingStripped: true
+          });
           return {
             content,
             model: data.model || provider.model,
             provider: provider.label,
             attempts: attempts.slice(),
             usage: data.usage,
-            finishReason: data.choices?.[0]?.finish_reason
+            finishReason: data.choices?.[0]?.finish_reason,
+            _transport: transport
           };
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
+          callLog[recIdx] = { ...callLog[recIdx], ok: false, error: msg.slice(0, 200) };
           attempts.push(`${provider.label}: ${msg}`);
           lastError = err instanceof LlmClientError ? err : new LlmClientError(`[${provider.label}] ${msg}`);
         }
@@ -195,7 +262,7 @@ function createLlmClient(config) {
     }
     throw lastError ?? new LlmClientError("All LLM providers failed after " + MAX_CHAIN_ROUNDS + " rounds.");
   }
-  return { chat, model };
+  return { chat, model, callLog };
 }
 function parseJsonFromLlm(text) {
   let cleaned = text.trim();
@@ -259,8 +326,8 @@ async function llmChatJson(client, systemPrompt, userPrompt, options) {
 
 // src/graph/scaffoldExtractor.ts
 async function extractScaffold(options) {
-  const { goal, techStack, fileList, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, fileList, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? createLlmClient(llmConfig);
   const fileListStr = fileList.length > 0 ? fileList.join("\n") : "(empty)";
   const systemPrompt = "You are a programming pedagogy expert. For ONE concrete project, extract the 'FOUNDATION & SETUP' feature (id F0) \u2014 the COMPLETE set of 'MUST-KNOW' steps the learner needs before studying the first feature. Break it into concrete ACTION steps (5-8 steps), each with completion_level='base'. Include:\n1. Tools required for this tech stack (IDE, simulator/emulator, terminal, git, package manager) + basic operations (open project, build, run, debug, commit).\n2. Create the initial project: from a template OR clone/open the base-project (the provided repo).\n3. MINIMAL programming knowledge of the language (variables, types, functions, if/for, view declaration) + build one small demo (e.g. a single-screen Hello World app) BEFORE touching the real project.\n4. Repo map of the actual project: folder structure, entry point, how to build/run, main architecture (MVVM/Flux...), important packages/modules.\n5. Development loop (build->run->see result->debug), how to read/fix basic compile errors, minimal git workflow (clone/branch/commit/push).\nkeywords[]: real tool/language terms (e.g. 'Xcode', 'Simulator', 'Git', 'Swift', '@main', 'MVVM'). files[]: leave [] or use real paths if the step touches specific files. description: ONE concise sentence, MAX 140 characters. intent: WHY this step matters. outcome: {user_visible: string, technical: string}. acceptance[]: 2 verifiable criteria. effort: {estimated_minutes: number, complexity: low|medium|high}. NEVER invent. ALL text must be in ENGLISH (technical terms stay as-is). Return JSON containing only feature F0.";
   const userPrompt = `App goal: ${goal}
@@ -345,8 +412,8 @@ ${content}`);
   return blocks.join("\n\n");
 }
 async function extractProjectOverview(options) {
-  const { goal, techStack, sdkApiIndex, fileContentsMap, astKeywords, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, sdkApiIndex, fileContentsMap, astKeywords, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? createLlmClient(llmConfig);
   const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
   const allFilesStr = buildSourceText(fileContentsMap);
   let keywordsAnchor = "";
@@ -355,7 +422,7 @@ async function extractProjectOverview(options) {
       (kw) => `- ${kw.keyword} (from ${kw.source})`
     );
     if (kwItems.length > 0) {
-      keywordsAnchor = "\nAST Domain Keywords & Patterns (from static analysis \u2014 use as context anchor):\n" + kwItems.join("\n") + "\n";
+      keywordsAnchor = "\nDomain Keywords & Patterns (from regex-based static scan \u2014 use as context anchor):\n" + kwItems.join("\n") + "\n";
     }
   }
   const systemPrompt = "You are a software architect. The app the user will build IS EXACTLY the provided files (not an SDK/lib). Analyze them and return a PROJECT OVERVIEW \u2014 meta only, DO NOT list steps (steps are handled in a later step). NEVER invent files/APIs. NEVER reference internal SDK/lib unless it appears in the given files.\nEND-USER VIEW (M1/Design Thinking): product.purpose must describe the USER PROBLEM (what the user does with the app, which need it solves). NEVER describe repo/artifacts.\nDEVELOPMENT STAGES: Include 4-6 development stages in product.development_stages. Each stage must have: stage (name), need (list of feature needs), learn (concepts learned), product_state (what works), temporary_approach, and validation.\nMISSING GAPS: Identify 0-5 missing_gaps (features/functionality that should exist but don't).\nTECH DEBT: Identify 0-5 tech_debt issues (code quality problems).\nALL text must be in ENGLISH.";
@@ -415,8 +482,8 @@ ${content}`);
   return blocks.join("\n\n");
 }
 async function extractFeatureSteps(options) {
-  const { goal, techStack, sdkApiIndex, fileContentsMap, feature, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, sdkApiIndex, fileContentsMap, feature, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? createLlmClient(llmConfig);
   const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
   const allFilesStr = buildSourceText2(fileContentsMap);
   const fid = feature.id || "F_UNK";
@@ -483,8 +550,8 @@ Split this feature into 2-6 action steps. Return JSON:
     concept_codes: []
   }));
 }
-async function extractFeatureStepsBatched(goal, techStack, sdkApiIndex, fileContentsMap, featuresMeta, llmConfig) {
-  const client = createLlmClient(llmConfig);
+async function extractFeatureStepsBatched(goal, techStack, sdkApiIndex, fileContentsMap, featuresMeta, llmConfig, sharedClient) {
+  const client = sharedClient ?? createLlmClient(llmConfig);
   const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
   const sourceText = buildSourceText2(fileContentsMap);
   const featuresListing = featuresMeta.map(
@@ -751,7 +818,7 @@ function inferDepthFromContext(keyword, fileContentsMap) {
   return { depth: "sio", rationale: `Default: treating '${keyword}' as SIO (implementation-level)` };
 }
 async function escalateAndMapConcepts(options) {
-  const { projectGraph, fileContentsMap, availableConcepts, conceptMapOverride, llmConfig } = options;
+  const { projectGraph, fileContentsMap, availableConcepts, conceptMapOverride, llmConfig, sharedClient } = options;
   const features = projectGraph.features || [];
   const allTerms = /* @__PURE__ */ new Set();
   for (const feature of features) {
@@ -767,7 +834,7 @@ async function escalateAndMapConcepts(options) {
     llmResults = conceptMapOverride;
   } else {
     try {
-      const client = createLlmClient(llmConfig);
+      const client = sharedClient ?? createLlmClient(llmConfig);
       const conceptBank = (availableConcepts || []).sort().join(", ") || "(empty)";
       const termEntries = termList.map((term) => {
         const snippets = extractTermSnippets(term, fileContentsMap);
@@ -820,13 +887,16 @@ Return JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "
       const cName = info.concept_name || kw;
       let depth = "sio";
       let depthRationale = "Default: SIO";
+      let depthSource = "override";
       if (info.depth && ["ulo", "cio", "sio"].includes(info.depth)) {
         depth = info.depth;
         depthRationale = `LLM classified as ${depth}`;
+        depthSource = "llm";
       } else {
         const inferred = inferDepthFromContext(kw, fileContentsMap);
         depth = inferred.depth;
         depthRationale = inferred.rationale;
+        depthSource = "heuristic";
       }
       const kwKey = `${cCode}::${kw}`;
       if (seen.has(kwKey)) continue;
@@ -844,6 +914,7 @@ Return JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "
         keyword: kw,
         depth,
         depth_rationale: depthRationale,
+        depth_source: depthSource,
         evidence_files: evidenceFiles
       });
     }
@@ -968,6 +1039,13 @@ var ULO_CODE_RE = /^ULO-[A-Z][A-Z0-9_]*-\d{2}$/;
 var CIO_CODE_RE = /^CIO-[A-Z][A-Z0-9_]*-\d{2}-[A-Z][A-Z0-9_]*$/;
 var SIO_CODE_RE = /^SIO-[A-Z0-9]+-[A-Z][A-Z0-9_]*-\d{2}$/;
 
+// src/utils/diacritics.ts
+var COMBINING_MARKS = /[\u0300-\u036f]/g;
+var D_WITH_STROKE = /đ/gi;
+function stripDiacritics(s) {
+  return s.normalize("NFD").replace(COMBINING_MARKS, "").replace(D_WITH_STROKE, "d").toLowerCase();
+}
+
 // src/parsers/syllabusParser.ts
 var STOP_WORDS = /* @__PURE__ */ new Set([
   "and",
@@ -1360,7 +1438,110 @@ function techSignalHits(text) {
   }
   return hits;
 }
-function auditDepthLayers(concepts) {
+var COMPLETABLE_VERBS = [
+  "build",
+  "create",
+  "implement",
+  "write",
+  "configure",
+  "add",
+  "use",
+  "apply",
+  "display",
+  "store",
+  "load",
+  "save",
+  "handle",
+  "parse",
+  "validate",
+  "test",
+  "register",
+  "compute",
+  "generate",
+  "print",
+  "format",
+  "convert",
+  "extend",
+  "define",
+  "execute",
+  "run",
+  "read",
+  "fetch",
+  "wrap",
+  "log",
+  "call",
+  "raise",
+  "install",
+  "import",
+  "export",
+  "declare",
+  "embed",
+  "model",
+  "represent",
+  "override",
+  "customize",
+  "enforce",
+  "mock",
+  "assert",
+  "query",
+  "index",
+  "cache",
+  "stream",
+  "split",
+  "join",
+  "strip",
+  "encode",
+  "decode",
+  "traverse",
+  "measure",
+  "evaluate",
+  "benchmark",
+  "diagnose",
+  "demonstrate",
+  "verify",
+  "organize",
+  "structure",
+  "choose",
+  "select",
+  "compare",
+  "distinguish",
+  "attach",
+  "annotate",
+  "expose",
+  "accept",
+  "manage",
+  "group",
+  "sort",
+  "filter",
+  "map",
+  "reduce",
+  "catch",
+  "throw",
+  "migrate",
+  "inspect",
+  "trace",
+  "parameterize",
+  "construct",
+  "design",
+  "capture",
+  // Completable implementation verbs present in production SIO output but
+  // missing from the original registry (2026-10-07 smoke test, swift kg):
+  "update",
+  "inject",
+  "compose",
+  "pass",
+  "modify",
+  "connect",
+  "remove",
+  "transform",
+  "trigger",
+  "refresh",
+  "persist",
+  "observe",
+  "arrange",
+  "derive"
+];
+function auditDepthLayers(concepts, transport) {
   return concepts.map((c) => {
     const ulo = (c.ulo ?? "").trim();
     const cio = (c.cio ?? "").trim();
@@ -1381,7 +1562,7 @@ function auditDepthLayers(concepts) {
     });
     const conceptKeywords = (c.keywords ?? []).map((k) => k.toLowerCase()).filter(Boolean);
     const sioOffConceptItems = conceptKeywords.length > 0 ? sioItems.filter((s) => !boundToConcept(s)) : [];
-    const COMPLETABLE = /\b(build|create|implement|write|configure|add|use|apply|display|store|load|save|handle|parse|validate|test|register|compute|generate|print|format|convert|extend|define|execute|run|read|fetch|wrap|log|call|raise|install|import|export|declare|embed|model|represent|override|customize|enforce|mock|assert|query|index|cache|stream|split|join|strip|encode|decode|traverse|measure|evaluate|benchmark|diagnose|demonstrate|verify|organize|structure|choose|select|compare|distinguish|attach|annotate|expose|accept|manage|group|sort|filter|map|reduce|catch|throw|migrate|inspect|trace|parameterize|construct|design|capture)\b/i;
+    const COMPLETABLE = new RegExp("\\b(?:" + COMPLETABLE_VERBS.join("|") + ")\\b", "i");
     const sioNotCompletable = sioItems.filter((s) => !COMPLETABLE.test(s) && !/`[^`]+`/.test(s));
     const density = (text) => {
       if (!text) return 0;
@@ -1421,7 +1602,8 @@ function auditDepthLayers(concepts) {
       clauseOk,
       codesOk,
       codeIssues,
-      passed
+      passed,
+      transport
     };
   });
 }
@@ -1431,14 +1613,14 @@ function excerpt(text, max) {
   const t = (text || "").trim();
   return t.length > max ? t.slice(0, max) + "..." : t;
 }
-async function chatJson(client, system, user) {
+async function chatJson(client, system, user, transport) {
   const r = await client.chat(
     [{ role: "system", content: system }, { role: "user", content: user }],
     { temperature: 0.1, maxTokens: parseInt(process.env.KG_MAX_TOKENS || "65536", 10) }
   );
   return parseJsonFromLlm(r.content);
 }
-var LO_BATCH_SIZE = 6;
+var LO_BATCH_SIZE = 10;
 function chunkConcepts(items, size) {
   const out = [];
   for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
@@ -1477,7 +1659,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
   for (const batch of chunkConcepts(concepts, LO_BATCH_SIZE)) {
     const batchList = batch.map((c) => "- " + c.id + " (" + c.name + ")" + (c.description ? ": " + excerpt(c.description, 160) : "")).join("\n");
     const batchUser = "Concepts:\n" + batchList + '\n\nReturn JSON:\n{"ulos":[{"concept_id":"C1","ulo":"..."}]}';
-    const uloRes = await chatJson(client, uloSystem, batchUser);
+    const uloRes = await chatJson(client, uloSystem, batchUser, transportResultFrom("9router", client.model, { framingStripped: true }));
     for (const u of uloRes.ulos ?? []) {
       if (u.concept_id && u.ulo) uloByConcept[u.concept_id] = standardStatement(u.ulo);
     }
@@ -1516,7 +1698,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
     new Set(batch.map((c) => c.id));
     const batchUloContext = batch.map((c) => "- " + c.id + " (" + c.name + "): " + (uloByConcept[c.id] || "(missing)")).join("\n");
     const batchCioUser = "Approved ULOs:\n" + batchUloContext + '\n\nReturn JSON:\n{"cios":[{"concept_id":"C1","cio":"..."}]}';
-    const cioRes = await chatJson(client, cioSystem, batchCioUser);
+    const cioRes = await chatJson(client, cioSystem, batchCioUser, transportResultFrom("9router", client.model, { framingStripped: true }));
     for (const x of cioRes.cios ?? []) {
       if (x.concept_id && x.cio) cioByConcept[x.concept_id] = standardStatement(x.cio);
     }
@@ -1541,15 +1723,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
     "   context where it is used. Application/Analysis/Creation skills are assessed",
     "   INDIRECTLY through completing these tasks \u2014 there is no fixed Bloom ceiling.",
     "   MACHINE CHECK: every item MUST contain at least one ACTION VERB from this whitelist",
-    "   (build, create, implement, write, configure, add, use, apply, display, store, load,",
-    "   save, handle, parse, validate, test, register, compute, generate, print, format,",
-    "   convert, extend, define, execute, run, read, fetch, wrap, log, call, raise, install,",
-    "   import, export, declare, embed, model, represent, override, customize, enforce, mock,",
-    "   assert, query, index, cache, stream, split, join, strip, encode, decode, traverse,",
-    "   measure, evaluate, benchmark, diagnose, demonstrate, verify, organize, structure,",
-    "   choose, select, compare, distinguish, attach, annotate, expose, accept, manage, group,",
-    "   sort, filter, map, reduce, catch, throw, migrate, inspect, trace, parameterize,",
-    "   construct, design, capture) \u2014 OR wrap the concrete construct in backticks.",
+    "   (" + COMPLETABLE_VERBS.join(", ") + ") \u2014 OR wrap the concrete construct in backticks.",
     "   Items with abstract verbs (understand, learn, know, grasp, appreciate, explore) and",
     "   no backtick construct FAIL the audit. Prefer starting the task phrase with the verb.",
     "3. 2-3 items per concept, each referencing a DIFFERENT concrete construct.",
@@ -1577,7 +1751,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
       "Return JSON:",
       '{"sios":[{"concept_id":"C1","sio":["...","..."]}]}'
     ].join("\n");
-    const sioRes = await chatJson(client, sioSystem, batchSioUser);
+    const sioRes = await chatJson(client, sioSystem, batchSioUser, transportResultFrom("9router", client.model, { framingStripped: true }));
     for (const x of sioRes.sios ?? []) {
       if (x.concept_id && Array.isArray(x.sio)) sioByConcept[x.concept_id] = x.sio.map((item) => standardStatement(String(item)));
     }
@@ -1630,7 +1804,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
         "- CIO: HOW mechanism, technology-agnostic, more concrete than ULO, Marr 2-Language neutral.",
         "- SIO: keyword-bound completable implementation tasks naming real constructs of " + techStack + ".",
         "- BINDING RULE: every SIO item must contain at least one of the concept's listed keywords VERBATIM (copy the exact keyword text into the sentence).",
-        "- COMPLETABILITY RULE: every SIO item must contain an actionable verb (build, create, implement, write, configure, parse, validate, handle, store, load, run, read, fetch, display, generate, format, convert, test, debug, trace, measure, design, structure, select, filter, sort, map, reduce, catch, throw, migrate, deploy, query, index, cache, stream, inspect) or wrap a concrete construct in backticks \u2014 abstract verbs (understand, learn, know, grasp, explore, appreciate) always fail.",
+        "- COMPLETABILITY RULE: every SIO item must contain an actionable verb (" + ["build", "create", "update", "inject", "compose", "pass", "modify", "use"].join(", ") + " ...full registry in the SIO authoring step) or wrap a concrete construct in backticks \u2014 abstract verbs (understand, learn, know, grasp, explore, appreciate) always fail.",
         "",
         JSON_ONLY
       ].join("\n");
@@ -1678,7 +1852,7 @@ async function authorDepthLayersHierarchically(client, concepts, techStack, warn
       "Depth-layer contract audit failed after repair for: " + detail + " \u2014 regenerate or fix the prompt contract (fail-closed, no silent fallback)"
     );
   }
-  return { uloByConcept, cioByConcept, sioByConcept, audits, warnings };
+  return { uloByConcept, cioByConcept, sioByConcept, audits, warnings, lastTransport: audits[0]?.transport };
 }
 function cell(v) {
   return (v || "").split(",").map((s) => s.trim()).filter(Boolean);
@@ -1730,7 +1904,7 @@ function loadKnowledgeTreeCatalog(tsvPath) {
 }
 function tokens(s) {
   return new Set(
-    s.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4)
+    stripDiacritics(s).replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4)
   );
 }
 function filterBySelection(catalog, selectedCategories, selectedTopics, analysisConcepts, maxConcepts = 120) {
@@ -1821,7 +1995,7 @@ async function standardizeConcepts(opts) {
     "     Adopt the tree's terminology. Only propose new when the tree genuinely has NO concept teaching that knowledge (broader AND narrower both fail).",
     '  2. "proposed_new" - no tree concept covers it at the same granularity. Propose an UPPER_SNAKE_CASE code (descriptive, stable, max 5 words) and a one-sentence definition.',
     "     If between 1 and 3 tree concepts are CLOSE but not exact, list their codes in possible_tree_matches for human review.",
-    `For a "standardized" decision ALSO return "adopted_keywords": the subset of that tree concept's keywords (from the shortlist) that make sense for the course TECH STACK. Drop keywords that name tooling from other ecosystems (e.g. JS test runners for a Python course) \u2014 keep conceptual keywords even when spelled generically. Maximum 8, ordered most-relevant first.`,
+    `For a "standardized" decision ALSO return "adopted_keywords": copy VERBATIM from that tree concept's keyword list in the shortlist (exact tokens, do not re-spell, singularize or translate). Pick the subset that makes sense for the course TECH STACK; if none fit, return an EMPTY array \u2014 never invent a keyword. Maximum 8, ordered most-relevant first.`,
     "Rules:",
     "- Judge by MEANING (definition + keywords), not by string similarity.",
     '- COVERAGE RULE: a "standardized" match must cover ALL primary dimensions of the input concept \u2014 every distinct aspect named in its title or description. A tree concept covering only ONE of several aspects (e.g. "interpreting error messages" for a concept about error handling AND user experience) is a PARTIAL match: decide "proposed_new" and list that tree code in possible_tree_matches.',
@@ -1861,10 +2035,25 @@ async function standardizeConcepts(opts) {
       const tc = catalog.concepts.find((x) => x.code === d.tree_code);
       if (!tc) throw new Error("Concept " + c.id + " standardized to unknown tree code " + d.tree_code + " \u2014 fail-closed");
       const treeKw = new Set(tc.keywords.map((k) => k.toLowerCase()));
-      const adopted = (d.adopted_keywords || []).map((k) => String(k)).filter((k) => {
-        if (treeKw.has(k.toLowerCase())) return true;
-        throw new Error("Concept " + c.id + ' adopted keyword "' + k + '" not in tree concept ' + tc.code + " \u2014 fail-closed");
-      });
+      const rawAdopted = (d.adopted_keywords || []).map((k) => String(k)).filter(Boolean);
+      let adopted;
+      if (tc.keywords.length === 0) {
+        adopted = rawAdopted.filter((k) => (c.keywords ?? []).some((ck) => ck.toLowerCase() === k.toLowerCase()));
+        if (adopted.length === 0) adopted = (c.keywords ?? []).slice(0, 8);
+        warnings.push("Concept " + c.id + ": tree concept " + tc.code + " has no keyword registry \u2014 adopted " + adopted.length + " keyword(s) from the analysis concept");
+      } else {
+        const norm = (k) => k.toLowerCase().replace(/ies$/, "y").replace(/s$/, "");
+        const treeKwNorm = new Set([...treeKw].map(norm));
+        const dropped = [];
+        adopted = rawAdopted.filter((k) => {
+          if (treeKw.has(k.toLowerCase()) || treeKwNorm.has(norm(k))) return true;
+          dropped.push(k);
+          return false;
+        });
+        if (dropped.length > 0) {
+          warnings.push("Concept " + c.id + ": dropped " + dropped.length + " adopted keyword(s) not in tree concept " + tc.code + " registry: " + dropped.join(", "));
+        }
+      }
       if (tc.keywords.length > 0 && adopted.length === 0) {
         throw new Error("Concept " + c.id + " standardized to " + tc.code + " without adopted_keywords \u2014 fail-closed");
       }
@@ -1904,6 +2093,15 @@ async function standardizeConcepts(opts) {
 }
 
 // src/graph/knowledgeGraphPipeline.ts
+var MIN_CALIBRATION_MINUTES = 15;
+var MAX_CALIBRATION_MINUTES = 60;
+var DEFAULT_CONCEPT_MINUTES = 30;
+var MIN_CALIBRATION_DIVERGENCE = 0.5;
+function calibrateConceptMinutes(sioCount, problemTypeCount, prereqCount, hasHighBloom) {
+  const ratio = (value, cap) => Math.min(1, Math.max(0, value) / cap);
+  const score = 0.3 * ratio(sioCount, 4) + 0.25 * ratio(problemTypeCount, 4) + 0.2 * ratio(prereqCount, 4) + 0.25 * (hasHighBloom ? 1 : 0);
+  return Math.round(MIN_CALIBRATION_MINUTES + score * (MAX_CALIBRATION_MINUTES - MIN_CALIBRATION_MINUTES));
+}
 function topologicalSort(concepts) {
   const inDegree = /* @__PURE__ */ new Map();
   const adjacency = /* @__PURE__ */ new Map();
@@ -1950,7 +2148,7 @@ async function generateKnowledgeGraph(options) {
     log("STEP_1", `Parsed syllabus: ${parsedSyllabus.units.length} units, ${parsedSyllabus.allTopics.length} topics`);
   }
   const client = createLlmClient(llmConfig);
-  const maxSyllabusChars = parseInt(process.env.KG_MAX_SYLLABUS_CHARS || "16000", 10);
+  const maxSyllabusChars = parseInt(process.env.KG_MAX_SYLLABUS_CHARS || "32000", 10);
   let truncatedSyllabus = "";
   if (syllabusText) {
     if (syllabusText.length > maxSyllabusChars) {
@@ -2069,7 +2267,7 @@ Return JSON:
   }
   {
     const STOP = /* @__PURE__ */ new Set(["and", "the", "for", "with", "from", "that", "this", "into", "when", "while", "using", "their", "your", "each", "how", "why", "what", "between", "through", "about"]);
-    const tokensFrom = (text) => text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4 && !STOP.has(w));
+    const tokensFrom = (text) => stripDiacritics(text).replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4 && !STOP.has(w));
     for (const c of concepts) {
       const existing = (c.keywords || []).map((k) => String(k).trim()).filter(Boolean);
       if (existing.length === 0) {
@@ -2140,23 +2338,32 @@ Return JSON:
       }
     }
     const idByTreeCode = new Map(concepts.filter((c) => c.tree_code).map((c) => [c.tree_code, c.id]));
+    const unmappedTreePrereqs = /* @__PURE__ */ new Set();
     for (const c of concepts) {
       for (const tp of c.tree_prerequisites || []) {
         const target = idByTreeCode.get(tp);
         if (target && target !== c.id && !(c.prerequisites || []).includes(target)) {
           c.prerequisites = [...c.prerequisites || [], target];
           warnings.push("Prereq seeded from tree: " + c.id + " <- " + tp + " (" + target + ")");
+        } else if (!target) {
+          unmappedTreePrereqs.add(tp);
         }
       }
     }
+    if (unmappedTreePrereqs.size > 0) {
+      const shown = [...unmappedTreePrereqs].slice(0, 10).join(", ");
+      warnings.push("Tree prereqs outside THIS analysis (no edge seeded, " + unmappedTreePrereqs.size + " codes): " + shown + (unmappedTreePrereqs.size > 10 ? ", ..." : ""));
+    }
     log("STEP_2_5", "Standardized: " + std.decisions.filter((d) => d.decision === "standardized").length + ", proposed new: " + std.decisions.filter((d) => d.decision === "proposed_new").length);
+  } else {
+    warnings.push("No knowledgeTreePath provided \u2014 concepts are NOT standardized against the knowledge tree (all proposed_new)");
   }
   log("STEP_3", "Checking for prerequisite cycles...");
   const cycles = detectPrerequisiteCycles(concepts);
   if (cycles.length > 0) {
     log("STEP_3", `Found ${cycles.length} cycle(s) in prerequisite chain \u2014 breaking cycles`);
     for (const cycle of cycles) {
-      warnings.push(`Cycle detected: ${cycle.join(" \u2192 ")} \u2014 breaking at weakest edge`);
+      warnings.push(`Cycle detected: ${cycle.join(" \u2192 ")} \u2014 removing the closing back-edge (last DFS edge; pedagogically arbitrary)`);
     }
     const { fixed, removed } = breakPrerequisiteCycles(concepts, cycles);
     for (let i = 0; i < concepts.length; i++) {
@@ -2237,14 +2444,11 @@ Return JSON:
       const hasHighBloom = (concept.problem_types || []).some(
         (pt) => ["Analyze", "Evaluate", "Create"].includes(pt.bloom_level || "")
       );
-      const score = Math.min(1, sioCount * 0.2 + ptCount * 0.15 + prereqCount * 0.15 + (hasHighBloom ? 0.2 : 0));
-      const calibrated = Math.round(15 + score * 45);
-      const llmEstimate = concept.estimated_minutes || 30;
-      if (llmEstimate === 30 || Math.abs(calibrated - llmEstimate) / llmEstimate > 0.5) {
+      const calibrated = calibrateConceptMinutes(sioCount, ptCount, prereqCount, hasHighBloom);
+      const llmEstimate = concept.estimated_minutes || DEFAULT_CONCEPT_MINUTES;
+      if (Math.abs(calibrated - llmEstimate) / llmEstimate > MIN_CALIBRATION_DIVERGENCE) {
         concept.estimated_minutes = calibrated;
-        if (llmEstimate !== calibrated) {
-          warnings.push("Concept " + concept.id + ": minutes calibrated " + llmEstimate + "m \u2192 " + calibrated + "m (score=" + score.toFixed(2) + ")");
-        }
+        warnings.push("Concept " + concept.id + ": minutes calibrated " + llmEstimate + "m \u2192 " + calibrated + "m");
       }
     }
     log("STEP_5c", "Minute calibration complete");
@@ -2269,7 +2473,8 @@ Return JSON:
   return {
     knowledgeGraph: verifiedGraph,
     warnings,
-    verificationReport: report
+    verificationReport: report,
+    provenance: client.callLog
   };
 }
 
@@ -2296,9 +2501,10 @@ async function generateHybridGraph(options) {
         description: "",
         total_project_minutes: 0,
         total_concept_minutes: 0,
-        estimated_total_minutes: 0
+        linked_prereq_minutes: 0
       },
-      warnings
+      warnings,
+      provenance: []
     };
   }
   const client = createLlmClient(llmConfig);
@@ -2379,9 +2585,14 @@ async function generateHybridGraph(options) {
       description: "Progressive completion path: " + phases.length + " phases, " + features.length + " features, " + concepts.length + " concepts",
       total_project_minutes: totalProjectMinutes,
       total_concept_minutes: totalConceptMinutes,
-      estimated_total_minutes: totalProjectMinutes + totalPrereqMinutes
+      // HG-1 (2026-10-05): renamed from estimated_total_minutes. It counts only
+      // concepts that HAVE a feature link (max per concept, not summed), so it
+      // is NOT the course total — see HybridGraphSchema.linked_prereq_minutes.
+      // The phase planner below commits to totalProjectMinutes + totalConceptMinutes.
+      linked_prereq_minutes: totalProjectMinutes + totalPrereqMinutes
     },
-    warnings
+    warnings,
+    provenance: client.callLog
   };
 }
 function auditPhasePlan(plan, features, concepts, links, warnings, log) {
@@ -2457,12 +2668,20 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
       } else {
         newIntroPhase.set(cid, order);
       }
+      introductions.push({ concept_id: cid, aspect, note: String(ri.note || "") });
+    }
+    for (const intro of introductions) {
+      const cid = intro.concept_id;
+      if (intro.aspect === "advanced") continue;
+      const introOrder = newIntroPhase.get(cid);
+      if (introOrder === void 0 || introOrder !== order) continue;
       for (const pre of prereqOf.get(cid) || []) {
-        if (!newIntroPhase.has(pre)) {
-          errors.push("Phase " + id + ": concept " + cid + " introduced before its prerequisite " + pre + " is introduced - violates the prerequisite chain");
+        const previewOrder = previewPhase.get(pre);
+        const covered = newIntroPhase.has(pre) || previewOrder !== void 0 && previewOrder < order;
+        if (!covered) {
+          errors.push("Phase " + id + ": concept " + cid + " introduced before its prerequisite " + pre + " is introduced (or previewed in an earlier phase) - violates the prerequisite chain");
         }
       }
-      introductions.push({ concept_id: cid, aspect, note: String(ri.note || "") });
     }
     phases.push({
       id,
@@ -2500,6 +2719,9 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
     if (anchor !== void 0 && anchor <= pOrder) {
       errors.push("Concept " + cid + " previewed in phase " + pOrder + " but fully introduced in phase " + anchor + " - preview must precede the anchor introduction");
     }
+    if (anchor === void 0) {
+      errors.push("Concept " + cid + " is previewed in phase " + pOrder + " but never fully introduced (aspect new) in any phase - a preview must have an anchor teach");
+    }
   }
   return { phases, errors };
 }