ollama-intern-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/ollama-intern-mcp/readme.png" alt="Ollama Intern MCP" width="500">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/ollama-intern-mcp/actions"><img alt="CI" src="https://github.com/mcp-tool-shop-org/ollama-intern-mcp/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <a href="https://mcp-tool-shop-org.github.io/ollama-intern-mcp/"><img alt="Landing Page" src="https://img.shields.io/badge/landing-page-8b5cf6"></a>
+  <a href="https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/"><img alt="Handbook" src="https://img.shields.io/badge/handbook-docs-10b981"></a>
+</p>
+
+> **The local intern for Claude Code.** 28 job-shaped tools, evidence-first briefs, durable artifacts.
+
+An MCP server that gives Claude Code a **local intern** with rules, tiers, a desk, and a filing cabinet. Claude picks the _tool_; the tool picks the _tier_ (Instant / Workhorse / Deep / Embed); the tier writes a file you can open next week.
+
+No cloud. No telemetry. No "autonomous" anything. Every call shows its work.
+
+---
+
+## Lead example — one call, one artifact
+
+```jsonc
+// Claude → ollama-intern-mcp
+{
+  "tool": "ollama_incident_pack",
+  "arguments": {
+    "title": "sprite pipeline 5 AM paging regression",
+    "logs": "[2026-04-16 05:07] worker-3 OOM killed\n[2026-04-16 05:07] ollama /api/ps reports evicted=true size=8.1GB\n...",
+    "source_paths": ["F:/AI/sprite-foundry/src/worker.ts", "memory/sprite-foundry-visual-mastery.md"]
+  }
+}
+```
+
+Returns an envelope pointing at a file on disk:
+
+```jsonc
+{
+  "result": {
+    "pack": "incident",
+    "slug": "2026-04-16-sprite-pipeline-5-am-paging-regression",
+    "artifact_md":   "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.md",
+    "artifact_json": "~/.ollama-intern/artifacts/incident/2026-04-16-sprite-pipeline-5-am-paging-regression.json",
+    "weak": false,
+    "evidence_count": 6,
+    "next_checks": ["residency.evicted across last 24h", "OLLAMA_MAX_LOADED_MODELS vs loaded size"]
+  },
+  "tier_used": "deep",
+  "model": "qwen2.5:14b-instruct-q4_K_M",
+  "hardware_profile": "dev-rtx5080",
+  "tokens_in": 4180, "tokens_out": 612,
+  "elapsed_ms": 8410,
+  "residency": { "in_vram": true, "evicted": false }
+}
+```
+
+That markdown file is the intern's desk output — headings, evidence block with cited ids, investigative `next_checks`, `weak: true` banner if evidence is thin. It's deterministic: the renderer is code, not a prompt. Open it tomorrow, diff it next week, export it into a handbook with `ollama_artifact_export_to_path`.
+
+Every competitor in this category leads with "save tokens." We lead with _here is the file the intern wrote._
+
+---
+
+## What's in here — four tiers, 28 tools
+
+| Tier | Count | What lives here |
+|---|---|---|
+| **Atoms** | 15 | Job-shaped primitives. `classify`, `extract`, `triage_logs`, `summarize_fast` / `deep`, `draft`, `research`, `corpus_search` / `answer` / `index` / `refresh` / `list`, `embed_search`, `embed`, `chat`. Batch-capable atoms (`classify`, `extract`, `triage_logs`) accept `items: [{id, text}]`. |
+| **Briefs** | 3 | Evidence-backed structured operator briefs. `incident_brief`, `repo_brief`, `change_brief`. Every claim cites an evidence id; unknowns stripped server-side. Weak evidence surfaces `weak: true` rather than fake narrative. |
+| **Packs** | 3 | Fixed-pipeline compound jobs that write durable markdown + JSON to `~/.ollama-intern/artifacts/`. `incident_pack`, `repo_pack`, `change_pack`. Deterministic renderers — no model calls on the artifact shape. |
+| **Artifacts** | 7 | Continuity surface over pack outputs. `artifact_list` / `read` / `diff` / `export_to_path`, plus three deterministic snippets: `incident_note`, `onboarding_section`, `release_note`. |
+
+Total: **18 primitives + 3 packs + 7 artifact tools = 28**.
+
+Freeze lines:
+- Atoms frozen at 18 (atoms + briefs). No new atom tools.
+- Packs frozen at 3. No new pack types.
+- Artifact tier frozen at 7.
+
+The full tool reference lives in the [handbook](https://mcp-tool-shop-org.github.io/ollama-intern-mcp/handbook/reference/).
+
+---
+
+## Install
+
+```bash
+npm install -g ollama-intern-mcp
+```
+
+Requires [Ollama](https://ollama.com) running locally and the tier models pulled.
+
+### Claude Code
+
+```json
+{
+  "mcpServers": {
+    "ollama-intern": {
+      "command": "npx",
+      "args": ["-y", "ollama-intern-mcp"],
+      "env": {
+        "OLLAMA_HOST": "http://127.0.0.1:11434",
+        "INTERN_PROFILE": "dev-rtx5080"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Same block, written to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
+
+### Model pulls
+
+**Default dev profile (RTX 5080 16GB and similar):**
+
+```bash
+ollama pull qwen2.5:7b-instruct-q4_K_M
+ollama pull qwen2.5-coder:7b-instruct-q4_K_M
+ollama pull qwen2.5:14b-instruct-q4_K_M
+ollama pull nomic-embed-text
+export OLLAMA_MAX_LOADED_MODELS=4
+export OLLAMA_KEEP_ALIVE=-1
+```
+
+**M5 Max profile (128GB unified):**
+
+```bash
+ollama pull qwen2.5:14b-instruct-q4_K_M
+ollama pull qwen2.5-coder:32b-instruct-q4_K_M
+ollama pull llama3.3:70b-instruct-q4_K_M
+ollama pull nomic-embed-text
+export INTERN_PROFILE=m5-max
+```
+
+Per-tier env vars (`INTERN_TIER_INSTANT`, `INTERN_TIER_WORKHORSE`, `INTERN_TIER_DEEP`, `INTERN_EMBED_MODEL`) still override profile picks for one-offs.
+
+---
+
+## Uniform envelope
+
+Every tool returns the same shape:
+
+```ts
+{
+  result: <tool-specific>,
+  tier_used: "instant" | "workhorse" | "deep" | "embed",
+  model: string,
+  hardware_profile: string,     // "dev-rtx5080" | "dev-rtx5080-llama" | "m5-max"
+  tokens_in: number,
+  tokens_out: number,
+  elapsed_ms: number,
+  residency: {
+    in_vram: boolean,
+    size_bytes: number,
+    size_vram_bytes: number,
+    evicted: boolean
+  } | null
+}
+```
+
+`residency` comes from Ollama's `/api/ps`. When `evicted: true` or `size_vram < size`, the model paged to disk and inference dropped 5–10× — surface this to the user so they know to restart Ollama or trim loaded-model count.
+
+Every call is logged as one NDJSON line to `~/.ollama-intern/log.ndjson`. Filter by `hardware_profile` to keep dev numbers out of publishable benchmarks.
+
+---
+
+## Hardware profiles
+
+| Profile | Instant | Workhorse | Deep | Embed |
+|---|---|---|---|---|
+| **`dev-rtx5080`** (default) | qwen2.5 7B | qwen2.5-coder 7B | qwen2.5 14B | nomic-embed-text |
+| `dev-rtx5080-llama` | qwen2.5 7B | qwen2.5-coder 7B | **llama3.1 8B** | nomic-embed-text |
+| `m5-max` | qwen2.5 14B | qwen2.5-coder 32B | llama3.3 70B | nomic-embed-text |
+
+**Same-family ladder on default dev** so bad outputs are tool/design problems, not cross-family mismatches. `dev-rtx5080-llama` is the parity rail — run the same gold evals through Llama 8B before committing to Llama on the M5 Max.
+
+---
+
+## Evidence laws
+
+These are enforced in the server, not the prompt:
+
+- **Citations required.** Every brief claim cites an evidence id.
+- **Unknowns stripped server-side.** Models that cite ids not in the evidence bundle have those ids dropped with a warning before the result returns.
+- **Weak is weak.** Thin evidence flags `weak: true` with coverage notes. Never smoothed into fake narrative.
+- **Investigative, not prescriptive.** `next_checks` / `read_next` / `likely_breakpoints` only. Prompts forbid "apply this fix."
+- **Deterministic renderers.** Artifact markdown shape is code, not a prompt. `draft` stays reserved for prose where model wording matters.
+- **Same-pack diffs only.** Cross-pack `artifact_diff` is refused loudly; payloads stay distinct.
+
+---
+
+## Artifacts & continuity
+
+Packs write to `~/.ollama-intern/artifacts/{incident,repo,change}/<slug>.(md|json)`. The artifact tier gives you a continuity surface without turning this into a file-management tool:
+
+- `artifact_list` — metadata-only index, filterable by pack, date, slug glob
+- `artifact_read` — typed read by `{pack, slug}` or `{json_path}`
+- `artifact_diff` — structured same-pack comparison; weak-flip surfaced
+- `artifact_export_to_path` — writes an existing artifact (with provenance header) to a caller-declared `allowed_roots`. Refuses existing files unless `overwrite: true`.
+- `artifact_incident_note_snippet` — operator-note fragment
+- `artifact_onboarding_section_snippet` — handbook fragment
+- `artifact_release_note_snippet` — DRAFT release-note fragment
+
+No model calls in this tier. All render from stored content.
+
+---
+
+## Threat model & telemetry
+
+**Data touched:** file paths the caller explicitly hands in (`ollama_research`, corpus tools), inline text, and artifacts the caller asks to be written under `~/.ollama-intern/artifacts/` or a caller-declared `allowed_roots`.
+
+**Data NOT touched:** anything outside `source_paths` / `allowed_roots`. `..` is rejected before normalize. `artifact_export_to_path` refuses existing files unless `overwrite: true`. Drafts targeting protected paths (`memory/`, `.claude/`, `docs/canon/`, etc.) require explicit `confirm_write: true`, enforced server-side.
+
+**Network egress:** **off by default.** The only outbound traffic is to the local Ollama HTTP endpoint. No cloud calls, no update pings, no crash reporting.
+
+**Telemetry:** **none.** Every call is logged as one NDJSON line to `~/.ollama-intern/log.ndjson` on your machine. Nothing leaves the box.
+
+**Errors:** structured shape `{ code, message, hint, retryable }`. Stack traces are never exposed through tool results.
+
+Full policy: [SECURITY.md](SECURITY.md).
+
+---
+
+## Standards
+
+Built to the [Shipcheck](https://github.com/mcp-tool-shop-org/shipcheck) bar. Hard gates A–D pass; see [SHIP_GATE.md](SHIP_GATE.md) and [SCORECARD.md](SCORECARD.md).
+
+- **A. Security** — SECURITY.md, threat model, no telemetry, path-safety, `confirm_write` on protected paths
+- **B. Errors** — structured shape across all tool results; no raw stacks
+- **C. Docs** — README current, CHANGELOG, LICENSE; tool schemas self-document
+- **D. Hygiene** — `npm run verify` (395 tests), CI with dep scanning, Dependabot, lockfile, `engines.node`
+
+---
+
+## Roadmap (hardening, not scope creep)
+
+- **Phase 1 — Delegation Spine** ✓ shipped: atom surface, uniform envelope, tiered routing, guardrails
+- **Phase 2 — Truth Spine** ✓ shipped: schema v2 chunking, BM25 + RRF, living corpora, evidence-backed briefs, retrieval eval pack
+- **Phase 3 — Pack & Artifact Spine** ✓ shipped: fixed-pipeline packs with durable artifacts + continuity tier
+- **Phase 4 — Adoption Spine** — real-use observation on the RTX 5080, hardening the rough edges that surface
+- **Phase 5 — M5 Max benchmarks** — publishable numbers once the hardware lands (~2026-04-24)
+
+Phase by hardening layer. The atom/pack/artifact surface stays frozen.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<p align="center">Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a></p>

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Threat Model
+
+Ollama Intern MCP is a **local delegation layer**. It runs on the user's machine and talks only to a local Ollama instance (`http://localhost:11434` by default). No cloud calls, no telemetry.
+
+The primary risks are not network-facing. They are:
+
+1. **Hallucinated output trusted as truth.** Small local models fabricate. Mitigated by server-enforced citation stripping, confidence thresholds, `source_preview` in summaries, and compile checks on code drafts.
+2. **Writes to protected truth surfaces.** Drafts must never overwrite canon, memory, or doctrine files by accident. Mitigated by a versioned protected-path list in [`src/protectedPaths.ts`](src/protectedPaths.ts) — writes targeting those paths require explicit `confirm_write: true`, enforced server-side (never prompt-side).
+3. **Silent model eviction** (Ollama issue #13227). Inference quietly degrades 5–10× when a model pages to disk. Mitigated by surfacing `residency` in every call envelope so Claude can detect degradation mechanically.
+4. **Path traversal in `ollama_research`.** Mitigated by validating every cited path against the `source_paths` input and stripping any unknown path before returning.
+
+## Reporting
+
+Email: 64996768+mcp-tool-shop@users.noreply.github.com
+
+Please do not file public issues for security bugs. We will acknowledge within 72 hours.
+
+## Supported Versions
+
+Pre-1.0. Only the latest release receives security fixes.

package/dist/corpus/chunker.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Heading-aware document chunker.
+ *
+ * `chunk()` is the size-based sliding-window primitive — kept as the
+ * low-level splitter that operates within a single heading section.
+ *
+ * `chunkDocument()` is the real entry point: it walks the document,
+ * splits on heading boundaries first, preserves fenced code blocks
+ * intact, classifies each segment (frontmatter / heading / paragraph /
+ * code / list), attaches the heading_path breadcrumb, and only then
+ * size-splits oversized segments. This gives retrieval real metadata
+ * to rank on (heading_path match, chunk_type filter, title boost).
+ *
+ * Boundaries are preserved in absolute char offsets against the input
+ * text so callers can slice back into the source if needed.
+ */
+export type ChunkType = "heading" | "paragraph" | "code" | "list" | "frontmatter";
+export interface Chunk {
+    index: number;
+    char_start: number;
+    char_end: number;
+    text: string;
+    heading_path: string[];
+    chunk_type: ChunkType;
+}
+export interface ChunkOptions {
+    chunk_chars: number;
+    chunk_overlap: number;
+}
+export declare const DEFAULT_CHUNK: ChunkOptions;
+export interface ChunkedDocument {
+    title: string | null;
+    chunks: Chunk[];
+}
+interface RawChunk {
+    index: number;
+    char_start: number;
+    char_end: number;
+    text: string;
+}
+/**
+ * Primitive size-based sliding-window splitter. Used internally by
+ * chunkDocument() to size-split oversized heading sections; also exposed
+ * so existing tests can exercise window math directly.
+ */
+export declare function chunk(text: string, opts?: ChunkOptions): RawChunk[];
+/**
+ * Heading-aware document chunker.
+ *
+ * Behavior:
+ *  - YAML frontmatter at the very top becomes a single "frontmatter" chunk.
+ *  - Every markdown heading (# through ######) updates a depth-indexed
+ *    stack; chunks inherit the heading_path of the section they sit in.
+ *  - Fenced code blocks (``` or ~~~) are preserved intact — never split.
+ *  - Non-code sections are classified as "list" if majority of non-empty
+ *    lines are list items, else "paragraph".
+ *  - Sections that exceed chunk_chars are size-split via chunk() with
+ *    overlap; sub-chunks inherit the parent's heading_path + type.
+ *  - Title = first H1 heading after frontmatter, else null.
+ */
+export declare function chunkDocument(text: string, opts?: ChunkOptions): ChunkedDocument;
+export {};
+//# sourceMappingURL=chunker.d.ts.map

package/dist/corpus/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../../src/corpus/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;AAElF,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,YAG3B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,YAA4B,GAAG,QAAQ,EAAE,CAwBlF;AAuED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,YAA4B,GACjC,eAAe,CAmIjB"}

package/dist/corpus/chunker.js

@@ -0,0 +1,230 @@
+/**
+ * Heading-aware document chunker.
+ *
+ * `chunk()` is the size-based sliding-window primitive — kept as the
+ * low-level splitter that operates within a single heading section.
+ *
+ * `chunkDocument()` is the real entry point: it walks the document,
+ * splits on heading boundaries first, preserves fenced code blocks
+ * intact, classifies each segment (frontmatter / heading / paragraph /
+ * code / list), attaches the heading_path breadcrumb, and only then
+ * size-splits oversized segments. This gives retrieval real metadata
+ * to rank on (heading_path match, chunk_type filter, title boost).
+ *
+ * Boundaries are preserved in absolute char offsets against the input
+ * text so callers can slice back into the source if needed.
+ */
+export const DEFAULT_CHUNK = {
+    chunk_chars: 800,
+    chunk_overlap: 100,
+};
+/**
+ * Primitive size-based sliding-window splitter. Used internally by
+ * chunkDocument() to size-split oversized heading sections; also exposed
+ * so existing tests can exercise window math directly.
+ */
+export function chunk(text, opts = DEFAULT_CHUNK) {
+    const size = Math.max(100, opts.chunk_chars);
+    const overlap = Math.min(opts.chunk_overlap, Math.floor(size / 2));
+    if (text.length === 0)
+        return [];
+    if (text.length <= size) {
+        return [{ index: 0, char_start: 0, char_end: text.length, text }];
+    }
+    const out = [];
+    const step = size - overlap;
+    let cursor = 0;
+    let i = 0;
+    while (cursor < text.length) {
+        const end = Math.min(cursor + size, text.length);
+        out.push({
+            index: i,
+            char_start: cursor,
+            char_end: end,
+            text: text.slice(cursor, end),
+        });
+        if (end === text.length)
+            break;
+        cursor += step;
+        i += 1;
+    }
+    return out;
+}
+const HEADING_RX = /^(#{1,6})\s+(.+?)\s*$/;
+const CODE_FENCE_RX = /^(```|~~~)/;
+const LIST_ITEM_RX = /^\s*([-*+]|\d+[.)])\s+/;
+function isHeadingLine(line) {
+    const m = HEADING_RX.exec(line);
+    if (!m)
+        return null;
+    return { depth: m[1].length, text: m[2] };
+}
+function isCodeFence(line) {
+    return CODE_FENCE_RX.test(line.trim());
+}
+function isListItem(line) {
+    return LIST_ITEM_RX.test(line);
+}
+function isListMajority(content) {
+    const lines = content.split(/\r?\n/).map((l) => l.replace(/\r$/, ""));
+    const nonEmpty = lines.filter((l) => l.trim().length > 0 && isHeadingLine(l) === null);
+    if (nonEmpty.length === 0)
+        return false;
+    const listCount = nonEmpty.filter(isListItem).length;
+    return listCount * 2 > nonEmpty.length;
+}
+/** Match YAML frontmatter at the very start of the document. */
+function extractFrontmatter(text) {
+    if (!text.startsWith("---"))
+        return null;
+    // Require newline right after leading ---
+    const afterOpen = text.indexOf("\n", 3);
+    if (afterOpen === -1)
+        return null;
+    // Find closing --- on its own line.
+    const rest = text.slice(afterOpen + 1);
+    const closeRx = /(^|\n)---\s*(\n|$)/;
+    const m = closeRx.exec(rest);
+    if (!m)
+        return null;
+    const closeStart = afterOpen + 1 + m.index + (m[1] === "" ? 0 : 1);
+    const closeEnd = afterOpen + 1 + m.index + m[0].length;
+    return { end: closeEnd, content: text.slice(0, closeEnd) };
+}
+function pushSegment(segments, type, headingPath, start, end, content) {
+    const trimmed = content.replace(/^\s+|\s+$/g, "");
+    if (trimmed.length === 0)
+        return;
+    segments.push({
+        type,
+        heading_path: headingPath,
+        char_start: start,
+        char_end: end,
+        content: trimmed,
+    });
+}
+/**
+ * Heading-aware document chunker.
+ *
+ * Behavior:
+ *  - YAML frontmatter at the very top becomes a single "frontmatter" chunk.
+ *  - Every markdown heading (# through ######) updates a depth-indexed
+ *    stack; chunks inherit the heading_path of the section they sit in.
+ *  - Fenced code blocks (``` or ~~~) are preserved intact — never split.
+ *  - Non-code sections are classified as "list" if majority of non-empty
+ *    lines are list items, else "paragraph".
+ *  - Sections that exceed chunk_chars are size-split via chunk() with
+ *    overlap; sub-chunks inherit the parent's heading_path + type.
+ *  - Title = first H1 heading after frontmatter, else null.
+ */
+export function chunkDocument(text, opts = DEFAULT_CHUNK) {
+    if (text.length === 0)
+        return { title: null, chunks: [] };
+    const segments = [];
+    let title = null;
+    let cursor = 0;
+    const fm = extractFrontmatter(text);
+    if (fm) {
+        pushSegment(segments, "frontmatter", [], 0, fm.end, fm.content);
+        cursor = fm.end;
+    }
+    const headingStack = [null, null, null, null, null, null];
+    const getPath = () => headingStack.filter((h) => h !== null);
+    let bufStart = cursor;
+    let bufEnd = cursor;
+    let bufText = "";
+    let inCode = false;
+    let codeStart = 0;
+    const flushBuf = () => {
+        if (bufText.length === 0)
+            return;
+        const type = isListMajority(bufText) ? "list" : "paragraph";
+        pushSegment(segments, type, getPath(), bufStart, bufEnd, bufText);
+        bufText = "";
+    };
+    // Line walker over text[cursor..].
+    let pos = cursor;
+    while (pos <= text.length) {
+        const nl = text.indexOf("\n", pos);
+        const lineEnd = nl === -1 ? text.length : nl;
+        const line = text.slice(pos, lineEnd).replace(/\r$/, "");
+        const lineStart = pos;
+        const nextPos = nl === -1 ? text.length + 1 : nl + 1;
+        if (inCode) {
+            if (isCodeFence(line)) {
+                const codeEnd = nextPos - (nl === -1 ? 1 : 0);
+                pushSegment(segments, "code", getPath(), codeStart, codeEnd, text.slice(codeStart, codeEnd));
+                inCode = false;
+                bufStart = nextPos;
+                bufEnd = nextPos;
+            }
+            pos = nextPos;
+            continue;
+        }
+        if (isCodeFence(line)) {
+            flushBuf();
+            inCode = true;
+            codeStart = lineStart;
+            pos = nextPos;
+            continue;
+        }
+        const heading = isHeadingLine(line);
+        if (heading) {
+            flushBuf();
+            for (let d = heading.depth + 1; d <= 6; d++)
+                headingStack[d - 1] = null;
+            headingStack[heading.depth - 1] = heading.text;
+            if (title === null && heading.depth === 1)
+                title = heading.text;
+            bufStart = lineStart;
+            bufEnd = nextPos;
+            bufText = line;
+            pos = nextPos;
+            continue;
+        }
+        if (bufText.length === 0) {
+            bufStart = lineStart;
+            bufText = line;
+        }
+        else {
+            bufText += "\n" + line;
+        }
+        bufEnd = nextPos;
+        pos = nextPos;
+    }
+    if (inCode) {
+        pushSegment(segments, "code", getPath(), codeStart, text.length, text.slice(codeStart));
+    }
+    else {
+        flushBuf();
+    }
+    // Size-split oversized segments; never cross heading boundaries.
+    const chunks = [];
+    let idx = 0;
+    for (const seg of segments) {
+        if (seg.content.length <= opts.chunk_chars || seg.type === "code") {
+            chunks.push({
+                index: idx++,
+                char_start: seg.char_start,
+                char_end: seg.char_end,
+                text: seg.content,
+                heading_path: seg.heading_path,
+                chunk_type: seg.type,
+            });
+            continue;
+        }
+        const sub = chunk(seg.content, opts);
+        for (const s of sub) {
+            chunks.push({
+                index: idx++,
+                char_start: seg.char_start + s.char_start,
+                char_end: seg.char_start + s.char_end,
+                text: s.text,
+                heading_path: seg.heading_path,
+                chunk_type: seg.type,
+            });
+        }
+    }
+    return { title, chunks };
+}
+//# sourceMappingURL=chunker.js.map

package/dist/corpus/chunker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.js","sourceRoot":"","sources":["../../src/corpus/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAkBH,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC,WAAW,EAAE,GAAG;IAChB,aAAa,EAAE,GAAG;CACnB,CAAC;AAcF;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,OAAqB,aAAa;IACpE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;IACnE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;QACxB,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC;IAC5B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACjD,GAAG,CAAC,IAAI,CAAC;YACP,KAAK,EAAE,CAAC;YACR,UAAU,EAAE,MAAM;YAClB,QAAQ,EAAE,GAAG;YACb,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC;SAC9B,CAAC,CAAC;QACH,IAAI,GAAG,KAAK,IAAI,CAAC,MAAM;YAAE,MAAM;QAC/B,MAAM,IAAI,IAAI,CAAC;QACf,CAAC,IAAI,CAAC,CAAC;IACT,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAUD,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAC3C,MAAM,aAAa,GAAG,YAAY,CAAC;AACnC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAE9C,SAAS,aAAa,CAAC,IAAY;IACjC,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,cAAc,CAAC,OAAe;IACrC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IACvF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;IACrD,OAAO,SAAS,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;AACzC,CAAC;AAED,gEAAgE;AAChE,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,0CAA0C;IAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACxC,IAAI,SAAS,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,oCAAoC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,oBAAoB,CAAC;IACrC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,UAAU,GAAG,SAAS,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,SAAS,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACvD,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,SAAS,WAAW,CAClB,QAAmB,EACnB,IAAe,EACf,WAAqB,EACrB,KAAa,EACb,GAAW,EACX,OAAe;IAEf,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAClD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,QAAQ,CAAC,IAAI,CAAC;QACZ,IAAI;QACJ,YAAY,EAAE,WAAW;QACzB,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,GAAG;QACb,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,OAAqB,aAAa;IAElC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAE1D,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,IAAI,KAAK,GAAkB,IAAI,CAAC;IAEhC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,EAAE,EAAE,CAAC;QACP,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;QAChE,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,MAAM,YAAY,GAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAG,GAAa,EAAE,CAC7B,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAEtD,IAAI,QAAQ,GAAG,MAAM,CAAC;IACtB,IAAI,MAAM,GAAG,MAAM,CAAC;IACpB,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACjC,MAAM,IAAI,GAAc,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;QACvE,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAClE,OAAO,GAAG,EAAE,CAAC;IACf,CAAC,CAAC;IAEF,mCAAmC;IACnC,IAAI,GAAG,GAAG,MAAM,CAAC;IACjB,OAAO,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,GAAG,CAAC;QACtB,MAAM,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAErD,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC9C,WAAW,CACT,QAAQ,EACR,MAAM,EACN,OAAO,EAAE,EACT,SAAS,EACT,OAAO,EACP,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAC/B,CAAC;gBACF,MAAM,GAAG,KAAK,CAAC;gBACf,QAAQ,GAAG,OAAO,CAAC;gBACnB,MAAM,GAAG,OAAO,CAAC;YACnB,CAAC;YACD,GAAG,GAAG,OAAO,CAAC;YACd,SAAS;QACX,CAAC;QAED,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,QAAQ,EAAE,CAAC;YACX,MAAM,GAAG,IAAI,CAAC;YACd,SAAS,GAAG,SAAS,CAAC;YACtB,GAAG,GAAG,OAAO,CAAC;YACd,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,OAAO,EAAE,CAAC;YACZ,QAAQ,EAAE,CAAC;YACX,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;gBAAE,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;YACxE,YAAY,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;YAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,KAAK,CAAC;gBAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;YAChE,QAAQ,GAAG,SAAS,CAAC;YACrB,MAAM,GAAG,OAAO,CAAC;YACjB,OAAO,GAAG,IAAI,CAAC;YACf,GAAG,GAAG,OAAO,CAAC;YACd,SAAS;QACX,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,QAAQ,GAAG,SAAS,CAAC;YACrB,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,IAAI,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,MAAM,GAAG,OAAO,CAAC;QACjB,GAAG,GAAG,OAAO,CAAC;IAChB,CAAC;IAED,IAAI,MAAM,EAAE,CAAC;QACX,WAAW,CACT,QAAQ,EACR,MAAM,EACN,OAAO,EAAE,EACT,SAAS,EACT,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CACtB,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,QAAQ,EAAE,CAAC;IACb,CAAC;IAED,iEAAiE;IACjE,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAClE,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK,EAAE,GAAG,EAAE;gBACZ,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,IAAI,EAAE,GAAG,CAAC,OAAO;gBACjB,YAAY,EAAE,GAAG,CAAC,YAAY;gBAC9B,UAAU,EAAE,GAAG,CAAC,IAAI;aACrB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrC,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK,EAAE,GAAG,EAAE;gBACZ,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;gBACzC,QAAQ,EAAE,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ;gBACrC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,YAAY,EAAE,GAAG,CAAC,YAAY;gBAC9B,UAAU,EAAE,GAAG,CAAC,IAAI;aACrB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC"}

package/dist/corpus/fusion.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Score fusion primitives — pure, deterministic, no I/O.
+ *
+ * RRF (Reciprocal Rank Fusion) combines multiple ranked lists into one.
+ * It is the standard fusion strategy in modern hybrid retrieval because
+ * it needs no score calibration — only ranks — so BM25 and cosine can
+ * be safely combined without learning a joint normalization.
+ *
+ * `applyFactBoost` is the "fact mode" reranker: a dominant multiplier
+ * for exact-substring matches plus a secondary multiplier for short
+ * chunks. Boost, never filter — chunks without a match keep their
+ * fused score and stay in the result so a near-miss query never
+ * collapses to empty.
+ */
+export interface Ranked {
+    /** Opaque chunk identifier. */
+    chunkId: string;
+    /** 1-indexed rank within the source list. */
+    rank: number;
+}
+export interface FusionList {
+    ranked: Ranked[];
+    /** Defaults to 1.0. Weighting is multiplicative on the RRF term. */
+    weight?: number;
+}
+/**
+ * Reciprocal Rank Fusion. Score for doc d =
+ *   sum over input lists i: weight_i / (K + rank_i(d))
+ * where K is a smoothing constant (default 60 — the canonical value from
+ * Cormack et al. 2009). A doc that appears in only one list is still
+ * scored; a doc absent from every list never appears in the output.
+ */
+export declare function rrfFuse(lists: FusionList[], k?: number): Map<string, number>;
+/**
+ * Convert a score-sorted list into a rank list. Ties are broken by the
+ * order the scores arrive — callers are responsible for passing in a
+ * deterministically sorted list. Ranks are 1-indexed as RRF expects.
+ */
+export declare function toRanked(scored: Array<{
+    chunkId: string;
+}>): Ranked[];
+export interface FactBoostOptions {
+    /** Multiplier applied when the chunk text contains the query substring (case-insensitive). */
+    exactSubstringMultiplier?: number;
+    /** Multiplier range for short chunks. Shorter = higher multiplier. */
+    shortChunkMaxMultiplier?: number;
+    /** Chunks at or below this length receive the full short-chunk boost. */
+    shortChunkFloorChars?: number;
+    /** Chunks at or above this length receive no short-chunk boost. */
+    shortChunkCeilingChars?: number;
+}
+export interface FactBoostInput {
+    chunkId: string;
+    score: number;
+}
+export interface FactBoostContext {
+    query: string;
+    chunkText: Map<string, string>;
+}
+/**
+ * Apply the fact-mode reranker. Returns a new list; input is not mutated.
+ * Dominant boost = exact substring match (multiplier ≈ 2.5x by default).
+ * Secondary boost = short-chunk preference (up to ≈ 1.15x, decays to 1.0).
+ * Non-matching chunks keep their fused score unchanged and stay in the list.
+ */
+export declare function applyFactBoost(scored: FactBoostInput[], ctx: FactBoostContext, opts?: FactBoostOptions): FactBoostInput[];
+//# sourceMappingURL=fusion.d.ts.map