@clazic/kordoc 2.4.11 → 2.4.12

package/dist/index.cjs

@@ -71,6 +71,224 @@ var init_page_range = __esm({
   }
 });
 
+// src/logging/logger.ts
+function createLoggerFromEnv(env = process.env) {
+  const level = parseLevel(env.KORDOC_LOG_LEVEL);
+  const includeStack = env.KORDOC_LOG_STACK === "1";
+  const filePath = env.KORDOC_LOG_FILE ? (0, import_path.resolve)(env.KORDOC_LOG_FILE) : "";
+  const config = {
+    level,
+    includeStack,
+    progressSampleMs: parsePositiveInt(env.KORDOC_LOG_PROGRESS_SAMPLE_MS, 1e3),
+    basenamePaths: env.KORDOC_LOG_BASENAME_PATHS === "1",
+    textLimit: parsePositiveInt(env.KORDOC_LOG_TEXT_LIMIT, 400)
+  };
+  const consoleSink = new ConsoleLogger(config);
+  const sinks = [consoleSink];
+  if (filePath) sinks.push(new JsonlLogger(config, filePath));
+  return new CompositeLogger(config, sinks);
+}
+function generateRunId(prefix = "run") {
+  return `${prefix}_${(0, import_crypto.randomUUID)().slice(0, 8)}`;
+}
+function parseLevel(input) {
+  const v = (input || "").toLowerCase();
+  if (v === "error" || v === "warn" || v === "info" || v === "debug" || v === "trace") return v;
+  return "error";
+}
+function maskSecrets(input) {
+  return input.replace(/nvapi-[A-Za-z0-9_\-]+/g, "nvapi-***").replace(/Bearer\s+[A-Za-z0-9_\-\.]+/gi, "Bearer ***");
+}
+function sanitizeMeta(meta, cfg) {
+  const out = {};
+  for (const [k, v] of Object.entries(meta)) {
+    if (/authorization|api[_-]?key|token/i.test(k)) {
+      out[k] = "***";
+      continue;
+    }
+    if (typeof v === "string") {
+      let next = maskSecrets(v);
+      if (cfg.basenamePaths && /path|file|dir/i.test(k)) {
+        next = (0, import_path.basename)(next);
+      }
+      out[k] = limitText(next, cfg.textLimit);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+function parsePositiveInt(input, fallback) {
+  const n = Number(input);
+  if (!Number.isFinite(n) || n < 0) return fallback;
+  return Math.floor(n);
+}
+function limitText(input, maxLen) {
+  if (maxLen <= 0) return input;
+  if (input.length <= maxLen) return input;
+  return `${input.slice(0, maxLen)}...(+${input.length - maxLen})`;
+}
+var import_fs, import_promises, import_path, import_crypto, LEVEL_ORDER, BaseLogger, ConsoleLogger, JsonlLogger, CompositeLogger;
+var init_logger = __esm({
+  "src/logging/logger.ts"() {
+    "use strict";
+    import_fs = require("fs");
+    import_promises = require("fs/promises");
+    import_path = require("path");
+    import_crypto = require("crypto");
+    LEVEL_ORDER = {
+      error: 0,
+      warn: 1,
+      info: 2,
+      debug: 3,
+      trace: 4
+    };
+    BaseLogger = class _BaseLogger {
+      constructor(config, context = {}) {
+        this.config = config;
+        this.context = context;
+      }
+      static progressSeenAt = /* @__PURE__ */ new Map();
+      shouldLog(level) {
+        return LEVEL_ORDER[level] <= LEVEL_ORDER[this.config.level];
+      }
+      shouldEmitProgress(ev) {
+        if (this.config.progressSampleMs <= 0) return true;
+        if ((ev.event ?? "message") !== "progress") return true;
+        if (ev.level === "error" || ev.level === "warn") return true;
+        const key = [
+          this.context.runId ?? ev.runId ?? "no-run",
+          this.context.component ?? ev.component ?? "no-component",
+          this.context.stage ?? ev.stage ?? "unknown",
+          ev.message
+        ].join("|");
+        const now = Date.now();
+        const prev = _BaseLogger.progressSeenAt.get(key) ?? 0;
+        if (now - prev < this.config.progressSampleMs) return false;
+        _BaseLogger.progressSeenAt.set(key, now);
+        return true;
+      }
+      merge(ev) {
+        const out = {
+          ...this.context,
+          ...ev,
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          level: ev.level,
+          stage: ev.stage ?? this.context.stage ?? "unknown",
+          event: ev.event ?? "message",
+          message: ev.message
+        };
+        if (!this.config.includeStack && out.error?.stack) {
+          out.error = { ...out.error, stack: void 0 };
+        }
+        if (out.meta) out.meta = sanitizeMeta(out.meta, this.config);
+        if (out.error?.message) out.error.message = maskSecrets(out.error.message);
+        if (out.message) out.message = limitText(maskSecrets(out.message), this.config.textLimit);
+        return out;
+      }
+      child(context) {
+        return new _BaseLogger(this.config, { ...this.context, ...context });
+      }
+      withRun(runId) {
+        return this.child({ runId });
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      log(event) {
+      }
+    };
+    ConsoleLogger = class extends BaseLogger {
+      log(event) {
+        if (!this.shouldLog(event.level)) return;
+        if (!this.shouldEmitProgress(event)) return;
+        const e = this.merge(event);
+        const prefix = `[${e.ts}] [${e.level.toUpperCase()}]${e.runId ? ` [${e.runId}]` : ""}${e.stage ? ` [${e.stage}]` : ""}`;
+        const line = `${prefix} ${e.message}${e.component ? ` (${e.component})` : ""}`;
+        if (e.level === "error") {
+          process.stderr.write(line + "\n");
+          if (e.error?.stack) process.stderr.write(e.error.stack + "\n");
+        } else {
+          process.stdout.write(line + "\n");
+        }
+      }
+    };
+    JsonlLogger = class _JsonlLogger extends BaseLogger {
+      constructor(config, filePath, context = {}) {
+        super(config, context);
+        this.filePath = filePath;
+        (0, import_fs.mkdirSync)((0, import_path.dirname)(filePath), { recursive: true });
+        _JsonlLogger.ensureState(filePath);
+      }
+      static states = /* @__PURE__ */ new Map();
+      static ensureState(path) {
+        let state = _JsonlLogger.states.get(path);
+        if (!state) {
+          state = { queue: [], flushing: false };
+          _JsonlLogger.states.set(path, state);
+          const flushSync = () => {
+            const s = _JsonlLogger.states.get(path);
+            if (!s || s.queue.length === 0) return;
+            const payload = s.queue.join("");
+            s.queue = [];
+            if (!payload) return;
+            (0, import_fs.appendFileSync)(path, payload, "utf-8");
+          };
+          process.on("beforeExit", flushSync);
+          process.on("exit", flushSync);
+        }
+        return state;
+      }
+      scheduleFlush(path) {
+        const state = _JsonlLogger.ensureState(path);
+        if (state.timer || state.flushing) return;
+        state.timer = setTimeout(() => {
+          state.timer = void 0;
+          void this.flush(path);
+        }, 200);
+      }
+      async flush(path) {
+        const state = _JsonlLogger.ensureState(path);
+        if (state.flushing) return;
+        if (state.queue.length === 0) return;
+        state.flushing = true;
+        const payload = state.queue.join("");
+        state.queue = [];
+        try {
+          await (0, import_promises.appendFile)(path, payload, "utf-8");
+        } finally {
+          state.flushing = false;
+          if (state.queue.length > 0) this.scheduleFlush(path);
+        }
+      }
+      log(event) {
+        if (!this.shouldLog(event.level)) return;
+        if (!this.shouldEmitProgress(event)) return;
+        const e = this.merge(event);
+        const state = _JsonlLogger.ensureState(this.filePath);
+        state.queue.push(JSON.stringify(e) + "\n");
+        this.scheduleFlush(this.filePath);
+      }
+      child(context) {
+        return new _JsonlLogger(this.config, this.filePath, { ...this.context, ...context });
+      }
+    };
+    CompositeLogger = class _CompositeLogger extends BaseLogger {
+      constructor(config, sinks, context = {}) {
+        super(config, context);
+        this.sinks = sinks;
+      }
+      log(event) {
+        if (!this.shouldLog(event.level)) return;
+        if (!this.shouldEmitProgress(event)) return;
+        for (const sink of this.sinks) sink.log(event);
+      }
+      child(context) {
+        const nextSinks = this.sinks.map((s) => s.child(context));
+        return new _CompositeLogger(this.config, nextSinks, { ...this.context, ...context });
+      }
+    };
+  }
+});
+
 // node_modules/cfb/cfb.js
 var require_cfb = __commonJS({
   "node_modules/cfb/cfb.js"(exports2, module2) {
@@ -390,8 +608,8 @@ var require_cfb = __commonJS({
         }
         return L.length - R.length;
       }
-      function dirname(p) {
-        if (p.charAt(p.length - 1) == "/") return p.slice(0, -1).indexOf("/") === -1 ? p : dirname(p.slice(0, -1));
+      function dirname4(p) {
+        if (p.charAt(p.length - 1) == "/") return p.slice(0, -1).indexOf("/") === -1 ? p : dirname4(p.slice(0, -1));
         var c = p.lastIndexOf("/");
         return c === -1 ? p : p.slice(0, c + 1);
       }
@@ -812,10 +1030,10 @@ var require_cfb = __commonJS({
           data.push([cfb.FullPaths[i2], cfb.FileIndex[i2]]);
         }
         for (i2 = 0; i2 < data.length; ++i2) {
-          var dad = dirname(data[i2][0]);
+          var dad = dirname4(data[i2][0]);
           s = fullPaths[dad];
           while (!s) {
-            while (dirname(dad) && !fullPaths[dirname(dad)]) dad = dirname(dad);
+            while (dirname4(dad) && !fullPaths[dirname4(dad)]) dad = dirname4(dad);
             data.push([dad, {
               name: filename(dad).replace("/", ""),
               type: 1,
@@ -825,7 +1043,7 @@ var require_cfb = __commonJS({
               content: null
             }]);
             fullPaths[dad] = true;
-            dad = dirname(data[i2][0]);
+            dad = dirname4(data[i2][0]);
             s = fullPaths[dad];
           }
         }
@@ -851,13 +1069,13 @@ var require_cfb = __commonJS({
             elt.size = 0;
             elt.type = 5;
           } else if (nm.slice(-1) == "/") {
-            for (j = i2 + 1; j < data.length; ++j) if (dirname(cfb.FullPaths[j]) == nm) break;
+            for (j = i2 + 1; j < data.length; ++j) if (dirname4(cfb.FullPaths[j]) == nm) break;
             elt.C = j >= data.length ? -1 : j;
-            for (j = i2 + 1; j < data.length; ++j) if (dirname(cfb.FullPaths[j]) == dirname(nm)) break;
+            for (j = i2 + 1; j < data.length; ++j) if (dirname4(cfb.FullPaths[j]) == dirname4(nm)) break;
             elt.R = j >= data.length ? -1 : j;
             elt.type = 1;
           } else {
-            if (dirname(cfb.FullPaths[i2 + 1] || "") == dirname(nm)) elt.R = i2 + 1;
+            if (dirname4(cfb.FullPaths[i2 + 1] || "") == dirname4(nm)) elt.R = i2 + 1;
             elt.type = 2;
           }
         }
@@ -2026,16 +2244,16 @@ var init_auto_detect = __esm({
 // src/ocr/cli-provider.ts
 function getTempDir() {
   if (!_tempDir) {
-    _tempDir = (0, import_path.join)(process.cwd(), ".kordoc_ocr_tmp");
-    (0, import_fs.mkdirSync)(_tempDir, { recursive: true });
+    _tempDir = (0, import_path2.join)(process.cwd(), ".kordoc_ocr_tmp");
+    (0, import_fs2.mkdirSync)(_tempDir, { recursive: true });
   }
   return _tempDir;
 }
 function createCliOcrProvider(mode) {
   return async (pageImage, pageNumber) => {
-    const tempPath = (0, import_path.join)(getTempDir(), `page-${pageNumber}.png`);
+    const tempPath = (0, import_path2.join)(getTempDir(), `page-${pageNumber}.png`);
     try {
-      (0, import_fs.writeFileSync)(tempPath, pageImage);
+      (0, import_fs2.writeFileSync)(tempPath, pageImage);
       let output;
       if (mode === "ollama") {
         output = await callOllamaApi(tempPath);
@@ -2045,7 +2263,7 @@ function createCliOcrProvider(mode) {
       return { markdown: stripCodeFence(output.trim()) };
     } finally {
       try {
-        (0, import_fs.unlinkSync)(tempPath);
+        (0, import_fs2.unlinkSync)(tempPath);
       } catch {
       }
     }
@@ -2082,7 +2300,7 @@ function callCli(mode, imagePath) {
   return output;
 }
 function callCodexCli(imagePath) {
-  const outPath = (0, import_path.join)((0, import_os.tmpdir)(), `kordoc-codex-out-${Date.now()}.txt`);
+  const outPath = (0, import_path2.join)((0, import_os.tmpdir)(), `kordoc-codex-out-${Date.now()}.txt`);
   try {
     const args = ["exec", OCR_PROMPT, "--image", imagePath, "--output-last-message", outPath];
     const model = process.env.KORDOC_CODEX_MODEL;
@@ -2104,7 +2322,7 @@ function callCodexCli(imagePath) {
     }
     let text;
     try {
-      text = (0, import_fs.readFileSync)(outPath, "utf-8");
+      text = (0, import_fs2.readFileSync)(outPath, "utf-8");
     } catch {
       text = result.stdout || "";
     }
@@ -2112,7 +2330,7 @@ function callCodexCli(imagePath) {
     return text;
   } finally {
     try {
-      (0, import_fs.unlinkSync)(outPath);
+      (0, import_fs2.unlinkSync)(outPath);
     } catch {
     }
   }
@@ -2169,13 +2387,13 @@ function stripCodeFence(text) {
   const match = text.match(/^```(?:markdown|md)?\s*([\s\S]*?)```\s*$/m);
   return match ? match[1].trim() : text;
 }
-var import_child_process2, import_fs, import_path, import_os, OCR_PROMPT, _tempDir;
+var import_child_process2, import_fs2, import_path2, import_os, OCR_PROMPT, _tempDir;
 var init_cli_provider = __esm({
   "src/ocr/cli-provider.ts"() {
     "use strict";
     import_child_process2 = require("child_process");
-    import_fs = require("fs");
-    import_path = require("path");
+    import_fs2 = require("fs");
+    import_path2 = require("path");
     import_os = require("os");
     OCR_PROMPT = `\uC774 PDF \uD398\uC774\uC9C0 \uC774\uBBF8\uC9C0\uC5D0\uC11C \uD14D\uC2A4\uD2B8\uC640 \uD14C\uC774\uBE14\uC744 \uCD94\uCD9C\uD558\uC5EC \uC21C\uC218 Markdown\uC73C\uB85C \uBCC0\uD658\uD558\uC138\uC694.
 \uADDC\uCE59:
@@ -2219,7 +2437,7 @@ async function createTesseractPoolProvider(concurrency) {
   const waitQueue = [];
   function acquire() {
     if (idle.length > 0) return Promise.resolve(idle.pop());
-    return new Promise((resolve) => waitQueue.push(resolve));
+    return new Promise((resolve4) => waitQueue.push(resolve4));
   }
   function release(w) {
     if (waitQueue.length > 0) {
@@ -2258,8 +2476,8 @@ __export(batch_provider_exports, {
 });
 function getBatchTempDir() {
   if (!_batchTempDir) {
-    _batchTempDir = (0, import_path2.join)(process.cwd(), ".kordoc_ocr_tmp");
-    (0, import_fs2.mkdirSync)(_batchTempDir, { recursive: true });
+    _batchTempDir = (0, import_path3.join)(process.cwd(), ".kordoc_ocr_tmp");
+    (0, import_fs3.mkdirSync)(_batchTempDir, { recursive: true });
     if (process.platform === "win32") {
       try {
         (0, import_child_process3.execSync)(`attrib +h "${_batchTempDir}"`, { stdio: "ignore" });
@@ -2279,8 +2497,8 @@ function createBatchCliProvider(mode, batchSize) {
       const tempFiles = [];
       try {
         for (const { image, pageNum } of pages) {
-          const path = (0, import_path2.join)(tempDir, `batch-p${pageNum}.png`);
-          (0, import_fs2.writeFileSync)(path, image);
+          const path = (0, import_path3.join)(tempDir, `batch-p${pageNum}.png`);
+          (0, import_fs3.writeFileSync)(path, image);
           tempFiles.push(path);
         }
         let output;
@@ -2300,7 +2518,7 @@ function createBatchCliProvider(mode, batchSize) {
       } finally {
         for (const f of tempFiles) {
           try {
-            (0, import_fs2.unlinkSync)(f);
+            (0, import_fs3.unlinkSync)(f);
           } catch {
           }
         }
@@ -2310,7 +2528,7 @@ function createBatchCliProvider(mode, batchSize) {
   };
 }
 function spawnAsync(cmd, args, opts) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = (0, import_child_process3.spawn)(cmd, args, {
       cwd: opts.cwd,
       env: process.env,
@@ -2346,7 +2564,7 @@ function spawnAsync(cmd, args, opts) {
       if (killed) {
         reject(new Error(`\uD0C0\uC784\uC544\uC6C3 (${Math.round(opts.timeoutMs / 1e3)}\uCD08)`));
       } else {
-        resolve({ stdout, stderr, exitCode: code ?? 1 });
+        resolve4({ stdout, stderr, exitCode: code ?? 1 });
       }
     });
     child.on("error", (err) => {
@@ -2383,7 +2601,7 @@ ${fileRefs}`;
   return output;
 }
 async function callBatchCodexCli(imagePaths) {
-  const outPath = (0, import_path2.join)((0, import_os2.tmpdir)(), `kordoc-codex-batch-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
+  const outPath = (0, import_path3.join)((0, import_os2.tmpdir)(), `kordoc-codex-batch-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
   try {
     const args = ["exec", BATCH_OCR_PROMPT];
     for (const p of imagePaths) {
@@ -2403,7 +2621,7 @@ async function callBatchCodexCli(imagePaths) {
     }
     let text;
     try {
-      text = (0, import_fs2.readFileSync)(outPath, "utf-8");
+      text = (0, import_fs3.readFileSync)(outPath, "utf-8");
     } catch {
       text = result.stdout || "";
     }
@@ -2411,7 +2629,7 @@ async function callBatchCodexCli(imagePaths) {
     return text;
   } finally {
     try {
-      (0, import_fs2.unlinkSync)(outPath);
+      (0, import_fs3.unlinkSync)(outPath);
     } catch {
     }
   }
@@ -2426,13 +2644,13 @@ function stripCodeFence2(text) {
   const match = text.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/m);
   return match ? match[1].trim() : text;
 }
-var import_child_process3, import_fs2, import_path2, import_os2, BATCH_OCR_PROMPT, DEFAULT_BATCH_SIZES, _batchTempDir;
+var import_child_process3, import_fs3, import_path3, import_os2, BATCH_OCR_PROMPT, DEFAULT_BATCH_SIZES, _batchTempDir;
 var init_batch_provider = __esm({
   "src/ocr/batch-provider.ts"() {
     "use strict";
     import_child_process3 = require("child_process");
-    import_fs2 = require("fs");
-    import_path2 = require("path");
+    import_fs3 = require("fs");
+    import_path3 = require("path");
     import_os2 = require("os");
     BATCH_OCR_PROMPT = "\uB2E4\uC74C \uBB38\uC11C \uD398\uC774\uC9C0 \uC774\uBBF8\uC9C0\uB4E4\uC744 OCR\uD558\uC5EC \uC21C\uC218 Markdown\uC73C\uB85C \uBCC0\uD658\uD558\uC138\uC694.\n\n\uADDC\uCE59:\n- \uAC01 \uD398\uC774\uC9C0 \uACB0\uACFC \uC0AC\uC774\uC5D0 \uBC18\uB4DC\uC2DC \uC774 \uAD6C\uBD84\uC790\uB97C \uC0BD\uC785: <!-- PAGE_BREAK -->\n- \uD14C\uC774\uBE14\uC740 Markdown \uD14C\uC774\uBE14 \uBB38\uBC95 \uC0AC\uC6A9 (| \uAD6C\uBD84, |---|---| \uD5E4\uB354 \uAD6C\uBD84\uC120 \uD3EC\uD568)\n- \uBCD1\uD569\uB41C \uC140\uC740 \uD574\uB2F9 \uC704\uCE58\uC5D0 \uB0B4\uC6A9 \uAE30\uC7AC\n- \uD5E4\uB529\uC740 \uAE00\uC790 \uD06C\uAE30\uC5D0 \uB530\uB77C ## ~ ###### \uC0AC\uC6A9\n- \uB9AC\uC2A4\uD2B8\uB294 - \uB610\uB294 1. \uC0AC\uC6A9\n- \uC774\uBBF8\uC9C0, \uB3C4\uD615 \uB4F1 \uBE44\uD14D\uC2A4\uD2B8 \uC694\uC18C\uB294 \uBB34\uC2DC\n- \uC6D0\uBB38\uC758 \uC77D\uAE30 \uC21C\uC11C\uC640 \uAD6C\uC870\uB97C \uC720\uC9C0\n- ```\uB85C \uAC10\uC2F8\uC9C0 \uB9D0\uACE0 \uC21C\uC218 Markdown\uB9CC \uCD9C\uB825";
     DEFAULT_BATCH_SIZES = {
@@ -2450,7 +2668,10 @@ __export(resolve_exports, {
   resolveOcrProvider: () => resolveOcrProvider
 });
 async function resolveOcrProvider(mode, warnings, concurrency, batchSize) {
+  const logger = createLoggerFromEnv().child({ component: "ocr/resolve.ts", stage: "ocr" });
+  logger.log({ level: "debug", event: "start", message: "OCR provider resolve \uC2DC\uC791", meta: { mode, concurrency, batchSize } });
   if (mode === "off") {
+    logger.log({ level: "warn", event: "error", message: "OCR \uBE44\uD65C\uC131\uD654 \uBAA8\uB4DC \uC694\uCCAD" });
     throw new Error("OCR\uC774 \uBE44\uD65C\uC131\uD654\uB418\uC5B4 \uC788\uC2B5\uB2C8\uB2E4 (--ocr off).");
   }
   if (mode !== "auto") {
@@ -2458,21 +2679,27 @@ async function resolveOcrProvider(mode, warnings, concurrency, batchSize) {
     if (mode === "tesseract") {
       const { createTesseractProvider: createTesseractProvider2, createTesseractPoolProvider: createTesseractPoolProvider2 } = await Promise.resolve().then(() => (init_tesseract_provider(), tesseract_provider_exports));
       if (concurrency && concurrency > 1) {
+        logger.log({ level: "info", event: "done", message: "Tesseract pool provider \uC120\uD0DD", meta: { concurrency } });
         return createTesseractPoolProvider2(concurrency);
       }
+      logger.log({ level: "info", event: "done", message: "Tesseract single provider \uC120\uD0DD" });
       return createTesseractProvider2();
     }
     if (mode === "gemini" || mode === "claude" || mode === "codex") {
       const { createBatchCliProvider: createBatchCliProvider2, DEFAULT_BATCH_SIZES: DEFAULT_BATCH_SIZES2 } = await Promise.resolve().then(() => (init_batch_provider(), batch_provider_exports));
       const effectiveBatch = batchSize ?? DEFAULT_BATCH_SIZES2[mode];
       if (effectiveBatch > 1) {
+        logger.log({ level: "info", event: "done", message: "Batch CLI provider \uC120\uD0DD", meta: { mode, batchSize: effectiveBatch } });
         return createBatchCliProvider2(mode, effectiveBatch);
       }
+      logger.log({ level: "info", event: "done", message: "CLI provider \uC120\uD0DD", meta: { mode } });
       return createCliOcrProvider(mode);
     }
+    logger.log({ level: "info", event: "done", message: "CLI provider \uC120\uD0DD", meta: { mode } });
     return createCliOcrProvider(mode);
   }
   const detected = detectAvailableOcr();
+  logger.log({ level: "info", event: "progress", message: "OCR auto \uAC10\uC9C0 \uACB0\uACFC", meta: { detected } });
   if (detected !== "codex") {
     if (detected === "tesseract") {
       warnings?.push({
@@ -2489,18 +2716,23 @@ async function resolveOcrProvider(mode, warnings, concurrency, batchSize) {
   if (detected === "tesseract") {
     const { createTesseractProvider: createTesseractProvider2, createTesseractPoolProvider: createTesseractPoolProvider2 } = await Promise.resolve().then(() => (init_tesseract_provider(), tesseract_provider_exports));
     if (concurrency && concurrency > 1) {
+      logger.log({ level: "info", event: "done", message: "AUTO: Tesseract pool provider \uC120\uD0DD", meta: { concurrency } });
       return createTesseractPoolProvider2(concurrency);
     }
+    logger.log({ level: "info", event: "done", message: "AUTO: Tesseract single provider \uC120\uD0DD" });
     return createTesseractProvider2();
   }
   if (detected === "gemini" || detected === "codex" || detected === "claude") {
     const { createBatchCliProvider: createBatchCliProvider2, DEFAULT_BATCH_SIZES: DEFAULT_BATCH_SIZES2 } = await Promise.resolve().then(() => (init_batch_provider(), batch_provider_exports));
     const effectiveBatch = batchSize ?? DEFAULT_BATCH_SIZES2[detected];
     if (effectiveBatch > 1) {
+      logger.log({ level: "info", event: "done", message: "AUTO: Batch CLI provider \uC120\uD0DD", meta: { mode: detected, batchSize: effectiveBatch } });
       return createBatchCliProvider2(detected, effectiveBatch);
     }
+    logger.log({ level: "info", event: "done", message: "AUTO: CLI provider \uC120\uD0DD", meta: { mode: detected } });
     return createCliOcrProvider(detected);
   }
+  logger.log({ level: "info", event: "done", message: "AUTO: CLI provider \uC120\uD0DD", meta: { mode: detected } });
   return createCliOcrProvider(detected);
 }
 var init_resolve = __esm({
@@ -2508,6 +2740,7 @@ var init_resolve = __esm({
     "use strict";
     init_auto_detect();
     init_cli_provider();
+    init_logger();
   }
 });
 
@@ -2667,9 +2900,18 @@ function isBatchProvider(p) {
   return !!p && typeof p === "object" && "__batch" in p && p.__batch === true;
 }
 async function ocrPages(doc, provider, pageFilter, effectivePageCount, warnings, concurrency = 1, onProgress) {
+  const logger = createLoggerFromEnv().child({ component: "ocr/provider.ts", stage: "ocr" });
+  logger.log({
+    level: "info",
+    event: "start",
+    message: "OCR \uD398\uC774\uC9C0 \uCC98\uB9AC \uC2DC\uC791",
+    meta: { effectivePageCount, concurrency, filteredPages: pageFilter?.size, batchProvider: isBatchProvider(provider) }
+  });
   const blocks = [];
   if (isBatchProvider(provider)) {
-    return ocrPagesBatch(doc, provider, pageFilter, effectivePageCount, warnings, concurrency, onProgress);
+    const result = await ocrPagesBatch(doc, provider, pageFilter, effectivePageCount, warnings, concurrency, onProgress);
+    logger.log({ level: "info", event: "done", message: "OCR \uBC30\uCE58 \uCC98\uB9AC \uC644\uB8CC", meta: { blocks: result.length } });
+    return result;
   }
   if (concurrency <= 1) {
     for (let i = 1; i <= effectivePageCount; i++) {
@@ -2685,8 +2927,16 @@ async function ocrPages(doc, provider, pageFilter, effectivePageCount, warnings,
           message: `\uD398\uC774\uC9C0 ${i} OCR \uC2E4\uD328: ${err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`,
           code: "OCR_PAGE_FAILED"
         });
+        logger.log({
+          level: "warn",
+          event: "progress",
+          message: "\uD398\uC774\uC9C0 OCR \uC2E4\uD328",
+          meta: { page: i },
+          error: { message: err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: err instanceof Error ? err.name : "Error" }
+        });
       }
     }
+    logger.log({ level: "info", event: "done", message: "OCR \uC21C\uCC28 \uCC98\uB9AC \uC644\uB8CC", meta: { blocks: blocks.length } });
     return blocks;
   }
   const pageNumbers = [];
@@ -2706,6 +2956,13 @@ async function ocrPages(doc, provider, pageFilter, effectivePageCount, warnings,
         message: `\uD398\uC774\uC9C0 ${pageNum} OCR \uC2E4\uD328: ${err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`,
         code: "OCR_PAGE_FAILED"
       });
+      logger.log({
+        level: "warn",
+        event: "progress",
+        message: "\uD398\uC774\uC9C0 OCR \uC2E4\uD328(\uBCD1\uB82C)",
+        meta: { page: pageNum },
+        error: { message: err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: err instanceof Error ? err.name : "Error" }
+      });
       return null;
     }
   });
@@ -2714,6 +2971,7 @@ async function ocrPages(doc, provider, pageFilter, effectivePageCount, warnings,
     if (!item) continue;
     for (const b of item.pageBlocks) blocks.push(b);
   }
+  logger.log({ level: "info", event: "done", message: "OCR \uBCD1\uB82C \uCC98\uB9AC \uC644\uB8CC", meta: { blocks: blocks.length, pages: pageNumbers.length } });
   return blocks;
 }
 async function ocrPagesBatch(doc, provider, pageFilter, effectivePageCount, warnings, concurrency = 1, onProgress) {
@@ -2796,12 +3054,15 @@ var init_provider = __esm({
   "src/ocr/provider.ts"() {
     "use strict";
     init_markdown_to_blocks();
+    init_logger();
   }
 });
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AllKeysCoolingDownError: () => AllKeysCoolingDownError,
+  ApiKeyRotationPool: () => ApiKeyRotationPool,
   VERSION: () => VERSION,
   blocksToMarkdown: () => blocksToMarkdown,
   compare: () => compare,
@@ -2820,10 +3081,11 @@ __export(index_exports, {
   parseHwp: () => parseHwp,
   parseHwpx: () => parseHwpx,
   parsePdf: () => parsePdf,
-  parseXlsx: () => parseXlsx
+  parseXlsx: () => parseXlsx,
+  runUnifiedOcrPipeline: () => runUnifiedOcrPipeline
 });
 module.exports = __toCommonJS(index_exports);
-var import_promises = require("fs/promises");
+var import_promises3 = require("fs/promises");
 
 // src/detect.ts
 var import_jszip = __toESM(require("jszip"), 1);
@@ -2876,7 +3138,7 @@ var import_jszip2 = __toESM(require("jszip"), 1);
 var import_xmldom = require("@xmldom/xmldom");
 
 // src/utils.ts
-var VERSION = true ? "2.4.11" : "0.0.0-dev";
+var VERSION = true ? "2.4.12" : "0.0.0-dev";
 function toArrayBuffer(buf) {
   if (buf.byteOffset === 0 && buf.byteLength === buf.buffer.byteLength) {
     return buf.buffer;
@@ -2884,9 +3146,13 @@ function toArrayBuffer(buf) {
   return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
 }
 var KordocError = class extends Error {
-  constructor(message) {
+  code;
+  stage;
+  constructor(message, opts = {}) {
     super(message);
     this.name = "KordocError";
+    this.code = opts.code;
+    this.stage = opts.stage;
   }
 };
 function isPathTraversal(name) {
@@ -2950,6 +3216,16 @@ function classifyError(err) {
   if (msg.includes("\uC2DC\uADF8\uB2C8\uCC98") || msg.includes("\uBCF5\uAD6C\uD560 \uC218 \uC5C6")) return "CORRUPTED";
   return "PARSE_ERROR";
 }
+function normalizeKordocError(err, fallbackMessage, stage = "unknown", fallbackCode = "PARSE_ERROR") {
+  if (err instanceof KordocError) {
+    if (!err.stage) err.stage = stage;
+    if (!err.code) err.code = fallbackCode;
+    return err;
+  }
+  const message = err instanceof Error ? err.message : fallbackMessage;
+  const code = err instanceof Error ? classifyError(err) : fallbackCode;
+  return new KordocError(message || fallbackMessage, { code, stage });
+}
 
 // src/table/builder.ts
 var MAX_COLS = 200;
@@ -3212,6 +3488,7 @@ var HEADING_RATIO_H3 = 1.15;
 
 // src/hwpx/parser.ts
 init_page_range();
+init_logger();
 var MAX_DECOMPRESS_SIZE = 500 * 1024 * 1024;
 var MAX_ZIP_ENTRIES = 2e3;
 function clampSpan(val, max) {
@@ -3303,50 +3580,89 @@ function stripDtd(xml) {
   return xml.replace(/<!DOCTYPE\s[^[>]*(\[[\s\S]*?\])?\s*>/gi, "");
 }
 async function parseHwpxDocument(buffer, options, existingZip) {
-  precheckZipSize(buffer, MAX_DECOMPRESS_SIZE, MAX_ZIP_ENTRIES);
-  let zip;
+  const logger = createLoggerFromEnv().child({ component: "hwpx/parser.ts", stage: "detect" });
+  logger.log({ level: "info", event: "start", message: "HWPX \uD30C\uC2F1 \uC2DC\uC791", meta: { size: buffer.byteLength } });
+  let lastParsedSection = 0;
   try {
-    zip = existingZip ?? await import_jszip2.default.loadAsync(buffer);
-  } catch {
-    return await extractFromBrokenZip(buffer);
-  }
-  const actualEntryCount = Object.keys(zip.files).length;
-  if (actualEntryCount > MAX_ZIP_ENTRIES) {
-    throw new KordocError("ZIP \uC5D4\uD2B8\uB9AC \uC218 \uCD08\uACFC (ZIP bomb \uC758\uC2EC)");
-  }
-  const decompressed = { total: 0 };
-  const metadata = {};
-  await extractHwpxMetadata(zip, metadata, decompressed);
-  const styleMap = await extractHwpxStyles(zip, decompressed);
-  const warnings = [];
-  const sectionPaths = await resolveSectionPaths(zip);
-  if (sectionPaths.length === 0) throw new KordocError("HWPX\uC5D0\uC11C \uC139\uC158 \uD30C\uC77C\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4");
-  metadata.pageCount = sectionPaths.length;
-  const pageFilter = options?.pages ? parsePageRange(options.pages, sectionPaths.length) : null;
-  const totalTarget = pageFilter ? pageFilter.size : sectionPaths.length;
-  const blocks = [];
-  let parsedSections = 0;
-  for (let si = 0; si < sectionPaths.length; si++) {
-    if (pageFilter && !pageFilter.has(si + 1)) continue;
-    const file = zip.file(sectionPaths[si]);
-    if (!file) continue;
+    precheckZipSize(buffer, MAX_DECOMPRESS_SIZE, MAX_ZIP_ENTRIES);
+    let zip;
     try {
-      const xml = await file.async("text");
-      decompressed.total += xml.length * 2;
-      if (decompressed.total > MAX_DECOMPRESS_SIZE) throw new KordocError("ZIP \uC555\uCD95 \uD574\uC81C \uD06C\uAE30 \uCD08\uACFC (ZIP bomb \uC758\uC2EC)");
-      blocks.push(...parseSectionXml(xml, styleMap, warnings, si + 1));
-      parsedSections++;
-      options?.onProgress?.(parsedSections, totalTarget);
-    } catch (secErr) {
-      if (secErr instanceof KordocError) throw secErr;
-      warnings.push({ page: si + 1, message: `\uC139\uC158 ${si + 1} \uD30C\uC2F1 \uC2E4\uD328: ${secErr instanceof Error ? secErr.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`, code: "PARTIAL_PARSE" });
-    }
-  }
-  const images = await extractImagesFromZip(zip, blocks, decompressed, warnings);
-  detectHwpxHeadings(blocks, styleMap);
-  const outline = blocks.filter((b) => b.type === "heading" && b.level && b.text).map((b) => ({ level: b.level, text: b.text, pageNumber: b.pageNumber }));
-  const markdown = blocksToMarkdown(blocks);
-  return { markdown, blocks, metadata, outline: outline.length > 0 ? outline : void 0, warnings: warnings.length > 0 ? warnings : void 0, images: images.length > 0 ? images : void 0 };
+      zip = existingZip ?? await import_jszip2.default.loadAsync(buffer);
+    } catch {
+      return await extractFromBrokenZip(buffer);
+    }
+    const actualEntryCount = Object.keys(zip.files).length;
+    if (actualEntryCount > MAX_ZIP_ENTRIES) {
+      throw new KordocError("ZIP \uC5D4\uD2B8\uB9AC \uC218 \uCD08\uACFC (ZIP bomb \uC758\uC2EC)");
+    }
+    const decompressed = { total: 0 };
+    const metadata = {};
+    await extractHwpxMetadata(zip, metadata, decompressed);
+    const styleMap = await extractHwpxStyles(zip, decompressed);
+    const warnings = [];
+    const sectionPaths = await resolveSectionPaths(zip);
+    if (sectionPaths.length === 0) throw new KordocError("HWPX\uC5D0\uC11C \uC139\uC158 \uD30C\uC77C\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4");
+    metadata.pageCount = sectionPaths.length;
+    logger.log({ level: "debug", stage: "convert", event: "progress", message: "\uC139\uC158 \uACBD\uB85C \uD574\uC11D \uC644\uB8CC", meta: { sections: sectionPaths.length } });
+    const pageFilter = options?.pages ? parsePageRange(options.pages, sectionPaths.length) : null;
+    const totalTarget = pageFilter ? pageFilter.size : sectionPaths.length;
+    const blocks = [];
+    let parsedSections = 0;
+    for (let si = 0; si < sectionPaths.length; si++) {
+      if (pageFilter && !pageFilter.has(si + 1)) continue;
+      const file = zip.file(sectionPaths[si]);
+      if (!file) continue;
+      try {
+        const xml = await file.async("text");
+        decompressed.total += xml.length * 2;
+        if (decompressed.total > MAX_DECOMPRESS_SIZE) throw new KordocError("ZIP \uC555\uCD95 \uD574\uC81C \uD06C\uAE30 \uCD08\uACFC (ZIP bomb \uC758\uC2EC)");
+        blocks.push(...parseSectionXml(xml, styleMap, warnings, si + 1));
+        parsedSections++;
+        options?.onProgress?.(parsedSections, totalTarget);
+        logger.log({
+          level: "debug",
+          stage: "convert",
+          event: "progress",
+          message: "\uC139\uC158 \uD30C\uC2F1 \uC644\uB8CC",
+          meta: { section: si + 1, parsedSections, totalTarget }
+        });
+        lastParsedSection = si + 1;
+      } catch (secErr) {
+        if (secErr instanceof KordocError) throw secErr;
+        warnings.push({ page: si + 1, message: `\uC139\uC158 ${si + 1} \uD30C\uC2F1 \uC2E4\uD328: ${secErr instanceof Error ? secErr.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`, code: "PARTIAL_PARSE" });
+        logger.log({
+          level: "warn",
+          stage: "convert",
+          event: "progress",
+          message: "\uC139\uC158 \uD30C\uC2F1 \uC2E4\uD328",
+          meta: { section: si + 1 },
+          error: { message: secErr instanceof Error ? secErr.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: secErr instanceof Error ? secErr.name : "Error" }
+        });
+      }
+    }
+    const images = await extractImagesFromZip(zip, blocks, decompressed, warnings);
+    detectHwpxHeadings(blocks, styleMap);
+    const outline = blocks.filter((b) => b.type === "heading" && b.level && b.text).map((b) => ({ level: b.level, text: b.text, pageNumber: b.pageNumber }));
+    const markdown = blocksToMarkdown(blocks);
+    logger.log({
+      level: "info",
+      stage: "finalize",
+      event: "done",
+      message: "HWPX \uD30C\uC2F1 \uC644\uB8CC",
+      meta: { blocks: blocks.length, warnings: warnings.length, images: images.length, outline: outline.length }
+    });
+    return { markdown, blocks, metadata, outline: outline.length > 0 ? outline : void 0, warnings: warnings.length > 0 ? warnings : void 0, images: images.length > 0 ? images : void 0 };
+  } catch (err) {
+    logger.log({
+      level: "error",
+      stage: "finalize",
+      event: "error",
+      message: "HWPX \uD30C\uC2F1 \uC2E4\uD328",
+      meta: { lastParsedSection },
+      error: { message: err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: err instanceof Error ? err.name : "Error", stack: err instanceof Error ? err.stack : void 0 }
+    });
+    throw err;
+  }
 }
 function imageExtToMime(ext) {
   switch (ext.toLowerCase()) {
@@ -5063,75 +5379,115 @@ function parseLenientCfb(data) {
 
 // src/hwp5/parser.ts
 init_page_range();
+init_logger();
 var CFB = __toESM(require_cfb(), 1);
 var MAX_SECTIONS = 100;
 var MAX_TOTAL_DECOMPRESS = 500 * 1024 * 1024;
 function parseHwp5Document(buffer, options) {
-  let cfb = null;
-  let lenientCfb = null;
-  const warnings = [];
+  const logger = createLoggerFromEnv().child({ component: "hwp5/parser.ts", stage: "detect" });
+  logger.log({ level: "info", event: "start", message: "HWP5 \uD30C\uC2F1 \uC2DC\uC791", meta: { size: buffer.length } });
+  let lastParsedSection = 0;
   try {
-    cfb = CFB.parse(buffer);
-  } catch {
+    let cfb = null;
+    let lenientCfb = null;
+    const warnings = [];
     try {
-      lenientCfb = parseLenientCfb(buffer);
-      warnings.push({ message: "\uC190\uC0C1\uB41C CFB \uCEE8\uD14C\uC774\uB108 \u2014 lenient \uBAA8\uB4DC\uB85C \uBCF5\uAD6C", code: "LENIENT_CFB_RECOVERY" });
+      cfb = CFB.parse(buffer);
     } catch {
-      throw new KordocError("CFB \uCEE8\uD14C\uC774\uB108 \uD30C\uC2F1 \uC2E4\uD328 (strict \uBC0F lenient \uBAA8\uB450)");
+      try {
+        lenientCfb = parseLenientCfb(buffer);
+        warnings.push({ message: "\uC190\uC0C1\uB41C CFB \uCEE8\uD14C\uC774\uB108 \u2014 lenient \uBAA8\uB4DC\uB85C \uBCF5\uAD6C", code: "LENIENT_CFB_RECOVERY" });
+      } catch {
+        throw new KordocError("CFB \uCEE8\uD14C\uC774\uB108 \uD30C\uC2F1 \uC2E4\uD328 (strict \uBC0F lenient \uBAA8\uB450)");
+      }
     }
-  }
-  const findStream = (path) => {
-    if (cfb) {
-      const entry = CFB.find(cfb, path);
-      return entry?.content ? Buffer.from(entry.content) : null;
+    const findStream = (path) => {
+      if (cfb) {
+        const entry = CFB.find(cfb, path);
+        return entry?.content ? Buffer.from(entry.content) : null;
+      }
+      return lenientCfb.findStream(path);
+    };
+    const headerData = findStream("/FileHeader");
+    if (!headerData) throw new KordocError("FileHeader \uC2A4\uD2B8\uB9BC \uC5C6\uC74C");
+    const header = parseFileHeader(headerData);
+    if (header.signature !== "HWP Document File") throw new KordocError("HWP \uC2DC\uADF8\uB2C8\uCC98 \uBD88\uC77C\uCE58");
+    if (header.flags & FLAG_ENCRYPTED) throw new KordocError("\uC554\uD638\uD654\uB41C HWP\uB294 \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4");
+    if (header.flags & FLAG_DRM) throw new KordocError("DRM \uBCF4\uD638\uB41C HWP\uB294 \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4");
+    const compressed = (header.flags & FLAG_COMPRESSED) !== 0;
+    const distribution = (header.flags & FLAG_DISTRIBUTION) !== 0;
+    const metadata = {
+      version: `${header.versionMajor}.x`
+    };
+    if (cfb) extractHwp5Metadata(cfb, metadata);
+    const docInfo = cfb ? parseDocInfoStream(cfb, compressed) : parseDocInfoFromStream(findStream("/DocInfo"), compressed);
+    const sections = distribution ? cfb ? findViewTextSections(cfb, compressed) : findViewTextSectionsLenient(lenientCfb, compressed) : cfb ? findSections(cfb) : findSectionsLenient(lenientCfb, compressed);
+    if (sections.length === 0) throw new KordocError("\uC139\uC158 \uC2A4\uD2B8\uB9BC\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4");
+    logger.log({ level: "debug", stage: "convert", event: "progress", message: "\uC139\uC158 \uBAA9\uB85D \uD574\uC11D \uC644\uB8CC", meta: { sections: sections.length, distribution } });
+    metadata.pageCount = sections.length;
+    const pageFilter = options?.pages ? parsePageRange(options.pages, sections.length) : null;
+    const totalTarget = pageFilter ? pageFilter.size : sections.length;
+    const blocks = [];
+    let totalDecompressed = 0;
+    let parsedSections = 0;
+    for (let si = 0; si < sections.length; si++) {
+      if (pageFilter && !pageFilter.has(si + 1)) continue;
+      try {
+        const sectionData = sections[si];
+        const data = !distribution && compressed ? decompressStream(Buffer.from(sectionData)) : Buffer.from(sectionData);
+        totalDecompressed += data.length;
+        if (totalDecompressed > MAX_TOTAL_DECOMPRESS) throw new KordocError("\uCD1D \uC555\uCD95 \uD574\uC81C \uD06C\uAE30 \uCD08\uACFC (decompression bomb \uC758\uC2EC)");
+        const records = readRecords(data);
+        const sectionBlocks = parseSection(records, docInfo, warnings, si + 1);
+        blocks.push(...sectionBlocks);
+        parsedSections++;
+        options?.onProgress?.(parsedSections, totalTarget);
+        logger.log({
+          level: "debug",
+          stage: "convert",
+          event: "progress",
+          message: "\uC139\uC158 \uD30C\uC2F1 \uC644\uB8CC",
+          meta: { section: si + 1, parsedSections, totalTarget }
+        });
+        lastParsedSection = si + 1;
+      } catch (secErr) {
+        if (secErr instanceof KordocError) throw secErr;
+        warnings.push({ page: si + 1, message: `\uC139\uC158 ${si + 1} \uD30C\uC2F1 \uC2E4\uD328: ${secErr instanceof Error ? secErr.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`, code: "PARTIAL_PARSE" });
+        logger.log({
+          level: "warn",
+          stage: "convert",
+          event: "progress",
+          message: "\uC139\uC158 \uD30C\uC2F1 \uC2E4\uD328",
+          meta: { section: si + 1 },
+          error: { message: secErr instanceof Error ? secErr.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: secErr instanceof Error ? secErr.name : "Error" }
+        });
+      }
     }
-    return lenientCfb.findStream(path);
-  };
-  const headerData = findStream("/FileHeader");
-  if (!headerData) throw new KordocError("FileHeader \uC2A4\uD2B8\uB9BC \uC5C6\uC74C");
-  const header = parseFileHeader(headerData);
-  if (header.signature !== "HWP Document File") throw new KordocError("HWP \uC2DC\uADF8\uB2C8\uCC98 \uBD88\uC77C\uCE58");
-  if (header.flags & FLAG_ENCRYPTED) throw new KordocError("\uC554\uD638\uD654\uB41C HWP\uB294 \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4");
-  if (header.flags & FLAG_DRM) throw new KordocError("DRM \uBCF4\uD638\uB41C HWP\uB294 \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4");
-  const compressed = (header.flags & FLAG_COMPRESSED) !== 0;
-  const distribution = (header.flags & FLAG_DISTRIBUTION) !== 0;
-  const metadata = {
-    version: `${header.versionMajor}.x`
-  };
-  if (cfb) extractHwp5Metadata(cfb, metadata);
-  const docInfo = cfb ? parseDocInfoStream(cfb, compressed) : parseDocInfoFromStream(findStream("/DocInfo"), compressed);
-  const sections = distribution ? cfb ? findViewTextSections(cfb, compressed) : findViewTextSectionsLenient(lenientCfb, compressed) : cfb ? findSections(cfb) : findSectionsLenient(lenientCfb, compressed);
-  if (sections.length === 0) throw new KordocError("\uC139\uC158 \uC2A4\uD2B8\uB9BC\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4");
-  metadata.pageCount = sections.length;
-  const pageFilter = options?.pages ? parsePageRange(options.pages, sections.length) : null;
-  const totalTarget = pageFilter ? pageFilter.size : sections.length;
-  const blocks = [];
-  let totalDecompressed = 0;
-  let parsedSections = 0;
-  for (let si = 0; si < sections.length; si++) {
-    if (pageFilter && !pageFilter.has(si + 1)) continue;
-    try {
-      const sectionData = sections[si];
-      const data = !distribution && compressed ? decompressStream(Buffer.from(sectionData)) : Buffer.from(sectionData);
-      totalDecompressed += data.length;
-      if (totalDecompressed > MAX_TOTAL_DECOMPRESS) throw new KordocError("\uCD1D \uC555\uCD95 \uD574\uC81C \uD06C\uAE30 \uCD08\uACFC (decompression bomb \uC758\uC2EC)");
-      const records = readRecords(data);
-      const sectionBlocks = parseSection(records, docInfo, warnings, si + 1);
-      blocks.push(...sectionBlocks);
-      parsedSections++;
-      options?.onProgress?.(parsedSections, totalTarget);
-    } catch (secErr) {
-      if (secErr instanceof KordocError) throw secErr;
-      warnings.push({ page: si + 1, message: `\uC139\uC158 ${si + 1} \uD30C\uC2F1 \uC2E4\uD328: ${secErr instanceof Error ? secErr.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`, code: "PARTIAL_PARSE" });
-    }
-  }
-  const images = cfb ? extractHwp5Images(cfb, blocks, compressed, warnings) : extractHwp5ImagesLenient(lenientCfb, blocks, compressed, warnings);
-  if (docInfo) {
-    detectHwp5Headings(blocks, docInfo);
-  }
-  const outline = blocks.filter((b) => b.type === "heading" && b.level && b.text).map((b) => ({ level: b.level, text: b.text, pageNumber: b.pageNumber }));
-  const markdown = blocksToMarkdown(blocks);
-  return { markdown, blocks, metadata, outline: outline.length > 0 ? outline : void 0, warnings: warnings.length > 0 ? warnings : void 0, images: images.length > 0 ? images : void 0 };
+    const images = cfb ? extractHwp5Images(cfb, blocks, compressed, warnings) : extractHwp5ImagesLenient(lenientCfb, blocks, compressed, warnings);
+    if (docInfo) {
+      detectHwp5Headings(blocks, docInfo);
+    }
+    const outline = blocks.filter((b) => b.type === "heading" && b.level && b.text).map((b) => ({ level: b.level, text: b.text, pageNumber: b.pageNumber }));
+    const markdown = blocksToMarkdown(blocks);
+    logger.log({
+      level: "info",
+      stage: "finalize",
+      event: "done",
+      message: "HWP5 \uD30C\uC2F1 \uC644\uB8CC",
+      meta: { blocks: blocks.length, warnings: warnings.length, images: images.length, outline: outline.length }
+    });
+    return { markdown, blocks, metadata, outline: outline.length > 0 ? outline : void 0, warnings: warnings.length > 0 ? warnings : void 0, images: images.length > 0 ? images : void 0 };
+  } catch (err) {
+    logger.log({
+      level: "error",
+      stage: "finalize",
+      event: "error",
+      message: "HWP5 \uD30C\uC2F1 \uC2E4\uD328",
+      meta: { lastParsedSection },
+      error: { message: err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: err instanceof Error ? err.name : "Error", stack: err instanceof Error ? err.stack : void 0 }
+    });
+    throw err;
+  }
 }
 function parseDocInfoStream(cfb, compressed) {
   try {
@@ -5678,6 +6034,8 @@ function arrangeCells(rows, cols, cells) {
 
 // src/pdf/parser.ts
 init_page_range();
+var import_module = require("module");
+var import_path4 = require("path");
 
 // src/pdf/line-detector.ts
 var import_pdf = require("pdfjs-dist/legacy/build/pdf.mjs");
@@ -5865,12 +6223,17 @@ function buildTableGrids(horizontals, verticals) {
     const rawXs = vLines.map((l) => l.x1);
     const colXs = clusterCoordinates(rawXs).sort((a, b) => a - b);
     if (rowYs.length < 2 || colXs.length < 2) continue;
+    const rowCount = rowYs.length - 1;
+    const colCount = colXs.length - 1;
+    if (rowCount <= 0 || colCount <= 0) continue;
+    if (rowCount * colCount < 2) continue;
     const bbox = {
       x1: colXs[0],
       y1: rowYs[rowYs.length - 1],
       x2: colXs[colXs.length - 1],
       y2: rowYs[0]
     };
+    if (!hasReliableGridStructure(rowYs, colXs, hLines, vLines, bbox)) continue;
     grids.push({ rowYs, colXs, bbox });
   }
   return mergeAdjacentGrids(grids);
@@ -5920,6 +6283,35 @@ function clusterCoordinates(values) {
   }
   return clusters.map((c) => c.sum / c.count);
 }
+function hasReliableGridStructure(rowYs, colXs, hLines, vLines, bbox) {
+  const internalRows = rowYs.slice(1, -1);
+  const internalCols = colXs.slice(1, -1);
+  const width = Math.max(1, bbox.x2 - bbox.x1);
+  const height = Math.max(1, bbox.y2 - bbox.y1);
+  const coverageThreshold = 0.55;
+  const coveredRows = internalRows.filter(
+    (y) => hLines.some((h) => Math.abs(h.y1 - y) <= COORD_MERGE_TOL && lineOverlapRatio(h.x1, h.x2, bbox.x1, bbox.x2) >= coverageThreshold)
+  ).length;
+  const coveredCols = internalCols.filter(
+    (x) => vLines.some((v) => Math.abs(v.x1 - x) <= COORD_MERGE_TOL && lineOverlapRatio(v.y1, v.y2, bbox.y1, bbox.y2) >= coverageThreshold)
+  ).length;
+  const rowCoverage = internalRows.length > 0 ? coveredRows / internalRows.length : 1;
+  const colCoverage = internalCols.length > 0 ? coveredCols / internalCols.length : 1;
+  const longHorizontal = hLines.filter((h) => Math.abs(h.x2 - h.x1) >= width * 0.7).length;
+  const longVertical = vLines.filter((v) => Math.abs(v.y2 - v.y1) >= height * 0.7).length;
+  const hasAxisSupport = longHorizontal >= 2 && longVertical >= 2;
+  if (!hasAxisSupport) return false;
+  if (internalRows.length > 0 && rowCoverage < 0.5) return false;
+  if (internalCols.length > 0 && colCoverage < 0.5) return false;
+  return true;
+}
+function lineOverlapRatio(a1, a2, b1, b2) {
+  const left = Math.max(Math.min(a1, a2), Math.min(b1, b2));
+  const right = Math.min(Math.max(a1, a2), Math.max(b1, b2));
+  const overlap = Math.max(0, right - left);
+  const target = Math.max(1, Math.abs(b2 - b1));
+  return overlap / target;
+}
 function groupConnectedLines(lines) {
   const parent = lines.map((_, i) => i);
   function find2(x) {
@@ -6296,6 +6688,9 @@ function buildClusterTable(rows, columns, pageNum) {
   };
 }
 
+// src/pdf/parser.ts
+init_logger();
+
 // src/pdf/polyfill.ts
 var pdfjsWorker = __toESM(require("pdfjs-dist/legacy/build/pdf.worker.mjs"), 1);
 var g = globalThis;
@@ -6316,6 +6711,17 @@ g.pdfjsWorker = pdfjsWorker;
 // src/pdf/parser.ts
 var import_pdf2 = require("pdfjs-dist/legacy/build/pdf.mjs");
 import_pdf2.GlobalWorkerOptions.workerSrc = "";
+var require2 = (0, import_module.createRequire)(
+  typeof __filename !== "undefined" ? __filename : (0, import_path4.resolve)(process.cwd(), "kordoc.require.cjs")
+);
+function resolvePdfjsWasmUrl() {
+  try {
+    const pdfjsPkg = require2.resolve("pdfjs-dist/package.json");
+    return (0, import_path4.join)((0, import_path4.dirname)(pdfjsPkg), "wasm/");
+  } catch {
+    return (0, import_path4.resolve)(process.cwd(), "node_modules/pdfjs-dist/wasm/");
+  }
+}
 var MAX_PAGES = 5e3;
 var MAX_TOTAL_TEXT = 500 * 1024 * 1024;
 function calcPdfTimeout(bufferSize) {
@@ -6331,7 +6737,8 @@ async function loadPdfWithTimeout(buffer) {
     data: new Uint8Array(buffer),
     useSystemFonts: true,
     disableFontFace: true,
-    isEvalSupported: false
+    isEvalSupported: false,
+    wasmUrl: resolvePdfjsWasmUrl()
   });
   let timer;
   try {
@@ -6348,7 +6755,47 @@ async function loadPdfWithTimeout(buffer) {
     if (timer !== void 0) clearTimeout(timer);
   }
 }
+function estimateImageBasedPdf(metrics) {
+  if (metrics.length === 0) {
+    return { isImageBased: true, score: 1, reason: "\uC0D8\uD50C \uD1B5\uACC4 \uC5C6\uC74C" };
+  }
+  const totalPages = metrics.length;
+  const totalChars = metrics.reduce((s, m) => s + m.nonWhitespaceChars, 0);
+  const totalItems = metrics.reduce((s, m) => s + m.visibleItems, 0);
+  const pagesWithText = metrics.filter((m) => m.nonWhitespaceChars >= 20 || m.visibleItems >= 15).length;
+  const avgChars = totalChars / totalPages;
+  const avgItems = totalItems / totalPages;
+  const textPresenceRatio = pagesWithText / totalPages;
+  let score = 0;
+  if (avgChars < 10) score += 0.45;
+  if (avgItems < 8) score += 0.35;
+  if (textPresenceRatio < 0.35) score += 0.25;
+  if (avgChars > 40) score -= 0.35;
+  if (avgItems > 25) score -= 0.35;
+  if (textPresenceRatio > 0.7) score -= 0.25;
+  score = Math.max(0, Math.min(1, score));
+  const isImageBased = score >= 0.5;
+  const reason = `avgChars=${avgChars.toFixed(1)}, avgItems=${avgItems.toFixed(1)}, textPresence=${(textPresenceRatio * 100).toFixed(0)}%, score=${score.toFixed(2)}`;
+  return { isImageBased, score, reason };
+}
+function summarizePartialFailures(failedPages, totalTarget) {
+  if (failedPages.length === 0) return null;
+  const sorted = [...failedPages].sort((a, b) => a - b);
+  const preview = sorted.slice(0, 10).join(", ");
+  const suffix = sorted.length > 10 ? ` \uC678 ${sorted.length - 10}\uD398\uC774\uC9C0` : "";
+  return `\uBD80\uBD84 \uD30C\uC2F1 \uC2E4\uD328 \uC694\uC57D: ${sorted.length}/${totalTarget}\uD398\uC774\uC9C0 \uC2E4\uD328 (p${preview}${suffix})`;
+}
+function shouldAbortForPartialFailures(failedPages, totalTarget, maxPartialFailureRatio) {
+  if (typeof maxPartialFailureRatio !== "number") {
+    return { abort: false, ratio: 0, threshold: 0 };
+  }
+  const threshold = Math.max(0, Math.min(1, maxPartialFailureRatio));
+  const ratio = totalTarget > 0 ? failedPages.length / totalTarget : 0;
+  return { abort: ratio > threshold, ratio, threshold };
+}
 async function parsePdfDocument(buffer, options) {
+  const logger = createLoggerFromEnv().child({ component: "pdf/parser.ts", stage: "detect" });
+  logger.log({ level: "info", event: "start", message: "PDF \uD30C\uC2F1 \uC2DC\uC791", meta: { size: buffer.byteLength } });
   const doc = await loadPdfWithTimeout(buffer);
   try {
     const pageCount = doc.numPages;
@@ -6357,9 +6804,13 @@ async function parsePdfDocument(buffer, options) {
     await extractPdfMetadata(doc, metadata);
     const blocks = [];
     const warnings = [];
+    const failedPages = [];
+    let lastParsedPage2 = 0;
+    const sampleMetricsByPage = /* @__PURE__ */ new Map();
     let totalChars = 0;
     let totalTextBytes = 0;
     const effectivePageCount = Math.min(pageCount, MAX_PAGES);
+    logger.log({ level: "debug", event: "progress", message: "PDF \uB85C\uB529 \uC644\uB8CC", meta: { pageCount, effectivePageCount } });
     const pageFilter = options?.pages ? parsePageRange(options.pages, effectivePageCount) : null;
     const totalTarget = pageFilter ? pageFilter.size : effectivePageCount;
     const fontSizeFreq = /* @__PURE__ */ new Map();
@@ -6396,11 +6847,17 @@ async function parsePdfDocument(buffer, options) {
           totalChars += t.replace(/\s/g, "").length;
           totalTextBytes += t.length * 2;
         }
+        sampleMetricsByPage.set(i, {
+          nonWhitespaceChars: visible.reduce((sum, it) => sum + it.text.replace(/\s/g, "").length, 0),
+          visibleItems: visible.length
+        });
+        lastParsedPage2 = i;
         if (totalTextBytes > MAX_TOTAL_TEXT) throw new KordocError("\uD14D\uC2A4\uD2B8 \uCD94\uCD9C \uD06C\uAE30 \uCD08\uACFC");
         parsedPages++;
         options?.onProgress?.(parsedPages, totalTarget);
       } catch (pageErr) {
         if (pageErr instanceof KordocError) throw pageErr;
+        if (!failedPages.includes(i)) failedPages.push(i);
         warnings.push({ page: i, message: `\uD398\uC774\uC9C0 ${i} \uD30C\uC2F1 \uC2E4\uD328: ${pageErr instanceof Error ? pageErr.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`, code: "PARTIAL_PARSE" });
       }
     };
@@ -6417,8 +6874,21 @@ async function parsePdfDocument(buffer, options) {
     for (const si of sampledIndices) {
       await parseSinglePage(targetPageNums[si]);
     }
-    const sampleParsed = parsedPages || sampledIndices.size;
-    const isImageBased = totalChars / Math.max(sampleParsed, 1) < 10;
+    const sampledMetrics = [];
+    for (const si of sampledIndices) {
+      const pageNum = targetPageNums[si];
+      const m = sampleMetricsByPage.get(pageNum);
+      if (m) sampledMetrics.push(m);
+    }
+    const imageBasedDecision = estimateImageBasedPdf(sampledMetrics);
+    const isImageBased = imageBasedDecision.isImageBased;
+    logger.log({
+      level: "info",
+      stage: "probe",
+      event: "done",
+      message: "\uC774\uBBF8\uC9C0 \uAE30\uBC18 \uD310\uC815",
+      meta: { isImageBased, reason: imageBasedDecision.reason, sampledPages: sampledMetrics.length }
+    });
     if (!isImageBased) {
       for (let si = 0; si < targetPageNums.length; si++) {
         if (!sampledIndices.has(si)) {
@@ -6426,11 +6896,41 @@ async function parsePdfDocument(buffer, options) {
         }
       }
     }
+    const partialSummary = summarizePartialFailures(failedPages, totalTarget);
+    if (partialSummary) {
+      warnings.push({
+        message: partialSummary,
+        code: "PARTIAL_PARSE"
+      });
+    }
+    if (isImageBased) {
+      warnings.push({
+        message: `\uC774\uBBF8\uC9C0 \uAE30\uBC18 \uD310\uC815: ${imageBasedDecision.reason}`,
+        code: "OCR_FALLBACK"
+      });
+    }
+    const partialPolicy = shouldAbortForPartialFailures(
+      failedPages,
+      totalTarget,
+      options?.maxPartialFailureRatio
+    );
+    if (partialPolicy.abort) {
+      throw new KordocError(
+        `\uBD80\uBD84 \uD30C\uC2F1 \uC2E4\uD328 \uBE44\uC728 \uCD08\uACFC: ${(partialPolicy.ratio * 100).toFixed(1)}% (\uD5C8\uC6A9 ${(partialPolicy.threshold * 100).toFixed(1)}%)`
+      );
+    }
     const parsedPageCount = parsedPages || (pageFilter ? pageFilter.size : effectivePageCount);
     if (isImageBased) {
       const ocrMode = options?.ocrMode ?? "auto";
       const concurrency = options?.ocrConcurrency ?? 1;
       const batchSize = options?.ocrBatchSize;
+      logger.log({
+        level: "info",
+        stage: "ocr",
+        event: "start",
+        message: "\uC774\uBBF8\uC9C0 \uAE30\uBC18 PDF OCR \uC2DC\uC791",
+        meta: { ocrMode, concurrency, batchSize, totalTarget }
+      });
       if (ocrMode === "off") {
         throw Object.assign(new KordocError(`\uC774\uBBF8\uC9C0 \uAE30\uBC18 PDF (${pageCount}\uD398\uC774\uC9C0, ${totalChars}\uC790)`), { isImageBased: true });
       }
@@ -6438,8 +6938,10 @@ async function parsePdfDocument(buffer, options) {
       const { ocrPages: ocrPages2 } = await Promise.resolve().then(() => (init_provider(), provider_exports));
       const tryProvider = async (provider, filter) => {
         try {
+          logger.log({ level: "debug", stage: "ocr", event: "progress", message: "OCR provider \uC2E4\uD589", meta: { filteredPages: filter?.size } });
           return await ocrPages2(doc, provider, filter, effectivePageCount, warnings, concurrency, options?.onProgress);
         } catch {
+          logger.log({ level: "warn", stage: "ocr", event: "progress", message: "OCR provider \uC2E4\uD589 \uC2E4\uD328(\uBE48 \uACB0\uACFC\uB85C \uCC98\uB9AC)" });
           return [];
         } finally {
           const terminable = provider;
@@ -6462,6 +6964,7 @@ async function parsePdfDocument(buffer, options) {
         for (const mode of getAutoFallbackChain2()) {
           if (pendingPages.size === 0) break;
           try {
+            logger.log({ level: "info", stage: "ocr", event: "progress", message: "OCR \uC5D4\uC9C4 \uC2DC\uB3C4", meta: { mode, pendingPages: pendingPages.size } });
             const modeFilter = pendingPages.size < effectivePageCount ? new Set(pendingPages) : pageFilter;
             const provider = await resolveOcrProvider2(mode, warnings, concurrency, batchSize);
             const blocks2 = await tryProvider(provider, modeFilter);
@@ -6476,10 +6979,20 @@ async function parsePdfDocument(buffer, options) {
                   code: "OCR_CLI_FALLBACK"
                 });
               }
+              logger.log({ level: "info", stage: "ocr", event: "progress", message: "OCR \uC5D4\uC9C4 \uCC98\uB9AC \uC644\uB8CC", meta: { mode, blocks: blocks2.length, pendingPages: pendingPages.size } });
             } else {
               warnings.push({ message: `OCR: '${mode}' \uACB0\uACFC \uC5C6\uC74C, \uB2E4\uC74C \uC5D4\uC9C4\uC73C\uB85C \uC2DC\uB3C4`, code: "OCR_CLI_FALLBACK" });
+              logger.log({ level: "warn", stage: "ocr", event: "progress", message: "OCR \uC5D4\uC9C4 \uACB0\uACFC \uC5C6\uC74C", meta: { mode } });
             }
-          } catch {
+          } catch (engineErr) {
+            logger.log({
+              level: "warn",
+              stage: "ocr",
+              event: "progress",
+              message: "OCR \uC5D4\uC9C4 \uCD08\uAE30\uD654/\uC2E4\uD589 \uC2E4\uD328",
+              meta: { mode },
+              error: { message: engineErr instanceof Error ? engineErr.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: engineErr instanceof Error ? engineErr.name : "Error" }
+            });
           }
         }
         allOcrBlocks.sort((a, b) => (a.pageNumber ?? 0) - (b.pageNumber ?? 0));
@@ -6497,6 +7010,7 @@ async function parsePdfDocument(buffer, options) {
       }
       if (ocrBlocks.length > 0) {
         const ocrMarkdown = blocksToMarkdown(ocrBlocks);
+        logger.log({ level: "info", stage: "ocr", event: "done", message: "\uC774\uBBF8\uC9C0 \uAE30\uBC18 OCR \uC644\uB8CC", meta: { blocks: ocrBlocks.length } });
         return {
           markdown: ocrMarkdown,
           blocks: ocrBlocks,
@@ -6522,8 +7036,25 @@ async function parsePdfDocument(buffer, options) {
     }
     detectMarkerHeadings(blocks);
     const outline = blocks.filter((b) => b.type === "heading" && b.level && b.text).map((b) => ({ level: b.level, text: b.text, pageNumber: b.pageNumber }));
-    let markdown = cleanPdfText(blocksToMarkdown(blocks));
+    let markdown = cleanPdfText(blocksToMarkdown(blocks), options?.pdfTextNormalization ?? "default");
+    logger.log({
+      level: "info",
+      stage: "finalize",
+      event: "done",
+      message: "PDF \uD30C\uC2F1 \uC644\uB8CC",
+      meta: { blocks: blocks.length, warnings: warnings.length, outline: outline.length, isImageBased: false }
+    });
     return { markdown, blocks, metadata, outline: outline.length > 0 ? outline : void 0, warnings: warnings.length > 0 ? warnings : void 0 };
+  } catch (err) {
+    logger.log({
+      level: "error",
+      stage: "finalize",
+      event: "error",
+      message: "PDF \uD30C\uC2F1 \uC2E4\uD328",
+      meta: { lastParsedPage },
+      error: { message: err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: err instanceof Error ? err.name : "Error", stack: err instanceof Error ? err.stack : void 0 }
+    });
+    throw err;
   } finally {
     await doc.destroy().catch(() => {
     });
@@ -6617,6 +7148,17 @@ function shouldDemoteTable(table) {
   const emptyCells = totalCells - allCells.length;
   if (table.rows <= 2 && emptyCells > totalCells * 0.5) return true;
   if (table.rows === 1 && !/\d{2,}/.test(allText)) return true;
+  if (table.cols >= 3 && table.rows <= 4) {
+    const markerCells = allCells.filter((t) => /^[□■◆○●▶▷◇◆]/.test(t)).length;
+    const numericCells = allCells.filter((t) => /\d/.test(t)).length;
+    if (markerCells >= Math.max(1, Math.floor(allCells.length * 0.35)) && numericCells <= Math.floor(allCells.length * 0.15)) {
+      return true;
+    }
+  }
+  if (table.cols >= 3 && table.rows >= 2) {
+    const sparseRows = table.cells.filter((row) => row.filter((c) => c.text.trim()).length <= 1).length;
+    if (sparseRows >= Math.ceil(table.rows * 0.7)) return true;
+  }
   return false;
 }
 function demoteTableToText(table) {
@@ -7172,10 +7714,15 @@ function mergeLineSimple(items) {
   }
   return result;
 }
-function cleanPdfText(text) {
-  return mergeKoreanLines(
-    text.replace(/^[\s]*[-–—]\s*[-–—]?\d+[-–—]?[\s]*[-–—]?[\s]*$/gm, "").replace(/^\s*\d+\s*\/\s*\d+\s*$/gm, "").replace(/\n\d{1,4}\n/g, "\n").replace(/\n\d{1,4}$/, "")
-  ).replace(/^(?!\|).{3,30}$/gm, (line) => collapseEvenSpacing(line)).replace(/\n{3,}/g, "\n\n").trim();
+function stripPdfPageNumberArtifacts(text) {
+  return text.replace(/^[\s]*[-–—]\s*[-–—]?\d+[-–—]?[\s]*[-–—]?[\s]*$/gm, "").replace(/^\s*\d+\s*\/\s*\d+\s*$/gm, "").replace(/\n\d{1,4}\n/g, "\n").replace(/\n\d{1,4}$/, "");
+}
+function cleanPdfText(text, mode = "default") {
+  const stripped = stripPdfPageNumberArtifacts(text);
+  if (mode === "strict-preserve") {
+    return stripped.replace(/\n{4,}/g, "\n\n\n").trim();
+  }
+  return mergeKoreanLines(stripped).replace(/^(?!\|).{3,30}$/gm, (line) => collapseEvenSpacing(line)).replace(/\n{3,}/g, "\n\n").trim();
 }
 function startsWithMarker(line) {
   const t = line.trimStart();
@@ -7379,6 +7926,7 @@ function mergeKoreanLines(text) {
 // src/xlsx/parser.ts
 var import_jszip3 = __toESM(require("jszip"), 1);
 var import_xmldom2 = require("@xmldom/xmldom");
+init_logger();
 var MAX_SHEETS = 100;
 var MAX_DECOMPRESS_SIZE3 = 500 * 1024 * 1024;
 var MAX_ROWS2 = 1e4;
@@ -7568,105 +8116,145 @@ function sheetToBlocks(sheetName, grid, merges, maxRow, maxCol, sheetIndex) {
   return blocks;
 }
 async function parseXlsxDocument(buffer, options, existingZip) {
-  precheckZipSize(buffer, MAX_DECOMPRESS_SIZE3);
-  const zip = existingZip ?? await import_jszip3.default.loadAsync(buffer);
-  const warnings = [];
-  const workbookFile = zip.file("xl/workbook.xml");
-  if (!workbookFile) {
-    throw new KordocError("\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 XLSX \uD30C\uC77C: xl/workbook.xml\uC774 \uC5C6\uC2B5\uB2C8\uB2E4");
-  }
-  let sharedStrings = [];
-  const ssFile = zip.file("xl/sharedStrings.xml");
-  if (ssFile) {
-    sharedStrings = parseSharedStrings(await ssFile.async("text"));
-  }
-  const sheets = parseWorkbook(await workbookFile.async("text"));
-  if (sheets.length === 0) {
-    throw new KordocError("XLSX \uD30C\uC77C\uC5D0 \uC2DC\uD2B8\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4");
-  }
-  let relsMap = /* @__PURE__ */ new Map();
-  const relsFile = zip.file("xl/_rels/workbook.xml.rels");
-  if (relsFile) {
-    relsMap = parseRels(await relsFile.async("text"));
-  }
-  let pageFilter = null;
-  if (options?.pages) {
-    const { parsePageRange: parsePageRange2 } = await Promise.resolve().then(() => (init_page_range(), page_range_exports));
-    pageFilter = parsePageRange2(options.pages, sheets.length);
-  }
-  const blocks = [];
-  const processedSheets = Math.min(sheets.length, MAX_SHEETS);
-  let totalCells = 0;
-  for (let i = 0; i < processedSheets; i++) {
-    if (pageFilter && !pageFilter.has(i + 1)) continue;
-    const sheet = sheets[i];
-    options?.onProgress?.(i + 1, processedSheets);
-    let sheetPath = relsMap.get(sheet.rId);
-    if (sheetPath) {
-      if (!sheetPath.startsWith("xl/") && !sheetPath.startsWith("/")) {
-        sheetPath = `xl/${sheetPath}`;
-      } else if (sheetPath.startsWith("/")) {
-        sheetPath = sheetPath.slice(1);
-      }
-    } else {
-      sheetPath = `xl/worksheets/sheet${i + 1}.xml`;
-    }
-    const sheetFile = zip.file(sheetPath);
-    if (!sheetFile) {
-      warnings.push({
-        page: i + 1,
-        message: `\uC2DC\uD2B8 "${sheet.name}" \uD30C\uC77C\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${sheetPath}`,
-        code: "PARTIAL_PARSE"
-      });
-      continue;
+  const logger = createLoggerFromEnv().child({ component: "xlsx/parser.ts", stage: "detect" });
+  logger.log({ level: "info", event: "start", message: "XLSX \uD30C\uC2F1 \uC2DC\uC791", meta: { size: buffer.byteLength } });
+  let lastProcessedSheet = 0;
+  try {
+    precheckZipSize(buffer, MAX_DECOMPRESS_SIZE3);
+    const zip = existingZip ?? await import_jszip3.default.loadAsync(buffer);
+    const warnings = [];
+    const workbookFile = zip.file("xl/workbook.xml");
+    if (!workbookFile) {
+      throw new KordocError("\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 XLSX \uD30C\uC77C: xl/workbook.xml\uC774 \uC5C6\uC2B5\uB2C8\uB2E4");
+    }
+    let sharedStrings = [];
+    const ssFile = zip.file("xl/sharedStrings.xml");
+    if (ssFile) {
+      sharedStrings = parseSharedStrings(await ssFile.async("text"));
+    }
+    const sheets = parseWorkbook(await workbookFile.async("text"));
+    if (sheets.length === 0) {
+      throw new KordocError("XLSX \uD30C\uC77C\uC5D0 \uC2DC\uD2B8\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4");
+    }
+    logger.log({ level: "debug", event: "progress", message: "\uC2DC\uD2B8 \uBAA9\uB85D \uB85C\uB4DC", meta: { sheets: sheets.length } });
+    let relsMap = /* @__PURE__ */ new Map();
+    const relsFile = zip.file("xl/_rels/workbook.xml.rels");
+    if (relsFile) {
+      relsMap = parseRels(await relsFile.async("text"));
+    }
+    let pageFilter = null;
+    if (options?.pages) {
+      const { parsePageRange: parsePageRange2 } = await Promise.resolve().then(() => (init_page_range(), page_range_exports));
+      pageFilter = parsePageRange2(options.pages, sheets.length);
     }
-    try {
-      const sheetXml = await sheetFile.async("text");
-      const { grid, merges, maxRow, maxCol } = parseWorksheet(sheetXml, sharedStrings);
-      totalCells += maxRow * maxCol;
-      if (totalCells > MAX_TOTAL_CELLS) {
-        warnings.push({ message: `\uCD1D \uC140 \uC218 \uC81C\uD55C \uCD08\uACFC (${totalCells.toLocaleString()}\uC140), \uC774\uD6C4 \uC2DC\uD2B8 \uC0DD\uB7B5`, code: "PARTIAL_PARSE" });
-        break;
+    const blocks = [];
+    const processedSheets = Math.min(sheets.length, MAX_SHEETS);
+    let totalCells = 0;
+    for (let i = 0; i < processedSheets; i++) {
+      if (pageFilter && !pageFilter.has(i + 1)) continue;
+      const sheet = sheets[i];
+      options?.onProgress?.(i + 1, processedSheets);
+      let sheetPath = relsMap.get(sheet.rId);
+      if (sheetPath) {
+        if (!sheetPath.startsWith("xl/") && !sheetPath.startsWith("/")) {
+          sheetPath = `xl/${sheetPath}`;
+        } else if (sheetPath.startsWith("/")) {
+          sheetPath = sheetPath.slice(1);
+        }
+      } else {
+        sheetPath = `xl/worksheets/sheet${i + 1}.xml`;
+      }
+      const sheetFile = zip.file(sheetPath);
+      if (!sheetFile) {
+        warnings.push({
+          page: i + 1,
+          message: `\uC2DC\uD2B8 "${sheet.name}" \uD30C\uC77C\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${sheetPath}`,
+          code: "PARTIAL_PARSE"
+        });
+        continue;
+      }
+      try {
+        const sheetXml = await sheetFile.async("text");
+        const { grid, merges, maxRow, maxCol } = parseWorksheet(sheetXml, sharedStrings);
+        totalCells += maxRow * maxCol;
+        if (totalCells > MAX_TOTAL_CELLS) {
+          warnings.push({ message: `\uCD1D \uC140 \uC218 \uC81C\uD55C \uCD08\uACFC (${totalCells.toLocaleString()}\uC140), \uC774\uD6C4 \uC2DC\uD2B8 \uC0DD\uB7B5`, code: "PARTIAL_PARSE" });
+          break;
+        }
+        const sheetBlocks = sheetToBlocks(sheet.name, grid, merges, maxRow, maxCol, i);
+        blocks.push(...sheetBlocks);
+        logger.log({
+          level: "debug",
+          stage: "convert",
+          event: "progress",
+          message: "\uC2DC\uD2B8 \uD30C\uC2F1 \uC644\uB8CC",
+          meta: { sheet: sheet.name, index: i + 1, processedSheets }
+        });
+        lastProcessedSheet = i + 1;
+      } catch (err) {
+        warnings.push({
+          page: i + 1,
+          message: `\uC2DC\uD2B8 "${sheet.name}" \uD30C\uC2F1 \uC2E4\uD328: ${err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`,
+          code: "PARTIAL_PARSE"
+        });
+        logger.log({
+          level: "warn",
+          stage: "convert",
+          event: "progress",
+          message: "\uC2DC\uD2B8 \uD30C\uC2F1 \uC2E4\uD328",
+          meta: { sheet: sheet.name, index: i + 1 },
+          error: { message: err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: err instanceof Error ? err.name : "Error" }
+        });
       }
-      const sheetBlocks = sheetToBlocks(sheet.name, grid, merges, maxRow, maxCol, i);
-      blocks.push(...sheetBlocks);
-    } catch (err) {
-      warnings.push({
-        page: i + 1,
-        message: `\uC2DC\uD2B8 "${sheet.name}" \uD30C\uC2F1 \uC2E4\uD328: ${err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958"}`,
-        code: "PARTIAL_PARSE"
-      });
     }
-  }
-  const metadata = {
-    pageCount: processedSheets
-  };
-  const coreFile = zip.file("docProps/core.xml");
-  if (coreFile) {
-    try {
-      const coreXml = await coreFile.async("text");
-      const doc = parseXml(coreXml);
-      const getFirst = (tag) => {
-        const els = doc.getElementsByTagName(tag);
-        return els.length > 0 ? (els[0].textContent ?? "").trim() : void 0;
-      };
-      metadata.title = getFirst("dc:title") || getFirst("dcterms:title");
-      metadata.author = getFirst("dc:creator");
-      metadata.description = getFirst("dc:description");
-      const created = getFirst("dcterms:created");
-      if (created) metadata.createdAt = created;
-      const modified = getFirst("dcterms:modified");
-      if (modified) metadata.modifiedAt = modified;
-    } catch {
+    const metadata = {
+      pageCount: processedSheets
+    };
+    const coreFile = zip.file("docProps/core.xml");
+    if (coreFile) {
+      try {
+        const coreXml = await coreFile.async("text");
+        const doc = parseXml(coreXml);
+        const getFirst = (tag) => {
+          const els = doc.getElementsByTagName(tag);
+          return els.length > 0 ? (els[0].textContent ?? "").trim() : void 0;
+        };
+        metadata.title = getFirst("dc:title") || getFirst("dcterms:title");
+        metadata.author = getFirst("dc:creator");
+        metadata.description = getFirst("dc:description");
+        const created = getFirst("dcterms:created");
+        if (created) metadata.createdAt = created;
+        const modified = getFirst("dcterms:modified");
+        if (modified) metadata.modifiedAt = modified;
+      } catch {
+      }
     }
+    const markdown = blocksToMarkdown(blocks);
+    logger.log({
+      level: "info",
+      stage: "finalize",
+      event: "done",
+      message: "XLSX \uD30C\uC2F1 \uC644\uB8CC",
+      meta: { blocks: blocks.length, warnings: warnings.length, pageCount: processedSheets }
+    });
+    return { markdown, blocks, metadata, warnings: warnings.length > 0 ? warnings : void 0 };
+  } catch (err) {
+    logger.log({
+      level: "error",
+      stage: "finalize",
+      event: "error",
+      message: "XLSX \uD30C\uC2F1 \uC2E4\uD328",
+      meta: { lastProcessedSheet },
+      error: { message: err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: err instanceof Error ? err.name : "Error", stack: err instanceof Error ? err.stack : void 0 }
+    });
+    throw err;
   }
-  const markdown = blocksToMarkdown(blocks);
-  return { markdown, blocks, metadata, warnings: warnings.length > 0 ? warnings : void 0 };
 }
 
 // src/docx/parser.ts
 var import_jszip4 = __toESM(require("jszip"), 1);
 var import_xmldom3 = require("@xmldom/xmldom");
+init_logger();
 var MAX_DECOMPRESS_SIZE4 = 500 * 1024 * 1024;
 function getChildElements(parent, localName) {
   const result = [];
@@ -8028,101 +8616,127 @@ async function extractImages(zip, rels, doc) {
   return { blocks, images };
 }
 async function parseDocxDocument(buffer, options, existingZip) {
-  precheckZipSize(buffer, MAX_DECOMPRESS_SIZE4);
-  const zip = existingZip ?? await import_jszip4.default.loadAsync(buffer);
-  const warnings = [];
-  const docFile = zip.file("word/document.xml");
-  if (!docFile) {
-    throw new KordocError("\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 DOCX \uD30C\uC77C: word/document.xml\uC774 \uC5C6\uC2B5\uB2C8\uB2E4");
-  }
-  let rels = /* @__PURE__ */ new Map();
-  const relsFile = zip.file("word/_rels/document.xml.rels");
-  if (relsFile) {
-    rels = parseRels2(await relsFile.async("text"));
-  }
-  let styles = /* @__PURE__ */ new Map();
-  const stylesFile = zip.file("word/styles.xml");
-  if (stylesFile) {
-    try {
-      styles = parseStyles(await stylesFile.async("text"));
-    } catch {
+  const logger = createLoggerFromEnv().child({ component: "docx/parser.ts", stage: "detect" });
+  logger.log({ level: "info", event: "start", message: "DOCX \uD30C\uC2F1 \uC2DC\uC791", meta: { size: buffer.byteLength } });
+  let lastProcessedNode = 0;
+  try {
+    precheckZipSize(buffer, MAX_DECOMPRESS_SIZE4);
+    const zip = existingZip ?? await import_jszip4.default.loadAsync(buffer);
+    const warnings = [];
+    const docFile = zip.file("word/document.xml");
+    if (!docFile) {
+      throw new KordocError("\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 DOCX \uD30C\uC77C: word/document.xml\uC774 \uC5C6\uC2B5\uB2C8\uB2E4");
+    }
+    let rels = /* @__PURE__ */ new Map();
+    const relsFile = zip.file("word/_rels/document.xml.rels");
+    if (relsFile) {
+      rels = parseRels2(await relsFile.async("text"));
+    }
+    let styles = /* @__PURE__ */ new Map();
+    const stylesFile = zip.file("word/styles.xml");
+    if (stylesFile) {
+      try {
+        styles = parseStyles(await stylesFile.async("text"));
+      } catch {
+      }
     }
-  }
-  let numbering = /* @__PURE__ */ new Map();
-  const numFile = zip.file("word/numbering.xml");
-  if (numFile) {
-    try {
-      numbering = parseNumbering(await numFile.async("text"));
-    } catch {
+    let numbering = /* @__PURE__ */ new Map();
+    const numFile = zip.file("word/numbering.xml");
+    if (numFile) {
+      try {
+        numbering = parseNumbering(await numFile.async("text"));
+      } catch {
+      }
     }
-  }
-  let footnotes = /* @__PURE__ */ new Map();
-  const fnFile = zip.file("word/footnotes.xml");
-  if (fnFile) {
-    try {
-      footnotes = parseFootnotes(await fnFile.async("text"));
-    } catch {
+    let footnotes = /* @__PURE__ */ new Map();
+    const fnFile = zip.file("word/footnotes.xml");
+    if (fnFile) {
+      try {
+        footnotes = parseFootnotes(await fnFile.async("text"));
+      } catch {
+      }
     }
-  }
-  const docXml = await docFile.async("text");
-  const doc = parseXml2(docXml);
-  const body = findElements(doc, "body");
-  if (body.length === 0) {
-    throw new KordocError("DOCX \uBCF8\uBB38(w:body)\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4");
-  }
-  const blocks = [];
-  const bodyEl = body[0];
-  const children = bodyEl.childNodes;
-  for (let i = 0; i < children.length; i++) {
-    const node = children[i];
-    if (node.nodeType !== 1) continue;
-    const el = node;
-    const localName = el.localName ?? el.tagName?.split(":").pop();
-    if (localName === "p") {
-      const block = parseParagraph(el, styles, numbering, footnotes, rels);
-      if (block) blocks.push(block);
-    } else if (localName === "tbl") {
-      const block = parseTable(el, styles, numbering, footnotes, rels);
-      if (block) blocks.push(block);
-    }
-  }
-  const { blocks: imgBlocks, images } = await extractImages(zip, rels, doc);
-  const metadata = {};
-  const coreFile = zip.file("docProps/core.xml");
-  if (coreFile) {
-    try {
-      const coreXml = await coreFile.async("text");
-      const coreDoc = parseXml2(coreXml);
-      const getFirst = (tag) => {
-        const els = coreDoc.getElementsByTagName(tag);
-        return els.length > 0 ? (els[0].textContent ?? "").trim() : void 0;
-      };
-      metadata.title = getFirst("dc:title") || getFirst("dcterms:title");
-      metadata.author = getFirst("dc:creator");
-      metadata.description = getFirst("dc:description");
-      const created = getFirst("dcterms:created");
-      if (created) metadata.createdAt = created;
-      const modified = getFirst("dcterms:modified");
-      if (modified) metadata.modifiedAt = modified;
-    } catch {
+    const docXml = await docFile.async("text");
+    const doc = parseXml2(docXml);
+    const body = findElements(doc, "body");
+    if (body.length === 0) {
+      throw new KordocError("DOCX \uBCF8\uBB38(w:body)\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4");
     }
+    const blocks = [];
+    const bodyEl = body[0];
+    const children = bodyEl.childNodes;
+    for (let i = 0; i < children.length; i++) {
+      const node = children[i];
+      if (node.nodeType !== 1) continue;
+      const el = node;
+      const localName = el.localName ?? el.tagName?.split(":").pop();
+      if (localName === "p") {
+        const block = parseParagraph(el, styles, numbering, footnotes, rels);
+        if (block) blocks.push(block);
+      } else if (localName === "tbl") {
+        const block = parseTable(el, styles, numbering, footnotes, rels);
+        if (block) blocks.push(block);
+      }
+      lastProcessedNode = i + 1;
+    }
+    logger.log({ level: "debug", stage: "convert", event: "progress", message: "\uBCF8\uBB38 \uBE14\uB85D \uD30C\uC2F1 \uC644\uB8CC", meta: { blocks: blocks.length } });
+    const { blocks: imgBlocks, images } = await extractImages(zip, rels, doc);
+    logger.log({ level: "debug", stage: "convert", event: "progress", message: "\uC774\uBBF8\uC9C0 \uCD94\uCD9C \uC644\uB8CC", meta: { imageBlocks: imgBlocks.length, images: images.length } });
+    const metadata = {};
+    const coreFile = zip.file("docProps/core.xml");
+    if (coreFile) {
+      try {
+        const coreXml = await coreFile.async("text");
+        const coreDoc = parseXml2(coreXml);
+        const getFirst = (tag) => {
+          const els = coreDoc.getElementsByTagName(tag);
+          return els.length > 0 ? (els[0].textContent ?? "").trim() : void 0;
+        };
+        metadata.title = getFirst("dc:title") || getFirst("dcterms:title");
+        metadata.author = getFirst("dc:creator");
+        metadata.description = getFirst("dc:description");
+        const created = getFirst("dcterms:created");
+        if (created) metadata.createdAt = created;
+        const modified = getFirst("dcterms:modified");
+        if (modified) metadata.modifiedAt = modified;
+      } catch {
+      }
+    }
+    const outline = blocks.filter((b) => b.type === "heading").map((b) => ({ level: b.level ?? 2, text: b.text ?? "" }));
+    const markdown = blocksToMarkdown(blocks);
+    logger.log({
+      level: "info",
+      stage: "finalize",
+      event: "done",
+      message: "DOCX \uD30C\uC2F1 \uC644\uB8CC",
+      meta: { blocks: blocks.length, warnings: warnings.length, outline: outline.length, images: images.length }
+    });
+    return {
+      markdown,
+      blocks,
+      metadata,
+      outline: outline.length > 0 ? outline : void 0,
+      warnings: warnings.length > 0 ? warnings : void 0,
+      images: images.length > 0 ? images : void 0
+    };
+  } catch (err) {
+    logger.log({
+      level: "error",
+      stage: "finalize",
+      event: "error",
+      message: "DOCX \uD30C\uC2F1 \uC2E4\uD328",
+      meta: { lastProcessedNode },
+      error: { message: err instanceof Error ? err.message : "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958", name: err instanceof Error ? err.name : "Error", stack: err instanceof Error ? err.stack : void 0 }
+    });
+    throw err;
   }
-  const outline = blocks.filter((b) => b.type === "heading").map((b) => ({ level: b.level ?? 2, text: b.text ?? "" }));
-  const markdown = blocksToMarkdown(blocks);
-  return {
-    markdown,
-    blocks,
-    metadata,
-    outline: outline.length > 0 ? outline : void 0,
-    warnings: warnings.length > 0 ? warnings : void 0,
-    images: images.length > 0 ? images : void 0
-  };
 }
 
 // src/index.ts
 init_cli_provider();
 init_tesseract_provider();
 init_markdown_to_blocks();
+init_logger();
 
 // src/diff/text-diff.ts
 function similarity(a, b) {
@@ -10621,15 +11235,726 @@ async function markdownToXlsx(markdown, options) {
   return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
 }
 
+// src/ocr/api-key-rotation.ts
+var AllKeysCoolingDownError = class extends Error {
+  waitMs;
+  constructor(waitMs) {
+    super(`\uBAA8\uB4E0 API \uD0A4\uAC00 cooldown \uC0C1\uD0DC\uC785\uB2C8\uB2E4. ${waitMs}ms \uD6C4 \uC7AC\uC2DC\uB3C4\uD558\uC138\uC694.`);
+    this.name = "AllKeysCoolingDownError";
+    this.waitMs = waitMs;
+  }
+};
+var ApiKeyRotationPool = class _ApiKeyRotationPool {
+  states;
+  baseCooldownMs;
+  maxCooldownMs;
+  cursor = -1;
+  constructor(keys, options = {}) {
+    const normalized = keys.map((k) => k.trim()).filter(Boolean);
+    if (normalized.length === 0) {
+      throw new Error("API \uD0A4\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    }
+    this.states = normalized.map((key, idx) => ({
+      key,
+      keyId: `key_${idx + 1}`,
+      totalRequests: 0,
+      successCount: 0,
+      failureCount: 0,
+      consecutiveFailures: 0
+    }));
+    this.baseCooldownMs = options.baseCooldownMs ?? 5e3;
+    this.maxCooldownMs = options.maxCooldownMs ?? 12e4;
+  }
+  static fromEnv(env = process.env) {
+    const multi = (env.NVIDIA_API_KEYS || "").split(",").map((v) => v.trim()).filter(Boolean);
+    if (multi.length > 0) return new _ApiKeyRotationPool(multi);
+    const single = (env.NVIDIA_API_KEY || "").trim();
+    if (single) return new _ApiKeyRotationPool([single]);
+    throw new Error("NVIDIA_API_KEYS \uB610\uB294 NVIDIA_API_KEY \uD658\uACBD\uBCC0\uC218\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");
+  }
+  acquire(now = Date.now()) {
+    const n = this.states.length;
+    for (let step = 1; step <= n; step++) {
+      const idx = (this.cursor + step) % n;
+      const s = this.states[idx];
+      if (!s.cooldownUntil || s.cooldownUntil <= now) {
+        this.cursor = idx;
+        s.totalRequests++;
+        s.lastUsedAt = now;
+        return { key: s.key, keyId: s.keyId };
+      }
+    }
+    const minCooldownUntil = this.states.map((s) => s.cooldownUntil ?? now).reduce((min, v) => Math.min(min, v), Number.POSITIVE_INFINITY);
+    throw new AllKeysCoolingDownError(Math.max(0, minCooldownUntil - now));
+  }
+  markSuccess(keyId) {
+    const s = this.find(keyId);
+    s.successCount++;
+    s.consecutiveFailures = 0;
+    s.cooldownUntil = void 0;
+  }
+  markFailure(keyId, opts = {}, now = Date.now()) {
+    const s = this.find(keyId);
+    s.failureCount++;
+    s.consecutiveFailures++;
+    const retryable = this.isRetryableFailure(opts.status, opts.timeout);
+    if (!retryable) return;
+    const exp = Math.max(0, s.consecutiveFailures - 1);
+    const backoff = Math.min(this.baseCooldownMs * 2 ** exp, this.maxCooldownMs);
+    const cooldown = Math.max(backoff, opts.retryAfterMs ?? 0);
+    s.cooldownUntil = now + cooldown;
+  }
+  snapshot() {
+    return this.states.map((s) => ({
+      keyId: s.keyId,
+      totalRequests: s.totalRequests,
+      successCount: s.successCount,
+      failureCount: s.failureCount,
+      consecutiveFailures: s.consecutiveFailures,
+      lastUsedAt: s.lastUsedAt,
+      cooldownUntil: s.cooldownUntil
+    }));
+  }
+  isRetryableFailure(status, timeout) {
+    if (timeout) return true;
+    if (status === 429) return true;
+    if (typeof status === "number" && status >= 500) return true;
+    return false;
+  }
+  find(keyId) {
+    const s = this.states.find((v) => v.keyId === keyId);
+    if (!s) throw new Error(`\uC54C \uC218 \uC5C6\uB294 keyId: ${keyId}`);
+    return s;
+  }
+};
+
+// src/pipeline/unified-ocr.ts
+var import_promises2 = require("fs/promises");
+var import_path5 = require("path");
+var import_child_process4 = require("child_process");
+var import_libreoffice_convert = __toESM(require("libreoffice-convert"), 1);
+init_logger();
+var libreConvert = import_libreoffice_convert.default.convert;
+var UnifiedOcrError = class extends Error {
+  code;
+  stage;
+  constructor(code, stage, message) {
+    super(message);
+    this.name = "UnifiedOcrError";
+    this.code = code;
+    this.stage = stage;
+  }
+};
+var DEFAULT_MODELS = [
+  "mistralai/mistral-medium-3-instruct",
+  "moonshotai/kimi-k2.5",
+  "moonshotai/kimi-k2-thinking",
+  "moonshotai/kimi-k2-instruct",
+  "moonshotai/kimi-k2-instruct-0905",
+  "qwen/qwen3.5-122b-a10b",
+  "qwen/qwen3.5-397b-a17b"
+];
+var DEFAULT_MODEL_MAX_TOKENS = {
+  "mistralai/mistral-medium-3-instruct": 8192,
+  "moonshotai/kimi-k2.5": 64e3,
+  "moonshotai/kimi-k2-thinking": 64e3,
+  "moonshotai/kimi-k2-instruct": 64e3,
+  "moonshotai/kimi-k2-instruct-0905": 64e3,
+  "qwen/qwen3.5-122b-a10b": 64e3,
+  "qwen/qwen3.5-397b-a17b": 64e3
+};
+var DEFAULT_STAGE_WEIGHTS = {
+  convert: 15,
+  render: 20,
+  probe: 5,
+  ocr: 45,
+  proofread: 10,
+  merge: 5
+};
+var OCR_PROMPT2 = "\uC774 \uC774\uBBF8\uC9C0 1\uC7A5\uC758 \uD14D\uC2A4\uD2B8\uC640 \uD45C\uB97C \uC694\uC57D \uC5C6\uC774 \uADF8\uB300\uB85C Markdown\uC73C\uB85C \uCD94\uCD9C\uD558\uC138\uC694. \uC808\uB300\uB85C \uB0B4\uC6A9\uC744 \uCD94\uCE21\uD558\uAC70\uB098 \uBC14\uAFB8\uC9C0 \uB9C8\uC138\uC694.";
+var PROOFREAD_PROMPT = [
+  "\uC544\uB798 Markdown\uC744 \uBE44\uD30C\uAD34 \uAD50\uC815\uB9CC \uC218\uD589\uD558\uC138\uC694.",
+  "\uADDC\uCE59:",
+  "- \uC0AC\uC2E4 \uCD94\uAC00/\uC0AD\uC81C/\uCD94\uCE21 \uAE08\uC9C0",
+  "- \uC22B\uC790, \uB2E8\uC704, \uACE0\uC720\uBA85\uC0AC \uBCC0\uACBD \uAE08\uC9C0",
+  "- \uC624\uD0C8\uC790, \uB744\uC5B4\uC4F0\uAE30, \uC904\uBC14\uAFC8, Markdown \uAD6C\uC870\uB9CC \uAD50\uC815",
+  "- \uACB0\uACFC\uB294 Markdown \uBCF8\uBB38\uB9CC \uCD9C\uB825"
+].join("\n");
+async function runUnifiedOcrPipeline(inputPath, options = {}) {
+  const absInput = (0, import_path5.resolve)(inputPath);
+  const stem = (0, import_path5.basename)(absInput, (0, import_path5.extname)(absInput));
+  const workspaceDir = (0, import_path5.resolve)(options.workspaceDir ?? (0, import_path5.join)((0, import_path5.dirname)(absInput), `${stem}_ocr_workspace`));
+  const imagesDir = (0, import_path5.join)(workspaceDir, "images");
+  const rawDir = (0, import_path5.join)(workspaceDir, "ocr", "raw");
+  const proofDir = (0, import_path5.join)(workspaceDir, "ocr", "proofread");
+  const diffDir = (0, import_path5.join)(workspaceDir, "ocr", "diff");
+  const outputPath = (0, import_path5.resolve)(options.outputPath ?? (0, import_path5.join)((0, import_path5.dirname)(absInput), `${stem}.md`));
+  const reportPath = (0, import_path5.join)(workspaceDir, "run-report.json");
+  const modelCachePath = (0, import_path5.join)((0, import_path5.dirname)(absInput), ".kordoc-model-cache.json");
+  const baseUrl = options.baseUrl ?? "https://integrate.api.nvidia.com/v1/chat/completions";
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  const maxRetriesPerPage = options.maxRetriesPerPage ?? 5;
+  const dpi = options.dpi ?? 300;
+  const modelsInput = options.modelCandidates?.length ? options.modelCandidates : DEFAULT_MODELS;
+  const modelCache = await loadModelCache(modelCachePath);
+  const models = sortModelsByCache(modelsInput, modelCache);
+  const modelMaxTokens = { ...DEFAULT_MODEL_MAX_TOKENS, ...options.modelMaxTokens ?? {} };
+  const stageWeights = normalizeWeights({ ...DEFAULT_STAGE_WEIGHTS, ...options.stageWeights ?? {} });
+  const keyPool = ApiKeyRotationPool.fromEnv();
+  const runId = options.runId ?? generateRunId("ocr");
+  const logger = (options.logger ?? createLoggerFromEnv()).withRun(runId).child({ component: "pipeline/unified-ocr.ts" });
+  await (0, import_promises2.mkdir)(imagesDir, { recursive: true });
+  await (0, import_promises2.mkdir)(rawDir, { recursive: true });
+  await (0, import_promises2.mkdir)(proofDir, { recursive: true });
+  await (0, import_promises2.mkdir)(diffDir, { recursive: true });
+  const timingsMs = {};
+  const markStageStart = (stage, message) => emitProgress(options.onEvent, stage, 0, stageWeights, { message, type: "stage_start" });
+  const markStageProgress = (stage, stagePercent, current, total, message) => emitProgress(options.onEvent, stage, stagePercent, stageWeights, { type: "stage_progress", current, total, message });
+  const markStageDone = (stage, message) => emitProgress(options.onEvent, stage, 100, stageWeights, { message, type: "stage_done" });
+  let currentStage = "convert";
+  const logStage = (level, stage, event, message, meta) => {
+    logger.log({ level, stage, event, message, meta });
+  };
+  try {
+    ensureSupportedInput(absInput);
+    let workingPdfPath = absInput;
+    const convertStart = Date.now();
+    currentStage = "convert";
+    markStageStart("convert", "\uBB38\uC11C\uB97C PDF\uB85C \uBCC0\uD658 \uC911");
+    logStage("info", "convert", "start", "\uBB38\uC11C\uB97C PDF\uB85C \uBCC0\uD658 \uC2DC\uC791", { input: absInput });
+    if ((0, import_path5.extname)(absInput).toLowerCase() !== ".pdf") {
+      await assertSofficeAvailable();
+      workingPdfPath = (0, import_path5.join)(workspaceDir, `${stem}.pdf`);
+      const inputBuffer = await (0, import_promises2.readFile)(absInput);
+      const out = await convertWithLibreOffice(inputBuffer, ".pdf");
+      await (0, import_promises2.writeFile)(workingPdfPath, out);
+    }
+    timingsMs.convert = Date.now() - convertStart;
+    markStageDone("convert", "PDF \uBCC0\uD658 \uC644\uB8CC");
+    logStage("info", "convert", "done", "PDF \uBCC0\uD658 \uC644\uB8CC", { elapsedMs: timingsMs.convert });
+    const renderStart = Date.now();
+    currentStage = "render";
+    markStageStart("render", "PDF \uD398\uC774\uC9C0 \uC774\uBBF8\uC9C0 \uC0DD\uC131 \uC911");
+    logStage("info", "render", "start", "PDF \uD398\uC774\uC9C0 \uB80C\uB354\uB9C1 \uC2DC\uC791", { pdf: workingPdfPath, dpi });
+    await renderPdfToPng(workingPdfPath, (0, import_path5.join)(imagesDir, "page"), dpi);
+    const images = await listPageImages(imagesDir);
+    if (images.length === 0) throw new UnifiedOcrError("RENDER_FAILED", "render", "\uD398\uC774\uC9C0 \uC774\uBBF8\uC9C0 \uC0DD\uC131 \uC2E4\uD328: \uACB0\uACFC \uC774\uBBF8\uC9C0\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    markStageProgress("render", 100, images.length, images.length, `\uD398\uC774\uC9C0 ${images.length}\uC7A5 \uC0DD\uC131`);
+    timingsMs.render = Date.now() - renderStart;
+    markStageDone("render", "\uC774\uBBF8\uC9C0 \uC0DD\uC131 \uC644\uB8CC");
+    logStage("info", "render", "done", "\uD398\uC774\uC9C0 \uC774\uBBF8\uC9C0 \uC0DD\uC131 \uC644\uB8CC", { pages: images.length, elapsedMs: timingsMs.render });
+    const probeStart = Date.now();
+    currentStage = "probe";
+    markStageStart("probe", "\uBAA8\uB378 \uC18D\uB3C4 \uD504\uB85C\uBE0C \uC218\uD589 \uC911");
+    logStage("info", "probe", "start", "\uBAA8\uB378 \uC18D\uB3C4 \uD504\uB85C\uBE0C \uC2DC\uC791", { models });
+    const probeImage = await pickRepresentativeImage(images);
+    const probeResults = [];
+    for (let i = 0; i < models.length; i++) {
+      const model = models[i];
+      const t0 = Date.now();
+      try {
+        await ocrImageViaNim({
+          imagePath: probeImage,
+          prompt: OCR_PROMPT2,
+          model,
+          maxTokens: modelMaxTokens[model] ?? 8192,
+          baseUrl,
+          keyPool,
+          timeoutMs,
+          maxRetries: 2,
+          logger,
+          stage: "probe"
+        });
+        probeResults.push({ model, durationMs: Date.now() - t0, success: true });
+      } catch (err) {
+        probeResults.push({
+          model,
+          durationMs: Date.now() - t0,
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+      markStageProgress("probe", Math.round((i + 1) / models.length * 100), i + 1, models.length, `\uBAA8\uB378 \uD504\uB85C\uBE0C ${i + 1}/${models.length}`);
+      logStage("debug", "probe", "progress", "\uBAA8\uB378 \uD504\uB85C\uBE0C \uC9C4\uD589", { index: i + 1, total: models.length, model, result: probeResults.at(-1) });
+    }
+    const selectedModel = chooseFastestModel(probeResults);
+    if (!selectedModel) throw new UnifiedOcrError("PROBE_FAILED", "probe", "\uC18D\uB3C4 \uD504\uB85C\uBE0C \uC2E4\uD328: \uC0AC\uC6A9 \uAC00\uB2A5\uD55C OCR \uBAA8\uB378\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    const fallbackModelOrder = probeResults.filter((r) => r.success).sort((a, b) => a.durationMs - b.durationMs).map((r) => r.model);
+    timingsMs.probe = Date.now() - probeStart;
+    await updateModelCache(modelCachePath, probeResults);
+    markStageDone("probe", `\uD504\uB85C\uBE0C \uC644\uB8CC: ${selectedModel}`);
+    logStage("info", "probe", "done", "\uBAA8\uB378 \uD504\uB85C\uBE0C \uC644\uB8CC", { selectedModel, probeResults, elapsedMs: timingsMs.probe, modelCachePath });
+    const ocrStart = Date.now();
+    currentStage = "ocr";
+    markStageStart("ocr", `OCR \uC9C4\uD589 \uC911 (${selectedModel})`);
+    logStage("info", "ocr", "start", "\uD398\uC774\uC9C0 OCR \uC2DC\uC791", { selectedModel, pageCount: images.length });
+    const rawPagePaths = [];
+    for (let i = 0; i < images.length; i++) {
+      const imagePath = images[i];
+      const markdown = await ocrImageWithFallback({
+        imagePath,
+        prompt: OCR_PROMPT2,
+        models: fallbackModelOrder,
+        modelMaxTokens,
+        baseUrl,
+        keyPool,
+        timeoutMs,
+        maxRetriesPerPage,
+        logger
+      });
+      const pagePath = (0, import_path5.join)(rawDir, `page_${String(i + 1).padStart(4, "0")}.md`);
+      await (0, import_promises2.writeFile)(pagePath, markdown, "utf-8");
+      rawPagePaths.push(pagePath);
+      markStageProgress("ocr", Math.round((i + 1) / images.length * 100), i + 1, images.length, `OCR ${i + 1}/${images.length}`);
+      logStage("debug", "ocr", "progress", "\uD398\uC774\uC9C0 OCR \uC644\uB8CC", { page: i + 1, total: images.length });
+    }
+    timingsMs.ocr = Date.now() - ocrStart;
+    markStageDone("ocr", "OCR \uC644\uB8CC");
+    logStage("info", "ocr", "done", "\uD398\uC774\uC9C0 OCR \uC644\uB8CC", { elapsedMs: timingsMs.ocr });
+    const proofStart = Date.now();
+    currentStage = "proofread";
+    markStageStart("proofread", "\uBE44\uD30C\uAD34 \uAD50\uC815 \uC9C4\uD589 \uC911");
+    logStage("info", "proofread", "start", "\uBE44\uD30C\uAD34 \uAD50\uC815 \uC2DC\uC791", { pages: rawPagePaths.length });
+    const proofedPaths = [];
+    for (let i = 0; i < rawPagePaths.length; i++) {
+      const rawMd = await (0, import_promises2.readFile)(rawPagePaths[i], "utf-8");
+      const prompt = `${PROOFREAD_PROMPT}
+
+---
+${rawMd}
+---`;
+      const corrected = await ocrImageViaNim({
+        textOnlyPrompt: prompt,
+        model: selectedModel,
+        maxTokens: modelMaxTokens[selectedModel] ?? 8192,
+        baseUrl,
+        keyPool,
+        timeoutMs,
+        maxRetries: maxRetriesPerPage,
+        logger,
+        stage: "proofread"
+      });
+      const safeCorrected = preserveNumericIntegrity(rawMd, corrected);
+      const taggedCorrected = addUncertainTag(rawMd, safeCorrected);
+      const pagePath = (0, import_path5.join)(proofDir, `page_${String(i + 1).padStart(4, "0")}.md`);
+      await (0, import_promises2.writeFile)(pagePath, taggedCorrected, "utf-8");
+      await (0, import_promises2.writeFile)(
+        (0, import_path5.join)(diffDir, `page_${String(i + 1).padStart(4, "0")}.json`),
+        JSON.stringify(buildDiffSummary(rawMd, taggedCorrected), null, 2),
+        "utf-8"
+      );
+      proofedPaths.push(pagePath);
+      markStageProgress("proofread", Math.round((i + 1) / rawPagePaths.length * 100), i + 1, rawPagePaths.length, `\uAD50\uC815 ${i + 1}/${rawPagePaths.length}`);
+      logStage("debug", "proofread", "progress", "\uD398\uC774\uC9C0 \uAD50\uC815 \uC644\uB8CC", { page: i + 1, total: rawPagePaths.length });
+    }
+    timingsMs.proofread = Date.now() - proofStart;
+    markStageDone("proofread", "\uAD50\uC815 \uC644\uB8CC");
+    logStage("info", "proofread", "done", "\uBE44\uD30C\uAD34 \uAD50\uC815 \uC644\uB8CC", { elapsedMs: timingsMs.proofread });
+    const mergeStart = Date.now();
+    currentStage = "merge";
+    markStageStart("merge", "\uCD5C\uC885 Markdown \uBCD1\uD569 \uC911");
+    logStage("info", "merge", "start", "\uCD5C\uC885 \uBCD1\uD569 \uC2DC\uC791", { pages: proofedPaths.length });
+    const merged = await mergeMarkdownPages(proofedPaths);
+    await (0, import_promises2.writeFile)(outputPath, merged, "utf-8");
+    timingsMs.merge = Date.now() - mergeStart;
+    markStageDone("merge", "\uBCD1\uD569 \uC644\uB8CC");
+    logStage("info", "merge", "done", "\uCD5C\uC885 \uBCD1\uD569 \uC644\uB8CC", { outputPath, elapsedMs: timingsMs.merge });
+    const report = {
+      inputPath: absInput,
+      outputPath,
+      workspaceDir,
+      selectedModel,
+      probeImage,
+      probeResults,
+      pageCount: images.length,
+      keyHealth: keyPool.snapshot(),
+      timingsMs,
+      modelCachePath
+    };
+    await (0, import_promises2.writeFile)(reportPath, JSON.stringify(report, null, 2), "utf-8");
+    logStage("info", "finalize", "done", "run-report \uC800\uC7A5 \uC644\uB8CC", { reportPath });
+    return { outputPath, reportPath, selectedModel };
+  } catch (err) {
+    const normalized = normalizePipelineError(err, currentStage);
+    emitProgress(options.onEvent, currentStage, 0, stageWeights, {
+      type: "error",
+      code: normalized.code,
+      message: normalized.message
+    });
+    logger.log({
+      level: "error",
+      stage: currentStage,
+      event: "error",
+      message: normalized.message,
+      error: {
+        code: normalized.code,
+        name: normalized.name,
+        message: normalized.message,
+        stack: normalized.stack
+      }
+    });
+    throw normalized;
+  }
+}
+function normalizeWeights(weights) {
+  const sum = Object.values(weights).reduce((a, b) => a + b, 0) || 1;
+  return {
+    convert: weights.convert / sum * 100,
+    render: weights.render / sum * 100,
+    probe: weights.probe / sum * 100,
+    ocr: weights.ocr / sum * 100,
+    proofread: weights.proofread / sum * 100,
+    merge: weights.merge / sum * 100
+  };
+}
+function computeOverallPercent(stage, stagePercent, weights) {
+  const order = ["convert", "render", "probe", "ocr", "proofread", "merge"];
+  let overall = 0;
+  for (const s of order) {
+    if (s === stage) {
+      overall += weights[s] * Math.max(0, Math.min(100, stagePercent)) / 100;
+      break;
+    }
+    overall += weights[s];
+  }
+  return Math.round(overall);
+}
+function emitProgress(cb, stage, stagePercent, weights, extra) {
+  if (!cb) return;
+  cb({
+    type: extra.type ?? "stage_progress",
+    stage,
+    stagePercent: Math.max(0, Math.min(100, Math.round(stagePercent))),
+    overallPercent: computeOverallPercent(stage, stagePercent, weights),
+    current: extra.current,
+    total: extra.total,
+    code: extra.code,
+    message: extra.message
+  });
+}
+async function convertWithLibreOffice(buffer, ext) {
+  return await new Promise((resolvePromise, reject) => {
+    libreConvert(buffer, ext, void 0, (err, done) => {
+      if (err || !done) {
+        reject(new UnifiedOcrError("CONVERT_FAILED", "convert", err?.message ?? "LibreOffice \uBCC0\uD658 \uC2E4\uD328"));
+        return;
+      }
+      resolvePromise(done);
+    });
+  });
+}
+async function renderPdfToPng(pdfPath, prefixPath, dpi) {
+  try {
+    await runCommand("pdftoppm", ["-png", "-r", String(dpi), pdfPath, prefixPath]);
+  } catch (err) {
+    throw new UnifiedOcrError("RENDER_FAILED", "render", err instanceof Error ? err.message : String(err));
+  }
+}
+async function runCommand(cmd, args) {
+  await new Promise((resolvePromise, reject) => {
+    const child = (0, import_child_process4.spawn)(cmd, args, { stdio: "pipe" });
+    let stderr = "";
+    child.stderr.on("data", (d) => {
+      stderr += String(d);
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolvePromise();
+      else reject(new Error(`${cmd} \uC2E4\uD328 (code=${code}): ${stderr.trim()}`));
+    });
+  });
+}
+async function assertSofficeAvailable() {
+  try {
+    await runCommand("soffice", ["--version"]);
+  } catch {
+    throw new UnifiedOcrError("SOFFICE_NOT_FOUND", "convert", "soffice\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. LibreOffice\uB97C \uC124\uCE58\uD574 \uC8FC\uC138\uC694.");
+  }
+}
+async function listPageImages(imagesDir) {
+  const files = await (0, import_promises2.readdir)(imagesDir);
+  return files.filter((f) => f.endsWith(".png")).sort((a, b) => naturalPageSort(a, b)).map((f) => (0, import_path5.join)(imagesDir, f));
+}
+function naturalPageSort(a, b) {
+  const na = Number((a.match(/\d+/g) || ["0"]).at(-1) || 0);
+  const nb = Number((b.match(/\d+/g) || ["0"]).at(-1) || 0);
+  return na - nb;
+}
+async function pickRepresentativeImage(images) {
+  const sample = images.slice(0, Math.min(images.length, 8));
+  const weighted = [];
+  for (const p of sample) {
+    const st = await (0, import_promises2.stat)(p);
+    if (st.size > 8 * 1024) weighted.push({ path: p, size: st.size });
+  }
+  const use = weighted.length > 0 ? weighted : await Promise.all(sample.map(async (p) => ({ path: p, size: (await (0, import_promises2.stat)(p)).size })));
+  use.sort((a, b) => a.size - b.size);
+  return use[Math.floor(use.length / 2)].path;
+}
+function chooseFastestModel(results) {
+  const ok = results.filter((r) => r.success).sort((a, b) => a.durationMs - b.durationMs);
+  return ok[0]?.model ?? null;
+}
+async function loadModelCache(path) {
+  try {
+    const raw = await (0, import_promises2.readFile)(path, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function sortModelsByCache(models, cache) {
+  if (!cache) return [...models];
+  return [...models].sort((a, b) => {
+    const av = cache.models[a]?.avgDurationMs ?? Number.POSITIVE_INFINITY;
+    const bv = cache.models[b]?.avgDurationMs ?? Number.POSITIVE_INFINITY;
+    return av - bv;
+  });
+}
+async function updateModelCache(path, probes) {
+  const prev = await loadModelCache(path);
+  const current = prev ?? { updatedAt: (/* @__PURE__ */ new Date()).toISOString(), models: {} };
+  for (const p of probes) {
+    if (!p.success) continue;
+    const existing = current.models[p.model];
+    if (!existing) {
+      current.models[p.model] = { count: 1, avgDurationMs: p.durationMs };
+    } else {
+      const nextCount = existing.count + 1;
+      current.models[p.model] = {
+        count: nextCount,
+        avgDurationMs: Math.round((existing.avgDurationMs * existing.count + p.durationMs) / nextCount)
+      };
+    }
+  }
+  current.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  await (0, import_promises2.writeFile)(path, JSON.stringify(current, null, 2), "utf-8");
+}
+async function ocrImageWithFallback(input) {
+  let lastErr = "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958";
+  for (const model of input.models) {
+    try {
+      return await ocrImageViaNim({
+        imagePath: input.imagePath,
+        prompt: input.prompt,
+        model,
+        maxTokens: input.modelMaxTokens[model] ?? 8192,
+        baseUrl: input.baseUrl,
+        keyPool: input.keyPool,
+        timeoutMs: input.timeoutMs,
+        maxRetries: input.maxRetriesPerPage,
+        logger: input.logger,
+        stage: "ocr"
+      });
+    } catch (err) {
+      lastErr = err instanceof Error ? err.message : String(err);
+    }
+  }
+  throw new UnifiedOcrError("OCR_FAILED", "ocr", `\uBAA8\uB4E0 OCR \uBAA8\uB378 \uC2E4\uD328: ${lastErr}`);
+}
+async function mergeMarkdownPages(paths) {
+  const out = [];
+  for (let i = 0; i < paths.length; i++) {
+    const txt = (await (0, import_promises2.readFile)(paths[i], "utf-8")).trim();
+    if (!txt) continue;
+    out.push(txt);
+  }
+  return out.join("\n\n");
+}
+async function ocrImageViaNim(input) {
+  const { model, maxTokens, baseUrl, keyPool, timeoutMs, maxRetries, logger, stage = "ocr" } = input;
+  let attempt = 0;
+  let lastErr = "\uC54C \uC218 \uC5C6\uB294 \uC624\uB958";
+  while (attempt < maxRetries) {
+    attempt++;
+    let acquired = null;
+    try {
+      acquired = keyPool.acquire();
+    } catch (err) {
+      if (err instanceof AllKeysCoolingDownError) {
+        logger?.log({
+          level: "warn",
+          stage,
+          event: "progress",
+          message: "\uBAA8\uB4E0 API \uD0A4 cooldown \uC0C1\uD0DC\uB85C \uB300\uAE30",
+          meta: { waitMs: err.waitMs, attempt, maxRetries, model }
+        });
+        await delay(err.waitMs);
+        continue;
+      }
+      throw err;
+    }
+    try {
+      const content = input.textOnlyPrompt ? [{ type: "text", text: input.textOnlyPrompt }] : [
+        { type: "text", text: input.prompt ?? OCR_PROMPT2 },
+        {
+          type: "image_url",
+          image_url: { url: `data:image/png;base64,${await encodeBase64(input.imagePath)}` }
+        }
+      ];
+      const body = {
+        model,
+        messages: [{ role: "user", content }],
+        max_tokens: maxTokens,
+        temperature: 0
+      };
+      logger?.log({
+        level: "debug",
+        stage,
+        event: "progress",
+        message: "NIM \uC694\uCCAD \uC2DC\uB3C4",
+        meta: { attempt, maxRetries, model, keyId: acquired.keyId, hasImage: Boolean(input.imagePath) }
+      });
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const resp = await fetch(baseUrl, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${acquired.key}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+        if (resp.ok) {
+          const json = await resp.json();
+          const text = json.choices?.[0]?.message?.content?.trim() ?? "";
+          keyPool.markSuccess(acquired.keyId);
+          logger?.log({
+            level: "debug",
+            stage,
+            event: "done",
+            message: "NIM \uC751\uB2F5 \uC131\uACF5",
+            meta: { attempt, model, keyId: acquired.keyId }
+          });
+          if (!text) throw new UnifiedOcrError("OCR_FAILED", "ocr", "OCR \uC751\uB2F5\uC774 \uBE44\uC5B4 \uC788\uC2B5\uB2C8\uB2E4.");
+          return stripCodeFence3(text);
+        }
+        const retryAfter = Number(resp.headers.get("retry-after") || "0");
+        const retryAfterMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : void 0;
+        keyPool.markFailure(acquired.keyId, { status: resp.status, retryAfterMs });
+        lastErr = `NIM \uC751\uB2F5 \uC624\uB958: ${resp.status}`;
+        logger?.log({
+          level: "warn",
+          stage,
+          event: "progress",
+          message: "NIM \uC751\uB2F5 \uC2E4\uD328",
+          meta: { attempt, model, status: resp.status, retryAfterMs, keyId: acquired.keyId }
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch (err) {
+      const isTimeout = err instanceof Error && err.name === "AbortError";
+      if (acquired) keyPool.markFailure(acquired.keyId, { timeout: isTimeout });
+      lastErr = err instanceof Error ? err.message : String(err);
+      logger?.log({
+        level: "warn",
+        stage,
+        event: "progress",
+        message: "NIM \uC694\uCCAD \uC608\uC678",
+        meta: { attempt, model, timeout: isTimeout, keyId: acquired?.keyId },
+        error: { message: lastErr, name: err instanceof Error ? err.name : "Error" }
+      });
+      await delay(500);
+    }
+  }
+  logger?.log({
+    level: "error",
+    stage,
+    event: "error",
+    message: "NIM \uCD5C\uB300 \uC7AC\uC2DC\uB3C4 \uCD08\uACFC",
+    meta: { model, maxRetries },
+    error: { code: "OCR_FAILED", message: lastErr }
+  });
+  throw new UnifiedOcrError("OCR_FAILED", "ocr", `OCR \uC7AC\uC2DC\uB3C4 \uCD08\uACFC: ${lastErr}`);
+}
+async function encodeBase64(path) {
+  const b = await (0, import_promises2.readFile)(path);
+  return b.toString("base64");
+}
+function stripCodeFence3(text) {
+  const m = text.match(/^```(?:markdown|md)?\s*([\s\S]*?)```\s*$/i);
+  return m ? m[1].trim() : text;
+}
+async function delay(ms) {
+  if (ms <= 0) return;
+  await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+function ensureSupportedInput(path) {
+  const ext = (0, import_path5.extname)(path).toLowerCase();
+  const allowed = /* @__PURE__ */ new Set([".pdf", ".hwp", ".hwpx", ".docx", ".xlsx"]);
+  if (!allowed.has(ext)) {
+    throw new UnifiedOcrError("UNSUPPORTED_INPUT", "convert", `\uC9C0\uC6D0\uD558\uC9C0 \uC54A\uB294 \uC785\uB825 \uD3EC\uB9F7: ${ext}`);
+  }
+}
+function extractNumericTokens(text) {
+  return text.match(/\d[\d,./-]*/g) ?? [];
+}
+function preserveNumericIntegrity(rawText, correctedText) {
+  const rawTokens = extractNumericTokens(rawText);
+  const correctedTokens = extractNumericTokens(correctedText);
+  if (rawTokens.length !== correctedTokens.length) return rawText;
+  for (let i = 0; i < rawTokens.length; i++) {
+    if (rawTokens[i] !== correctedTokens[i]) return rawText;
+  }
+  return correctedText;
+}
+function addUncertainTag(rawText, correctedText) {
+  if (correctedText.includes("[\uD655\uC778\uD544\uC694:")) return correctedText;
+  const rawLen = rawText.trim().length;
+  const corrLen = correctedText.trim().length;
+  if (rawLen === 0 || corrLen === 0) return correctedText;
+  const rawLines = rawText.split("\n").filter(Boolean).length;
+  const corrLines = correctedText.split("\n").filter(Boolean).length;
+  const rawTableLines = rawText.split("\n").filter((l) => l.includes("|")).length;
+  const corrTableLines = correctedText.split("\n").filter((l) => l.includes("|")).length;
+  const suspicious = corrLen < rawLen * 0.75 || corrLines < Math.max(1, Math.floor(rawLines * 0.8)) || rawTableLines >= 2 && corrTableLines < Math.floor(rawTableLines * 0.7);
+  if (!suspicious) return correctedText;
+  return `${correctedText}
+
+[\uD655\uC778\uD544\uC694: \uAD50\uC815 \uACB0\uACFC\uAC00 \uCD95\uC57D\uB418\uC5C8\uC744 \uC218 \uC788\uC5B4 \uC6D0\uBB38\uACFC \uB300\uC870\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.]`;
+}
+function buildDiffSummary(before, after) {
+  return {
+    changed: before !== after,
+    beforeLength: before.length,
+    afterLength: after.length
+  };
+}
+function normalizePipelineError(err, stage) {
+  if (err instanceof UnifiedOcrError) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  const codeByStage = {
+    convert: "CONVERT_FAILED",
+    render: "RENDER_FAILED",
+    probe: "PROBE_FAILED",
+    ocr: "OCR_FAILED",
+    proofread: "PROOFREAD_FAILED",
+    merge: "MERGE_FAILED"
+  };
+  return new UnifiedOcrError(codeByStage[stage] ?? "UNKNOWN", stage, message);
+}
+
 // src/index.ts
 async function parse2(input, options) {
+  const logger = createLoggerFromEnv().withRun(generateRunId("parse")).child({ component: "index.ts", stage: "detect" });
+  logger.log({ level: "info", event: "start", message: "parse \uD638\uCD9C \uC2DC\uC791" });
   let buffer;
   if (typeof input === "string") {
     try {
-      const buf = await (0, import_promises.readFile)(input);
+      const buf = await (0, import_promises3.readFile)(input);
       buffer = toArrayBuffer(buf);
     } catch (err) {
       const msg = err instanceof Error && "code" in err && err.code === "ENOENT" ? `\uD30C\uC77C\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${input}` : `\uD30C\uC77C \uC77D\uAE30 \uC2E4\uD328: ${input}`;
+      logger.log({
+        level: "error",
+        stage: "detect",
+        event: "error",
+        message: msg,
+        error: { code: "PARSE_ERROR", message: msg, name: err instanceof Error ? err.name : "Error" }
+      });
       return { success: false, fileType: "unknown", error: msg, code: "PARSE_ERROR" };
     }
   } else if (Buffer.isBuffer(input)) {
@@ -10638,13 +11963,23 @@ async function parse2(input, options) {
     buffer = input;
   }
   if (!buffer || buffer.byteLength === 0) {
+    logger.log({ level: "error", stage: "detect", event: "error", message: "\uBE48 \uC785\uB825 \uBC84\uD37C", error: { code: "EMPTY_INPUT", message: "\uBE48 \uC785\uB825 \uBC84\uD37C", name: "KordocError" } });
     return { success: false, fileType: "unknown", error: "\uBE48 \uBC84\uD37C\uC774\uAC70\uB098 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 \uC785\uB825\uC785\uB2C8\uB2E4.", code: "EMPTY_INPUT" };
   }
   const MAX_FILE_SIZE = 500 * 1024 * 1024;
   if (buffer.byteLength > MAX_FILE_SIZE) {
+    logger.log({
+      level: "error",
+      stage: "detect",
+      event: "error",
+      message: "\uD30C\uC77C \uD06C\uAE30 \uCD08\uACFC",
+      meta: { size: buffer.byteLength },
+      error: { code: "FILE_TOO_LARGE", message: "\uD30C\uC77C \uD06C\uAE30 \uCD08\uACFC", name: "KordocError" }
+    });
     return { success: false, fileType: "unknown", error: `\uD30C\uC77C \uD06C\uAE30 \uCD08\uACFC: ${(buffer.byteLength / 1024 / 1024).toFixed(1)}MB (\uCD5C\uB300 500MB)`, code: "FILE_TOO_LARGE" };
   }
   const format = detectFormat(buffer);
+  logger.log({ level: "info", event: "done", message: "\uD3EC\uB9F7 \uAC10\uC9C0 \uC644\uB8CC", meta: { format } });
   switch (format) {
     case "hwpx": {
       const { format: zipFormat, zip } = await detectZipFormat(buffer);
@@ -10722,7 +12057,8 @@ async function parseHwpx(buffer, options, zip) {
     const { markdown, blocks, metadata, outline, warnings, images } = await parseHwpxDocument(buffer, options, zip);
     return { success: true, fileType: "hwpx", markdown, blocks, metadata, outline, warnings, images: images?.length ? images : void 0 };
   } catch (err) {
-    return { success: false, fileType: "hwpx", error: err instanceof Error ? err.message : "HWPX \uD30C\uC2F1 \uC2E4\uD328", code: classifyError(err) };
+    const normalized = normalizeKordocError(err, "HWPX \uD30C\uC2F1 \uC2E4\uD328", "finalize");
+    return { success: false, fileType: "hwpx", error: normalized.message, code: normalized.code ?? classifyError(normalized) };
   }
 }
 async function parseHwp(buffer, options) {
@@ -10730,7 +12066,8 @@ async function parseHwp(buffer, options) {
     const { markdown, blocks, metadata, outline, warnings, images } = parseHwp5Document(Buffer.from(buffer), options);
     return { success: true, fileType: "hwp", markdown, blocks, metadata, outline, warnings, images: images?.length ? images : void 0 };
   } catch (err) {
-    return { success: false, fileType: "hwp", error: err instanceof Error ? err.message : "HWP \uD30C\uC2F1 \uC2E4\uD328", code: classifyError(err) };
+    const normalized = normalizeKordocError(err, "HWP \uD30C\uC2F1 \uC2E4\uD328", "finalize");
+    return { success: false, fileType: "hwp", error: normalized.message, code: normalized.code ?? classifyError(normalized) };
   }
 }
 async function parsePdf(buffer, options) {
@@ -10738,8 +12075,15 @@ async function parsePdf(buffer, options) {
     const { markdown, blocks, metadata, outline, warnings, isImageBased } = await parsePdfDocument(buffer, options);
     return { success: true, fileType: "pdf", markdown, blocks, metadata, outline, warnings, isImageBased };
   } catch (err) {
+    const normalized = normalizeKordocError(err, "PDF \uD30C\uC2F1 \uC2E4\uD328", "finalize");
     const isImageBased = err instanceof Error && "isImageBased" in err ? true : void 0;
-    return { success: false, fileType: "pdf", error: err instanceof Error ? err.message : "PDF \uD30C\uC2F1 \uC2E4\uD328", code: classifyError(err), isImageBased };
+    return {
+      success: false,
+      fileType: "pdf",
+      error: normalized.message,
+      code: normalized.code ?? classifyError(normalized),
+      isImageBased
+    };
   }
 }
 async function parseXlsx(buffer, options, zip) {
@@ -10747,7 +12091,8 @@ async function parseXlsx(buffer, options, zip) {
     const { markdown, blocks, metadata, warnings } = await parseXlsxDocument(buffer, options, zip);
     return { success: true, fileType: "xlsx", markdown, blocks, metadata, warnings };
   } catch (err) {
-    return { success: false, fileType: "xlsx", error: err instanceof Error ? err.message : "XLSX \uD30C\uC2F1 \uC2E4\uD328", code: classifyError(err) };
+    const normalized = normalizeKordocError(err, "XLSX \uD30C\uC2F1 \uC2E4\uD328", "finalize");
+    return { success: false, fileType: "xlsx", error: normalized.message, code: normalized.code ?? classifyError(normalized) };
   }
 }
 async function parseDocx(buffer, options, zip) {
@@ -10755,11 +12100,14 @@ async function parseDocx(buffer, options, zip) {
     const { markdown, blocks, metadata, outline, warnings, images } = await parseDocxDocument(buffer, options, zip);
     return { success: true, fileType: "docx", markdown, blocks, metadata, outline, warnings, images: images?.length ? images : void 0 };
   } catch (err) {
-    return { success: false, fileType: "docx", error: err instanceof Error ? err.message : "DOCX \uD30C\uC2F1 \uC2E4\uD328", code: classifyError(err) };
+    const normalized = normalizeKordocError(err, "DOCX \uD30C\uC2F1 \uC2E4\uD328", "finalize");
+    return { success: false, fileType: "docx", error: normalized.message, code: normalized.code ?? classifyError(normalized) };
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AllKeysCoolingDownError,
+  ApiKeyRotationPool,
   VERSION,
   blocksToMarkdown,
   compare,
@@ -10778,7 +12126,8 @@ async function parseDocx(buffer, options, zip) {
   parseHwp,
   parseHwpx,
   parsePdf,
-  parseXlsx
+  parseXlsx,
+  runUnifiedOcrPipeline
 });
 /*! Bundled license information: