@thanh01.pmt/domain-kit 0.1.0

package/dist/chunk-MOKNFLUD.mjs

@@ -0,0 +1,851 @@
+// src/utils/llmClient.ts
+var LlmClientError = class extends Error {
+  constructor(message, status, cause) {
+    super(message);
+    this.status = status;
+    this.cause = cause;
+    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");
+  push("openrouter", "https://openrouter.ai/api/v1", process.env.OPENROUTER_API_KEY || "", process.env.OPENROUTER_MODEL || "nvidia/nemotron-3-ultra-550b-a55b");
+  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;
+}
+var MIN_REQUEST_INTERVAL_MS = 2500;
+var lastRequestAt = 0;
+async function pacedDelay() {
+  const wait = lastRequestAt + MIN_REQUEST_INTERVAL_MS - Date.now();
+  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+  lastRequestAt = Date.now();
+}
+function createLlmClient(config) {
+  const chain = resolveProviderChain(config);
+  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."
+    );
+  }
+  primary.apiKey;
+  primary.baseUrl;
+  const model = primary.model;
+  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);
+    const attempts = [];
+    let lastError = null;
+    const TRANSIENT = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+    const REQUEST_TIMEOUT_MS = Number(process.env.LLM_REQUEST_TIMEOUT_MS || 3e5);
+    const MAX_CHAIN_ROUNDS = 3;
+    for (let round = 1; round <= MAX_CHAIN_ROUNDS; round++) {
+      if (round > 1) {
+        attempts.push("round " + (round - 1) + " failed \u2014 backing off 20s before rewalking the chain");
+        await new Promise((resolve) => setTimeout(resolve, 2e4));
+      }
+      for (const provider of chain) {
+        try {
+          const headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${provider.apiKey}`
+          };
+          const payload = {
+            model: provider.model,
+            messages,
+            temperature,
+            max_tokens: maxTokens
+          };
+          await pacedDelay();
+          const doFetch = () => fetch(`${provider.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "Authorization": `Bearer ${provider.apiKey}`
+            },
+            body: JSON.stringify({
+              model: provider.model,
+              messages,
+              temperature,
+              max_tokens: maxTokens
+            }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+          });
+          let response;
+          try {
+            response = await doFetch();
+          } catch (netErr) {
+            attempts.push(`${provider.label}: network error (${netErr instanceof Error ? netErr.message : String(netErr)}) \u2014 retrying once`);
+            await new Promise((r) => setTimeout(r, 5e3));
+            lastRequestAt = Date.now();
+            response = await doFetch();
+          }
+          if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            const err = new LlmClientError(
+              `[${provider.label}] LLM API error: ${response.status} ${response.statusText} \u2014 ${body.slice(0, 200)}`,
+              response.status
+            );
+            if (response.status === 429) {
+              const retryAfterRaw = response.headers.get("retry-after");
+              const retryAfterMs = Math.min(
+                6e4,
+                Math.max(15e3, (Number.isFinite(Number(retryAfterRaw)) ? Number(retryAfterRaw) : 20) * 1e3)
+              );
+              attempts.push(`${provider.label}: 429 rate-limited \u2014 backing off ${Math.round(retryAfterMs / 1e3)}s`);
+              await new Promise((resolve) => setTimeout(resolve, retryAfterMs));
+              lastRequestAt = Date.now();
+              const retry = await fetch(`${provider.baseUrl}/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+              });
+              if (!retry.ok) throw err;
+              const retryData = await retry.json();
+              const retryContent2 = retryData.choices?.[0]?.message?.content || "";
+              if (!retryContent2.trim()) throw err;
+              return {
+                content: retryContent2,
+                model: retryData.model || provider.model,
+                provider: provider.label,
+                attempts: attempts.slice(),
+                usage: retryData.usage,
+                finishReason: retryData.choices?.[0]?.finish_reason
+              };
+            }
+            if (TRANSIENT.has(response.status)) {
+              await new Promise((r) => setTimeout(r, 3e3));
+              const retry = await fetch(`${provider.baseUrl}/chat/completions`, {
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                method: "POST",
+                headers: {
+                  "Content-Type": "application/json",
+                  "Authorization": `Bearer ${provider.apiKey}`
+                },
+                body: JSON.stringify({
+                  model: provider.model,
+                  messages,
+                  temperature,
+                  max_tokens: maxTokens
+                })
+              });
+              if (!retry.ok) throw err;
+              const retryData = await retry.json();
+              const retryContent = retryData.choices?.[0]?.message?.content || "";
+              return {
+                content: retryContent,
+                model: retryData.model || provider.model,
+                provider: provider.label,
+                attempts: attempts.slice(),
+                usage: retryData.usage,
+                finishReason: retryData.choices?.[0]?.finish_reason
+              };
+            }
+            throw err;
+          }
+          const data = await response.json();
+          const wrappedError = data.error;
+          if (wrappedError) {
+            throw new LlmClientError("[" + provider.label + "] upstream error " + (wrappedError.code ?? "") + ": " + (wrappedError.message ?? "unknown"));
+          }
+          const content = data.choices?.[0]?.message?.content || "";
+          if (!content.trim()) {
+            throw new LlmClientError("[" + provider.label + "] empty completion returned");
+          }
+          return {
+            content,
+            model: data.model || provider.model,
+            provider: provider.label,
+            attempts: attempts.slice(),
+            usage: data.usage,
+            finishReason: data.choices?.[0]?.finish_reason
+          };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          attempts.push(`${provider.label}: ${msg}`);
+          lastError = err instanceof LlmClientError ? err : new LlmClientError(`[${provider.label}] ${msg}`);
+        }
+      }
+      if (round < MAX_CHAIN_ROUNDS) continue;
+      throw lastError ?? new LlmClientError("All LLM providers failed (empty chain).");
+    }
+    throw lastError ?? new LlmClientError("All LLM providers failed after " + MAX_CHAIN_ROUNDS + " rounds.");
+  }
+  return { chat, model };
+}
+function parseJsonFromLlm(text) {
+  let cleaned = text.trim();
+  if (cleaned.startsWith("```json")) {
+    cleaned = cleaned.slice(7);
+  } else if (cleaned.startsWith("```")) {
+    cleaned = cleaned.slice(3);
+  }
+  if (cleaned.endsWith("```")) {
+    cleaned = cleaned.slice(0, -3);
+  }
+  cleaned = cleaned.trim();
+  try {
+    return JSON.parse(cleaned);
+  } catch {
+    const start = cleaned.indexOf("{");
+    if (start >= 0) {
+      let depth = 0;
+      let inString = false;
+      let escape = false;
+      for (let i = start; i < cleaned.length; i++) {
+        const ch = cleaned[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) {
+            try {
+              return JSON.parse(cleaned.slice(start, i + 1));
+            } catch {
+            }
+          }
+        }
+      }
+    }
+    throw new LlmClientError(`Failed to parse JSON from LLM response: ${cleaned.slice(0, 200)}`);
+  }
+}
+async function llmChatJson(client, systemPrompt, userPrompt, options) {
+  const result = await client.chat(
+    [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: userPrompt }
+    ],
+    options
+  );
+  return parseJsonFromLlm(result.content);
+}
+
+// src/graph/scaffoldExtractor.ts
+async function extractScaffold(options) {
+  const { goal, techStack, fileList, llmConfig } = options;
+  const client = 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}
+Tech stack: ${techStack}
+
+PROJECT FILE LIST (base-project):
+${fileListStr}
+
+Return JSON:
+{
+  "feature": {
+    "id": "F0",
+    "name": "FOUNDATION & SETUP",
+    "description": "Get familiar with the tools, create/clone the project, learn minimal knowledge and the repo map",
+    "platform": "app",
+    "steps": [
+      {
+        "id": "F0-S1",
+        "sequence": 1,
+        "name": "Action step name",
+        "description": "Detailed description of the concrete actions",
+        "files": [],
+        "api_usage": [],
+        "keywords": ["Xcode", "Terminal"],
+        "completion_level": "base",
+        "intent": "Learn how to setup the IDE and run a minimal Swift app",
+        "outcome": {"user_visible": "App builds and runs", "technical": "Toolchain verified"},
+        "acceptance": ["Xcode builds without errors", "Simulator launches successfully"],
+        "effort": {"estimated_minutes": 20, "complexity": "low"}
+      }
+    ]
+  }
+}
+`;
+  try {
+    const result = await llmChatJson(client, systemPrompt, userPrompt, {
+      temperature: 0.1,
+      maxTokens: parseInt(process.env.PG_C0_MAX_TOKENS || "16384", 10)
+    });
+    const feat = result.feature;
+    if (!feat || !Array.isArray(feat.steps) || feat.steps.length === 0) {
+      console.warn("[WARN] Scaffold LLM returned no steps \u2014 skipping F0");
+      return null;
+    }
+    const steps = feat.steps.map((s, i) => ({
+      id: `F0-S${i + 1}`,
+      sequence: i + 1,
+      name: String(s.name || `Step ${i + 1}`),
+      description: String(s.description || ""),
+      files: Array.isArray(s.files) ? s.files : [],
+      api_usage: Array.isArray(s.api_usage) ? s.api_usage : [],
+      keywords: Array.isArray(s.keywords) ? s.keywords : [],
+      completion_level: "base",
+      platform: String(s.platform || "app"),
+      intent: String(s.intent || ""),
+      outcome: s.outcome && typeof s.outcome === "object" ? s.outcome : void 0,
+      acceptance: Array.isArray(s.acceptance) ? s.acceptance : [],
+      effort: s.effort && typeof s.effort === "object" ? s.effort : void 0,
+      requirement_ids: [],
+      concept_codes: []
+    }));
+    return {
+      id: "F0",
+      name: String(feat.name || "FOUNDATION & SETUP"),
+      description: String(feat.description || ""),
+      platform: String(feat.platform || "app"),
+      steps
+    };
+  } catch (err) {
+    console.error(`[ERROR] extractScaffold failed: ${err}`);
+    return null;
+  }
+}
+
+// src/graph/overviewExtractor.ts
+function buildSourceText(fileContentsMap) {
+  const blocks = [];
+  for (const [relPath, content] of fileContentsMap) {
+    blocks.push(`### FILE: ${relPath}
+${content}`);
+  }
+  return blocks.join("\n\n");
+}
+async function extractProjectOverview(options) {
+  const { goal, techStack, sdkApiIndex, fileContentsMap, astKeywords, llmConfig } = options;
+  const client = 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 = "";
+  if (astKeywords && astKeywords.length > 0) {
+    const kwItems = astKeywords.slice(0, 30).map(
+      (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";
+    }
+  }
+  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.";
+  const userPrompt = `App goal: ${goal}
+Tech stack: ${techStack}
+${keywordsAnchor}
+Filtered SDK API list (used_in_demo):
+${JSON.stringify(usedSdkApis, null, 0)}
+
+Source code of the files:
+${allFilesStr}
+
+Return JSON per the schema:
+{
+  "schema_version": 2,
+  "project": {"name": "...", "project_type": "app", "platforms": ["ios"]},
+  "product": {
+    "purpose": "END-USER problem being solved",
+    "problem_statement": "Core user problem",
+    "primary_users": ["who the main users are"],
+    "development_stages": [
+      {
+        "stage": "Stage 1: Foundation & Setup",
+        "need": ["Core app shell"],
+        "learn": ["App lifecycle, basic UI"],
+        "product_state": "App launches with static mock data",
+        "temporary_approach": "Hardcoded array",
+        "validation": "Main screen loads"
+      }
+    ],
+    "features": [
+      {"id": "F1", "name": "Feature name", "description": "Feature description", "platform": "ios"}
+    ],
+    "user_journeys": [{"name": "...", "feature_ids": ["F1"]}]
+  },
+  "architecture": {"layers": [], "services": [], "state_management": "..."},
+  "decomposition": {"milestones": [{"id": "M1", "phase": "MVP", "name": "...", "goal": "...", "feature_ids": ["F1"]}]}
+}`;
+  const result = await llmChatJson(client, systemPrompt, userPrompt, {
+    temperature: 0.1,
+    maxTokens: parseInt(process.env.PG_C1_MAX_TOKENS || "32768", 10)
+  });
+  const prod = result.product;
+  if (prod && !Array.isArray(prod.development_stages)) {
+    prod.development_stages = [];
+  }
+  return result;
+}
+
+// src/graph/stepExtractor.ts
+function buildSourceText2(fileContentsMap) {
+  const blocks = [];
+  for (const [relPath, content] of fileContentsMap) {
+    blocks.push(`### FILE: ${relPath}
+${content}`);
+  }
+  return blocks.join("\n\n");
+}
+async function extractFeatureSteps(options) {
+  const { goal, techStack, sdkApiIndex, fileContentsMap, feature, llmConfig } = options;
+  const client = 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";
+  const fname = feature.name || fid;
+  const fdesc = feature.description || "";
+  const systemPrompt = "You are a software architect. Split ONE feature into ACTION steps (implementation steps) the learner must code sequentially. Each step must carry files[] (CORRECT paths in the source), api_usage[] (only from the provided SDK API index), keywords[] (real terms/language features in the files), and completion_level \u2208 {base, mvp, extend, polish}.\n  - base = foundation/setup\n  - mvp = make the app minimally WORKING for this feature\n  - extend = make it real/richer\n  - polish = robustness (error handling, tests, validation)\nInclude metadata: intent, outcome ({user_visible, technical}), acceptance[] (2 verifiable criteria), effort ({estimated_minutes, complexity}).\ndescription: ONE concise sentence, MAX 140 characters. NEVER invent files/APIs. Return ONLY the steps array. ALL text must be in ENGLISH.";
+  const userPrompt = `App goal: ${goal}
+Tech stack: ${techStack}
+
+FEATURE TO SPLIT: ${fid} \u2014 ${fname}
+Feature description: ${fdesc}
+
+SDK API list (used_in_demo):
+${JSON.stringify(usedSdkApis)}
+
+Source code:
+${allFilesStr}
+
+Split this feature into 2-6 action steps. Return JSON:
+{
+  "steps": [
+    {
+      "id": "${fid}-S1",
+      "sequence": 1,
+      "name": "Action step name",
+      "description": "One concise sentence (max 140 chars)",
+      "files": ["path/to/file.swift"],
+      "api_usage": ["ChatClient"],
+      "keywords": ["@State", "NavigationStack"],
+      "completion_level": "mvp",
+      "intent": "Create reactive state container",
+      "outcome": {"user_visible": "Chat view updates", "technical": "ChatViewModel conforms to ObservableObject"},
+      "acceptance": ["ViewModel publishes messages", "UI re-renders on state mutation"],
+      "effort": {"estimated_minutes": 30, "complexity": "medium"}
+    }
+  ]
+}`;
+  const result = await llmChatJson(client, systemPrompt, userPrompt, {
+    temperature: 0.1,
+    maxTokens: parseInt(process.env.PG_C2_MAX_TOKENS || "32768", 10)
+  });
+  const rawSteps = result.steps || [];
+  const clampedSteps = rawSteps.length > 6 ? rawSteps.slice(0, 6) : rawSteps.length < 2 && rawSteps.length > 0 ? rawSteps : rawSteps;
+  if (rawSteps.length > 6) {
+    console.warn(`[WARN] LLM returned ${rawSteps.length} steps for ${fid}, clamped to 6`);
+  } else if (rawSteps.length === 0) {
+    console.warn(`[WARN] LLM returned 0 steps for ${fid}`);
+  }
+  return clampedSteps.map((s, i) => ({
+    id: `${fid}-S${i + 1}`,
+    sequence: i + 1,
+    name: String(s.name || `Step ${i + 1}`),
+    description: String(s.description || ""),
+    files: Array.isArray(s.files) ? s.files : [],
+    api_usage: Array.isArray(s.api_usage) ? s.api_usage : [],
+    keywords: Array.isArray(s.keywords) ? s.keywords : [],
+    completion_level: String(s.completion_level || "mvp"),
+    platform: String(s.platform || feature.platform || "app"),
+    intent: String(s.intent || ""),
+    outcome: s.outcome,
+    acceptance: Array.isArray(s.acceptance) ? s.acceptance : [],
+    effort: s.effort,
+    requirement_ids: [],
+    concept_codes: []
+  }));
+}
+async function extractFeatureStepsBatched(goal, techStack, sdkApiIndex, fileContentsMap, featuresMeta, llmConfig) {
+  const client = 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(
+    (f) => `- ${f.id || "F?"}: ${f.name || ""} \u2014 ${f.description || ""}`
+  ).join("\n");
+  const systemPrompt = "You are a software architect. Split MULTIPLE features into ACTION steps. Each step must carry files[], api_usage[], keywords[], and completion_level \u2208 {base, mvp, extend, polish}. Include metadata: intent, outcome ({user_visible, technical}), acceptance[] (2 verifiable criteria), effort ({estimated_minutes, complexity}). description: ONE concise sentence, MAX 140 characters. NEVER invent files/APIs. Return ONLY the JSON. ALL text must be in ENGLISH.";
+  const userPrompt = `App goal: ${goal}
+Tech stack: ${techStack}
+
+SDK API list (used_in_demo):
+${JSON.stringify(usedSdkApis)}
+
+Source code:
+${sourceText}
+
+FEATURES to split into steps:
+${featuresListing}
+
+For EACH feature above, produce 4-6 action steps. Each step must include:
+id, sequence, name, description, files, api_usage, keywords, completion_level, platform,
+intent, outcome ({user_visible, technical}), acceptance[] (2 criteria), effort ({estimated_minutes, complexity}).
+
+Return JSON with a "steps" dict keyed by feature_id:
+{
+  "steps": {
+    "<feature_id>": [
+      {
+        "id": "<feature_id>-S1",
+        "sequence": 1,
+        "name": "Step name",
+        "description": "Concise sentence (max 140 chars)",
+        "files": ["path/to/file"],
+        "api_usage": ["APIName"],
+        "keywords": ["keyword"],
+        "completion_level": "mvp",
+        "platform": "app",
+        "intent": "Step intent",
+        "outcome": {"user_visible": "User visible result", "technical": "Technical result"},
+        "acceptance": ["Criterion 1", "Criterion 2"],
+        "effort": {"estimated_minutes": 30, "complexity": "medium"}
+      }
+    ]
+  }
+}`;
+  const result = await llmChatJson(client, systemPrompt, userPrompt, {
+    temperature: 0.1,
+    maxTokens: parseInt(process.env.PG_C2_MAX_TOKENS || "32768", 10)
+  });
+  const stepsDict = result.steps;
+  const output = /* @__PURE__ */ new Map();
+  if (stepsDict && typeof stepsDict === "object") {
+    for (const [fid, rawSteps] of Object.entries(stepsDict)) {
+      if (!Array.isArray(rawSteps)) continue;
+      const featMeta = featuresMeta.find((f) => f.id === fid);
+      const steps = rawSteps.map((s, i) => ({
+        id: `${fid}-S${i + 1}`,
+        sequence: i + 1,
+        name: String(s.name || `Step ${i + 1}`),
+        description: String(s.description || ""),
+        files: Array.isArray(s.files) ? s.files : [],
+        api_usage: Array.isArray(s.api_usage) ? s.api_usage : [],
+        keywords: Array.isArray(s.keywords) ? s.keywords : [],
+        completion_level: String(s.completion_level || "mvp"),
+        platform: String(s.platform || featMeta?.platform || "app"),
+        intent: String(s.intent || ""),
+        outcome: s.outcome,
+        acceptance: Array.isArray(s.acceptance) ? s.acceptance : [],
+        effort: s.effort,
+        requirement_ids: [],
+        concept_codes: []
+      }));
+      output.set(fid, steps);
+    }
+  }
+  return output;
+}
+
+// src/graph/graphVerifier.ts
+function verifyProjectGraph(projectGraph, options) {
+  const { sdkApiIndex, fileContentsMap } = options;
+  const sdkApiNames = new Set(sdkApiIndex.sdk_apis.map((api) => api.name));
+  const hallucinations = [];
+  const features = projectGraph.features || [];
+  for (const feature of features) {
+    const fid = feature.id || "F_UNK";
+    const isFoundation = fid === "F0";
+    for (const step of feature.steps || []) {
+      const sid = step.id || `${fid}-SUNK`;
+      const validFiles = [];
+      for (const f of step.files || []) {
+        if (fileContentsMap.has(f)) {
+          validFiles.push(f);
+        } else {
+          hallucinations.push({
+            type: "file",
+            item: f,
+            feature_id: fid,
+            step_id: sid,
+            reason: `File '${f}' not found in repository`
+          });
+        }
+      }
+      step.files = validFiles;
+      const validApis = [];
+      for (const api of step.api_usage || []) {
+        if (sdkApiNames.size === 0 || sdkApiNames.has(api)) {
+          validApis.push(api);
+        } else {
+          hallucinations.push({
+            type: "api",
+            item: api,
+            feature_id: fid,
+            step_id: sid,
+            reason: `API '${api}' not found in SDK API index`
+          });
+        }
+      }
+      step.api_usage = validApis;
+      if (isFoundation) continue;
+      const validKws = [];
+      for (const kw of step.keywords || []) {
+        const kwLow = kw.toLowerCase();
+        const isSingleWord = !kwLow.includes(" ");
+        let found = false;
+        for (const f of validFiles) {
+          const content = (fileContentsMap.get(f) || "").toLowerCase();
+          if (isSingleWord) {
+            found = new RegExp(`\\b${kwLow.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(content);
+          } else {
+            found = content.includes(kwLow);
+          }
+          if (found) break;
+        }
+        if (!found) {
+          for (const content of fileContentsMap.values()) {
+            const lc = content.toLowerCase();
+            if (isSingleWord) {
+              found = new RegExp(`\\b${kwLow.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(lc);
+            } else {
+              found = lc.includes(kwLow);
+            }
+            if (found) break;
+          }
+        }
+        if (found) {
+          validKws.push(kw);
+        } else {
+          hallucinations.push({
+            type: "keyword",
+            item: kw,
+            feature_id: fid,
+            step_id: sid,
+            reason: `Keyword '${kw}' not found in target files`
+          });
+        }
+      }
+      step.keywords = validKws;
+    }
+  }
+  return { graph: projectGraph, hallucinations };
+}
+
+// src/graph/conceptEscalator.ts
+function toUpperSnake(term) {
+  let s = term.replace(/^[^\w]+/, "");
+  s = s.replace(/([a-z0-9])([A-Z])/g, "$1_$2");
+  s = s.replace(/[^\w]+/g, "_");
+  const res = s.toUpperCase().replace(/^_+|_+$/g, "");
+  return res || "CONCEPT";
+}
+function extractTermSnippets(term, fileContentsMap, maxSnippets = 1) {
+  const snippets = [];
+  const termLow = term.toLowerCase();
+  for (const [relPath, content] of fileContentsMap) {
+    const lines = content.split("\n");
+    for (let idx = 0; idx < lines.length; idx++) {
+      if (lines[idx].toLowerCase().includes(termLow)) {
+        const start = Math.max(0, idx - 1);
+        const end = Math.min(lines.length, idx + 2);
+        let snippet = lines.slice(start, end).map((l) => l.trim()).filter(Boolean).join(" ");
+        if (snippet.length > 120) snippet = snippet.slice(0, 120) + "...";
+        if (snippet) snippets.push(`[${relPath}]: ${snippet}`);
+        if (snippets.length >= maxSnippets) break;
+      }
+    }
+    if (snippets.length >= maxSnippets) break;
+  }
+  return snippets;
+}
+function inferDepthFromContext(keyword, fileContentsMap) {
+  const kw = keyword.toLowerCase();
+  const sioPatterns = [
+    /^@/,
+    // SwiftUI decorators: @State, @Binding
+    /^import\s/,
+    // Import statements
+    /\(\)$/,
+    // Function calls
+    /\.prototype/,
+    // Prototype methods
+    /^new\s/,
+    // Constructor calls
+    /^async\s/,
+    // Async keywords
+    /^await\s/
+  ];
+  if (sioPatterns.some((p) => p.test(keyword))) {
+    return { depth: "sio", rationale: `Keyword '${keyword}' is a specific API/syntax pattern` };
+  }
+  const cioPatterns = [
+    /pattern/i,
+    /protocol/i,
+    /architecture/i,
+    /lifecycle/i,
+    /observer/i,
+    /singleton/i,
+    /factory/i,
+    /delegate/i,
+    /state\s*management/i,
+    /data\s*flow/i,
+    /binding/i,
+    /mvvm/i,
+    /mvc/i,
+    /flux/i,
+    /redux/i,
+    /authentication/i,
+    /authorization/i,
+    /persistence/i,
+    /caching/i,
+    /serialization/i
+  ];
+  if (cioPatterns.some((p) => p.test(keyword))) {
+    return { depth: "cio", rationale: `Keyword '${keyword}' represents a mechanism/pattern` };
+  }
+  const uloPatterns = [
+    /design\s*thinking/i,
+    /user\s*needs/i,
+    /problem\s*statement/i,
+    /foundation/i,
+    /setup/i,
+    /overview/i,
+    /introduction/i,
+    /scaffold/i,
+    /hello\s*world/i,
+    /getting\s*started/i
+  ];
+  if (uloPatterns.some((p) => p.test(keyword))) {
+    return { depth: "ulo", rationale: `Keyword '${keyword}' is a foundational/introductory concept` };
+  }
+  for (const content of fileContentsMap.values()) {
+    const lines = content.split("\n");
+    for (const line of lines) {
+      if (line.toLowerCase().includes(kw)) {
+        if (/^(import|from|require|use |#include)/.test(line.trim())) {
+          return { depth: "sio", rationale: `Keyword '${keyword}' found in import statement` };
+        }
+        if (/^\/\/|^\/\*|^#|^-->/.test(line.trim())) {
+          return { depth: "ulo", rationale: `Keyword '${keyword}' found in comment/doc` };
+        }
+        return { depth: "sio", rationale: `Keyword '${keyword}' used in implementation code` };
+      }
+    }
+  }
+  return { depth: "sio", rationale: `Default: treating '${keyword}' as SIO (implementation-level)` };
+}
+async function escalateAndMapConcepts(options) {
+  const { projectGraph, fileContentsMap, availableConcepts, conceptMapOverride, llmConfig } = options;
+  const features = projectGraph.features || [];
+  const allTerms = /* @__PURE__ */ new Set();
+  for (const feature of features) {
+    for (const step of feature.steps || []) {
+      for (const api of step.api_usage || []) allTerms.add(api);
+      for (const kw of step.keywords || []) allTerms.add(kw);
+    }
+  }
+  if (allTerms.size === 0) return /* @__PURE__ */ new Map();
+  const termList = Array.from(allTerms).sort();
+  let llmResults = {};
+  if (conceptMapOverride) {
+    llmResults = conceptMapOverride;
+  } else {
+    try {
+      const client = createLlmClient(llmConfig);
+      const conceptBank = (availableConcepts || []).sort().join(", ") || "(empty)";
+      const termEntries = termList.map((term) => {
+        const snippets = extractTermSnippets(term, fileContentsMap);
+        return snippets.length > 0 ? `- ${term} (Usage context: ${snippets[0]})` : `- ${term}`;
+      });
+      const systemPrompt = `You are a knowledge classification expert. For each concrete keyword/API, determine:
+1. The neutral concept it belongs to (UPPER_SNAKE_CASE)
+2. The depth level: ulo | cio | sio
+
+DEPTH DEFINITIONS:
+- ulo (WHAT + WHY): The keyword introduces a concept \u2014 "what is it, why does it exist"
+  Example: In a scaffold step, "@State is SwiftUI's way of managing local view state"
+- cio (HOW): The keyword demonstrates a mechanism \u2014 "how it works"
+  Example: "@State triggers view re-render when value changes \u2014 mechanism is value-type observation"
+- sio (IMPLEMENTATION): The keyword is a concrete API/syntax used in code
+  Example: "Using @State var isActive: Bool = false in ContentView"
+
+RULES:
+1. PREFER an EXISTING concept from the CONCEPT_BANK below if the keyword is a manifestation of that concept.
+2. ONLY create a NEW concept (UPPER_SNAKE_CASE, NOT ending in _CONCEPT, NOT containing a specific technology name) when NO concept in the bank covers it.
+3. CONCEPT_BANK: ${conceptBank.slice(0, 12e3)}
+4. Depth is per-keyword-in-context, NOT per-concept. The same concept can have ULO at one step and SIO at another.
+Return JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "...", "depth": "ulo|cio|sio"}}}`;
+      const userPrompt = "Classify the following keyword/API list into neutral concepts WITH depth levels.\nCode usage context is provided to disambiguate depth:\n" + termEntries.join("\n") + '\n\nReturn JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "...", "depth": "ulo|cio|sio"}}}';
+      const result = await llmChatJson(client, systemPrompt, userPrompt, {
+        temperature: 0.1,
+        maxTokens: 16384
+      });
+      llmResults = result.results || {};
+    } catch (err) {
+      console.warn(`[WARN] Concept escalation LLM failed (${err}), using fallback depth inference`);
+    }
+  }
+  const featureConcepts = /* @__PURE__ */ new Map();
+  for (const feature of features) {
+    const fid = feature.id || "F_UNK";
+    const featureFiles = /* @__PURE__ */ new Set();
+    for (const step of feature.steps || []) {
+      for (const f of step.files || []) featureFiles.add(f);
+    }
+    const fTerms = [
+      ...feature.api_usage || [],
+      ...(feature.steps || []).flatMap((s) => [...s.api_usage || [], ...s.keywords || []])
+    ];
+    const items = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const kw of fTerms) {
+      const info = llmResults[kw] || {};
+      const cCode = info.concept_code || toUpperSnake(kw);
+      const cName = info.concept_name || kw;
+      let depth = "sio";
+      let depthRationale = "Default: SIO";
+      if (info.depth && ["ulo", "cio", "sio"].includes(info.depth)) {
+        depth = info.depth;
+        depthRationale = `LLM classified as ${depth}`;
+      } else {
+        const inferred = inferDepthFromContext(kw, fileContentsMap);
+        depth = inferred.depth;
+        depthRationale = inferred.rationale;
+      }
+      const kwKey = `${cCode}::${kw}`;
+      if (seen.has(kwKey)) continue;
+      seen.add(kwKey);
+      const evidenceFiles = [];
+      for (const f of featureFiles) {
+        const content = fileContentsMap.get(f) || "";
+        if (content.toLowerCase().includes(kw.toLowerCase())) {
+          evidenceFiles.push(f);
+        }
+      }
+      items.push({
+        concept_code: cCode,
+        concept_name: cName,
+        keyword: kw,
+        depth,
+        depth_rationale: depthRationale,
+        evidence_files: evidenceFiles
+      });
+    }
+    featureConcepts.set(fid, items);
+  }
+  return featureConcepts;
+}
+
+export { createLlmClient, escalateAndMapConcepts, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, llmChatJson, parseJsonFromLlm, verifyProjectGraph };
+//# sourceMappingURL=chunk-MOKNFLUD.mjs.map
+//# sourceMappingURL=chunk-MOKNFLUD.mjs.map