rag-memory-epf-mcp 6.4.0 → 6.4.1

package/dist/src/kg/relation-evidence.js

@@ -0,0 +1,438 @@
+// kg-relation-evidence (specs/changes/kg-relation-evidence/proposal.md r3, D1·D2).
+// Evidence-backed relationship chunks: everything that must be computed identically in four places —
+// generation, the commit-time re-check, and both KG embedding write-backs (dedicated + backfill).
+// Pure functions first; the resolvers further down take a better-sqlite3 handle and never open a
+// transaction themselves: callers own the transaction (CODE_CONTEXT §2).
+import { createHash } from 'node:crypto';
+export const EVIDENCE_FORMAT = 'evidence-v1';
+// Policy limits for this experiment, not a claim of sufficiency (proposal D1). Over-cap input is
+// refused, never truncated, and an item is never dropped from S to fit.
+export const EVIDENCE_CAPS = Object.freeze({ maxEntries: 8, maxQuoteCodepoints: 4000, maxBodyCodepoints: 8000 });
+export const FINGERPRINT_TAG = 'kg-evidence-fp/1';
+export const LEGACY_CMP_TAG = 'kg-legacy-cmp/1';
+// "Evidence-backed" is a claim about references, not about truth (proposal D1, last bullet).
+export const EVIDENCE_SEMANTICS = 'caller-selected evidence; the engine verified the references exist verbatim; not an independent proof of the relation';
+// Codepoints, never UTF-16 units: '🎉'.length === 2 but cpLength('🎉') === 1. Caps and [start, end)
+// are defined in codepoints (D1), like chunk start_pos/end_pos since migration 11.
+export function cpLength(s) {
+    let n = 0;
+    for (const _ of s)
+        n++;
+    return n;
+}
+export function cpSlice(s, start, end) {
+    return Array.from(s).slice(start, end).join('');
+}
+// SHA-256 of the UTF-8 bytes, lowercase hex. No normalisation, no newline rewriting. Node encodes a
+// lone surrogate as U+FFFD (EF BF BD), the same bytes TextEncoder produces.
+export function sha256Utf8(s) {
+    return createHash('sha256').update(s, 'utf8').digest('hex');
+}
+// Fixed order: kind, then ref, then hash with null first; strings compared by code unit. The reader
+// sorts with the same function, so "same sources" means the same sorted list.
+export function compareSourceTuples(a, b) {
+    const c = (x, y) => (x < y ? -1 : x > y ? 1 : 0);
+    if (a.source_kind !== b.source_kind)
+        return c(a.source_kind, b.source_kind);
+    if (a.source_ref !== b.source_ref)
+        return c(a.source_ref, b.source_ref);
+    // An absent hash is null (global constraints): normalise here so undefined vs 'a' is not a tie.
+    const ah = a.source_hash ?? null;
+    const bh = b.source_hash ?? null;
+    if (ah === bh)
+        return 0;
+    if (ah === null)
+        return -1;
+    if (bh === null)
+        return 1;
+    return c(ah, bh);
+}
+function int(v, what) {
+    if (typeof v !== 'number' || !Number.isInteger(v))
+        throw new Error(`fingerprint: ${what} must be an integer (got ${String(v)})`);
+    return v;
+}
+// The one serialisation (plan "Fingerprint serialisation"). Positional arrays only, so no key order can
+// drift; evidence in INPUT order — the range is included because the same quote text can sit at two
+// positions of one chunk ([0,13) vs [14,27), REVIEW-ALPHA2 §2.1).
+export function fingerprintSerialization(f) {
+    const refs = f.refs.map((r) => r.kind === 'document'
+        ? ['document', r.document_id, r.chunk_id, int(r.start, 'start'), int(r.end, 'end'), r.chunk_text_sha256, r.quote_sha256]
+        : ['observation', r.observation_id, r.entity_id, int(r.revision_no, 'revision_no'), r.content_sha256,
+            [...r.sources].sort(compareSourceTuples).map((s) => [s.source_kind, s.source_ref, s.source_hash ?? null])]);
+    return JSON.stringify([FINGERPRINT_TAG, f.relationship_id, f.source_entity_id, f.target_entity_id,
+        f.relation_type, f.source_name, f.target_name, f.kg_format, refs, int(f.profile_id, 'profile_id')]);
+}
+export function computeInputFingerprint(f) {
+    return sha256Utf8(fingerprintSerialization(f));
+}
+export function fingerprintFromMetadata(m, profileId) {
+    return computeInputFingerprint({
+        relationship_id: m.relationship_id, source_entity_id: m.source_entity_id, target_entity_id: m.target_entity_id,
+        relation_type: m.relation_type, source_name: m.source_entity, target_name: m.target_entity,
+        kg_format: EVIDENCE_FORMAT, refs: m.evidence_refs, profile_id: profileId,
+    });
+}
+// Claim line (raw type, direction kept) + each quote verbatim in input order (D1). No IDs, hashes or
+// internal state in the embedded text.
+export function buildEvidenceBody(sourceName, relationType, targetName, quotes) {
+    return [`${sourceName} — ${relationType} — ${targetName}`, ...quotes].join('\n\n');
+}
+// Same deterministic id as the triplet chunk (index.ts:2311): one relationship chunk per relationship.
+export function evidenceChunkId(relationshipId) {
+    return `kg_relationship_${relationshipId}`;
+}
+export function parseEvidenceMetadata(raw) {
+    if (raw === null)
+        return null;
+    let m;
+    try {
+        m = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!m || typeof m !== 'object' || m.kg_format !== EVIDENCE_FORMAT)
+        return null;
+    return m;
+}
+// D2⑤ comparison value. Evidence-v1: the stored fingerprint, but only if it still recomputes from the
+// row's own metadata and belongs to this row (a hand-edited or foreign row is never "equal"). Legacy
+// entity/triplet rows have no fingerprint field, so the value is derived at read time from the source
+// identity + body hash. Anything missing returns null, and null is never equal (proposal D2⑤).
+export function kgComparisonValue(row) {
+    if (row.text === null)
+        return null;
+    let meta;
+    try {
+        const parsed = JSON.parse(row.metadata ?? '{}');
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        meta = parsed;
+    }
+    catch {
+        return null;
+    }
+    if (meta.kg_format !== undefined) {
+        if (meta.kg_format !== EVIDENCE_FORMAT || row.chunk_type !== 'relationship')
+            return null;
+        const m = meta;
+        if (typeof m.input_fingerprint !== 'string' || typeof m.fingerprint_profile_id !== 'number')
+            return null;
+        // A row without a source id is never equal (D2⑤), even if its metadata agrees with that null.
+        if (typeof row.relationship_id !== 'string' || row.relationship_id === '')
+            return null;
+        if (m.relationship_id !== row.relationship_id)
+            return null;
+        // Identifiers must be non-empty; names and the raw type are stored as-is and may legitimately be
+        // empty strings (the engine accepts them), so for those only a non-string is "missing".
+        for (const k of [m.source_entity_id, m.target_entity_id]) {
+            if (typeof k !== 'string' || k === '')
+                return null;
+        }
+        for (const k of [m.source_entity, m.target_entity, m.relation_type]) {
+            if (typeof k !== 'string')
+                return null;
+        }
+        // Final review A2: the reader (resolveEvidenceStatus) and every dependency lookup (collectCiting) treat
+        // an empty or malformed evidence_refs as ineligible; a row that cannot be resolved must not be
+        // comparable either, even when its stored fingerprint recomputes from that metadata.
+        const refs = m.evidence_refs;
+        if (!Array.isArray(refs) || refs.length === 0 || !refs.every(isWellFormedRef))
+            return null;
+        try {
+            if (fingerprintFromMetadata(m, m.fingerprint_profile_id) !== m.input_fingerprint)
+                return null;
+        }
+        catch {
+            return null;
+        }
+        return `fp:${m.input_fingerprint}`;
+    }
+    const sourceId = row.chunk_type === 'entity' ? row.entity_id : row.chunk_type === 'relationship' ? row.relationship_id : null;
+    if (!sourceId)
+        return null;
+    return `legacy:${sha256Utf8(JSON.stringify([LEGACY_CMP_TAG, row.chunk_type, sourceId, sha256Utf8(row.text)]))}`;
+}
+// Taken immediately BEFORE inference; writeKgVectorIfCurrent (index.ts) re-checks all of it at write.
+export function captureKgEmbedInput(row, profileId) {
+    return { rowid: row.rowid, chunk_id: row.chunk_id, text_sha256: sha256Utf8(row.text ?? ''), cmp: kgComparisonValue(row), profile_id: profileId };
+}
+// (resolvers are added by Tasks 5, 6 and 7 below this line)
+// ---- D1 resolution (generation AND commit re-check run exactly this) ----
+export class EvidenceInputError extends Error {
+    code;
+    itemIndex;
+    constructor(code, itemIndex, detail) {
+        super(`generateRelationEvidenceChunks: item ${itemIndex}: ${code}${detail ? ` (${detail})` : ''}`);
+        this.code = code;
+        this.itemIndex = itemIndex;
+        this.name = 'EvidenceInputError';
+    }
+}
+export class EvidenceCommitConflictError extends Error {
+    itemIndex;
+    reason;
+    constructor(itemIndex, reason) {
+        super(`generateRelationEvidenceChunks: item ${itemIndex} changed between preparation and commit: ${reason}`);
+        this.itemIndex = itemIndex;
+        this.reason = reason;
+        this.name = 'EvidenceCommitConflictError';
+    }
+}
+const WHY_STATUSES = ['reason-stated', 'relation-only', 'unjudged'];
+// Every stored source of an observation, sorted (D1: the real rows, never a summary label).
+export function readSourceTuples(db, observationId) {
+    const rows = db.prepare(`SELECT source_kind, source_ref, source_hash FROM observation_sources WHERE observation_id = ?`)
+        .all(observationId);
+    return rows.map(r => ({ source_kind: r.source_kind, source_ref: r.source_ref, source_hash: r.source_hash ?? null }))
+        .sort(compareSourceTuples);
+}
+function sourceSummary(sources) {
+    if (sources.length === 0)
+        return 'unrecorded';
+    return sources.every(s => s.source_kind === 'import') ? 'import-only' : 'recorded';
+}
+// Validate one item against the CURRENT rows and build its body + metadata. Any failure throws
+// EvidenceInputError; nothing is written here. Order matters for the commit re-check
+// (REVIEW-ALPHA3 §3.1): an observation's ACTIVE status and a document chunk's type/parent are checked
+// before any hash or fingerprint, because a retract keeps id, revision and content and changes only
+// the status (lifecycle.ts:146-147) — the fingerprint alone cannot see it.
+export function resolveEvidenceItem(db, item, itemIndex, profileId) {
+    const fail = (code, detail = '') => { throw new EvidenceInputError(code, itemIndex, detail); };
+    if (!item || typeof item !== 'object')
+        fail('invalid-item');
+    if (typeof item.relationship_id !== 'string' || item.relationship_id === '')
+        fail('invalid-item', 'relationship_id');
+    if (!Array.isArray(item.evidence) || item.evidence.length === 0)
+        fail('empty-evidence');
+    if (item.evidence.length > EVIDENCE_CAPS.maxEntries)
+        fail('too-many-entries', `${item.evidence.length} > ${EVIDENCE_CAPS.maxEntries}`);
+    const rel = db.prepare(`
+    SELECT r.id, r.source_entity, r.target_entity, r.relationType, r.confidence,
+           e1.name AS source_name, e2.name AS target_name
+    FROM relationships r
+    JOIN entities e1 ON e1.id = r.source_entity
+    JOIN entities e2 ON e2.id = r.target_entity
+    WHERE r.id = ?`).get(item.relationship_id);
+    if (!rel)
+        return fail('unknown-relationship', item.relationship_id);
+    // kgComparisonValue (D2⑤) never accepts an empty endpoint id, so a chunk published with one could never
+    // be embedded by either CAS path. The schema has no non-empty CHECK and importGraph copies ids as given,
+    // so the shared preparation/commit resolver checks it before any write. Names and the raw type may
+    // legitimately be empty; only the ids are identifiers (REVIEW-T5-2_ I2).
+    if (typeof rel.source_entity !== 'string' || rel.source_entity === '' || typeof rel.target_entity !== 'string' || rel.target_entity === '') {
+        return fail('invalid-relationship-endpoint', item.relationship_id);
+    }
+    const refs = [];
+    const quotes = [];
+    // Array.from visits every index; forEach alone skips holes, so new Array(1) passed the 1–8 count with zero
+    // resolved entries and [ref, <hole>] dropped one silently (D1: at least one entry, none dropped;
+    // REVIEW-T5-2_ I1). This is a JS manager API, so no JSON layer turns holes into null first. A hole
+    // reads as undefined and fails as an invalid entry.
+    Array.from(item.evidence).forEach((e, j) => {
+        if (!e || typeof e !== 'object')
+            return fail('unknown-evidence-kind', `entry ${j}${j in item.evidence ? '' : ': hole'}`);
+        if (e.kind === 'document') {
+            if (typeof e.chunk_id !== 'string')
+                return fail('unknown-chunk', `entry ${j}`);
+            const c = db.prepare(`
+        SELECT m.chunk_id, m.chunk_type, m.document_id, m.text, d.id AS doc_id
+        FROM chunk_metadata m LEFT JOIN documents d ON d.id = m.document_id
+        WHERE m.chunk_id = ?`).get(e.chunk_id);
+            if (!c)
+                return fail('unknown-chunk', `entry ${j}: ${e.chunk_id}`);
+            if (c.chunk_type !== 'document' || c.document_id === null || c.doc_id === null || c.text === null) {
+                return fail('not-a-document-chunk', `entry ${j}: ${e.chunk_id}`);
+            }
+            if (typeof e.start !== 'number' || typeof e.end !== 'number' || !Number.isInteger(e.start) || !Number.isInteger(e.end)) {
+                return fail('range-not-integer', `entry ${j}`);
+            }
+            const n = cpLength(c.text);
+            if (!(0 <= e.start && e.start < e.end && e.end <= n))
+                return fail('range-out-of-bounds', `entry ${j}: [${e.start},${e.end}) of ${n} codepoints`);
+            if (e.end - e.start > EVIDENCE_CAPS.maxQuoteCodepoints)
+                return fail('quote-over-cap', `entry ${j}: ${e.end - e.start} codepoints`);
+            const quote = cpSlice(c.text, e.start, e.end);
+            if (sha256Utf8(quote) !== e.quote_sha256)
+                return fail('quote-hash-mismatch', `entry ${j}`);
+            refs.push({ kind: 'document', document_id: c.document_id, chunk_id: c.chunk_id, start: e.start, end: e.end,
+                chunk_text_sha256: sha256Utf8(c.text), quote_sha256: e.quote_sha256 });
+            quotes.push(quote);
+            return;
+        }
+        if (e.kind === 'observation') {
+            if (typeof e.observation_id !== 'string')
+                return fail('unknown-observation', `entry ${j}`);
+            const o = db.prepare(`SELECT observation_id, entity_id, revision_no, content, status FROM entity_observations WHERE observation_id = ?`)
+                .get(e.observation_id);
+            if (!o)
+                return fail('unknown-observation', `entry ${j}: ${e.observation_id}`);
+            if (o.status !== 'active')
+                return fail('observation-not-active', `entry ${j}: status ${o.status}`);
+            if (o.revision_no !== e.revision_no)
+                return fail('observation-revision-mismatch', `entry ${j}`);
+            if (sha256Utf8(o.content) !== e.content_sha256)
+                return fail('observation-content-mismatch', `entry ${j}`);
+            const len = cpLength(o.content); // the quoted unit is the WHOLE current content; never cut
+            if (len > EVIDENCE_CAPS.maxQuoteCodepoints)
+                return fail('quote-over-cap', `entry ${j}: ${len} codepoints`);
+            const sources = readSourceTuples(db, o.observation_id);
+            refs.push({ kind: 'observation', observation_id: o.observation_id, entity_id: o.entity_id, revision_no: o.revision_no,
+                content_sha256: e.content_sha256, status_at_generation: 'active', sources, source_summary: sourceSummary(sources) });
+            quotes.push(o.content);
+            return;
+        }
+        return fail('unknown-evidence-kind', `entry ${j}`);
+    });
+    const sup = item.support === undefined ? {} : item.support;
+    if (sup === null || typeof sup !== 'object')
+        fail('invalid-support');
+    const why = sup.why_status ?? 'unjudged';
+    if (!WHY_STATUSES.includes(why))
+        fail('invalid-support', `why_status ${String(why)}`);
+    if (sup.valid_time !== undefined && typeof sup.valid_time !== 'string')
+        fail('invalid-support', 'valid_time');
+    if (sup.scope_note !== undefined && typeof sup.scope_note !== 'string')
+        fail('invalid-support', 'scope_note');
+    const text = buildEvidenceBody(rel.source_name, rel.relationType, rel.target_name, quotes);
+    const bodyCp = cpLength(text);
+    if (bodyCp > EVIDENCE_CAPS.maxBodyCodepoints)
+        fail('body-over-cap', `${bodyCp} codepoints`);
+    const fp = computeInputFingerprint({
+        relationship_id: rel.id, source_entity_id: rel.source_entity, target_entity_id: rel.target_entity,
+        relation_type: rel.relationType, source_name: rel.source_name, target_name: rel.target_name,
+        kg_format: EVIDENCE_FORMAT, refs, profile_id: profileId,
+    });
+    const metadata = {
+        kg_format: EVIDENCE_FORMAT,
+        relationship_id: rel.id, source_entity_id: rel.source_entity, target_entity_id: rel.target_entity,
+        source_entity: rel.source_name, target_entity: rel.target_name, relation_type: rel.relationType, direction: 'source->target',
+        confidence: rel.confidence,
+        evidence_refs: refs,
+        support: { why_status: why, valid_time: sup.valid_time ?? null, scope_note: sup.scope_note ?? null },
+        generated_ref_status: 'refs-resolved',
+        input_fingerprint: fp, fingerprint_profile_id: profileId,
+        body_codepoints: bodyCp,
+        embedded_truncation: 'unchecked',
+        evidence_semantics: EVIDENCE_SEMANTICS,
+    };
+    return { chunk_id: evidenceChunkId(rel.id), relationship_id: rel.id, text, body_codepoints: bodyCp, metadata };
+}
+// legacy triplet -> claim_only, no refs. evidence-v1 -> each reference resolved against the CURRENT
+// rows; all available -> refs_available, anything else (missing, mismatch, malformed or empty list) ->
+// refs_unavailable. An inactive or historical revision is 'mismatch', never 'available'.
+export function resolveEvidenceStatus(db, meta) {
+    if (!meta || meta.kg_format === undefined)
+        return { status: 'claim_only', refs: [] };
+    const list = meta.kg_format === EVIDENCE_FORMAT && Array.isArray(meta.evidence_refs) ? meta.evidence_refs : null;
+    if (!list || list.length === 0)
+        return { status: 'refs_unavailable', refs: [] };
+    const refs = list.map((r, i) => resolveOneRef(db, r, i));
+    return { status: refs.every(r => r.status === 'available') ? 'refs_available' : 'refs_unavailable', refs };
+}
+// R4 (REVIEW-PLAN): structure is checked at runtime before any field is used — `as SourceTuple[]` is not
+// a check, and `sources: [null]` used to reach `s.source_kind`. A structurally malformed reference is
+// 'mismatch' (so the chunk is refs_unavailable), never a TypeError. Real DB errors are NOT caught here.
+const isStr = (v) => typeof v === 'string';
+const isInt = (v) => typeof v === 'number' && Number.isInteger(v);
+export function isSourceTuple(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const s = v;
+    return isStr(s.source_kind) && isStr(s.source_ref) && (s.source_hash === null || isStr(s.source_hash));
+}
+export function isWellFormedRef(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const r = v;
+    if (r.kind === 'document') {
+        return isStr(r.document_id) && isStr(r.chunk_id) && isInt(r.start) && isInt(r.end) && isStr(r.chunk_text_sha256) && isStr(r.quote_sha256);
+    }
+    if (r.kind === 'observation') {
+        return isStr(r.observation_id) && isStr(r.entity_id) && isInt(r.revision_no) && isStr(r.content_sha256)
+            && Array.isArray(r.sources) && r.sources.every(isSourceTuple);
+    }
+    return false;
+}
+function resolveOneRef(db, raw, index) {
+    const r = raw && typeof raw === 'object' ? raw : {};
+    const out = (status, text = null) => ({ index, kind: typeof r.kind === 'string' ? r.kind : 'unknown', status, ref: raw, text });
+    if (!isWellFormedRef(raw))
+        return out('mismatch');
+    if (r.kind === 'document') {
+        const c = db.prepare(`
+      SELECT m.chunk_type, m.document_id, m.text, d.id AS doc_id
+      FROM chunk_metadata m LEFT JOIN documents d ON d.id = m.document_id WHERE m.chunk_id = ?`)
+            .get(r.chunk_id);
+        if (!c || c.doc_id === null)
+            return out('missing');
+        if (c.chunk_type !== 'document' || c.document_id !== r.document_id || c.text === null)
+            return out('mismatch');
+        if (sha256Utf8(c.text) !== r.chunk_text_sha256)
+            return out('mismatch');
+        if (typeof r.start !== 'number' || typeof r.end !== 'number' || !Number.isInteger(r.start) || !Number.isInteger(r.end))
+            return out('mismatch');
+        if (!(0 <= r.start && r.start < r.end && r.end <= cpLength(c.text)))
+            return out('mismatch');
+        const quote = cpSlice(c.text, r.start, r.end);
+        if (sha256Utf8(quote) !== r.quote_sha256)
+            return out('mismatch');
+        return out('available', quote);
+    }
+    if (r.kind === 'observation') {
+        const o = db.prepare(`SELECT entity_id, revision_no, content, status FROM entity_observations WHERE observation_id = ?`)
+            .get(r.observation_id);
+        if (!o)
+            return out('missing');
+        if (o.status !== 'active' || o.entity_id !== r.entity_id || o.revision_no !== r.revision_no || sha256Utf8(o.content) !== r.content_sha256) {
+            return out('mismatch');
+        }
+        const now = readSourceTuples(db, r.observation_id).map(s => [s.source_kind, s.source_ref, s.source_hash]);
+        const stored = [...r.sources].sort(compareSourceTuples).map(s => [s.source_kind, s.source_ref, s.source_hash]);
+        if (JSON.stringify(now) !== JSON.stringify(stored))
+            return out('mismatch');
+        return out('available', o.content);
+    }
+    return out('mismatch');
+}
+function evidenceRowViews(db) {
+    const rows = db.prepare(`SELECT rowid, metadata FROM chunk_metadata WHERE chunk_type = 'relationship' AND metadata LIKE '%evidence-v1%'`).all();
+    const out = [];
+    for (const r of rows) {
+        let m;
+        try {
+            m = JSON.parse(r.metadata ?? 'null');
+        }
+        catch {
+            out.push({ rowid: r.rowid, refs: null });
+            continue;
+        }
+        if (!m || typeof m !== 'object') {
+            out.push({ rowid: r.rowid, refs: null });
+            continue;
+        }
+        const meta = m;
+        if (meta.kg_format !== EVIDENCE_FORMAT)
+            continue; // a legacy row that merely mentions the string
+        out.push({ rowid: r.rowid, refs: Array.isArray(meta.evidence_refs) ? meta.evidence_refs : null });
+    }
+    return out;
+}
+function collectCiting(db, hit) {
+    return evidenceRowViews(db)
+        .filter(v => v.refs === null || v.refs.length === 0 || v.refs.some(r => !isWellFormedRef(r) || hit(r)))
+        .map(v => v.rowid);
+}
+export function collectEvidenceRowidsCitingObservations(db, observationIds) {
+    if (observationIds.length === 0)
+        return [];
+    const ids = new Set(observationIds);
+    return collectCiting(db, r => r.kind === 'observation' && typeof r.observation_id === 'string' && ids.has(r.observation_id));
+}
+export function collectEvidenceRowidsCitingDocument(db, documentId) {
+    return collectCiting(db, r => r.kind === 'document' && r.document_id === documentId);
+}
+export function collectEvidenceRowidsCitingOwnerEntity(db, entityId) {
+    return collectCiting(db, r => r.kind === 'observation' && r.entity_id === entityId);
+}

package/dist/src/observations/projection.d.ts

@@ -2,3 +2,5 @@ import type Database from 'better-sqlite3';
 export declare function rebuildProjection(db: Database.Database, entityId: string): void;
 export declare function deleteStaleKgChunks(db: Database.Database, entityId: string): number;
 export declare function deleteKgRelationshipChunks(db: Database.Database, relationshipIds: string[]): number;
+export declare function deleteKgChunkRows(db: Database.Database, rowids: number[]): number;
+export declare function refreshKgRelationshipConfidence(db: Database.Database, relationshipId: string): number;

package/dist/src/observations/projection.js

@@ -46,3 +46,52 @@ export function deleteKgRelationshipChunks(db, relationshipIds) {
     }
     return n;
 }
+// kg-relation-evidence D2: the one place that removes KG chunk rows by rowid. A rowid that is not a
+// KG row (or no longer exists) is skipped BEFORE anything is deleted, so a rowid reused by a document
+// chunk never loses its vector. Order: vector (vec0 needs a literal integer rowid), entity links,
+// metadata (the chunks_fts delete trigger fires on the metadata row). Callers already inside a
+// transaction pass rowids they collected before mutating the source.
+export function deleteKgChunkRows(db, rowids) {
+    let n = 0;
+    for (const raw of new Set(rowids)) {
+        const rowid = Number(raw);
+        if (!Number.isInteger(rowid) || rowid < 0)
+            throw new Error(`Invalid rowid: ${raw}`);
+        const row = db.prepare(`SELECT chunk_type FROM chunk_metadata WHERE rowid = ?`).get(rowid);
+        if (!row || (row.chunk_type !== 'entity' && row.chunk_type !== 'relationship'))
+            continue;
+        db.exec(`DELETE FROM chunks WHERE rowid = ${rowid}`);
+        db.prepare(`DELETE FROM chunk_entities WHERE chunk_rowid = ?`).run(rowid);
+        n += db.prepare(`DELETE FROM chunk_metadata WHERE rowid = ?`).run(rowid).changes;
+    }
+    return n;
+}
+// kg-relation-evidence D2②: relationship KG chunks (triplet and evidence-v1) carry a DISPLAY copy of
+// `confidence` (index.ts:2319-2324). It is not a search input, so refresh it in place: the body, the
+// input_hash and the vector stay, and kg_format / evidence_refs / input_fingerprint are never touched.
+// The narrowed FTS trigger (migration 12) fires only on text/chunk_id, so this does not reindex.
+export function refreshKgRelationshipConfidence(db, relationshipId) {
+    const rel = db.prepare(`SELECT confidence FROM relationships WHERE id = ?`).get(relationshipId);
+    if (!rel)
+        return 0;
+    const rows = db.prepare(`SELECT rowid, metadata FROM chunk_metadata WHERE chunk_type = 'relationship' AND relationship_id = ?`).all(relationshipId);
+    let n = 0;
+    for (const r of rows) {
+        let meta;
+        try {
+            meta = JSON.parse(r.metadata ?? '{}');
+        }
+        catch {
+            continue;
+        } // malformed: the reader reports it
+        if (!meta || typeof meta !== 'object')
+            continue;
+        const m = meta;
+        if (m.confidence === rel.confidence)
+            continue;
+        m.confidence = rel.confidence;
+        db.prepare(`UPDATE chunk_metadata SET metadata = ? WHERE rowid = ?`).run(JSON.stringify(m), r.rowid);
+        n++;
+    }
+    return n;
+}

package/dist/src/tools/knowledge-graph-tools.js

@@ -287,7 +287,7 @@ const hybridSearchCapability = {
             },
             limit: {
                 type: 'number',
-                description: 'Maximum number of results to return',
+                description: 'Maximum number of results to return AND the retrieval depth (each query variant requests up to limit x 3 vector and up to limit x 3 FTS candidates, then merged), so hybridSearch(q, 30) cut to 10 can differ from hybridSearch(q, 10)',
                 default: 5
             },
             useGraph: {
@@ -312,6 +312,8 @@ chunk out of the top-5 in ~40% of known-item queries. For relationship explorati
 - (!important!) **Graph re-ranking is opt-in (default false since v5.3.0)** — it re-orders candidates by matched/connected entity links, which is measured to hurt known-item retrieval; enable it only for backward compatibility or controlled evaluation
 - (!important!) Graph re-ranking does not generate candidates — for "what is connected to X" use openNodes -> getNeighbors
 - (!important!) relevance_score is a RANK score on the default call: 1/(60 + vector rank) + 1/(60 + FTS rank), at most 2/61; it is not a similarity or probability and is only comparable within one call (vector_similarity and fts_boost are reported alongside)
+- (!important!) limit is both the maximum result count and the retrieval depth (each query variant requests up to limit x 3 vector candidates and up to limit x 3 FTS candidates, which are then merged), so results, even the top-1, can differ between limits; for comparisons fix the call limit and cut k from the returned list
+- (!important!) full_context_available means getDetailedContext can resolve the stored chunk body; it is not a verified-evidence signal (for knowledge-graph relationship chunks read evidence_status there)
 - (!important!) **Best results when knowledge graph is well-populated** with entities and relationships
 </importantNotes>
 
@@ -345,7 +347,7 @@ chunk out of the top-5 in ~40% of known-item queries. For relationship explorati
 
 <parameters>
 - query: Search query — a natural-language question or an exact term/identifier (string, required)
-- limit: Maximum results to return, default 5 (number, optional)
+- limit: Maximum results to return AND retrieval depth (up to limit x 3 vector and limit x 3 FTS candidates per query variant), default 5 (number, optional). For comparisons fix the call limit and cut k from the returned list
 - useGraph: Enable knowledge graph re-ranking, default false / opt-in (boolean, optional)
 </parameters>
 
@@ -356,7 +358,7 @@ chunk out of the top-5 in ~40% of known-item queries. For relationship explorati
 </examples>`;
 const hybridSearchSchema = {
     query: z.string().describe('The search query to find relevant information'),
-    limit: z.number().optional().default(5).describe('Maximum number of results to return'),
+    limit: z.number().optional().default(5).describe('Maximum number of results to return; also the retrieval depth (up to limit x 3 vector and limit x 3 FTS candidates per query variant)'),
     useGraph: z.boolean().optional().default(false).describe('Opt-in legacy/experimental graph re-ranker (default false since v5.3.0; measured to hurt known-item retrieval; for exploration use openNodes -> getNeighbors)'),
 };
 export const hybridSearchTool = {
@@ -461,6 +463,8 @@ Perfect drill-down tool for exploring the full content behind search result high
 - (!important!) **Returns complete chunk text** - not just summaries or highlights
 - (!important!) **Includes surrounding chunks** - for better context understanding
 - (!important!) **Shows entity associations** - to understand knowledge graph connections
+- (!important!) **Knowledge-graph chunks** (chunk_type entity/relationship) return document_id: null and document_title: null with source_kind and source_id; an entity chunk returns the entity and its active observations, a relationship chunk returns the relationship, evidence_status (claim_only | refs_available | refs_unavailable) and per-reference evidence_refs (available | missing | mismatch)
+- (!important!) evidence_status is reference resolution, not a truth verdict: refs_available means every cited quote or observation still matches verbatim (current chunk range and hashes, or the current active observation revision); whoever generated the chunk selected the evidence
 </importantNotes>
 
 <whenToUseThisTool>

package/docs/UPDATING.md

@@ -108,6 +108,16 @@ path and holder pid (e.g. `.download-<key>.lock`). Verify the holder process
 is genuinely gone or hung (`ps -p <pid>`), then remove the lock file manually;
 the next start becomes a clean download owner.
 
+## v6.4.1 (schema v14, unchanged): evidence-backed relationship chunks (opt-in), KG lifecycle fixes, faster oversize split
+
+**What changes for an existing database.** Nothing is migrated and search defaults are unchanged (the 113-query
+parity run on a frozen real project database returned the same ids, scores and field types as 6.4.0). Documents
+chunked from now on are stamped `fallback=cp-window-N`; documents stamped `cp-exact-N` by 6.4.0 stay current format
+and an unchanged-content sync does not re-chunk them. KG chunks for a deleted relationship or a changed cited source
+now leave search in the same transaction. **`importGraph` now refuses non-string document ids and
+observation-source ids** (the whole import, nothing written) — a dump produced by `exportGraph` uses string ids.
+Details: README changelog.
+
 ## v6.4.0 (schema v14, unchanged): `hybridSearch` default = rank fusion, summaries opt-in
 
 (Published first as `6.4.0-rc.1` on the `next` dist-tag; promoted to `latest` after the published artifact passed a

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "rag-memory-epf-mcp",
- "version": "6.4.0",
+ "version": "6.4.1",
  "engines": {
   "node": ">=24"
  },
@@ -45,7 +45,7 @@
   "prepare": "npm run build",
   "watch": "tsc --watch",
   "verify:invariants": "node test/chunk-invariants.test.mjs",
-  "verify:engine": "node test/engine-smoke.test.mjs && node test/launch-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs && node test/entity-embed-cap.test.mjs && node test/migration12.test.mjs && node test/model-cache.test.mjs && node test/embedding-gate.test.mjs && node test/lazy-boot.test.mjs && node test/reconciliation.test.mjs && node test/backfill.test.mjs && node test/fts-query.test.mjs && node test/search-contracts.test.mjs && node test/tool-contracts.test.mjs && node test/bounded-exit.test.mjs && node test/observation-schema.test.mjs && node test/search-graph-default.test.mjs && node test/observation-migration.test.mjs && node test/observation-lifecycle.test.mjs && node test/observation-contracts.test.mjs && node test/observation-search.test.mjs && node test/observation-cascade.test.mjs && node test/observation-realdata.test.mjs && node test/chunker-c.test.mjs && node test/migration14.test.mjs && node test/chunk-params-validation.test.mjs && node test/vector-reuse.test.mjs && node test/entity-range-linking.test.mjs && node test/alias-link-gate.test.mjs && node test/entity-name-boundary.test.mjs && node test/stats-chunking.test.mjs && node test/migration14-realdata.test.mjs && node test/migration14-realdata-sync.test.mjs && node test/search-summaries-off.test.mjs && node test/search-fusion-rrf.test.mjs && node test/query-input.test.mjs && node test/document-return-contracts.test.mjs && node test/observation-date-prefix.test.mjs && node test/delete-entities-cascade.test.mjs && node test/delete-entities-kg-hygiene.test.mjs && node test/backup-publish-portable.test.mjs && node test/graph-context-explain.test.mjs && node test/eval-graph-role-libs.test.mjs && node test/eval-graph-role-t5b.test.mjs && node --test test/eval-graph-role-t8-fix.test.mjs && node --test test/eval-graph-role-t7-upstream.test.mjs && node --test test/eval-graph-role-t11-decision.test.mjs && node --test test/eval-graph-role-prereq-fix.test.mjs && node test/db-path.test.mjs && node test/mmap-option.test.mjs && node test/wal-exit.test.mjs && node test/wal-sidecar-guard.test.mjs",
+  "verify:engine": "node test/engine-smoke.test.mjs && node test/launch-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs && node test/entity-embed-cap.test.mjs && node test/migration12.test.mjs && node test/model-cache.test.mjs && node test/embedding-gate.test.mjs && node test/lazy-boot.test.mjs && node test/reconciliation.test.mjs && node test/backfill.test.mjs && node test/fts-query.test.mjs && node test/search-contracts.test.mjs && node test/tool-contracts.test.mjs && node test/bounded-exit.test.mjs && node test/observation-schema.test.mjs && node test/search-graph-default.test.mjs && node test/observation-migration.test.mjs && node test/observation-lifecycle.test.mjs && node test/observation-contracts.test.mjs && node test/observation-search.test.mjs && node test/observation-cascade.test.mjs && node test/observation-realdata.test.mjs && node --no-concurrent-sparkplug test/chunker-c.test.mjs && node test/migration14.test.mjs && node test/chunk-params-validation.test.mjs && node test/vector-reuse.test.mjs && node test/entity-range-linking.test.mjs && node test/alias-link-gate.test.mjs && node test/entity-name-boundary.test.mjs && node test/stats-chunking.test.mjs && node test/migration14-realdata.test.mjs && node test/migration14-realdata-sync.test.mjs && node test/search-summaries-off.test.mjs && node test/search-fusion-rrf.test.mjs && node test/query-input.test.mjs && node test/document-return-contracts.test.mjs && node test/observation-date-prefix.test.mjs && node test/delete-entities-cascade.test.mjs && node test/delete-entities-kg-hygiene.test.mjs && node test/backup-publish-portable.test.mjs && node test/graph-context-explain.test.mjs && node test/eval-graph-role-libs.test.mjs && node test/eval-graph-role-t5b.test.mjs && node --test test/eval-graph-role-t8-fix.test.mjs && node --test test/eval-graph-role-t7-upstream.test.mjs && node --test test/eval-graph-role-t11-decision.test.mjs && node --test test/eval-graph-role-prereq-fix.test.mjs && node test/db-path.test.mjs && node test/mmap-option.test.mjs && node test/wal-exit.test.mjs && node test/wal-sidecar-guard.test.mjs && node test/kg-evidence-core.test.mjs && node test/kg-delete-relation.test.mjs && node test/kg-confidence-copy.test.mjs && node test/kg-embed-cas.test.mjs && node test/kg-relation-evidence.test.mjs && node test/kg-detail-context.test.mjs && node test/kg-evidence-invalidation.test.mjs && node test/kg-evidence-cas.test.mjs && node test/kg-defaults.test.mjs && node test/chunker-oversize-cost.test.mjs && node test/chunker-structure-parity.test.mjs && node test/search-limit-depth.test.mjs && node test/kg-import-id-contract.test.mjs && node test/kg-evidence-guards.test.mjs",
   "test": "npm run build && npm run verify:invariants && npm run verify:engine",
   "prepublishOnly": "npm run build && npm run verify:invariants && npm run verify:engine"
  },