@gcunharodrigues/wrxn 0.2.1 → 0.4.0

package/bin/wrxn.cjs

@@ -11,7 +11,10 @@ const worktree = require('../lib/worktree.cjs');
 const executor = require('../lib/executor.cjs');
 const onboard = require('../lib/onboard.cjs');
 const connect = require('../lib/connect.cjs');
+const brain = require('../lib/brain.cjs');
 const statusline = require('../lib/statusline.cjs');
+const { convert } = require('../lib/convert.cjs');
+const { ingest } = require('../lib/ingest.cjs');
 
 const PKG_ROOT = path.join(__dirname, '..');
 
@@ -54,6 +57,12 @@ function parseArgs(argv) {
       args.flags.owner = argv[++i];
     } else if (a === '--probe') {
       args.flags.probe = argv[++i];
+    } else if (a === '--distillation') {
+      args.flags.distillation = argv[++i];
+    } else if (a === '--limit') {
+      args.flags.limit = argv[++i];
+    } else if (a === '--type') {
+      args.flags.type = argv[++i];
     } else if (a === '--check-report') {
       args.flags['check-report'] = true;
     } else if (a.startsWith('--')) {
@@ -105,6 +114,17 @@ Usage:
       list                       print all registered connections (agent-readable JSON)
       get <name>                 print one connection by name
 
+  wrxn brain query "<q>" [--json] [--limit <n>] [--type <prose|code|NodeType>] [--neighbors] [--root <dir>]
+                                 ask the warm Brain (recon-wrxn's code+prose graph) from the terminal.
+                                 WHOLE-BRAIN by default. Discovers the live serve door via
+                                 .recon-wrxn/serve-endpoint.json and POSTs the query; prints ranked
+                                 hits (name · type · file:line). If the Brain is not warm (no live
+                                 serve), prints a clear error and exits non-zero — no cold load.
+                                 --json emits the structured hits · --limit asks the door for top n ·
+                                 --type post-filters (prose=Page/Section, code=the rest, or an exact
+                                 NodeType) · --neighbors expands each hit to its 1-hop graph neighbors
+                                 (callers/callees/relationships via recon_explain).
+
   wrxn statusline [--inject [--path <script>]]
                                  SYNAPSE live-window writer. With no flag: report whether a statusline
                                  is configured (~/.claude/settings.json) + print the marker-bounded
@@ -112,6 +132,20 @@ Usage:
                                  resolved (or --path) statusline script, idempotently (append-only,
                                  never overwrites). init NEVER touches your statusline.
 
+  wrxn convert <file> [--cpu]    convert a source file to Markdown and print it. Per-format routing:
+                                 markitdown (html/docx/txt/pptx/xlsx) · docling (pdf, with automatic
+                                 CPU fallback on a GPU arch-crash) · pure-JS floor when Python is
+                                 absent. --cpu forces docling onto CPU from the first attempt.
+
+  wrxn ingest <file> [--distillation <result.json>] [--root <dir>]
+                                 distill a source into the memory wiki: convert (slice 05) → an LLM
+                                 (the ingest skill) produces a summary + N note pages → write them
+                                 to .wrxn/wiki/, each stamped derived_from the raw source, which is
+                                 kept under .wrxn/raw/. ADDITIVE-ONLY: an existing page is never
+                                 overwritten (re-runs are safe). --distillation feeds the skill's
+                                 result JSON (summary,notes); without it, the harness points you at
+                                 the ingest skill.
+
   wrxn onboard [--root <dir>]    scaffold the Day-1 operator file set under context/ from a filled
                                  aios-intake.md (the deterministic half of the onboard skill;
                                  workspace installs only). Idempotent.
@@ -120,7 +154,7 @@ Profiles: --project (default, the dev pipeline + intelligence + enforcement) |
           --workspace (adds the operator layer: onboard/audit/level-up + intake + decisions log +
           connections registry).`;
 
-function main(argv) {
+async function main(argv) {
   const args = parseArgs(argv);
 
   if (args.flags.version) {
@@ -294,6 +328,43 @@ function main(argv) {
     return 0;
   }
 
+  if (cmd === 'convert') {
+    const file = args._[1];
+    if (!file) { process.stderr.write('wrxn: convert requires <file>\n'); return 2; }
+    try {
+      const md = await convert(path.resolve(file), { gpu: args.flags.cpu ? false : undefined });
+      process.stdout.write(md.endsWith('\n') ? md : md + '\n');
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
+  if (cmd === 'ingest') {
+    const file = args._[1];
+    if (!file) { process.stderr.write('wrxn: ingest requires <file>\n'); return 2; }
+    const root = path.resolve(args.flags.root || process.cwd());
+    // The distillation is the LLM step (the `ingest` skill). The CLI feeds its structured result via
+    // --distillation <result.json>; without one, the harness's defaultDistill points back to the skill.
+    let distill;
+    if (args.flags.distillation) {
+      const dpath = path.resolve(args.flags.distillation);
+      distill = () => JSON.parse(fs.readFileSync(dpath, 'utf8'));
+    }
+    try {
+      const report = await ingest(path.resolve(file), { root, ...(distill ? { distill } : {}) });
+      process.stdout.write(`wrxn ingest ${report.source} → raw ${report.raw}\n`);
+      for (const p of report.written) process.stdout.write(`  wrote   ${p}\n`);
+      for (const p of report.skipped) process.stdout.write(`  skipped ${p} (exists — additive-only, never clobbered)\n`);
+      process.stdout.write(`${report.written.length} written, ${report.skipped.length} skipped.\n`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
   if (cmd === 'onboard') {
     const root = path.resolve(args.flags.root || process.cwd());
     let report;
@@ -353,6 +424,32 @@ function main(argv) {
     }
   }
 
+  if (cmd === 'brain') {
+    const sub = args._[1];
+    if (sub !== 'query') {
+      process.stderr.write(`wrxn: unknown brain subcommand "${sub || ''}" (expected: query)\n\n${USAGE}\n`);
+      return 2;
+    }
+    const q = args._[2];
+    if (!q) { process.stderr.write('wrxn: brain query requires "<query>"\n'); return 2; }
+    const opts = { json: !!args.flags.json, neighbors: !!args.flags.neighbors };
+    if (args.flags.limit != null) {
+      const n = parseInt(args.flags.limit, 10);
+      if (!Number.isInteger(n) || n <= 0) { process.stderr.write('wrxn: --limit requires a positive integer\n'); return 2; }
+      opts.limit = n;
+    }
+    if (args.flags.type) opts.type = String(args.flags.type);
+    const root = path.resolve(args.flags.root || process.cwd());
+    try {
+      const res = await brain.query(q, opts, { root });
+      process.stdout.write(brain.formatHits(res.hits, opts) + '\n');
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
   if (cmd === 'statusline') {
     const home = process.env.HOME || os.homedir();
     const detection = statusline.detectStatusLine(home);
@@ -397,4 +494,7 @@ function main(argv) {
   return 2;
 }
 
-process.exit(main(process.argv.slice(2)));
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => { process.stderr.write(`wrxn: ${err && err.message ? err.message : err}\n`); process.exit(1); }
+);

package/lib/brain.cjs

@@ -0,0 +1,295 @@
+'use strict';
+
+// WRXN brain query (recon-brain-recall-03) — interrogate the warm Brain from the terminal.
+//
+// The Brain is recon-wrxn's unified code+prose knowledge graph, loaded WARM inside the `recon serve`
+// process Claude Code boots for a session. This command reaches it over the loopback find door that
+// serve announces via a discovery file — it is WHOLE-BRAIN (code AND prose, no scope filter by
+// default), the operator's on-demand counterpart to the prose-only proactive Recall hook.
+//
+// Endpoint-first (v1): if no warm door is discoverable, we raise a clear, actionable error and the CLI
+// exits non-zero — there is NO cold one-shot load (that would pay the index + embedder cost the warm
+// serve already absorbs).
+//
+// The query path takes an INJECTED transport + endpoint reader (deps) so its behavior is unit-testable
+// with no live serve — mirrors the injected-invoker seam in lib/connect.cjs and the recall hook's
+// httpTransport. lib/brain.cjs is PACKAGE code (invoked via bin/wrxn.cjs), NOT payload — no manifest
+// entry, consistent with lib/connect.cjs / lib/executor.cjs / lib/onboard.cjs.
+//
+// The discovery contract (serve-endpoint.json {pid,port}, pid-liveness) is duplicated here from the
+// payload recall-surface hook ON PURPOSE: that hook must be node-stdlib-only and self-contained (it
+// ships into installs without the kernel lib), so package code cannot import it. The contract is ~20
+// stable lines — duplicating it across the install boundary is the same self-containment trade the
+// payload hooks make for findInstallRoot.
+
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+
+const ENDPOINT_REL = path.join('.recon-wrxn', 'serve-endpoint.json');
+const FIND_PATH = '/api/tools/recon_find';
+const EXPLAIN_PATH = '/api/tools/recon_explain';
+const TIMEOUT_MS = 5000; // generous: an interactive CLI, not the per-prompt 150ms recall budget
+const MAX_RESPONSE_BYTES = 256 * 1024; // hard cap on an accumulated door response body (anti-flood)
+const PROSE_TYPES = new Set(['Page', 'Section']);
+const WALK_UP_LIMIT = 12;
+
+// ── discovery (the cross-repo warm-door contract) ────────────────────────────────────
+
+// A pid is alive unless process.kill(pid,0) throws. ESRCH = gone; EPERM = owned by another user but
+// alive. Mirrors the cross-repo discovery contract (and the recall hook).
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return !!e && e.code === 'EPERM';
+  }
+}
+
+// Refuse a discovery file another user could have planted, or that is group/world-writable — trusting
+// it would let a hostile workspace point the door host/port at an exfil/injection sink. lstat (not
+// stat) so a symlink's OWN ownership/mode is judged, not its target's. A platform without getuid (no
+// POSIX ownership) skips the uid check but still enforces the mode check. Any fault → not trusted.
+function endpointTrusted(file) {
+  let st;
+  try {
+    st = fs.lstatSync(file);
+  } catch {
+    return false;
+  }
+  if (typeof process.getuid === 'function' && st.uid !== process.getuid()) return false; // foreign owner
+  if ((st.mode & 0o022) !== 0) return false; // group/world-writable
+  return true;
+}
+
+// Walk up from startDir to the first directory carrying .recon-wrxn/serve-endpoint.json; read and
+// validate {pid,port}; trust it only when it is well-owned (not planted), well-formed, and the pid is
+// alive. Returns {pid,port,root} or null (the Brain is not warm: absent, untrusted, malformed, missing
+// fields, or a dead process).
+function discoverEndpoint(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < WALK_UP_LIMIT; i++) {
+    const file = path.join(dir, ENDPOINT_REL);
+    if (fs.existsSync(file)) {
+      if (!endpointTrusted(file)) return null; // foreign-owned or loose perms → not warm
+      let obj;
+      try {
+        obj = JSON.parse(fs.readFileSync(file, 'utf8'));
+      } catch {
+        return null; // malformed → not warm
+      }
+      const pid = Number(obj && obj.pid);
+      const port = Number(obj && obj.port);
+      if (!Number.isInteger(pid) || pid <= 0) return null;
+      if (!Number.isInteger(port) || port <= 0) return null;
+      if (!pidAlive(pid)) return null; // dead process → not warm
+      return { pid, port, root: dir };
+    }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// ── transport (injectable; default = real loopback POST) ─────────────────────────────
+
+// Default transport: a real loopback POST with a hard timeout. Injectable so unit tests never touch
+// the network (mirrors lib/connect.cjs's invoke seam). Resolves {statusCode, body}; rejects on socket
+// error or timeout.
+function httpTransport({ port, path: reqPath, body, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const payload = Buffer.from(JSON.stringify(body));
+    const deadline = timeoutMs || TIMEOUT_MS;
+    let settled = false;
+    let wall = null;
+    const done = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      if (wall) clearTimeout(wall);
+      fn(arg);
+    };
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        path: reqPath,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': payload.length },
+      },
+      (res) => {
+        const chunks = [];
+        let total = 0;
+        res.on('data', (c) => {
+          total += c.length;
+          if (total > MAX_RESPONSE_BYTES) { req.destroy(new Error('brain door response too large')); return; }
+          chunks.push(c);
+        });
+        res.on('end', () => done(resolve, { statusCode: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+        res.on('error', (e) => done(reject, e));
+      }
+    );
+    req.on('error', (e) => done(reject, e));
+    // Idle timeout (no bytes for `deadline`) AND an independent wall-clock — the latter bounds a trickle
+    // attacker that dribbles bytes to keep the idle timer from ever firing.
+    req.setTimeout(deadline, () => req.destroy(new Error('brain door timeout')));
+    wall = setTimeout(() => req.destroy(new Error('brain door wall-clock timeout')), deadline);
+    req.write(payload);
+    req.end();
+  });
+}
+
+// POST a door tool and return the parsed JSON body. Raises a clean error (never a crash) on a transport
+// fault, a non-200 status, or a non-JSON body.
+async function postTool(transport, port, reqPath, body, timeoutMs) {
+  let resp;
+  try {
+    resp = await transport({ port, path: reqPath, body, timeoutMs: timeoutMs || TIMEOUT_MS });
+  } catch (err) {
+    throw new Error(`Brain door request to ${reqPath} failed: ${err.message}`);
+  }
+  if (!resp || resp.statusCode !== 200) {
+    throw new Error(`Brain door returned HTTP ${resp ? resp.statusCode : 'no-response'} for ${reqPath}`);
+  }
+  try {
+    return JSON.parse(resp.body);
+  } catch {
+    throw new Error(`Brain door returned a malformed (non-JSON) response for ${reqPath}`);
+  }
+}
+
+// ── pure helpers ─────────────────────────────────────────────────────────────────────
+
+function isProse(hit) {
+  return !!hit && PROSE_TYPES.has(hit.type);
+}
+
+// Post-filter hits by --type (the find request can't carry a type ARRAY, so prose=Page+Section is
+// always a post-filter): 'prose' → Page/Section, 'code' → everything else, else an exact NodeType.
+function filterByType(hits, type) {
+  if (!type) return hits;
+  if (type === 'prose') return hits.filter(isProse);
+  if (type === 'code') return hits.filter((h) => !isProse(h));
+  const t = String(type).toLowerCase();
+  return hits.filter((h) => String(h && h.type).toLowerCase() === t);
+}
+
+// Extract a hit's 1-hop neighbors from the door's structured recon_explain response:
+//   { result, neighbors: NeighborHit[] }, NeighborHit = { name, type, file, line, relationship }
+//   relationship ∈ caller | callee | import | importedBy | method | implementedBy | usedBy | testRef
+// Strictly 1-hop. Consumes that real shape directly — no relationship-bucket guesswork. A missing or
+// non-array `neighbors` (e.g. a degraded/empty explain) yields [] so the hit simply has no neighbors.
+function extractNeighbors(resp) {
+  if (!resp || typeof resp !== 'object' || !Array.isArray(resp.neighbors)) return [];
+  return resp.neighbors.map((n) => {
+    const r = n || {};
+    const out = { name: r.name, type: r.type, file: r.file };
+    if (r.line != null) out.line = r.line;
+    if (r.relationship) out.relationship = r.relationship;
+    return out;
+  });
+}
+
+// ── formatting (pure) ────────────────────────────────────────────────────────────────
+
+function hitLine(h) {
+  const name = h.name || '(unnamed)';
+  const type = h.type || '?';
+  const loc = h.file ? `${h.file}${h.line != null ? ':' + h.line : ''}` : '';
+  return loc ? `${name} · ${type} · ${loc}` : `${name} · ${type}`;
+}
+
+function neighborLine(n) {
+  const rel = n.relationship ? ` [${n.relationship}]` : '';
+  return `    - ${hitLine(n)}${rel}`;
+}
+
+// Render results: --json re-emits the structured hits; default is a human text list. With --neighbors,
+// each hit's 1-hop neighbors are listed indented beneath it.
+function formatHits(hits, opts = {}) {
+  const list = Array.isArray(hits) ? hits : [];
+  if (opts.json) return JSON.stringify(list, null, 2);
+  if (!list.length) return 'no results';
+  const lines = [];
+  for (const h of list) {
+    lines.push(hitLine(h));
+    if (opts.neighbors) {
+      const ns = Array.isArray(h.neighbors) ? h.neighbors : [];
+      if (ns.length) for (const n of ns) lines.push(neighborLine(n));
+      else lines.push('    (no 1-hop neighbors)');
+    }
+  }
+  return lines.join('\n');
+}
+
+// ── the query (IO shell over the injected seam) ──────────────────────────────────────
+
+const NOT_WARM =
+  'Brain is not warm — no live recon serve door found (.recon-wrxn/serve-endpoint.json is absent, ' +
+  'malformed, or its process is dead). Open a Claude Code session (which boots recon serve), or run ' +
+  '`recon serve` with the find door enabled, then retry.';
+
+/**
+ * Query the warm Brain. Whole-brain (code+prose) by default.
+ * @param {string} q          the query string
+ * @param {object} opts       { json?, limit?, type?, neighbors? }
+ * @param {object} deps       { root?, discover?, transport?, timeoutMs? } — injected seam for tests
+ * @returns {Promise<{hits: object[]}>}
+ * @throws  a clear error when the Brain is not warm, or on a malformed/non-200 door response.
+ */
+async function query(q, opts = {}, deps = {}) {
+  const term = String(q == null ? '' : q).trim();
+  if (!term) throw new Error('wrxn brain query requires a non-empty query string');
+
+  const startDir = deps.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const discover = deps.discover || discoverEndpoint;
+  const transport = deps.transport || httpTransport;
+  const timeoutMs = deps.timeoutMs || TIMEOUT_MS;
+
+  const door = discover(startDir);
+  if (!door) throw new Error(NOT_WARM);
+
+  const findBody = { query: term };
+  if (Number.isInteger(opts.limit) && opts.limit > 0) findBody.limit = opts.limit;
+
+  const found = await postTool(transport, door.port, FIND_PATH, findBody, timeoutMs);
+  if (!Array.isArray(found.hits)) {
+    throw new Error(
+      'Brain door returned an unexpected response shape (no structured `hits` array) — the recon-wrxn ' +
+      'serve door may predate the structured find response.'
+    );
+  }
+
+  let hits = filterByType(found.hits, opts.type);
+
+  // --neighbors: 1-hop expansion per hit via recon_explain — the ONLY place 1-hop lives. A per-hit
+  // explain failure degrades to empty neighbors (the find already succeeded); it never crashes.
+  if (opts.neighbors) {
+    for (const h of hits) {
+      const explainBody = { name: h.name };
+      if (h.file) explainBody.file = h.file;
+      try {
+        h.neighbors = extractNeighbors(await postTool(transport, door.port, EXPLAIN_PATH, explainBody, timeoutMs));
+      } catch {
+        h.neighbors = [];
+      }
+    }
+  }
+
+  return { hits };
+}
+
+module.exports = {
+  query,
+  formatHits,
+  discoverEndpoint,
+  pidAlive,
+  httpTransport,
+  filterByType,
+  extractNeighbors,
+  isProse,
+  FIND_PATH,
+  EXPLAIN_PATH,
+  PROSE_TYPES,
+};

package/lib/convert.cjs

@@ -0,0 +1,215 @@
+'use strict';
+
+// Converter primitive (multiformat-distill-05) — convert(srcPath) → Markdown, per-format routing.
+//
+// Decision (ADR 0001 / PRD §5, empirically baked off): markitdown is the primary subprocess for the
+// office/web matrix (html/docx/pptx/xlsx); txt is a zero-dep pass-through; PDF escalates to docling
+// (SOTA tables + OCR), which auto-grabs the GPU and CRASHES on arch-incompat (the GTX-1070/Pascal
+// sm_61 trap — torch cu13x ships no sm_61 kernel) → we force CPU on that crash. When Python /
+// markitdown is absent (ENOENT) we degrade to the pure-JS floor (turndown / mammoth / unpdf / SheetJS).
+//
+// The spawn boundary is INJECTED, mirroring lib/connect.cjs's injectable `invoke`: convert(src,{run})
+// takes a converter runner so routing, ENOENT-degrade, and the CPU fallback are unit-testable WITHOUT
+// any real binary. defaultRun does the real spawnSync — that is what makes the integration check
+// "validated by invocation". convert is async only so the pure-JS floor (mammoth/unpdf are async)
+// can be wired in completely; the primary subprocess path is plain blocking spawnSync.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Extension → logical format. (.htm folds into html.)
+const FORMATS = {
+  '.html': 'html',
+  '.htm': 'html',
+  '.docx': 'docx',
+  '.txt': 'txt',
+  '.pptx': 'pptx',
+  '.xlsx': 'xlsx',
+  '.pdf': 'pdf',
+};
+
+// CUDA / arch-incompat crash signatures — the Pascal sm_61 trap and friends. docling auto-grabs the
+// GPU; a torch build with no matching SM kernel dies with "no kernel image is available...".
+const ARCH_CRASH_RE = /no kernel image|kernel image is available|sm_\d+|CUDA error|CUDA_ERROR|device-side assert|out of memory/i;
+
+const SPAWN_OPTS = { encoding: 'utf8', timeout: 600000, maxBuffer: 256 * 1024 * 1024 };
+
+// ── the injected boundary's real implementation ────────────────────────────────
+
+/**
+ * Run a converter subprocess and normalize its result to { ok, markdown } | { ok:false, error }.
+ * error.code is 'ENOENT' (not installed → degrade), 'CRASH' (arch-incompat → CPU retry), or 'EXIT'.
+ */
+function defaultRun(tool, srcPath, { device } = {}) {
+  if (tool === 'markitdown') {
+    const r = spawnSync('markitdown', [srcPath], SPAWN_OPTS);
+    return normalize(r);
+  }
+  if (tool === 'docling') {
+    // docling writes <basename>.md into an --output dir (no markdown on stdout); read it back.
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wrxn-docling-'));
+    try {
+      const args = [srcPath, '--to', 'md', '--output', outDir];
+      const opts = { ...SPAWN_OPTS };
+      if (device === 'cpu') {
+        args.push('--device', 'cpu');
+        opts.env = { ...process.env, CUDA_VISIBLE_DEVICES: '' };
+      }
+      const r = spawnSync('docling', args, opts);
+      if (r.error) return { ok: false, error: classifyError(r.error) };
+      if (r.status !== 0 || r.signal) {
+        const stderr = r.stderr || '';
+        const code = ARCH_CRASH_RE.test(stderr) || r.signal ? 'CRASH' : 'EXIT';
+        return { ok: false, error: { code, status: r.status, signal: r.signal, message: stderr.trim() } };
+      }
+      return { ok: true, markdown: readDoclingOutput(outDir, srcPath) };
+    } finally {
+      fs.rmSync(outDir, { recursive: true, force: true });
+    }
+  }
+  throw new Error(`unknown converter tool: ${tool}`);
+}
+
+function normalize(r) {
+  if (r.error) return { ok: false, error: classifyError(r.error) };
+  if (r.status !== 0 || r.signal) {
+    return { ok: false, error: { code: 'EXIT', status: r.status, signal: r.signal, message: (r.stderr || '').trim() } };
+  }
+  return { ok: true, markdown: r.stdout };
+}
+
+function classifyError(err) {
+  return { code: err.code || 'ERR', message: err.message || String(err) };
+}
+
+function readDoclingOutput(outDir, srcPath) {
+  const base = path.basename(srcPath, path.extname(srcPath));
+  const preferred = path.join(outDir, `${base}.md`);
+  if (fs.existsSync(preferred)) return fs.readFileSync(preferred, 'utf8');
+  // Fall back to the first .md docling produced (naming can vary by version).
+  const md = fs.readdirSync(outDir).find((f) => f.toLowerCase().endsWith('.md'));
+  if (!md) throw new Error(`docling produced no markdown in ${outDir}`);
+  return fs.readFileSync(path.join(outDir, md), 'utf8');
+}
+
+// ── the pure-JS floor (no-Python degrade) ───────────────────────────────────────
+
+function lazy(mod) {
+  try {
+    return require(mod);
+  } catch {
+    throw new Error(
+      `pure-JS floor needs "${mod}" but it is not installed, and the primary converter is absent. ` +
+      `Install the primary path (pip install 'markitdown[all]' / docling) or the floor (npm i ${mod}).`
+    );
+  }
+}
+
+/** The no-Python in-process floor (research §2: turndown / mammoth / unpdf / SheetJS). Async. */
+async function defaultFloor(fmt, srcPath) {
+  if (fmt === 'txt') return fs.readFileSync(srcPath, 'utf8');
+  if (fmt === 'html') {
+    const Turndown = lazy('turndown');
+    const td = new Turndown();
+    try {
+      const { gfm } = require('turndown-plugin-gfm');
+      td.use(gfm);
+    } catch { /* gfm tables are a nice-to-have, not required */ }
+    return td.turndown(fs.readFileSync(srcPath, 'utf8'));
+  }
+  if (fmt === 'docx') {
+    const mammoth = lazy('mammoth');
+    const Turndown = lazy('turndown');
+    const { value: html } = await mammoth.convertToHtml({ path: srcPath });
+    return new Turndown().turndown(html);
+  }
+  if (fmt === 'pdf') {
+    const { extractText, getDocumentProxy } = lazy('unpdf');
+    const buf = new Uint8Array(fs.readFileSync(srcPath));
+    const pdf = await getDocumentProxy(buf);
+    const { text } = await extractText(pdf, { mergePages: true });
+    return text;
+  }
+  if (fmt === 'xlsx') {
+    const XLSX = lazy('xlsx');
+    const wb = XLSX.readFile(srcPath);
+    return wb.SheetNames.map((n) => `## ${n}\n\n${XLSX.utils.sheet_to_csv(wb.Sheets[n])}`).join('\n\n');
+  }
+  if (fmt === 'pptx') {
+    const officeParser = lazy('officeparser');
+    return await officeParser.parseOfficeAsync(srcPath);
+  }
+  throw new Error(`no pure-JS floor for format "${fmt}"`);
+}
+
+// ── the primitive ───────────────────────────────────────────────────────────────
+
+/**
+ * Convert a source file to Markdown via per-format routing.
+ * @param {string} srcPath
+ * @param {{ run?: Function, floor?: Function, gpu?: boolean }} [opts]
+ *   run   — injectable converter boundary (default: defaultRun, the real spawnSync).
+ *   floor — injectable pure-JS floor (default: defaultFloor).
+ *   gpu   — false forces docling onto CPU from the first attempt (skips the GPU probe/crash).
+ * @returns {Promise<string>} the markdown.
+ */
+async function convert(srcPath, { run = defaultRun, floor = defaultFloor, gpu } = {}) {
+  // Resolve to an absolute path up front so a leading-dash filename can never be read as a CLI flag
+  // by the converter subprocess — the dash-neutralization must not depend on the caller (slice-06
+  // ingest calls convert() directly, not via the CLI).
+  srcPath = path.resolve(srcPath);
+  // Pre-check existence up front (mirrors lib/ingest.cjs's source-not-found guard) so a missing file
+  // is rejected with a clean message and NEVER reaches the converter subprocess — whose Python
+  // traceback (markitdown/docling) would otherwise leak to the user verbatim (multiformat-distill-08).
+  if (!fs.existsSync(srcPath)) throw new Error(`wrxn convert: source not found: ${srcPath}`);
+  const ext = path.extname(srcPath).toLowerCase();
+  const fmt = FORMATS[ext];
+  if (!fmt) {
+    throw new Error(`wrxn convert: unsupported format "${ext || '(none)'}" — supported: ${Object.keys(FORMATS).join(', ')}`);
+  }
+
+  // txt is already plain text — pass it through (zero-dep, always works).
+  if (fmt === 'txt') {
+    return fs.readFileSync(srcPath, 'utf8');
+  }
+
+  if (fmt === 'pdf') {
+    return convertPdf(srcPath, { run, floor, gpu });
+  }
+
+  // markitdown-primary formats (html/docx/pptx/xlsx).
+  const r = run('markitdown', srcPath);
+  if (r.ok) return r.markdown;
+  if (r.error && r.error.code === 'ENOENT') {
+    return floor(fmt, srcPath); // markitdown absent → degrade to the pure-JS floor
+  }
+  throw new Error(`wrxn convert: markitdown failed on ${path.basename(srcPath)} — ${r.error.message || r.error.code}`);
+}
+
+/** PDF tier: docling (GPU/auto) → CPU on an arch-crash → pure-JS floor if docling is absent. */
+async function convertPdf(srcPath, { run, floor, gpu }) {
+  const firstDevice = gpu === false ? 'cpu' : undefined; // undefined = let docling pick (GPU/auto)
+  const r = run('docling', srcPath, { device: firstDevice });
+  if (r.ok) return r.markdown;
+  if (r.error && r.error.code === 'ENOENT') {
+    return floor('pdf', srcPath); // no docling → unpdf floor
+  }
+  if (r.error && r.error.code === 'CRASH' && firstDevice !== 'cpu') {
+    // arch-incompat / GPU crash → force CPU (CUDA_VISIBLE_DEVICES='' + --device cpu).
+    const cpu = run('docling', srcPath, { device: 'cpu' });
+    if (cpu.ok) return cpu.markdown;
+    if (cpu.error && cpu.error.code === 'ENOENT') return floor('pdf', srcPath);
+    throw new Error(`wrxn convert: docling failed on the CPU fallback for ${path.basename(srcPath)} — ${cpu.error.message || cpu.error.code}`);
+  }
+  throw new Error(`wrxn convert: docling failed on ${path.basename(srcPath)} — ${r.error.message || r.error.code}`);
+}
+
+module.exports = {
+  convert,
+  defaultRun,
+  defaultFloor,
+  FORMATS,
+  ARCH_CRASH_RE,
+};