@monoes/monomindcli 2.14.0 → 2.15.0

package/dist/src/knowledge/capture-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-envelope.js","sourceRoot":"","sources":["../../../src/knowledge/capture-envelope.ts"],"names":[],"mappings":"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"}

package/dist/src/knowledge/capture-text.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Text extraction for web captures (RCL-01) — the HTML/MHTML arm of
+ * `extractText`, kept here so `cap-documents.ts` stays a dispatch table.
+ *
+ * @module v1/cli/knowledge/capture-text
+ */
+export declare const HTML_EXTENSIONS: Set<string>;
+export declare const MHTML_EXTENSIONS: Set<string>;
+export declare function isCaptureExtension(ext: string): boolean;
+/**
+ * Clean text for an archived page.
+ *
+ * PRECEDENCE — when the file sits in a capture envelope, the sibling
+ * `readable.md` wins. It was produced by Readability against the LIVE DOM,
+ * with lazy images resolved, the consent modal dismissed and the site's own JS
+ * finished; nothing derived from the archived markup can beat that. Our own
+ * extractor is the fallback for archives nobody cleaned.
+ *
+ * Returns '' rather than throwing — an unreadable capture is a document with
+ * no text, not a failed ingest.
+ */
+export declare function extractCaptureText(absolutePath: string, ext: string): string;
+//# sourceMappingURL=capture-text.d.ts.map

package/dist/src/knowledge/capture-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-text.d.ts","sourceRoot":"","sources":["../../../src/knowledge/capture-text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,eAAO,MAAM,eAAe,aAAuC,CAAC;AACpE,eAAO,MAAM,gBAAgB,aAA8B,CAAC;AAE5D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAiB5E"}

package/dist/src/knowledge/capture-text.js

@@ -0,0 +1,49 @@
+/**
+ * Text extraction for web captures (RCL-01) — the HTML/MHTML arm of
+ * `extractText`, kept here so `cap-documents.ts` stays a dispatch table.
+ *
+ * @module v1/cli/knowledge/capture-text
+ */
+import * as fs from 'node:fs';
+import { readableSiblingFor } from './capture-envelope.js';
+import { htmlToMarkdown } from './html-extract.js';
+import { mhtmlToHtml } from './mhtml.js';
+export const HTML_EXTENSIONS = new Set(['.html', '.htm', '.xhtml']);
+export const MHTML_EXTENSIONS = new Set(['.mhtml', '.mht']);
+export function isCaptureExtension(ext) {
+    return HTML_EXTENSIONS.has(ext) || MHTML_EXTENSIONS.has(ext);
+}
+/**
+ * Clean text for an archived page.
+ *
+ * PRECEDENCE — when the file sits in a capture envelope, the sibling
+ * `readable.md` wins. It was produced by Readability against the LIVE DOM,
+ * with lazy images resolved, the consent modal dismissed and the site's own JS
+ * finished; nothing derived from the archived markup can beat that. Our own
+ * extractor is the fallback for archives nobody cleaned.
+ *
+ * Returns '' rather than throwing — an unreadable capture is a document with
+ * no text, not a failed ingest.
+ */
+export function extractCaptureText(absolutePath, ext) {
+    try {
+        const readable = readableSiblingFor(absolutePath);
+        if (readable)
+            return fs.readFileSync(readable, 'utf-8');
+    }
+    catch {
+        /* no envelope, or an unreadable one — extract from the file itself */
+    }
+    try {
+        if (MHTML_EXTENSIONS.has(ext)) {
+            // latin1 preserves the raw bytes: transfer encoding comes off first, and
+            // the real charset is only known per MIME part.
+            return htmlToMarkdown(mhtmlToHtml(fs.readFileSync(absolutePath, 'latin1')).html);
+        }
+        return htmlToMarkdown(fs.readFileSync(absolutePath, 'utf-8'));
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=capture-text.js.map

package/dist/src/knowledge/capture-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-text.js","sourceRoot":"","sources":["../../../src/knowledge/capture-text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AACpE,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAE5D,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,OAAO,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB,EAAE,GAAW;IAClE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;QAClD,IAAI,QAAQ;YAAE,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;IACD,IAAI,CAAC;QACH,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,yEAAyE;YACzE,gDAAgD;YAChD,OAAO,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,cAAc,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/src/knowledge/citation.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Paragraph-level citation (RCL-10).
+ *
+ * A search hit already knows WHICH document it came from. A citation has to
+ * know WHERE IN IT: the character span of the chunk against the extracted
+ * text, an anchor that survives being written down, and a way back to the
+ * live page at that passage.
+ *
+ * Three pieces, deliberately separate:
+ *
+ *  - `span:<start>-<end>` — a tag written next to every chunk at ingest, so a
+ *    search result carries offsets without re-reading the document.
+ *  - the ANCHOR `<hash12>#<start>-<end>` — offsets bound to the content hash
+ *    of the exact version they were measured against. Quoting an offset range
+ *    without the version it belongs to is how citations rot: the document is
+ *    re-captured, the text shifts, and the quote silently points at other
+ *    words. A stale anchor here is DETECTED (`stale: true`), never served as
+ *    if it were still true.
+ *  - a W3C text fragment (`#:~:text=`) — the link a human clicks, which lands
+ *    on the sentence even though the site never had an id there.
+ *
+ * Everything above `resolveCitation` is pure and synchronous so the pipeline
+ * can use it while ingesting. `resolveCitation` reaches back into the
+ * document-pipeline through a DYNAMIC import: the pipeline imports this
+ * module statically, and a static import back would close the cycle.
+ *
+ * @module v1/cli/knowledge/citation
+ */
+import type { CaptureProvenance } from './capture-envelope.js';
+export declare const SPAN_TAG_PREFIX = "span:";
+export interface ChunkSpan {
+    chunkIndex: number;
+    startChar: number;
+    endChar: number;
+}
+/** The tag written beside a chunk at ingest: `span:<start>-<end>`. */
+export declare function spanTag(startChar: number, endChar: number): string;
+/** Offsets from a chunk's tag list, or null when it predates span tags. */
+export declare function parseSpanTag(tags: readonly string[] | undefined): {
+    startChar: number;
+    endChar: number;
+} | null;
+/** `<hash12>#<start>-<end>` — offsets bound to the version they were measured against. */
+export declare function citationAnchor(contentHash: string, startChar: number, endChar: number): string;
+export declare function parseCitationAnchor(anchor: string): {
+    hashPrefix: string;
+    startChar: number;
+    endChar: number;
+} | null;
+/** True when the anchor was cut against this document version. */
+export declare function anchorMatchesHash(anchor: string, contentHash: string): boolean;
+/**
+ * The prose of a passage: § context prefixes gone, markdown syntax gone,
+ * whitespace collapsed.
+ *
+ * `skipHeadings` drops heading lines as well, which is what a text fragment
+ * wants — a heading is usually its own element on the page, so starting a
+ * range there matches less reliably than starting at the paragraph. It falls
+ * back to including them when the passage is nothing but headings.
+ */
+export declare function passageProse(passage: string, skipHeadings?: boolean): string;
+/** The head of a passage as a quotable sentence or two — the words a reader
+ *  would see on the page, not the markdown we stored. */
+export declare function passageQuote(passage: string, maxChars?: number): string;
+/**
+ * A W3C scroll-to-text fragment for this passage.
+ *
+ * Long passages use the `textStart,textEnd` form rather than the whole
+ * paragraph: the spec matches across the range, and a shorter pair survives
+ * the site re-flowing its markup between capture and click.
+ */
+export declare function textFragment(passage: string): string;
+/** The captured page's URL, pointed at the passage. Returns undefined when
+ *  there is no URL — a citation into a local file has no link to give. */
+export declare function citationUrl(url: string | undefined, passage: string): string | undefined;
+export interface Citation {
+    /** `<scope>:<filePath>` — the pipeline's own document id. */
+    docId: string;
+    filePath: string;
+    scope: string;
+    chunkIndex: number;
+    startChar: number;
+    endChar: number;
+    /** Hash of the text the offsets were cut against, i.e. the file as it is NOW. */
+    contentHash: string;
+    anchor: string;
+    /** The cited text itself, straight out of the extracted document. */
+    passage: string;
+    /** The head of the passage, collapsed — what an agent puts in quotes. */
+    quote: string;
+    /** Present only when the anchor asked for a version this file no longer is. */
+    stale?: boolean;
+    version?: number;
+    title?: string;
+    url?: string;
+    /** `url` with a text fragment appended: the link that lands on the passage. */
+    citeUrl?: string;
+    capturedAt?: string;
+    source?: string;
+    provenance?: CaptureProvenance;
+}
+export interface ResolveCitationOptions {
+    rootDir?: string;
+    scope?: string;
+    /** Chunk index, as reported on a search hit. */
+    chunkIndex?: number;
+    /** An anchor string from a previous citation — resolved by offsets, and
+     *  flagged `stale` when it names a version this document no longer is. */
+    anchor?: string;
+}
+/**
+ * Resolve a citation back to the passage it came from.
+ *
+ * `target` is whatever the caller has written down: an indexed file path, a
+ * capture's `canonicalUrl`, or the `<scope>:<path>` docId. Throws with a
+ * message meant for a human when the document is not indexed, its file is
+ * gone, or the chunk does not exist — a citation that cannot be checked must
+ * fail loudly, not resolve to an empty string.
+ */
+export declare function resolveCitation(target: string, opts?: ResolveCitationOptions): Promise<Citation>;
+//# sourceMappingURL=citation.d.ts.map

package/dist/src/knowledge/citation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation.d.ts","sourceRoot":"","sources":["../../../src/knowledge/citation.ts"],"names":[],"mappings":"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"}

package/dist/src/knowledge/citation.js

@@ -0,0 +1,252 @@
+/**
+ * Paragraph-level citation (RCL-10).
+ *
+ * A search hit already knows WHICH document it came from. A citation has to
+ * know WHERE IN IT: the character span of the chunk against the extracted
+ * text, an anchor that survives being written down, and a way back to the
+ * live page at that passage.
+ *
+ * Three pieces, deliberately separate:
+ *
+ *  - `span:<start>-<end>` — a tag written next to every chunk at ingest, so a
+ *    search result carries offsets without re-reading the document.
+ *  - the ANCHOR `<hash12>#<start>-<end>` — offsets bound to the content hash
+ *    of the exact version they were measured against. Quoting an offset range
+ *    without the version it belongs to is how citations rot: the document is
+ *    re-captured, the text shifts, and the quote silently points at other
+ *    words. A stale anchor here is DETECTED (`stale: true`), never served as
+ *    if it were still true.
+ *  - a W3C text fragment (`#:~:text=`) — the link a human clicks, which lands
+ *    on the sentence even though the site never had an id there.
+ *
+ * Everything above `resolveCitation` is pure and synchronous so the pipeline
+ * can use it while ingesting. `resolveCitation` reaches back into the
+ * document-pipeline through a DYNAMIC import: the pipeline imports this
+ * module statically, and a static import back would close the cycle.
+ *
+ * @module v1/cli/knowledge/citation
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const SPAN_TAG_PREFIX = 'span:';
+/** The tag written beside a chunk at ingest: `span:<start>-<end>`. */
+export function spanTag(startChar, endChar) {
+    return `${SPAN_TAG_PREFIX}${startChar}-${endChar}`;
+}
+/** Offsets from a chunk's tag list, or null when it predates span tags. */
+export function parseSpanTag(tags) {
+    for (const tag of tags ?? []) {
+        if (typeof tag !== 'string' || !tag.startsWith(SPAN_TAG_PREFIX))
+            continue;
+        const m = /^span:(\d+)-(\d+)$/.exec(tag);
+        if (!m)
+            continue;
+        const startChar = Number(m[1]);
+        const endChar = Number(m[2]);
+        if (endChar < startChar)
+            continue;
+        return { startChar, endChar };
+    }
+    return null;
+}
+const ANCHOR_HASH_CHARS = 12;
+/** `<hash12>#<start>-<end>` — offsets bound to the version they were measured against. */
+export function citationAnchor(contentHash, startChar, endChar) {
+    return `${(contentHash || '').slice(0, ANCHOR_HASH_CHARS)}#${startChar}-${endChar}`;
+}
+export function parseCitationAnchor(anchor) {
+    const m = /^([0-9a-f]{4,64})#(\d+)-(\d+)$/.exec((anchor || '').trim());
+    if (!m)
+        return null;
+    const startChar = Number(m[2]);
+    const endChar = Number(m[3]);
+    if (endChar < startChar)
+        return null;
+    return { hashPrefix: m[1], startChar, endChar };
+}
+/** True when the anchor was cut against this document version. */
+export function anchorMatchesHash(anchor, contentHash) {
+    const parsed = parseCitationAnchor(anchor);
+    if (!parsed)
+        return false;
+    return (contentHash || '').startsWith(parsed.hashPrefix);
+}
+// ── Quotes and links ───────────────────────────────────────────────
+const QUOTE_MAX_CHARS = 320;
+const CONTEXT_PREFIX_RE = /^(§ [^\n]*\n)+/;
+const HEADING_LINE_RE = /^\s{0,3}#{1,6}\s+/;
+/**
+ * One line of markdown as the words a reader sees.
+ *
+ * This matters more than it looks: a text fragment built from `# Pricing ##
+ * Starter Nine dollars` matches NOTHING on the live page, because the page
+ * never contained a `#`. The link is only worth having if it is made of the
+ * prose the site actually renders.
+ */
+function stripMarkdown(line) {
+    return line
+        .replace(HEADING_LINE_RE, '')
+        .replace(/^\s{0,3}>\s?/, '')
+        .replace(/^\s{0,3}([-*+]|\d+\.)\s+/, '')
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+        .replace(/`{1,3}([^`]*)`{1,3}/g, '$1')
+        .replace(/(\*\*|__)(.*?)\1/g, '$2')
+        .replace(/(\*|_)(?=\S)(.*?)(?<=\S)\1/g, '$2')
+        .trim();
+}
+/**
+ * The prose of a passage: § context prefixes gone, markdown syntax gone,
+ * whitespace collapsed.
+ *
+ * `skipHeadings` drops heading lines as well, which is what a text fragment
+ * wants — a heading is usually its own element on the page, so starting a
+ * range there matches less reliably than starting at the paragraph. It falls
+ * back to including them when the passage is nothing but headings.
+ */
+export function passageProse(passage, skipHeadings = false) {
+    const lines = String(passage ?? '')
+        .replace(CONTEXT_PREFIX_RE, '')
+        .split('\n');
+    const keep = (only) => lines
+        .filter((l) => !only || !HEADING_LINE_RE.test(l))
+        .map(stripMarkdown)
+        .filter(Boolean)
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const body = keep(skipHeadings);
+    return body || keep(false);
+}
+/** The head of a passage as a quotable sentence or two — the words a reader
+ *  would see on the page, not the markdown we stored. */
+export function passageQuote(passage, maxChars = QUOTE_MAX_CHARS) {
+    const text = passageProse(passage);
+    if (text.length <= maxChars)
+        return text;
+    const window = text.slice(0, maxChars);
+    const stop = Math.max(window.lastIndexOf('. '), window.lastIndexOf('? '), window.lastIndexOf('! '));
+    return stop > maxChars * 0.4 ? window.slice(0, stop + 1) : `${window.trimEnd()}…`;
+}
+/** `,` and `-` are syntax inside a text fragment, so they cannot be left raw. */
+function encodeFragmentPart(text) {
+    return encodeURIComponent(text).replace(/-/g, '%2D').replace(/,/g, '%2C');
+}
+const FRAGMENT_WORDS = 8;
+/**
+ * A W3C scroll-to-text fragment for this passage.
+ *
+ * Long passages use the `textStart,textEnd` form rather than the whole
+ * paragraph: the spec matches across the range, and a shorter pair survives
+ * the site re-flowing its markup between capture and click.
+ */
+export function textFragment(passage) {
+    const text = passageProse(passage, true).slice(0, 2000);
+    if (!text)
+        return '';
+    const words = text.split(' ').filter(Boolean);
+    if (words.length <= FRAGMENT_WORDS * 2)
+        return `:~:text=${encodeFragmentPart(text)}`;
+    const start = words.slice(0, FRAGMENT_WORDS).join(' ');
+    const end = words.slice(-FRAGMENT_WORDS).join(' ');
+    return `:~:text=${encodeFragmentPart(start)},${encodeFragmentPart(end)}`;
+}
+/** The captured page's URL, pointed at the passage. Returns undefined when
+ *  there is no URL — a citation into a local file has no link to give. */
+export function citationUrl(url, passage) {
+    if (!url)
+        return undefined;
+    const fragment = textFragment(passage);
+    if (!fragment)
+        return url;
+    const hash = url.indexOf('#');
+    const base = hash === -1 ? url : url.slice(0, hash);
+    return `${base}#${fragment}`;
+}
+function fileEntry(absolutePath) {
+    const stat = fs.statSync(absolutePath);
+    return {
+        path: absolutePath,
+        absolutePath,
+        extension: path.extname(absolutePath).toLowerCase(),
+        size: stat.size,
+        modified: stat.mtime,
+        created: stat.birthtime,
+    };
+}
+/**
+ * Resolve a citation back to the passage it came from.
+ *
+ * `target` is whatever the caller has written down: an indexed file path, a
+ * capture's `canonicalUrl`, or the `<scope>:<path>` docId. Throws with a
+ * message meant for a human when the document is not indexed, its file is
+ * gone, or the chunk does not exist — a citation that cannot be checked must
+ * fail loudly, not resolve to an empty string.
+ */
+export async function resolveCitation(target, opts = {}) {
+    const pipeline = await import('./document-pipeline.js');
+    const { extractText } = await import('../capabilities/cap-documents.js');
+    const rootDir = opts.rootDir ?? pipeline.getKnowledgeRoot(opts.scope);
+    const scope = opts.scope;
+    const record = pipeline.findDocumentRecord(rootDir, target, scope);
+    if (!record)
+        throw new Error(`not indexed: ${target}`);
+    if (!fs.existsSync(record.filePath)) {
+        throw new Error(`source file is gone: ${record.filePath} (re-ingest the capture to cite it)`);
+    }
+    const text = await extractText(fileEntry(record.filePath));
+    if (!text)
+        throw new Error(`no text could be extracted from ${record.filePath}`);
+    const hash = crypto.createHash('sha256').update(text).digest('hex');
+    let startChar;
+    let endChar;
+    let chunkIndex;
+    const parsedAnchor = opts.anchor ? parseCitationAnchor(opts.anchor) : null;
+    if (opts.anchor && !parsedAnchor)
+        throw new Error(`malformed citation anchor: ${opts.anchor}`);
+    if (parsedAnchor) {
+        startChar = Math.min(parsedAnchor.startChar, text.length);
+        endChar = Math.min(parsedAnchor.endChar, text.length);
+        const spans = await pipeline.chunkSpans(text);
+        chunkIndex = spans.findIndex((s) => s.startChar === startChar);
+        if (chunkIndex === -1) {
+            chunkIndex = spans.findIndex((s) => s.startChar <= startChar && startChar < s.endChar);
+        }
+    }
+    else {
+        chunkIndex = opts.chunkIndex ?? 0;
+        const spans = await pipeline.chunkSpans(text);
+        const span = spans[chunkIndex];
+        if (!span) {
+            throw new Error(`chunk ${chunkIndex} is out of range: ${path.basename(record.filePath)} has ${spans.length} chunk(s)`);
+        }
+        startChar = span.startChar;
+        endChar = span.endChar;
+    }
+    const passage = text.slice(startChar, endChar);
+    const url = record.canonicalUrl ?? record.provenance?.canonicalUrl ?? record.provenance?.url;
+    const stale = parsedAnchor
+        ? !anchorMatchesHash(opts.anchor, hash)
+        : hash !== record.contentHash;
+    return {
+        docId: `${record.scope}:${record.filePath}`,
+        filePath: record.filePath,
+        scope: record.scope,
+        chunkIndex: chunkIndex === -1 ? 0 : chunkIndex,
+        startChar,
+        endChar,
+        contentHash: hash,
+        anchor: citationAnchor(hash, startChar, endChar),
+        passage,
+        quote: passageQuote(passage),
+        ...(stale ? { stale: true } : {}),
+        ...(record.version ? { version: record.version } : {}),
+        ...(record.provenance?.title ? { title: record.provenance.title } : {}),
+        ...(url ? { url, citeUrl: citationUrl(url, passage) } : {}),
+        ...(record.provenance?.capturedAt ? { capturedAt: record.provenance.capturedAt } : {}),
+        ...(record.provenance?.source ? { source: record.provenance.source } : {}),
+        ...(record.provenance ? { provenance: record.provenance } : {}),
+    };
+}
+//# sourceMappingURL=citation.js.map

package/dist/src/knowledge/citation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation.js","sourceRoot":"","sources":["../../../src/knowledge/citation.ts"],"names":[],"mappings":"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"}

package/dist/src/knowledge/document-chunking.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Document chunking — turning a document's extracted text into the enriched
+ * chunks that get embedded and stored.
+ *
+ * Two passes, in this order:
+ *  1. CHUNK — split on heading/paragraph boundaries (shared `@monoes/memory`
+ *     chunker, with an inline fallback kept byte-identical to it).
+ *  2. ENRICH — replace each chunk's leaf-heading prefix with a situating blurb
+ *     (doc title + full heading path + summary) so the embedding model can tell
+ *     two identically-titled sections of different documents apart.
+ *
+ * Split out of document-pipeline.ts. Pure string work: no fs, no network, no
+ * store access — which is what makes chunk spans reproducible at citation time
+ * (`chunkSpans`) without re-reading anything.
+ *
+ * @module v1/cli/knowledge/document-chunking
+ */
+import type { ChunkSpan } from './citation.js';
+export interface TextChunk {
+    chunkId: string;
+    docId: string;
+    text: string;
+    startChar: number;
+    endChar: number;
+    chunkIndex: number;
+}
+export declare function chunkDocument(docId: string, text: string): Promise<TextChunk[]>;
+/**
+ * Replace each chunk's `§ heading` prefix with a richer situating blurb:
+ *   § <doc title> · <full heading path>
+ *   <doc summary for non-first chunks>
+ *
+ * First chunks that start with their own heading are left untouched (the
+ * heading IS the context). The summary line is omitted for the first
+ * chunk since it is adjacent to the summary text anyway.
+ */
+export declare function enrichChunks(chunks: TextChunk[], fullText: string, filePath: string): TextChunk[];
+/** Chunk spans for a text, using the SAME chunker the ingest used — this is
+ *  what makes a chunk index resolvable back to a character range without
+ *  storing the text twice. */
+export declare function chunkSpans(text: string): Promise<ChunkSpan[]>;
+//# sourceMappingURL=document-chunking.d.ts.map

package/dist/src/knowledge/document-chunking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-chunking.d.ts","sourceRoot":"","sources":["../../../src/knowledge/document-chunking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AA6GD,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAOrF;AAwGD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAoCjG;AAED;;8BAE8B;AAC9B,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAOnE"}