renor-engine 0.0.0-stage → 1.0.0

package/dist/importing/serialize.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderNoteMarkdown = renderNoteMarkdown;
+exports.destinationRelPath = destinationRelPath;
+/**
+ * Produce the bytes to write for a note.
+ *
+ * The source's **original Markdown is preferred whenever it is reachable**: it is the
+ * source of truth, and carrying a document is not re-parsing it (the constraint on this
+ * path is that no re-parse, re-chunk or re-embed is run — not that a document may not
+ * be carried).
+ *
+ * Reconstruction is the fallback for an index whose content tree is unavailable. It
+ * concatenates the source's own chunk texts in order with the heading structure their
+ * `heading_path` values already describe — not a re-parse, but a projection: it is
+ * lossy for YAML comments and key order, and a caller that falls back is told so by
+ * `fromOriginalBytes: false`.
+ *
+ * Chunk spans are **located in the bytes actually written**, not copied from the source
+ * index. Measured on a real 22,774-chunk index, only 475 of 594 sampled stored spans
+ * contained their own chunk text (the engine's paragraph splitter accumulates its
+ * offsets approximately), while 593 of 594 chunk texts were found in the note body. A
+ * copied span would therefore mis-cite a fifth of chunks; a located span is true of the
+ * file being written by construction.
+ */
+function renderNoteMarkdown(note) {
+    const fromOriginalBytes = typeof note.originalContent === 'string';
+    const content = fromOriginalBytes
+        ? note.originalContent
+        : reconstructNoteMarkdown(note);
+    const located = locateChunkLines(content, note.chunks);
+    let chunksNotLocated = 0;
+    let chunksSpanInherited = 0;
+    const chunkLines = located.lines.map((span, index) => {
+        if (located.found[index])
+            return span;
+        chunksNotLocated += 1;
+        const chunk = note.chunks[index];
+        // The source's stored span describes the source's own bytes. That is exactly what is
+        // being written on the original-bytes path, so it may be inherited there. On the
+        // reconstruction path the written file has different bytes (frontmatter re-rendered,
+        // headings materialised, empty chunks dropped), so an inherited coordinate would
+        // point at unrelated text — report it as unknown instead.
+        if (fromOriginalBytes && typeof chunk?.startLine === 'number' && typeof chunk.endLine === 'number') {
+            chunksSpanInherited += 1;
+            return { startLine: chunk.startLine, endLine: chunk.endLine };
+        }
+        return { startLine: 0, endLine: 0 };
+    });
+    return { content, chunkLines, fromOriginalBytes, chunksNotLocated, chunksSpanInherited };
+}
+/** Half-open line spans for each chunk, found by locating its text in the content. */
+function locateChunkLines(content, chunks) {
+    const lines = [];
+    const found = [];
+    const newlinesBefore = newlineCounter(content);
+    let cursor = 0;
+    for (const chunk of chunks) {
+        const needle = chunk.text.replace(/[ \t]+$/gm, '').trim();
+        if (!needle) {
+            lines.push({ startLine: 0, endLine: 0 });
+            found.push(false);
+            continue;
+        }
+        let at = content.indexOf(needle, cursor);
+        if (at < 0)
+            at = content.indexOf(needle);
+        if (at < 0) {
+            lines.push({ startLine: 0, endLine: 0 });
+            found.push(false);
+            continue;
+        }
+        const startLine = newlinesBefore(at);
+        lines.push({ startLine, endLine: startLine + needle.split('\n').length });
+        found.push(true);
+        cursor = at + needle.length;
+    }
+    return { lines, found };
+}
+/**
+ * Counts the newlines before an offset, resuming from where the previous count stopped.
+ *
+ * Chunks are located in document order, so each count reads only the text since the last one
+ * and the pass over a note is linear in its size. Rescanning from offset 0 for every chunk cost
+ * chunks x bytes: a 13 MB note with 8,000 chunks took minutes to preview. An offset before the
+ * last stop (a chunk found out of order) is reached from whichever end is nearer, so no count
+ * reads more characters than the rescan did.
+ */
+function newlineCounter(content) {
+    let stop = 0; // `newlines` is exact for content[0, stop)
+    let newlines = 0;
+    return index => {
+        if (index >= stop)
+            newlines += countNewlines(content, stop, index);
+        else if (index < stop - index)
+            newlines = countNewlines(content, 0, index);
+        else
+            newlines -= countNewlines(content, index, stop);
+        stop = index;
+        return newlines;
+    };
+}
+function countNewlines(content, from, to) {
+    let count = 0;
+    for (let i = from; i < to; i += 1) {
+        if (content.charCodeAt(i) === 10)
+            count += 1;
+    }
+    return count;
+}
+/**
+ * Rebuild a note body from its chunks, materialising heading paths that the chunk text
+ * does not itself carry. The lines are joined verbatim — no blank-line collapsing —
+ * because the chunk spans are computed against these exact bytes.
+ */
+function reconstructNoteMarkdown(note) {
+    const lines = [];
+    const frontmatter = renderFrontmatter(note.frontmatter);
+    if (frontmatter.length > 0)
+        lines.push('---', ...frontmatter, '---', '');
+    let stack = [];
+    const first = note.chunks[0];
+    if (first && !/^#{1,3}\s/.test(first.text.trimStart()) && note.title) {
+        lines.push(`# ${note.title}`, '');
+        stack = [note.title];
+    }
+    for (const chunk of note.chunks) {
+        const text = chunk.text.replace(/[ \t]+$/gm, '').trim();
+        if (!text)
+            continue;
+        const startsWithHeading = /^#{1,3}\s/.test(text);
+        const headingStack = chunk.headingPath
+            ? chunk.headingPath.split(' > ').map(s => s.trim()).filter(Boolean)
+            : [];
+        if (startsWithHeading) {
+            if (headingStack.length > 0)
+                stack = headingStack;
+        }
+        else if (headingStack.length > 0) {
+            let common = 0;
+            while (common < Math.min(headingStack.length, stack.length) && headingStack[common] === stack[common])
+                common += 1;
+            for (let level = common; level < headingStack.length; level += 1) {
+                lines.push(`${'#'.repeat(Math.min(level + 1, 3))} ${headingStack[level]}`);
+            }
+            stack = headingStack.slice();
+        }
+        if (lines.length > 0 && lines[lines.length - 1] !== '')
+            lines.push('');
+        lines.push(...text.split('\n'));
+    }
+    return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}
+/**
+ * Frontmatter as YAML key/scalar lines. Values are JSON-encoded, which is a valid YAML
+ * scalar or flow collection for every JSON value, so a round-trip through the engine's
+ * own frontmatter parser cannot produce malformed YAML.
+ */
+function renderFrontmatter(frontmatter) {
+    const out = [];
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key))
+            continue;
+        if (value === undefined)
+            continue;
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined || encoded.length > 4096)
+            continue;
+        out.push(`${key}: ${encoded}`);
+    }
+    return out;
+}
+/** `namespace/relPath`, with every segment sanitized so a source path cannot escape. */
+function destinationRelPath(namespace, sourceRelPath) {
+    const cleanNamespace = sanitizeSegments(namespace);
+    const clean = sanitizeSegments(sourceRelPath);
+    if (!clean)
+        throw new Error(`source path ${JSON.stringify(sourceRelPath)} has no usable segments`);
+    return cleanNamespace ? `${cleanNamespace}/${clean}` : clean;
+}
+function sanitizeSegments(value) {
+    return value
+        .split('/')
+        .map(segment => segment.trim())
+        .filter(segment => segment !== '' && segment !== '.' && segment !== '..')
+        .map(segment => segment.replace(/[\u0000-\u001F\u007F]/g, '_'))
+        .join('/');
+}

package/dist/importing/source.js

@@ -0,0 +1,463 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRelative = toRelative;
+exports.isSelected = isSelected;
+exports.readRenorIndexSource = readRenorIndexSource;
+exports.readBundleSource = readBundleSource;
+exports.readSource = readSource;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const client_1 = require("../db/client");
+const types_1 = require("./types");
+/** Relative path with forward slashes, or the input unchanged when it is not under the root. */
+function toRelative(sourceRoot, absolutePath) {
+    const root = path_1.default.resolve(sourceRoot);
+    const abs = path_1.default.resolve(absolutePath);
+    const rel = path_1.default.relative(root, abs);
+    if (rel === '' || rel.startsWith('..') || path_1.default.isAbsolute(rel))
+        return absolutePath;
+    return rel.split(path_1.default.sep).join('/');
+}
+function matchesPrefix(relPath, prefixes) {
+    return prefixes.some(prefix => {
+        const clean = prefix.replace(/^(\.?\/)+/, '').replace(/\/+$/, '');
+        return relPath === clean || relPath.startsWith(clean + '/');
+    });
+}
+/** Selection is explicit: a path must pass `include` (when given) and survive `exclude`. */
+function isSelected(relPath, filter) {
+    if (filter.include.length > 0 && !matchesPrefix(relPath, filter.include))
+        return false;
+    if (filter.exclude.length > 0 && matchesPrefix(relPath, filter.exclude))
+        return false;
+    return true;
+}
+/**
+ * Read a Renor-shaped index (any store that uses the engine's `notes`/`chunks`/`facts`
+ * tables, including another Renor workspace or the personal brain) as an import bundle.
+ *
+ * The database is opened `readonly` so a source can never be written by an import —
+ * including the WAL side files a write-capable open would touch.
+ */
+function readRenorIndexSource(options) {
+    // Through the sanctioned opener (`src/db/client.ts`), which enforces read-only at the
+    // SQLite level so an import can never write to the store it is reading.
+    const db = (0, client_1.openReadOnlyDb)(options.dbPath);
+    try {
+        const filter = {
+            include: options.include ?? [],
+            exclude: options.exclude ?? [],
+            limit: options.limit,
+        };
+        const allNotes = db.prepare('SELECT path, title, kind, modified_at, frontmatter_json FROM notes').all();
+        const selected = [];
+        let filteredOut = 0;
+        for (const row of allNotes) {
+            const rel = toRelative(options.sourceRoot, row.path);
+            if (!isSelected(rel, filter)) {
+                filteredOut += 1;
+                continue;
+            }
+            // The lifecycle's synthetic `_mcp_` row is not a note document.
+            if (rel === '_mcp_') {
+                filteredOut += 1;
+                continue;
+            }
+            selected.push({ row, rel });
+        }
+        selected.sort((a, b) => a.rel.localeCompare(b.rel));
+        const limited = options.limit !== undefined && options.limit >= 0
+            ? selected.slice(0, options.limit)
+            : selected;
+        const chunksByNote = new Map();
+        const entitiesByNote = new Map();
+        const contentsByNote = new Map();
+        const chunkStmt = db.prepare('SELECT note_path, heading_path, text, token_count, start_line, end_line FROM chunks WHERE note_path = ? ORDER BY id');
+        // The lifecycle sentinel owns canonical entities; carrying those would duplicate
+        // the destination's own lifecycle entity for the same subject.
+        const entityStmt = db.prepare(`SELECT type, canonical_name, aliases_json, confidence FROM entities
+        WHERE source_note = ? AND source_note != '_mcp_'`);
+        const contentRoot = path_1.default.resolve(options.contentRoot ?? options.sourceRoot);
+        for (const { row, rel } of limited) {
+            const rows = chunkStmt.all(row.path);
+            chunksByNote.set(row.path, rows.map(r => ({
+                headingPath: r.heading_path ?? '',
+                text: r.text,
+                tokenCount: r.token_count,
+                // The same span rule as the bundle adapter: a coordinate that cannot be a citation
+                // is dropped rather than inherited into the destination's `chunks` rows.
+                ...normalizedSpan(r.start_line, r.end_line),
+            })));
+            const entityRows = entityStmt.all(row.path);
+            entitiesByNote.set(row.path, entityRows.map(e => ({
+                type: e.type,
+                canonicalName: e.canonical_name,
+                aliases: parseAliases(e.aliases_json),
+                confidence: typeof e.confidence === 'number' ? e.confidence : 1,
+            })));
+            // Prefer the source's own bytes: they are the source of truth, they keep the
+            // stored chunk line ranges truthful, and copying a document is not re-parsing it.
+            const original = readOriginalContent(contentRoot, rel);
+            if (original !== null)
+                contentsByNote.set(row.path, original);
+        }
+        const notes = limited.map(({ row, rel }) => ({
+            sourcePath: row.path,
+            relPath: rel,
+            title: row.title,
+            kind: row.kind ?? null,
+            modifiedAt: row.modified_at,
+            frontmatter: parseFrontmatter(row.frontmatter_json),
+            chunks: chunksByNote.get(row.path) ?? [],
+            entities: entitiesByNote.get(row.path) ?? [],
+            originalContent: contentsByNote.get(row.path),
+        }));
+        // Only CURRENT facts are carried: a superseded value is history the destination
+        // would have to replay in order, and the source's own ledger is the authority for
+        // its lifecycle. Carrying closed rows would duplicate history under new ids.
+        const factsAvailable = db.prepare('SELECT count(*) AS c FROM facts WHERE valid_to IS NULL').get().c;
+        const factRows = db.prepare(`SELECT e.canonical_name AS subject, f.predicate AS predicate, f.object_text AS object_text,
+              f.scope AS scope, f.valid_from AS valid_from, f.valid_to AS valid_to,
+              f.source_path AS source_path
+         FROM facts f
+         JOIN entities e ON e.id = f.subject_entity_id
+        WHERE f.valid_to IS NULL AND f.object_text IS NOT NULL AND e.canonical_name IS NOT NULL
+        ORDER BY f.valid_from DESC, f.id DESC`).all();
+        const selectedNotePaths = new Set(limited.map(({ row }) => row.path));
+        const facts = [];
+        for (const row of factRows) {
+            const isLedgerFact = row.source_path === '_mcp_';
+            // Ledger-derived facts are the owner's explicitly stated memory: a small, global,
+            // high-value set. They are carried by default (the point of an import is to see
+            // what Renor already holds) and skipped only when the caller excludes them.
+            if (isLedgerFact) {
+                if (matchesPrefix('_mcp_', filter.exclude) || matchesPrefix('ledger', filter.exclude))
+                    continue;
+            }
+            else if (!selectedNotePaths.has(row.source_path)) {
+                continue;
+            }
+            facts.push({
+                subject: String(row.subject),
+                predicate: String(row.predicate),
+                object: String(row.object_text),
+                scope: row.scope ?? 'global',
+                validFrom: row.valid_from,
+                sourcePath: row.source_path,
+                origin: isLedgerFact ? 'ledger' : 'note',
+                ledgerSource: isLedgerFact ? 'import:renor-index' : 'import:renor-index',
+            });
+        }
+        return {
+            format: types_1.BUNDLE_FORMAT,
+            sourceLabel: options.label ?? 'renor-index',
+            notes,
+            facts,
+            stats: {
+                notesAvailable: allNotes.length,
+                notesSelected: notes.length,
+                notesFilteredOut: filteredOut + (selected.length - limited.length),
+                notesWithOriginalBytes: notes.filter(n => n.originalContent !== undefined).length,
+                chunksSelected: notes.reduce((sum, n) => sum + n.chunks.length, 0),
+                factsAvailable,
+                factsSelected: facts.length,
+            },
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * The source note's original bytes, when the content tree is reachable. Returns null
+ * when the file is absent, so the caller falls back to reconstruction and reports it.
+ */
+function readOriginalContent(contentRoot, relPath) {
+    const candidate = path_1.default.resolve(contentRoot, relPath);
+    const root = path_1.default.resolve(contentRoot);
+    const rel = path_1.default.relative(root, candidate);
+    if (rel === '' || rel.startsWith('..') || path_1.default.isAbsolute(rel))
+        return null;
+    try {
+        return fs_1.default.readFileSync(candidate, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function parseAliases(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.filter((v) => typeof v === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+function parseFrontmatter(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Read a `renor-memory-export/v1` JSONL bundle written by any provider.
+ * One JSON record per line: `{"type":"note",…}` / `{"type":"fact",…}` / `{"type":"meta",…}`.
+ *
+ * `filter` is applied HERE, in the adapter, exactly as the index adapter applies it —
+ * `include`/`exclude` select note records by `relPath`, `limit` caps the selection, and
+ * `_mcp_`/`ledger` in `exclude` drops the owner's ledger-derived facts. An adapter that
+ * returned everything would make the CLI's selection flags a silent no-op, and
+ * `--exclude Private` would import the private notes anyway. `filter` is optional so the
+ * adapter can still be used as a plain bundle reader.
+ */
+function readBundleSource(filePath, filter = { include: [], exclude: [] }) {
+    const include = filter.include ?? [];
+    const exclude = filter.exclude ?? [];
+    const raw = fs_1.default.readFileSync(filePath, 'utf8');
+    const parsedNotes = [];
+    const parsedFacts = [];
+    let sourceLabel = path_1.default.basename(filePath, path_1.default.extname(filePath));
+    let format = types_1.BUNDLE_FORMAT;
+    const lines = raw.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`bundle line ${i + 1} is not valid JSON`);
+        }
+        if (record?.type === 'meta') {
+            if (typeof record.format === 'string')
+                format = record.format;
+            if (typeof record.source === 'string')
+                sourceLabel = record.source;
+            continue;
+        }
+        if (record?.type === 'note') {
+            // Every field that reaches canonical bytes is validated where it is read: `String(x)`
+            // accepted anything, so a malformed record became the literal text `[object Object]`,
+            // which is then written into Markdown, indexed, and (for a fact) recorded in the
+            // ledger as though it were memory.
+            const note = `note ${bundleLabel(record.relPath ?? record.path)}`;
+            const at = bundleWhere(note, i);
+            const relPathFromRecord = record.relPath ?? record.path;
+            parsedNotes.push({
+                sourcePath: bundleString(record.path, '', 'path', at),
+                relPath: bundleString(relPathFromRecord, '', 'relPath', at),
+                title: bundleString(record.title, '', 'title', at),
+                kind: typeof record.kind === 'string' ? record.kind : null,
+                modifiedAt: bundleString(record.modifiedAt, '', 'modifiedAt', at),
+                frontmatter: record.frontmatter && typeof record.frontmatter === 'object' ? record.frontmatter : {},
+                chunks: Array.isArray(record.chunks)
+                    ? record.chunks.map((c, index) => {
+                        const chunk = bundleWhere(note, i, `chunk ${index}`);
+                        return {
+                            headingPath: bundleString(c?.headingPath, '', 'headingPath', chunk),
+                            text: bundleString(c?.text, '', 'text', chunk),
+                            tokenCount: bundleNumber(c?.tokenCount, 0, 'tokenCount', chunk),
+                            // Spans must survive the round trip: they are the only fallback for a chunk
+                            // whose text cannot be located, so dropping them would silently make a
+                            // bundle-sourced import behave differently from a direct index read. A span
+                            // that cannot be a citation — negative, fractional, or reversed — is dropped
+                            // here instead of being inherited as a coordinate.
+                            ...normalizedSpan(c?.startLine, c?.endLine),
+                        };
+                    })
+                    : [],
+                entities: Array.isArray(record.entities)
+                    ? record.entities.map((e, index) => {
+                        const entity = bundleWhere(note, i, `entity ${index}`);
+                        return {
+                            type: bundleString(e?.type, 'note', 'type', entity),
+                            canonicalName: bundleString(e?.canonicalName, '', 'canonicalName', entity),
+                            aliases: Array.isArray(e?.aliases)
+                                ? e.aliases.map((a, aliasIndex) => (bundleString(a, '', `alias ${aliasIndex}`, entity)))
+                                : [],
+                            confidence: bundleNumber(e?.confidence, 1, 'confidence', entity),
+                        };
+                    })
+                    : [],
+                originalContent: typeof record.originalContent === 'string' ? record.originalContent : undefined,
+            });
+            continue;
+        }
+        if (record?.type === 'fact') {
+            // `String(x)` on a fact field fabricated `[object Object]` as a canonical ledger value.
+            const at = bundleWhere('fact', i);
+            parsedFacts.push({
+                subject: bundleString(record.subject, '', 'subject', at),
+                predicate: bundleString(record.predicate, '', 'predicate', at),
+                object: bundleString(record.object, '', 'object', at),
+                scope: String(record.scope ?? 'global'),
+                validFrom: String(record.validFrom ?? ''),
+                sourcePath: String(record.sourcePath ?? ''),
+                origin: record.origin === 'ledger' ? 'ledger' : 'note',
+                eventId: typeof record.eventId === 'string' ? record.eventId : undefined,
+                closedEvent: record.closedEvent ?? null,
+                ledgerSource: typeof record.ledgerSource === 'string' ? record.ledgerSource : undefined,
+            });
+            continue;
+        }
+        throw new Error(`bundle line ${i + 1} has unknown record type ${JSON.stringify(record?.type)}`);
+    }
+    if (format !== types_1.BUNDLE_FORMAT) {
+        throw new Error(`unsupported bundle format ${JSON.stringify(format)}; expected ${types_1.BUNDLE_FORMAT}`);
+    }
+    // Selection, in the same order and with the same rule the index adapter uses: the index
+    // adapter sorts by relative path BEFORE applying `limit`, so a bundle is sorted here too
+    // and `--limit N` selects the same records whichever order the provider wrote them in.
+    const selection = { include, exclude };
+    const selected = [];
+    let notesFilteredOut = 0;
+    for (const note of parsedNotes) {
+        if (!isSelected(note.relPath, selection)) {
+            notesFilteredOut += 1;
+            continue;
+        }
+        selected.push(note);
+    }
+    selected.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    const notes = filter.limit !== undefined && filter.limit >= 0
+        ? selected.slice(0, filter.limit)
+        : selected;
+    notesFilteredOut += selected.length - notes.length;
+    // Facts follow the notes: a note-derived fact for a note that was not selected is not
+    // carried, and the owner's ledger-derived facts (`_mcp_`) are carried by default and
+    // dropped only when explicitly excluded — the same rule the index adapter applies.
+    // Both a note's source path and its relative path count as naming it, because a
+    // provider may write either.
+    const selectedPaths = new Set();
+    for (const note of notes) {
+        selectedPaths.add(note.sourcePath);
+        selectedPaths.add(note.relPath);
+    }
+    const facts = [];
+    for (const fact of parsedFacts) {
+        if (fact.sourcePath === '_mcp_') {
+            if (matchesPrefix('_mcp_', exclude) || matchesPrefix('ledger', exclude))
+                continue;
+            facts.push(fact);
+            continue;
+        }
+        // A fact that names no path at all carries no note association that selection could
+        // be applied to; one that names a path must belong to a selected note.
+        if (fact.sourcePath !== '' && !selectedPaths.has(fact.sourcePath))
+            continue;
+        facts.push(fact);
+    }
+    return {
+        format,
+        sourceLabel,
+        notes,
+        facts,
+        stats: {
+            notesAvailable: parsedNotes.length,
+            notesSelected: notes.length,
+            notesFilteredOut,
+            notesWithOriginalBytes: notes.filter(n => n.originalContent !== undefined).length,
+            chunksSelected: notes.reduce((sum, n) => sum + n.chunks.length, 0),
+            factsAvailable: parsedFacts.length,
+            factsSelected: facts.length,
+        },
+    };
+}
+/** A label for a record whose own identity may be malformed, safe to print in an error. */
+function bundleLabel(raw) {
+    return typeof raw === 'string' ? JSON.stringify(raw) : JSON.stringify(raw ?? '');
+}
+/**
+ * A string field of a bundle record, validated where the record is read.
+ *
+ * An absent/null field keeps its default, so existing bundles stay readable; a
+ * present-but-non-string field is refused, naming the line, the record and the field.
+ */
+function bundleString(raw, fallback, field, where) {
+    if (raw === undefined || raw === null)
+        return fallback;
+    if (typeof raw !== 'string') {
+        throw new Error(`${where} has an invalid ${field} ${JSON.stringify(raw)}: expected a string`);
+    }
+    return raw;
+}
+/** Where a bundle record's field lives, so a malformed value is named precisely. */
+function bundleWhere(origin, lineIndex, part) {
+    return `bundle line ${lineIndex + 1}: ${origin}${part ? ` ${part}` : ''}`;
+}
+/**
+ * A line span, or nothing when it cannot be a citation.
+ *
+ * A negative or fractional span was copied verbatim and could be inherited into
+ * `chunks.start_line`/`end_line` and handed back as a citation range, so a span that is not
+ * a non-negative, ordered integer pair is treated exactly like "text not located": unknown.
+ */
+function normalizedSpan(startLine, endLine) {
+    if (typeof startLine !== 'number' || typeof endLine !== 'number')
+        return {};
+    if (!Number.isInteger(startLine) || !Number.isInteger(endLine))
+        return {};
+    if (startLine < 0 || endLine < startLine)
+        return {};
+    return { startLine, endLine };
+}
+/**
+ * A numeric field of a bundle record, validated where the record is read.
+ *
+ * `Number(record.field ?? default)` accepted anything: a malformed `tokenCount` became
+ * `NaN`, travelled through the plan, and only failed at the write layer as
+ * `NOT NULL constraint failed: chunks.token_count` — after canonical note bytes had been
+ * written, and reported as a *ledger replay* rejection. Invalid input is a property of the
+ * bundle, so it is rejected here, before any write, naming the line, the note and the
+ * field. An absent/null field keeps its default, so existing bundles stay readable.
+ */
+function bundleNumber(raw, fallback, field, where) {
+    if (raw === undefined || raw === null)
+        return fallback;
+    const value = typeof raw === 'number'
+        ? raw
+        : typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : Number.NaN;
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`${where} has an invalid ${field} ${JSON.stringify(raw)}: expected a non-negative finite number`);
+    }
+    return value;
+}
+/** Open a source from a `kind:path` spec. */
+function readSource(spec, filter) {
+    const separator = spec.indexOf(':');
+    if (separator < 0) {
+        throw new Error('source must be given as kind:path (for example renor-index:/path/index.db)');
+    }
+    const kind = spec.slice(0, separator);
+    const target = spec.slice(separator + 1);
+    if (kind === 'renor-index') {
+        return readRenorIndexSource({
+            dbPath: target,
+            sourceRoot: filter.sourceRoot ?? path_1.default.dirname(path_1.default.dirname(target)),
+            contentRoot: filter.contentRoot,
+            include: filter.include,
+            exclude: filter.exclude,
+            limit: filter.limit,
+            label: filter.label,
+        });
+    }
+    if (kind === 'bundle') {
+        return readBundleSource(target, {
+            include: filter.include,
+            exclude: filter.exclude,
+            limit: filter.limit,
+        });
+    }
+    throw new Error(`unknown source kind ${JSON.stringify(kind)}; expected renor-index or bundle`);
+}

package/dist/importing/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/** Portable memory bundle: the interface every import source must produce. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUNDLE_FORMAT = void 0;
+/** The bundle format this module reads and writes. */
+exports.BUNDLE_FORMAT = 'renor-memory-export/v1';