noteconnection 1.7.0 → 1.9.0

package/dist/src/indexing/IndexLifecycle.js

@@ -0,0 +1,217 @@
+"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());
+    }
+    /**
+     * Moves the indexed path in place. Rebuilding units would allocate new
+     * segments and make a path-only identity transition look like content
+     * churn, so the existing index identity is deliberately preserved.
+     */
+    updateDocumentSourcePath(documentId, sourcePath, updatedAt) {
+        const unitIds = this.unitIdsByDocumentId.get(String(documentId || '').trim()) || [];
+        let updatedCount = 0;
+        unitIds.forEach((unitId) => {
+            const unit = this.units.get(unitId);
+            if (!unit) {
+                return;
+            }
+            this.units.set(unitId, {
+                ...unit,
+                sourcePath,
+                updatedAt,
+            });
+            updatedCount += 1;
+        });
+        return updatedCount;
+    }
+    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,73 @@
+"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);
+    });
+    test('updates indexed source paths in place during a document move', () => {
+        let idCounter = 0;
+        const lifecycle = new IndexLifecycle_1.IndexLifecycle((prefix = 'index') => `${prefix}_${++idCounter}`, (value) => `hash_${value.length}`);
+        const indexed = lifecycle.syncDocumentIndex({
+            resourceId: 'resource_move',
+            projectionId: 'projection_move',
+            documentId: 'doc_move',
+            sourcePath: 'Knowledge_Base/old.md',
+            language: 'en',
+            workspaceId: 'workspace',
+            corpusId: 'corpus',
+            title: 'old',
+            content: '# Move\nContent',
+            atoms: [],
+            indexedAt: '2026-05-26T06:00:00.000Z',
+        });
+        expect(lifecycle.updateDocumentSourcePath('doc_move', 'Knowledge_Base/new.md', '2026-05-26T07:00:00.000Z')).toBe(indexed.units.length);
+        expect(lifecycle.listUnitsByProjectionIds(['projection_move'])).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                sourcePath: 'Knowledge_Base/new.md',
+                updatedAt: '2026-05-26T07:00:00.000Z',
+            }),
+        ]));
+    });
+});

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 });

package/dist/src/knowledge.api.contract.test.js

@@ -0,0 +1,172 @@
+"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"));
+describe('Knowledge mastery API contract wiring', () => {
+    const serverSource = fs.readFileSync(path.join(__dirname, 'server.ts'), 'utf8');
+    const knowledgeRoutesSource = fs.readFileSync(path.join(__dirname, 'routes', 'knowledge.ts'), 'utf8');
+    const learningApiSource = fs.readFileSync(path.join(__dirname, 'learning', 'api.ts'), 'utf8');
+    const learningPlatformSource = fs.readFileSync(path.join(__dirname, 'learning', 'KnowledgeLearningPlatform.ts'), 'utf8');
+    test('server exposes planned /api/knowledge endpoints', () => {
+        const endpoints = [
+            '/api/knowledge/state',
+            '/api/knowledge/store-diagnostics',
+            '/api/knowledge/store/reload',
+            '/api/knowledge/ingest',
+            '/api/knowledge/ingest-diff',
+            '/api/knowledge/query',
+            '/api/knowledge/conversation',
+            '/api/knowledge/workflow-artifacts',
+            '/api/knowledge/workflow-artifacts/review-follow-up',
+            '/api/knowledge/mastery/diagnose',
+            '/api/knowledge/mastery/misconceptions',
+            '/api/knowledge/path',
+            '/api/knowledge/session/plan',
+            '/api/knowledge/session/action',
+            '/api/knowledge/session/execute',
+            '/api/knowledge/session/history',
+            '/api/knowledge/quality/snapshot',
+            '/api/knowledge/quality/baseline',
+            '/api/knowledge/quality/baseline/clear',
+            '/api/knowledge/quality/baseline/evaluate',
+            '/api/knowledge/quality/evaluate',
+            '/api/knowledge/ingest/guardrails/evaluate',
+            '/api/knowledge/tutor/action',
+            '/api/knowledge/memory/policy',
+        ];
+        const aggregatedRouteSource = `${serverSource}\n${knowledgeRoutesSource}`;
+        endpoints.forEach((endpoint) => {
+            expect(aggregatedRouteSource).toContain(endpoint);
+        });
+    });
+    test('server initializes local knowledge learning platform', () => {
+        expect(serverSource).toContain("from './learning'");
+        expect(serverSource).toContain('createKnowledgeLearningPlatform');
+        expect(serverSource).toContain('createKnowledgeGraphStore');
+        expect(serverSource).toContain('createGraphDbSnapshotAdapter');
+        expect(serverSource).toContain('knowledgeLearningPlatform');
+        expect(serverSource).toContain('KNOWLEDGE_GRAPH_STORE_BACKEND');
+    });
+    test('learning module declares all required public APIs', () => {
+        const requiredInterfaces = [
+            'interface KnowledgeIngestAPI',
+            'interface KnowledgeQueryAPI',
+            'interface MasteryDiagnosticsAPI',
+            'interface MasteryMisconceptionAPI',
+            'interface LearningPathAPI',
+            'interface StudySessionAPI',
+            'interface StudySessionHistoryAPI',
+            'interface StudySessionActionAPI',
+            'interface WorkflowArtifactReviewFollowUpAPI',
+            'interface StudySessionPlanExecutionAPI',
+            'interface TutorActionAPI',
+            'interface MemoryPolicyAPI',
+            'interface LearningQualityGateAPI',
+            'interface LearningQualitySnapshotAPI',
+            'interface IngestGuardrailAPI',
+        ];
+        requiredInterfaces.forEach((interfaceName) => {
+            expect(learningApiSource).toContain(interfaceName);
+        });
+    });
+    test('modular knowledge routes reference concrete platform methods or live runtime-runbook route ops', () => {
+        const platformMethods = [
+            'queryMasteryDiagnostics',
+            'generateLearningPath',
+            'queryKnowledgeQueryBackendComparisonHistory',
+            'queryKnowledgeQueryBackendComparisonTrend',
+            'queryWorkflowArtifacts',
+            'executeWorkflowArtifactReviewFollowUp',
+            'getRuntimeCapabilityMatrix',
+            'evaluateIngestGuardrail',
+        ];
+        platformMethods.forEach((methodName) => {
+            expect(knowledgeRoutesSource).toContain(`knowledgeLearningPlatform.${methodName}`);
+            expect(learningPlatformSource).toContain(`${methodName}(`);
+        });
+        const runtimeRunbookOpsMethods = [
+            'getRunbook',
+            'verify',
+            'getHistory',
+            'getChecks',
+            'getActionQueue',
+            'getRemediationHistory',
+            'getReplaySchedule',
+            'recordRemediationEvent',
+            'replayRemediationEvent',
+            'updateReplaySchedule',
+            'tickReplaySchedule',
+        ];
+        runtimeRunbookOpsMethods.forEach((methodName) => {
+            expect(knowledgeRoutesSource).toContain(`runtimeRunbookOps?.${methodName}`);
+        });
+        expect(knowledgeRoutesSource.includes('knowledgeLearningPlatform.getAgentConversationTurnCacheDiagnostics')).toBe(false);
+        expect(knowledgeRoutesSource.includes('knowledgeLearningPlatform.getAgentConversationTurnCacheTrend')).toBe(false);
+        expect(serverSource.includes('result: getAgentConversationTurnCacheDiagnostics()')).toBe(true);
+        expect(serverSource.includes('queryAgentConversationTurnCacheAlertTrend(request)')).toBe(true);
+    });
+    test('runtime runbook modular routes forward live query parameters instead of dropping them', () => {
+        [
+            "params.get('checkId')",
+            "params.get('focus')",
+            "params.get('focusLimit')",
+            "params.get('sinceMinutes')",
+            "params.get('status')",
+            "params.get('checkQuery')",
+            "params.get('queueLimit')",
+            "params.get('priority')",
+            "params.get('category')",
+            "params.get('remediationStatus')",
+            "params.get('remediationTrend')",
+            'runtimeRunbookOps?.verify',
+            'runtimeRunbookOps?.getChecks',
+            'runtimeRunbookOps?.getActionQueue',
+        ].forEach((token) => {
+            expect(knowledgeRoutesSource).toContain(token);
+        });
+    });
+    test('server escalation fast lane covers the full ANN governance family including prefilter effectiveness', () => {
+        [
+            "selectedCheckId === 'query_vector_acceleration_index_sync_health'",
+            "selectedCheckId === 'query_vector_acceleration_circuit_state'",
+            "selectedCheckId === 'query_vector_acceleration_calibration_readiness'",
+            "selectedCheckId === 'query_vector_acceleration_traceability'",
+            "selectedCheckId === 'query_vector_acceleration_prefilter_effectiveness'",
+        ].forEach((token) => {
+            expect(serverSource).toContain(token);
+        });
+    });
+});