noteconnection 1.7.0 → 1.8.0

package/dist/src/frontend.locale.contract.test.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function getNestedStringValue(record, dottedKey) {
+    const value = dottedKey.split('.').reduce((current, segment) => {
+        if (!current || typeof current !== 'object' || !(segment in current)) {
+            return null;
+        }
+        return current[segment];
+    }, record);
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+describe('frontend locale contract', () => {
+    const repoRoot = path.resolve(__dirname, '..');
+    const enLocale = JSON.parse(fs.readFileSync(path.join(repoRoot, 'src', 'frontend', 'locales', 'en.json'), 'utf8'));
+    const zhLocale = JSON.parse(fs.readFileSync(path.join(repoRoot, 'src', 'frontend', 'locales', 'zh.json'), 'utf8'));
+    const requiredKeys = [
+        'analysis_title',
+        'node_details',
+        'reader_loading',
+        'reader_outline_title',
+        'reader_outline_empty',
+    ];
+    test('required reader and analysis keys resolve in both locales', () => {
+        const missing = requiredKeys.filter((key) => (!getNestedStringValue(enLocale, key) || !getNestedStringValue(zhLocale, key)));
+        expect(missing).toEqual([]);
+    });
+});

package/dist/src/godot.sidecar.bootstrap.contract.test.js

@@ -0,0 +1,244 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const url_1 = require("url");
+class TempDir {
+    constructor(prefix) {
+        this.path = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), `${prefix}-`));
+    }
+    child(relative) {
+        return path.join(this.path, relative);
+    }
+    mkdir(relative) {
+        const target = this.child(relative);
+        fs.mkdirSync(target, { recursive: true });
+        return target;
+    }
+    cleanup() {
+        fs.rmSync(this.path, { recursive: true, force: true });
+    }
+}
+function sha256File(filePath) {
+    return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+describe('godot sidecar bootstrap contracts', () => {
+    const repoRoot = path.resolve(__dirname, '..');
+    const sidecarUtilsPath = path.join(repoRoot, 'scripts', 'tauri-sidecar-utils.js');
+    let sidecarUtils;
+    let temp;
+    beforeAll(() => {
+        sidecarUtils = require(sidecarUtilsPath);
+    });
+    beforeEach(() => {
+        temp = new TempDir('noteconnection-godot-bootstrap');
+    });
+    afterEach(() => {
+        if (temp) {
+            temp.cleanup();
+        }
+    });
+    test('downloads and caches a host godot binary when a pinned file URL is configured', async () => {
+        const fakeRepoRoot = temp.mkdir('repo');
+        const downloadRoot = temp.mkdir('downloads');
+        const cacheRoot = temp.mkdir('cache');
+        const sourceBinaryPath = path.join(downloadRoot, 'godot-linux-x64');
+        const sourceBinary = Buffer.alloc(sidecarUtils.MIN_GODOT_BINARY_BYTES + 64, 7);
+        fs.writeFileSync(sourceBinaryPath, sourceBinary);
+        const result = await sidecarUtils.prepareGodotSidecar({
+            repoRoot: fakeRepoRoot,
+            platform: 'linux',
+            arch: 'x64',
+            env: {
+                NOTE_CONNECTION_GODOT_DOWNLOAD_URL: (0, url_1.pathToFileURL)(sourceBinaryPath).href,
+                NOTE_CONNECTION_GODOT_DOWNLOAD_SHA256: sha256File(sourceBinaryPath),
+                NOTE_CONNECTION_GODOT_CACHE_DIR: cacheRoot,
+            },
+            logger: console,
+        });
+        expect(result.outcome).toBe('prepared');
+        expect(result.sourceKind).toBe('download');
+        expect(fs.existsSync(result.targetPath)).toBe(true);
+        expect(fs.existsSync(result.cachePath)).toBe(true);
+        expect(fs.readFileSync(result.targetPath)).toEqual(sourceBinary);
+        expect(fs.readFileSync(result.cachePath)).toEqual(sourceBinary);
+    });
+    test('accepts GitHub Releases URLs as pinned bootstrap sources without provider-specific branching', () => {
+        const fakeRepoRoot = temp.mkdir('repo');
+        const cacheRoot = temp.mkdir('cache');
+        const githubReleaseUrl = 'https://github.com/Jacobinwwey/NoteConnection/releases/download/v1.7.0/godot-x86_64-unknown-linux-gnu';
+        const context = sidecarUtils.resolveGodotBootstrapContext({
+            repoRoot: fakeRepoRoot,
+            platform: 'linux',
+            arch: 'x64',
+            env: {
+                NOTE_CONNECTION_GODOT_DOWNLOAD_URL: githubReleaseUrl,
+                NOTE_CONNECTION_GODOT_DOWNLOAD_SHA256: 'abc123',
+                NOTE_CONNECTION_GODOT_CACHE_DIR: cacheRoot,
+            },
+        });
+        expect(context).not.toBeNull();
+        expect(context?.downloadUrl).toBe(githubReleaseUrl);
+        expect(context?.expectedSha256).toBe('abc123');
+        expect(context?.cachePath).toBe(path.join(cacheRoot, 'godot-x86_64-unknown-linux-gnu'));
+        expect(context?.targetPath).toBe(path.join(fakeRepoRoot, 'src-tauri', 'bin', 'godot-x86_64-unknown-linux-gnu'));
+    });
+    test('accepts generic object-storage mirror URLs through the same bootstrap contract', () => {
+        const fakeRepoRoot = temp.mkdir('repo');
+        const cacheRoot = temp.mkdir('cache');
+        const objectStorageUrl = 'https://mirror.example.invalid/noteconnection/godot/godot-x86_64-unknown-linux-gnu';
+        const context = sidecarUtils.resolveGodotBootstrapContext({
+            repoRoot: fakeRepoRoot,
+            platform: 'linux',
+            arch: 'x64',
+            env: {
+                NOTE_CONNECTION_GODOT_DOWNLOAD_URL: objectStorageUrl,
+                NOTE_CONNECTION_GODOT_DOWNLOAD_SHA256: 'def456',
+                NOTE_CONNECTION_GODOT_CACHE_DIR: cacheRoot,
+            },
+        });
+        expect(context).not.toBeNull();
+        expect(context?.downloadUrl).toBe(objectStorageUrl);
+        expect(context?.expectedSha256).toBe('def456');
+        expect(context?.cachePath).toBe(path.join(cacheRoot, 'godot-x86_64-unknown-linux-gnu'));
+    });
+    test('reuses cached godot binary when the original download source is gone', async () => {
+        const fakeRepoRoot = temp.mkdir('repo');
+        const downloadRoot = temp.mkdir('downloads');
+        const cacheRoot = temp.mkdir('cache');
+        const sourceBinaryPath = path.join(downloadRoot, 'godot-linux-x64');
+        fs.writeFileSync(sourceBinaryPath, Buffer.alloc(sidecarUtils.MIN_GODOT_BINARY_BYTES + 32, 3));
+        const env = {
+            NOTE_CONNECTION_GODOT_DOWNLOAD_URL: (0, url_1.pathToFileURL)(sourceBinaryPath).href,
+            NOTE_CONNECTION_GODOT_DOWNLOAD_SHA256: sha256File(sourceBinaryPath),
+            NOTE_CONNECTION_GODOT_CACHE_DIR: cacheRoot,
+        };
+        const first = await sidecarUtils.prepareGodotSidecar({
+            repoRoot: fakeRepoRoot,
+            platform: 'linux',
+            arch: 'x64',
+            env,
+            logger: console,
+        });
+        expect(first.sourceKind).toBe('download');
+        fs.rmSync(sourceBinaryPath, { force: true });
+        fs.rmSync(first.targetPath, { force: true });
+        const second = await sidecarUtils.prepareGodotSidecar({
+            repoRoot: fakeRepoRoot,
+            platform: 'linux',
+            arch: 'x64',
+            env,
+            logger: console,
+        });
+        expect(second.outcome).toBe('prepared');
+        expect(second.sourceKind).toBe('cache');
+        expect(fs.existsSync(second.targetPath)).toBe(true);
+    });
+    test('rejects downloaded godot binaries when sha256 does not match the pinned value', async () => {
+        const fakeRepoRoot = temp.mkdir('repo');
+        const downloadRoot = temp.mkdir('downloads');
+        const cacheRoot = temp.mkdir('cache');
+        const sourceBinaryPath = path.join(downloadRoot, 'godot-linux-x64');
+        fs.writeFileSync(sourceBinaryPath, Buffer.alloc(sidecarUtils.MIN_GODOT_BINARY_BYTES + 16, 9));
+        await expect(sidecarUtils.prepareGodotSidecar({
+            repoRoot: fakeRepoRoot,
+            platform: 'linux',
+            arch: 'x64',
+            env: {
+                NOTE_CONNECTION_GODOT_DOWNLOAD_URL: (0, url_1.pathToFileURL)(sourceBinaryPath).href,
+                NOTE_CONNECTION_GODOT_DOWNLOAD_SHA256: 'deadbeef',
+                NOTE_CONNECTION_GODOT_CACHE_DIR: cacheRoot,
+            },
+            logger: console,
+        })).rejects.toThrow(/sha256/i);
+    });
+    test('does not require a linux host godot binary by default when validating sidecars', () => {
+        const fakeRepoRoot = temp.mkdir('repo');
+        const binDir = temp.mkdir(path.join('repo', 'src-tauri', 'bin'));
+        fs.writeFileSync(path.join(binDir, 'server-x86_64-unknown-linux-gnu'), 'server');
+        fs.writeFileSync(path.join(binDir, 'markdown-worker-x86_64-unknown-linux-gnu'), 'worker');
+        const result = sidecarUtils.validateTauriSidecars({
+            repoRoot: fakeRepoRoot,
+            platform: 'linux',
+            arch: 'x64',
+        });
+        expect(sidecarUtils.resolveHostGodotBinaryName({ platform: 'linux', arch: 'x64' })).toBe('godot-x86_64-unknown-linux-gnu');
+        expect(result.invalid).toEqual([]);
+    });
+    test('requires the windows host godot binary together with server and markdown worker sidecars', () => {
+        const fakeRepoRoot = temp.mkdir('repo');
+        const binDir = temp.mkdir(path.join('repo', 'src-tauri', 'bin'));
+        fs.writeFileSync(path.join(binDir, 'server-x86_64-pc-windows-msvc.exe'), 'server');
+        fs.writeFileSync(path.join(binDir, 'markdown-worker-x86_64-pc-windows-msvc.exe'), 'worker');
+        const missingGodot = sidecarUtils.validateTauriSidecars({
+            repoRoot: fakeRepoRoot,
+            platform: 'win32',
+            arch: 'x64',
+        });
+        expect(missingGodot.invalid).toEqual([
+            expect.stringContaining('godot-x86_64-pc-windows-msvc.exe'),
+        ]);
+        fs.writeFileSync(path.join(binDir, 'godot-x86_64-pc-windows-msvc.exe'), Buffer.alloc(sidecarUtils.MIN_GODOT_BINARY_BYTES + 8, 5));
+        const ready = sidecarUtils.validateTauriSidecars({
+            repoRoot: fakeRepoRoot,
+            platform: 'win32',
+            arch: 'x64',
+        });
+        expect(ready.invalid).toEqual([]);
+    });
+    test('treats git-lfs pointer placeholders as invalid server and markdown-worker sidecars', () => {
+        const fakeRepoRoot = temp.mkdir('repo');
+        const binDir = temp.mkdir(path.join('repo', 'src-tauri', 'bin'));
+        const lfsPointer = [
+            'version https://git-lfs.github.com/spec/v1',
+            'oid sha256:deadbeef',
+            'size 12345678',
+        ].join('\n');
+        fs.writeFileSync(path.join(binDir, 'server-x86_64-unknown-linux-gnu'), lfsPointer);
+        fs.writeFileSync(path.join(binDir, 'markdown-worker-x86_64-unknown-linux-gnu'), lfsPointer);
+        const result = sidecarUtils.validateTauriSidecars({
+            repoRoot: fakeRepoRoot,
+            platform: 'linux',
+            arch: 'x64',
+        });
+        expect(result.invalid).toEqual([
+            expect.stringContaining('server-x86_64-unknown-linux-gnu'),
+            expect.stringContaining('markdown-worker-x86_64-unknown-linux-gnu'),
+        ]);
+    });
+});

package/dist/src/indexing/IndexLifecycle.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexLifecycle = void 0;
+const SegmentBuilder_1 = require("./SegmentBuilder");
+const UnitBuilder_1 = require("./UnitBuilder");
+class IndexLifecycle {
+    constructor(nextId, computeHash) {
+        this.nextId = nextId;
+        this.computeHash = computeHash;
+        this.units = new Map();
+        this.segments = new Map();
+        this.unitIdsByDocumentId = new Map();
+        this.segmentIdsByAtomId = new Map();
+        this.unitBuilder = new UnitBuilder_1.UnitBuilder(computeHash);
+        this.segmentBuilder = new SegmentBuilder_1.SegmentBuilder(computeHash);
+    }
+    syncDocumentIndex(input) {
+        this.retireDocumentIndex(input.documentId);
+        const unitDrafts = this.unitBuilder.buildDocumentAndAtomUnits({
+            documentId: input.documentId,
+            sourcePath: input.sourcePath,
+            language: input.language,
+            workspaceId: input.workspaceId,
+            corpusId: input.corpusId,
+            title: input.title,
+            content: input.content,
+        }, input.atoms);
+        const createdUnits = [];
+        const createdSegments = [];
+        unitDrafts.forEach((draft) => {
+            const unitId = this.nextId('idx_unit');
+            const builtSegments = this.segmentBuilder.buildSegments(draft.content);
+            const segmentIds = [];
+            builtSegments.forEach((segmentDraft) => {
+                const segmentId = this.nextId('idx_segment');
+                const segment = {
+                    segmentId,
+                    unitId,
+                    resourceId: input.resourceId,
+                    projectionId: input.projectionId,
+                    documentId: draft.documentId,
+                    atomId: draft.atomId,
+                    workspaceId: draft.workspaceId,
+                    corpusId: draft.corpusId,
+                    modality: 'text',
+                    segmentIndex: segmentDraft.segmentIndex,
+                    content: segmentDraft.content,
+                    contentHash: segmentDraft.contentHash,
+                    tokenCount: segmentDraft.tokenCount,
+                    state: 'indexed',
+                    error: null,
+                    representationVersion: 'noteconnection-index-segment-v1',
+                    createdAt: input.indexedAt,
+                    updatedAt: input.indexedAt,
+                };
+                this.segments.set(segmentId, segment);
+                createdSegments.push(segment);
+                segmentIds.push(segmentId);
+            });
+            const unit = {
+                unitId,
+                resourceId: input.resourceId,
+                projectionId: input.projectionId,
+                documentId: draft.documentId,
+                atomId: draft.atomId,
+                workspaceId: draft.workspaceId,
+                corpusId: draft.corpusId,
+                sourcePath: draft.sourcePath,
+                language: draft.language,
+                title: draft.title,
+                content: draft.content,
+                unitKind: draft.unitKind,
+                unitIndex: draft.unitIndex,
+                contentHash: draft.contentHash,
+                state: 'indexed',
+                error: null,
+                segmentIds,
+                createdAt: input.indexedAt,
+                updatedAt: input.indexedAt,
+            };
+            this.units.set(unitId, unit);
+            createdUnits.push(unit);
+            const existingUnitIds = this.unitIdsByDocumentId.get(input.documentId) || [];
+            existingUnitIds.push(unitId);
+            this.unitIdsByDocumentId.set(input.documentId, existingUnitIds);
+            if (draft.atomId) {
+                this.segmentIdsByAtomId.set(draft.atomId, [...segmentIds]);
+            }
+        });
+        return {
+            units: createdUnits,
+            segments: createdSegments,
+        };
+    }
+    retireDocumentIndex(documentId) {
+        const unitIds = this.unitIdsByDocumentId.get(String(documentId || '').trim()) || [];
+        unitIds.forEach((unitId) => {
+            const unit = this.units.get(unitId);
+            if (!unit) {
+                return;
+            }
+            if (unit.atomId) {
+                this.segmentIdsByAtomId.delete(unit.atomId);
+            }
+            unit.segmentIds.forEach((segmentId) => {
+                this.segments.delete(segmentId);
+            });
+            this.units.delete(unitId);
+        });
+        this.unitIdsByDocumentId.delete(String(documentId || '').trim());
+    }
+    listSegmentsForAtom(atomId) {
+        const segmentIds = this.segmentIdsByAtomId.get(String(atomId || '').trim()) || [];
+        return segmentIds
+            .map((segmentId) => this.segments.get(segmentId))
+            .filter((segment) => Boolean(segment));
+    }
+    listUnitsByProjectionIds(projectionIds) {
+        const allowedProjectionIds = new Set(projectionIds
+            .map((projectionId) => String(projectionId || '').trim())
+            .filter(Boolean));
+        if (allowedProjectionIds.size <= 0) {
+            return [];
+        }
+        return Array.from(this.units.values())
+            .filter((unit) => allowedProjectionIds.has(unit.projectionId))
+            .sort((left, right) => left.unitId.localeCompare(right.unitId));
+    }
+    listSegmentsByUnitIds(unitIds) {
+        const allowedUnitIds = new Set(unitIds
+            .map((unitId) => String(unitId || '').trim())
+            .filter(Boolean));
+        if (allowedUnitIds.size <= 0) {
+            return [];
+        }
+        return Array.from(this.segments.values())
+            .filter((segment) => allowedUnitIds.has(segment.unitId))
+            .sort((left, right) => left.segmentId.localeCompare(right.segmentId));
+    }
+    hasIndexedSegmentsForAtom(atomId) {
+        return this.listSegmentsForAtom(atomId).some((segment) => segment.state === 'indexed');
+    }
+    buildSummary() {
+        const states = {
+            pending: 0,
+            indexing: 0,
+            indexed: 0,
+            failed: 0,
+            disabled: 0,
+        };
+        this.units.forEach((unit) => {
+            states[unit.state] += 1;
+        });
+        return {
+            totalUnits: this.units.size,
+            totalSegments: this.segments.size,
+            states,
+            activeDocuments: this.unitIdsByDocumentId.size,
+            activeAtomUnits: Array.from(this.units.values()).filter((unit) => unit.atomId !== null).length,
+        };
+    }
+    buildSnapshot() {
+        return {
+            units: Array.from(this.units.values()).map((unit) => ({
+                ...unit,
+                segmentIds: [...unit.segmentIds],
+            })),
+            segments: Array.from(this.segments.values()).map((segment) => ({ ...segment })),
+        };
+    }
+    restoreFromSnapshot(snapshot) {
+        this.units.clear();
+        this.segments.clear();
+        this.unitIdsByDocumentId.clear();
+        this.segmentIdsByAtomId.clear();
+        (snapshot?.segments || []).forEach((segment) => {
+            this.segments.set(segment.segmentId, { ...segment });
+        });
+        (snapshot?.units || []).forEach((unit) => {
+            this.units.set(unit.unitId, {
+                ...unit,
+                segmentIds: [...unit.segmentIds],
+            });
+            if (unit.documentId) {
+                const existingUnitIds = this.unitIdsByDocumentId.get(unit.documentId) || [];
+                existingUnitIds.push(unit.unitId);
+                this.unitIdsByDocumentId.set(unit.documentId, existingUnitIds);
+            }
+            if (unit.atomId) {
+                this.segmentIdsByAtomId.set(unit.atomId, [...unit.segmentIds]);
+            }
+        });
+    }
+}
+exports.IndexLifecycle = IndexLifecycle;

package/dist/src/indexing/IndexLifecycle.test.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const IndexLifecycle_1 = require("./IndexLifecycle");
+describe('IndexLifecycle', () => {
+    test('indexes document and atom units, then retires them by document', () => {
+        let idCounter = 0;
+        const lifecycle = new IndexLifecycle_1.IndexLifecycle((prefix = 'index') => `${prefix}_${++idCounter}`, (value) => `hash_${value.length}`);
+        const atom = {
+            id: 'atom_1',
+            stableKey: 'doc_a::intro',
+            documentId: 'doc_a',
+            sourcePath: 'Knowledge_Base/optics/doc_a.md',
+            title: 'Intro',
+            content: 'Absorption affects transmitted intensity.',
+            representationType: 'text',
+            keywords: ['absorption', 'intensity'],
+            evidenceSpanIds: ['evidence_1'],
+            createdAt: '2026-05-26T00:00:00.000Z',
+            updatedAt: '2026-05-26T00:00:00.000Z',
+            metadata: {
+                sectionPath: ['Intro'],
+                version: 1,
+                sourceHash: 'hash_doc_a',
+                language: 'en',
+            },
+        };
+        const indexed = lifecycle.syncDocumentIndex({
+            resourceId: 'resource_1',
+            projectionId: 'projection_1',
+            documentId: 'doc_a',
+            sourcePath: 'Knowledge_Base/optics/doc_a.md',
+            language: 'en',
+            workspaceId: 'optics',
+            corpusId: 'optics',
+            title: 'doc_a',
+            content: '# Intro\nAbsorption affects transmitted intensity.',
+            atoms: [atom],
+            indexedAt: '2026-05-26T00:00:00.000Z',
+        });
+        expect(indexed.units.length).toBeGreaterThan(0);
+        expect(indexed.segments.length).toBeGreaterThan(0);
+        expect(lifecycle.hasIndexedSegmentsForAtom('atom_1')).toBe(true);
+        expect(lifecycle.listUnitsByProjectionIds(['projection_1']).length).toBe(indexed.units.length);
+        expect(lifecycle.listSegmentsByUnitIds(indexed.units.map((unit) => unit.unitId)).length).toBe(indexed.segments.length);
+        lifecycle.retireDocumentIndex('doc_a');
+        expect(lifecycle.hasIndexedSegmentsForAtom('atom_1')).toBe(false);
+        expect(lifecycle.buildSummary().totalUnits).toBe(0);
+    });
+});

package/dist/src/indexing/SegmentBuilder.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SegmentBuilder = void 0;
+class SegmentBuilder {
+    constructor(computeHash) {
+        this.computeHash = computeHash;
+    }
+    buildSegments(content, options = {}) {
+        const normalizedContent = String(content || '').trim();
+        if (!normalizedContent) {
+            return [];
+        }
+        const maxSegmentChars = Math.max(120, Math.floor(Number(options.maxSegmentChars) || 420));
+        const paragraphs = normalizedContent
+            .split(/\n{2,}/)
+            .map((paragraph) => paragraph.trim())
+            .filter(Boolean);
+        const segments = [];
+        let current = '';
+        const flush = () => {
+            const value = current.trim();
+            if (!value) {
+                current = '';
+                return;
+            }
+            segments.push({
+                content: value,
+                segmentIndex: segments.length,
+                tokenCount: value.split(/\s+/).filter(Boolean).length,
+                contentHash: this.computeHash(value),
+            });
+            current = '';
+        };
+        paragraphs.forEach((paragraph) => {
+            const candidate = current ? `${current}\n\n${paragraph}` : paragraph;
+            if (candidate.length > maxSegmentChars && current) {
+                flush();
+            }
+            if (paragraph.length > maxSegmentChars) {
+                const tokens = paragraph.split(/\s+/).filter(Boolean);
+                let buffer = '';
+                tokens.forEach((token) => {
+                    const tokenCandidate = buffer ? `${buffer} ${token}` : token;
+                    if (tokenCandidate.length > maxSegmentChars && buffer) {
+                        current = buffer;
+                        flush();
+                        buffer = token;
+                        return;
+                    }
+                    buffer = tokenCandidate;
+                });
+                if (buffer) {
+                    current = buffer;
+                    flush();
+                }
+                return;
+            }
+            current = current ? `${current}\n\n${paragraph}` : paragraph;
+        });
+        flush();
+        return segments;
+    }
+}
+exports.SegmentBuilder = SegmentBuilder;

package/dist/src/indexing/UnitBuilder.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnitBuilder = void 0;
+class UnitBuilder {
+    constructor(computeHash) {
+        this.computeHash = computeHash;
+    }
+    buildDocumentAndAtomUnits(document, atoms) {
+        const units = [];
+        const normalizedDocumentContent = String(document.content || '').trim();
+        if (normalizedDocumentContent) {
+            units.push({
+                documentId: document.documentId,
+                atomId: null,
+                sourcePath: document.sourcePath,
+                language: document.language,
+                workspaceId: document.workspaceId,
+                corpusId: document.corpusId,
+                title: document.title,
+                content: normalizedDocumentContent,
+                unitKind: 'knowledge_document',
+                unitIndex: 0,
+                contentHash: this.computeHash(normalizedDocumentContent),
+            });
+        }
+        atoms.forEach((atom, index) => {
+            const normalizedContent = String(atom.content || '').trim();
+            if (!normalizedContent) {
+                return;
+            }
+            units.push({
+                documentId: atom.documentId,
+                atomId: atom.id,
+                sourcePath: atom.sourcePath,
+                language: String(atom.metadata?.language || document.language || 'unknown').trim() || 'unknown',
+                workspaceId: document.workspaceId,
+                corpusId: document.corpusId,
+                title: atom.title,
+                content: normalizedContent,
+                unitKind: 'knowledge_atom',
+                unitIndex: index + 1,
+                contentHash: this.computeHash(normalizedContent),
+            });
+        });
+        return units;
+    }
+}
+exports.UnitBuilder = UnitBuilder;

package/dist/src/indexing/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });