rag-memory-epf-mcp 3.6.0 → 5.0.0

package/dist/index.js

@@ -21,8 +21,12 @@ import modularity from 'graphology-metrics/graph/modularity.js';
 import { getAllMCPTools, validateToolArgs, getSystemInfo } from './src/tools/tool-registry.js';
 // Import migration system
 import { MigrationManager } from './src/migrations/migration-manager.js';
+import { backupBeforeMigration } from './src/backup/preflight.js';
+import { rebuildProjection, deleteStaleKgChunks } from './src/observations/projection.js';
+import { addRevision, correctRevision, transitionStatus, linkSources, nextProjectionOrder } from './src/observations/lifecycle.js';
+import { getObservationHistory } from './src/observations/history.js';
 // Import chunk text algorithm (extracted for publish-time invariant testing)
-import { chunkText as splitTextIntoChunks } from './src/chunkText.js';
+import { chunkStructured as chunkStructuredText, effectiveSignature, isCurrentFormatSignature, LEGACY_SIGNATURE, DEFAULT_MAX_TOKENS } from './src/chunkerC.js';
 import { migrations } from './src/migrations/migrations.js';
 // v3.6 lite install: model lifecycle + version-independent cache (A′ boundary)
 import { EmbeddingGate, GateNotReadyError, GateDisabledError, TerminalConfigError } from './src/embeddingGate.js';
@@ -105,6 +109,36 @@ const TEXT_BUILDER_VERSION = 'tb1';
 // edge belongs to an adjacent chunk and must be removed so TextDecoder does
 // not emit U+FFFD. Pass trimHead/trimTail=false to preserve head/tail bytes.
 // (Implementation moved to src/chunkText.ts for testability.)
+export class SyncCasConflictError extends Error {
+    constructor(documentId) { super(`sync CAS conflict on ${documentId}`); this.name = 'SyncCasConflictError'; }
+}
+// Test-only fault hook (v13 setMigrationFaultPoint 선례 — 환경변수 금지: 상시 스위치는
+// 오설정 한 줄로 sync 를 깬다).
+let __syncFaultHook = null;
+export function setSyncFaultPoint(point, fn) {
+    __syncFaultHook = point && fn ? (p) => { if (p === point)
+        fn(); } : null;
+}
+// Pure vector-reuse decision (spec §5.2 조건 1~5). Returns an OWNED Buffer copy:
+// a Buffer read back from SQLite has no byteOffset-0 guarantee, and inserting
+// `.buffer` of a subarray would write the wrong 4,096 bytes (advisor r5-9).
+export function selectReusableVector(candidates, text, currentProfileId, sha256hex) {
+    const h = sha256hex(text);
+    for (const r of candidates) {
+        if (!r.embedding)
+            continue; // 조건 1: 벡터 실존
+        if (r.input_hash !== h)
+            continue; // 조건 2: input_hash 일치
+        if (r.text !== text)
+            continue; // 조건 3: exact text 최종판정
+        if (r.profile_id !== currentProfileId)
+            continue; // 조건 4: 현행 프로필
+        if (r.provenance_state !== 'verified' && r.provenance_state !== 'legacy_assumed')
+            continue; // 조건 5 (NULL 제외)
+        return { vec: Buffer.from(r.embedding), provenance: r.provenance_state }; // owned copy
+    }
+    return null;
+}
 function safeRowid(value) {
     const n = Number(value);
     if (!Number.isInteger(n) || n < 0) {
@@ -129,6 +163,9 @@ export class RAGKnowledgeGraphManager {
     // v3.6 (spec §3): initialize = DB + migrations + profile only. The embedding
     // model is NEVER awaited here — main() connects the MCP server first and the
     // gate loads in the background (lazy) or is awaited explicitly (eager).
+    // __testForceFkOff: 음성 대조군 전용. FK 게이트가 실제로 부팅을 막는지 시험한다.
+    // 이름에 __test 를 박아 둔 이유는 이것이 프로덕션 설정 표면이 아니라는 것을
+    // 호출부에서 읽히게 하기 위해서다.
     async initialize(opts = {}) {
         console.error('🚀 Initializing RAG Knowledge Graph MCP Server...');
         this.db = new Database(DB_FILE_PATH);
@@ -140,9 +177,34 @@ export class RAGKnowledgeGraphManager {
         this.db.pragma('temp_store = MEMORY');
         this.db.pragma('mmap_size = 268435456');
         this.db.pragma('foreign_keys = ON');
+        // spec §5.2: 관찰 lifecycle 의 무결성은 전부 FK CASCADE 를 전제한다 — root 를 지우면
+        // revision 이, revision 을 지우면 source 가 따라가야 history 가 고아로 남지 않는다.
+        // FK 가 꺼진 채 돌면 그 계약이 조용히 무효가 되고, 그게 최악이다. 스키마를 건드리기
+        // 전에(= runMigrations 앞에서) 멈춘다.
+        // 트랜잭션 내부에서는 이 pragma 가 no-op 이므로(실측 before=1·during=1·after=1)
+        // 부팅 시점 확인이 유일한 방어 지점이다.
+        //
+        // 음성 대조군 주입은 **인자로만** 받는다. 환경변수로 두면 프로덕션 경로에
+        // "부팅을 막는 스위치"가 상시 존재하게 되고, 오설정 한 줄로 서버가 안 뜬다
+        // (advisor beta 자기의심 2 = "더 나쁘다"). 테스트는 manager 를 직접 만들므로
+        // 인자 주입으로 충분하다.
+        if (opts.__testForceFkOff)
+            this.db.pragma('foreign_keys = OFF');
+        {
+            const fk = this.db.pragma('foreign_keys', { simple: true });
+            if (Number(fk) !== 1) {
+                throw new Error(`foreign_keys is ${fk}, expected 1. The observation lifecycle relies on FK CASCADE ` +
+                    `for history integrity; refusing to run migrations without it.`);
+            }
+        }
         this.encoding = get_encoding("cl100k_base");
         await this.runMigrations();
         this.currentProfileId = this.ensureCurrentProfile();
+        // v14 (spec §7.2): 런타임이 기본 chunker 의 SSOT — 마이그레이션의 리터럴은 동결된
+        // 역사이고, 기본값이 진화하면(c2 등) 이 upsert 가 부팅마다 현재값을 기록한다.
+        this.db.prepare(`INSERT INTO server_meta (key, value) VALUES ('current_default_chunker', ?)
+                     ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
+            .run(effectiveSignature(DEFAULT_MAX_TOKENS));
         this.embeddingsMode = opts.skipModel
             ? 'off'
             : (process.env.RAG_MEMORY_EMBEDDINGS || 'lazy');
@@ -322,18 +384,44 @@ export class RAGKnowledgeGraphManager {
     // where another tool call can retrieve the pre-mutation vector, and a crash
     // between mutation and re-embed leaves a clean missing state (backfill
     // target), never a stale-searchable one.
+    // spec §4.5 단계 1: 관찰 변경 · projection 재합성 · entity vector 무효화 ·
+    // stale KG chunk 제거를 한 트랜잭션으로 묶는다. 하나만 되면 검색이 낡은
+    // 사실을 계속 반환한다.
+    // mutate 가 명시적으로 false 를 반환하면 "아무것도 바꾸지 않았다"는 뜻이고
+    // projection 재합성·벡터 무효화·KG 정리를 건너뛴다. 이 경로가 없으면
+    // 무변경 upsert 나 dedup-only add 가 **정상 벡터를 지우고 재임베딩도 안 해서**
+    // 검색 품질만 깎는다(advisor 구현리뷰 r1 발견 1, 실행 재현).
+    // 반환값 = 실제로 변경이 있었는가.
     mutateEntityAndInvalidate(entityId, mutate) {
+        let changed = false;
         const tx = this.db.transaction(() => {
-            mutate();
-            const meta = this.db.prepare(`SELECT rowid FROM entity_embedding_metadata WHERE entity_id = ?`)
-                .get(entityId);
-            if (meta) {
-                this.db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${Number(meta.rowid)}`);
-                this.db.prepare(`DELETE FROM entity_embedding_metadata WHERE entity_id = ?`).run(entityId);
-            }
+            changed = mutate() !== false;
+            if (!changed)
+                return;
+            rebuildProjection(this.db, entityId);
+            this.invalidateDerivedForEntity(entityId);
         });
         tx();
-        this.coordinator?.invalidateCoverage();
+        if (changed)
+            this.coordinator?.invalidateCoverage();
+        return changed;
+    }
+    // 관찰이 바뀐 entity 의 파생 상태를 무효화한다: entity vector + stale KG chunk.
+    // **트랜잭션을 열지 않는다** — 호출자가 이미 하나의 단위 안에 있다고 가정한다.
+    //
+    // importGraph 가 이 단계를 건너뛰고 있었다: projection 만 재합성하고 파생 상태를
+    // 그대로 둬서, 이미 존재하는 entity 를 import 로 덮으면 옛 벡터·옛 KG chunk 가
+    // 계속 검색에 나왔다(advisor beta 발견 2, hybridSearch 로 실측 재현).
+    // 그래서 "모든 관찰 변경은 mutateEntityAndInvalidate 를 통한다"는 규칙에
+    // 예외가 하나 있었고, 그 예외가 정확히 그 규칙이 막으려던 결함을 만들었다.
+    invalidateDerivedForEntity(entityId) {
+        const meta = this.db.prepare(`SELECT rowid FROM entity_embedding_metadata WHERE entity_id = ?`)
+            .get(entityId);
+        if (meta) {
+            this.db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${Number(meta.rowid)}`);
+            this.db.prepare(`DELETE FROM entity_embedding_metadata WHERE entity_id = ?`).run(entityId);
+        }
+        deleteStaleKgChunks(this.db, entityId);
     }
     // §6a-1 invariant: when an entity's embedding input changed but re-embedding
     // is unavailable, its old vector must not stay searchable.
@@ -434,6 +522,11 @@ export class RAGKnowledgeGraphManager {
         });
         // Get pending migrations before running them
         const pendingBefore = migrationManager.getPendingMigrations();
+        // spec §5.1: 대기 중 마이그레이션이 있으면 먼저 일관 스냅샷을 남긴다.
+        // 실패는 throw = fail-closed (백업 없이 스키마를 바꾸지 않는다).
+        // await: 백업은 Online Backup API 를 쓰므로 비동기다. 여기서 await 를 빠뜨리면
+        // 백업이 끝나기 전에 마이그레이션이 시작한다 = 백업 없이 스키마를 바꾸는 것이다.
+        await backupBeforeMigration(this.db, DB_FILE_PATH, pendingBefore.map(m => m.version), migrationManager.getCurrentVersion());
         // Run pending migrations
         const result = await migrationManager.runMigrations();
         console.error(`🔧 Database schema ready (version ${result.currentVersion}, ${result.applied} migrations applied)`);
@@ -469,45 +562,73 @@ export class RAGKnowledgeGraphManager {
         if (!this.db)
             throw new Error('Database not initialized');
         const result = [];
+        // v13: 관찰은 lifecycle 테이블이 정본이고 entities.observations 는 projection 이다.
+        // entity 행은 빈 배열로 만들고 rebuildProjection 이 채운다.
         const insertStmt = this.db.prepare(`
       INSERT OR IGNORE INTO entities (id, name, entityType, observations, metadata)
-      VALUES (?, ?, ?, ?, ?)
+      VALUES (?, ?, ?, '[]', ?)
     `);
+        const stripDate = (s2) => s2.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
         for (const entity of entities) {
             const entityId = `entity_${entity.name.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
-            const timestamped = (entity.observations || []).map(o => this._timestampObservation(o));
-            // Try insert first
-            const insertResult = insertStmt.run(entityId, entity.name, entity.entityType, JSON.stringify(timestamped), '{}');
-            if (insertResult.changes > 0) {
-                // New entity created. CRUD success is independent of model readiness
-                // (spec §5): not-ready -> row stays vectorless (queued for backfill).
-                console.error(`🔮 Generating embedding for new entity: ${entity.name}`);
+            const ts = new Date().toISOString();
+            const ids = [];
+            let created = false;
+            let addedCount = 0;
+            let typeUpdated = false;
+            // entity INSERT 도 같은 트랜잭션 안이다. 밖에 두면 lifecycle INSERT 가
+            // 실패할 때 entity 행만 남는 split state 가 생긴다
+            // (advisor 구현리뷰 r1 발견 2, 실행 재현).
+            const changed = this.mutateEntityAndInvalidate(entityId, () => {
+                created = insertStmt.run(entityId, entity.name, entity.entityType, '{}').changes > 0;
+                if (!created && entity.entityType && entity.entityType !== 'CONCEPT') {
+                    const cur = this.db.prepare(`SELECT entityType FROM entities WHERE id = ?`)
+                        .get(entityId);
+                    if (cur && cur.entityType !== entity.entityType) {
+                        this.db.prepare(`UPDATE entities SET entityType = ? WHERE id = ?`)
+                            .run(entity.entityType, entityId);
+                        typeUpdated = true;
+                    }
+                }
+                const activeRows = this.db.prepare(`SELECT observation_id, content FROM entity_observations
+           WHERE entity_id = ? AND status = 'active'`).all(entityId);
+                const activeByBare = new Map(activeRows.map(r => [stripDate(r.content), r.observation_id]));
+                let sourcesAdded = 0;
+                for (const raw of (entity.observations || [])) {
+                    const content = this._timestampObservation(raw);
+                    const bare = stripDate(content);
+                    const dupId = activeByBare.get(bare);
+                    if (dupId) {
+                        // 같은 사실이 다른 출처에서 다시 왔다 = evidence 추가, 새 revision 아님.
+                        if (entity.sources?.length)
+                            sourcesAdded += linkSources(this.db, dupId, entity.sources, ts);
+                        ids.push(null);
+                        continue;
+                    }
+                    const id = addRevision(this.db, {
+                        entityId, content, status: entity.status ?? 'active', sources: entity.sources, ts
+                    });
+                    activeByBare.set(bare, id);
+                    ids.push(id);
+                    addedCount++;
+                }
+                // 아무것도 안 바뀌었으면 projection·벡터·KG 를 건드리지 않는다.
+                return created || typeUpdated || addedCount > 0 || sourcesAdded > 0;
+            });
+            const projected = JSON.parse(this.db.prepare(`SELECT observations FROM entities WHERE id = ?`)
+                .get(entityId).observations);
+            // 재임베딩은 무효화가 실제로 일어났을 때만. 조건이 갈리면
+            // "벡터를 지우고 다시 만들지 않는" 창이 생긴다.
+            if (changed) {
+                console.error(created
+                    ? `🔮 Generating embedding for new entity: ${entity.name}`
+                    : `♻️ Upserted entity: ${entity.name} (+${addedCount} obs${typeUpdated ? ', type→' + entity.entityType : ''})`);
                 const embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
-                result.push({ ...entity, observations: timestamped, embedding_status });
+                result.push({ ...entity, observations: projected, created,
+                    observation_ids: ids, embedding_status });
             }
             else {
-                // Entity already exists — upsert: merge observations and update entityType
-                const existing = this.db.prepare(`SELECT observations, entityType FROM entities WHERE id = ?`)
-                    .get(entityId);
-                if (existing) {
-                    const currentObs = JSON.parse(existing.observations);
-                    // Strip date prefix for dedup comparison
-                    const stripDate = (s) => s.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
-                    const currentBare = new Set(currentObs.map(stripDate));
-                    const newObs = timestamped.filter(o => !currentBare.has(stripDate(o)));
-                    const needsTypeUpdate = entity.entityType && entity.entityType !== 'CONCEPT' && entity.entityType !== existing.entityType;
-                    if (newObs.length > 0 || needsTypeUpdate) {
-                        const mergedObs = [...currentObs, ...newObs];
-                        const updatedType = needsTypeUpdate ? entity.entityType : existing.entityType;
-                        this.mutateEntityAndInvalidate(entityId, () => {
-                            this.db.prepare(`UPDATE entities SET observations = ?, entityType = ? WHERE id = ?`)
-                                .run(JSON.stringify(mergedObs), updatedType, entityId);
-                        });
-                        console.error(`♻️ Upserted entity: ${entity.name} (+${newObs.length} obs${needsTypeUpdate ? ', type→' + updatedType : ''})`);
-                        const embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
-                        result.push({ ...entity, observations: mergedObs, embedding_status });
-                    }
-                }
+                result.push({ ...entity, observations: projected, created, observation_ids: ids });
             }
         }
         return result;
@@ -551,35 +672,144 @@ export class RAGKnowledgeGraphManager {
         const results = [];
         for (const obs of observations) {
             const entityId = `entity_${obs.entityName.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
-            // Get current observations
-            const entity = this.db.prepare(`
-        SELECT observations FROM entities WHERE id = ?
-      `).get(entityId);
-            if (!entity) {
+            const entity = this.db.prepare(`SELECT id FROM entities WHERE id = ?`).get(entityId);
+            if (!entity)
                 throw new Error(`Entity with name ${obs.entityName} not found`);
-            }
-            const currentObservations = JSON.parse(entity.observations);
-            const stripDate = (s) => s.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
-            const currentBare = new Set(currentObservations.map(stripDate));
-            const timestamped = obs.contents.map(c => this._timestampObservation(c));
-            const newObservations = timestamped.filter(c => !currentBare.has(stripDate(c)));
-            if (newObservations.length > 0) {
-                const updatedObservations = [...currentObservations, ...newObservations];
-                this.mutateEntityAndInvalidate(entityId, () => {
-                    this.db.prepare(`
-            UPDATE entities SET observations = ? WHERE id = ?
-          `).run(JSON.stringify(updatedObservations), entityId);
-                });
-                // Regenerate embedding for the updated entity (queued when not ready)
+            // dedup 기준은 v3.6 과 같다: 날짜 prefix 를 뗀 본문이 active 에 이미 있으면
+            // 새 revision 을 만들지 않는다. 다만 v13 에서는 같은 사실이 다른 출처에서 다시
+            // 온 것이므로 그 revision 에 source link 를 더한다(spec §8.3 T13).
+            const stripDate = (s2) => s2.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
+            const activeRows = this.db.prepare(`SELECT observation_id, content FROM entity_observations
+         WHERE entity_id = ? AND status = 'active'`).all(entityId);
+            const activeByBare = new Map(activeRows.map(r => [stripDate(r.content), r.observation_id]));
+            const ts = new Date().toISOString();
+            const ids = [];
+            const added = [];
+            let sourcesAdded = 0;
+            const changed = this.mutateEntityAndInvalidate(entityId, () => {
+                for (const raw of obs.contents) {
+                    const content = this._timestampObservation(raw);
+                    const bare = stripDate(content);
+                    const dupId = activeByBare.get(bare);
+                    if (dupId) {
+                        if (obs.sources?.length)
+                            sourcesAdded += linkSources(this.db, dupId, obs.sources, ts);
+                        ids.push(null);
+                        continue;
+                    }
+                    const id = addRevision(this.db, {
+                        entityId, content, status: obs.status ?? 'active', sources: obs.sources, ts
+                    });
+                    activeByBare.set(bare, id);
+                    ids.push(id);
+                    added.push(content);
+                }
+                // 아무것도 안 바뀌었으면 projection·벡터·KG 를 건드리지 않는다.
+                // 이 반환이 없으면 빈 contents 나 dedup-only add 가 정상 벡터를
+                // 지우고 재임베딩도 안 한다(advisor 구현리뷰 r1 발견 1).
+                return added.length > 0 || sourcesAdded > 0;
+            });
+            let embedding_status;
+            if (changed) {
                 console.error(`🔮 Regenerating embedding for updated entity: ${obs.entityName}`);
-                const embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
-                results.push({ entityName: obs.entityName, addedObservations: newObservations, embedding_status });
-                continue;
+                embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
             }
-            results.push({ entityName: obs.entityName, addedObservations: newObservations });
+            results.push({ entityName: obs.entityName, observation_ids: ids,
+                addedObservations: added, embedding_status });
         }
         return results;
     }
+    async correctObservation(observationId, content, changeKind = 'correction', reason) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const row = this.db.prepare(`SELECT entity_id FROM entity_observations WHERE observation_id = ?`)
+            .get(observationId);
+        if (!row)
+            throw new Error(`observation ${observationId} not found`);
+        let newId = '';
+        const ts = new Date().toISOString();
+        this.mutateEntityAndInvalidate(row.entity_id, () => {
+            newId = correctRevision(this.db, {
+                observationId, content: this._timestampObservation(content),
+                changeKind, reason: reason ?? null, ts
+            });
+        });
+        await this.tryEmbedEntity(row.entity_id, 'bulk');
+        return newId;
+    }
+    async _transition(observationId, event, reason) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const row = this.db.prepare(`SELECT entity_id FROM entity_observations WHERE observation_id = ?`)
+            .get(observationId);
+        if (!row)
+            throw new Error(`observation ${observationId} not found`);
+        const ts = new Date().toISOString();
+        this.mutateEntityAndInvalidate(row.entity_id, () => {
+            transitionStatus(this.db, { observationId, event, reason: reason ?? null, ts });
+        });
+        await this.tryEmbedEntity(row.entity_id, 'bulk');
+    }
+    async retractObservation(observationId, reason) {
+        return this._transition(observationId, 'retract', reason);
+    }
+    async restoreObservation(observationId, reason) {
+        return this._transition(observationId, 'restore', reason);
+    }
+    async approveObservation(observationId, reason) {
+        return this._transition(observationId, 'approve', reason);
+    }
+    async declineObservation(observationId, reason) {
+        return this._transition(observationId, 'decline', reason);
+    }
+    // DESTRUCTIVE. Physically removes revisions (and their sources via CASCADE).
+    //
+    // Chain contract (advisor 구현리뷰 r1 발견 4): a revision chain is
+    // rev1 <- rev2 <- ... and purging a middle revision would either fail on the
+    // supersedes_id FK or leave a chain pointing at a deleted row, plus events
+    // whose from_id/to_id dangle. So purge is defined as **suffix purge from the
+    // target to the newest revision of that root**, newest-first:
+    //   - purging the newest revision removes exactly it
+    //   - purging rev2 of a 3-revision chain removes rev3 then rev2
+    //   - purging rev1 removes the whole chain
+    // Events for purged revisions are removed too, so no event dangles.
+    // The root row is always kept: its projection_order stays reserved, because
+    // reusing an order would make a later restore/approve fail on the
+    // active-order index.
+    async purgeObservation(observationId, confirm) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        if (confirm !== 'PURGE') {
+            throw new Error(`purgeObservation refused: pass confirm='PURGE' to physically delete a revision. ` +
+                `This destroys history — retractObservation() is almost always what you want.`);
+        }
+        const row = this.db.prepare(`SELECT entity_id, root_id, revision_no FROM entity_observations WHERE observation_id = ?`)
+            .get(observationId);
+        if (!row)
+            return { purged: 0 };
+        let purged = 0;
+        this.mutateEntityAndInvalidate(row.entity_id, () => {
+            // newest-first so each DELETE has no successor referencing it
+            const victims = this.db.prepare(`SELECT observation_id FROM entity_observations
+         WHERE root_id = ? AND revision_no >= ?
+         ORDER BY revision_no DESC`).all(row.root_id, row.revision_no);
+            for (const v of victims) {
+                this.db.prepare(`DELETE FROM observation_events WHERE from_id = ? OR to_id = ?`)
+                    .run(v.observation_id, v.observation_id);
+                purged += this.db.prepare(`DELETE FROM entity_observations WHERE observation_id = ?`)
+                    .run(v.observation_id).changes;
+            }
+            return purged > 0;
+        });
+        await this.tryEmbedEntity(row.entity_id, 'bulk');
+        return { purged };
+    }
+    // spec §6.2: 과거 판본은 여기서만 나온다. 일반 검색은 active 만 반환한다.
+    async getObservationHistory(sel) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        return getObservationHistory(this.db, sel);
+    }
     async deleteEntities(entityNames) {
         if (!this.db)
             throw new Error('Database not initialized');
@@ -647,34 +877,85 @@ export class RAGKnowledgeGraphManager {
     // Pre-3.6 this method silently left STALE entity vectors behind (the input
     // text changed but the vector was never regenerated) — fixed via
     // tryEmbedEntity, which also covers the not-ready dirty contract.
+    // DEPRECATED shim (v13, one version only). Content-addressed deletion cannot
+    // express "which revision" — use retractObservation(observation_id) instead.
+    // Semantics: exact-string match against ACTIVE revisions -> soft retract.
+    //
+    // The whole call is one transaction and ambiguity is judged before any
+    // mutation: if any item matches 2+ active revisions the call aborts with 0
+    // mutations (spec §6.3). That is a deliberate change from v3.6, which deleted
+    // every duplicate and carried on — a machine cannot pick which revision was meant.
+    //
+    // Duplicate ids across items are collapsed. Without that, listing the same
+    // (entity, content) twice retracted it once and then failed on an illegal
+    // transition, returning an error *after* committing part of the batch
+    // (advisor 구현리뷰 r1 발견 3, 실행 재현). Embedding runs after the commit.
     async deleteObservations(deletions) {
         if (!this.db)
             throw new Error('Database not initialized');
+        const plan = [];
+        const ambiguous = [];
+        const claimed = new Set(); // 항목 간 중복 id 흡수
+        for (const d of deletions) {
+            const entityId = `entity_${d.entityName.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
+            const ids = [];
+            for (const content of d.observations) {
+                const rows = this.db.prepare(`SELECT observation_id FROM entity_observations
+           WHERE entity_id = ? AND status = 'active' AND content = ?`).all(entityId, content);
+                if (rows.length > 1) {
+                    ambiguous.push({ entityName: d.entityName, content, matches: rows.length });
+                    continue;
+                }
+                if (rows.length === 1 && !claimed.has(rows[0].observation_id)) {
+                    claimed.add(rows[0].observation_id);
+                    ids.push(rows[0].observation_id);
+                }
+                // rows.length === 0 -> no-op (v3.6 behaviour, spec §6.3-3)
+            }
+            plan.push({ entityName: d.entityName, entityId, ids });
+        }
+        if (ambiguous.length > 0) {
+            throw new Error(`AMBIGUOUS_OBSERVATION_MATCH: ${ambiguous.length} item(s) matched multiple active ` +
+                `revisions; 0 mutations were applied. Use retractObservation(observation_id) instead. ` +
+                `Conflicts: ${JSON.stringify(ambiguous)}`);
+        }
+        // pass 2 — mutate everything in ONE transaction so a failure anywhere
+        // leaves zero mutations. Per-plan transactions plus an awaited embedding
+        // in between made a partial commit observable.
+        const touched = plan.filter(p => p.ids.length > 0);
+        const ts = new Date().toISOString();
+        if (touched.length > 0) {
+            const tx = this.db.transaction(() => {
+                for (const p of touched) {
+                    for (const id of p.ids) {
+                        transitionStatus(this.db, { observationId: id, event: 'retract',
+                            reason: 'deleteObservations (deprecated shim)', ts });
+                    }
+                    rebuildProjection(this.db, p.entityId);
+                    const meta = this.db.prepare(`SELECT rowid FROM entity_embedding_metadata WHERE entity_id = ?`)
+                        .get(p.entityId);
+                    if (meta) {
+                        this.db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${Number(meta.rowid)}`);
+                        this.db.prepare(`DELETE FROM entity_embedding_metadata WHERE entity_id = ?`)
+                            .run(p.entityId);
+                    }
+                    deleteStaleKgChunks(this.db, p.entityId);
+                }
+            });
+            tx();
+            this.coordinator?.invalidateCoverage();
+        }
+        // pass 3 — embedding after the commit
         const results = [];
         let total = 0;
-        for (const deletion of deletions) {
-            const entityId = `entity_${deletion.entityName.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
-            const entity = this.db.prepare(`
-        SELECT observations FROM entities WHERE id = ?
-      `).get(entityId);
-            if (!entity) {
-                results.push({ entityName: deletion.entityName, deleted: 0, embedding_status: 'n/a' });
-                continue;
-            }
-            const currentObservations = JSON.parse(entity.observations);
-            const filteredObservations = currentObservations.filter((obs) => !deletion.observations.includes(obs));
-            const deleted = currentObservations.length - filteredObservations.length;
-            if (deleted === 0) {
-                results.push({ entityName: deletion.entityName, deleted: 0, embedding_status: 'n/a' });
+        for (const p of plan) {
+            if (p.ids.length === 0) {
+                results.push({ entityName: p.entityName, deleted: 0, embedding_status: 'n/a' });
                 continue;
             }
-            this.mutateEntityAndInvalidate(entityId, () => {
-                this.db.prepare(`UPDATE entities SET observations = ? WHERE id = ?`)
-                    .run(JSON.stringify(filteredObservations), entityId);
-            });
-            const embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
-            total += deleted;
-            results.push({ entityName: deletion.entityName, deleted, embedding_status });
+            const embedding_status = await this.tryEmbedEntity(p.entityId, 'bulk');
+            results.push({ entityName: p.entityName, deleted: p.ids.length, embedding_status });
+            total += p.ids.length;
         }
         return { results, total_deleted: total };
     }
@@ -1597,21 +1878,32 @@ export class RAGKnowledgeGraphManager {
     // CJK), so the function maintains parallel UTF-16 and codepoint cursors and
     // reports codepoint offsets. On a coincidental indexOf miss the char offsets
     // are NULL.
-    chunkText(text, maxTokens = 800, overlap = 160) {
+    chunkStructured(text, maxTokens = DEFAULT_MAX_TOKENS) {
         if (!this.encoding)
             throw new Error('Tokenizer not initialized');
-        const segments = splitTextIntoChunks(text, this.encoding, maxTokens, overlap);
-        return segments.map((seg, idx) => ({
+        return chunkStructuredText(text, this.encoding, maxTokens).map((seg, idx) => ({
             id: '',
             document_id: '',
             chunk_index: idx,
             text: seg.text,
             start_pos: seg.start_pos,
             end_pos: seg.end_pos,
-            start_token: seg.start_token,
-            end_token: seg.end_token
+            // c1 has no token-space offsets (spec §4.3, r4 D4). Legacy rows keep theirs.
+            start_token: null,
+            end_token: null
         }));
     }
+    // spec §7.1 (r4·r5-8): overlap is rejected on BOTH public paths, BEFORE any
+    // content/dedup judgment — silently accepting it on unchanged content would
+    // void the contract. maxTokens must be a positive integer.
+    validateChunkParams(params) {
+        const { maxTokens = DEFAULT_MAX_TOKENS, overlap = 0 } = params || {};
+        if (!Number.isInteger(maxTokens) || maxTokens <= 0)
+            throw new Error(`chunkParams.maxTokens must be a positive integer (got ${maxTokens})`);
+        if (overlap !== 0)
+            throw new Error(`chunkParams.overlap is no longer supported (chunker c1 has no overlap); omit it or pass 0 (got ${overlap})`);
+        return { maxTokens };
+    }
     // Generate embeddings using sentence transformers
     // isQuery: true for search queries (adds instruction prefix), false for documents/entities
     async generateEmbedding(text, dimensions = 1024, isQuery = false, priority = 'interactive') {
@@ -1636,31 +1928,32 @@ export class RAGKnowledgeGraphManager {
     async syncDocumentFromFile(filePath, documentId, options = {}) {
         if (!this.db)
             throw new Error('Database not initialized');
-        // 1. Resolve content: raw file verbatim (default) or explicit override.
-        //    Content is read on the server and never routed through the model context.
-        const content = options.content !== undefined
-            ? options.content
-            : fsSync.readFileSync(filePath, 'utf-8');
-        const bytes = Buffer.byteLength(content, 'utf-8');
-        // 2. Metadata: default source=path, updated=today, content_hash; caller can override.
-        const today = new Date().toISOString().slice(0, 10);
-        const contentHash = createHash('sha256').update(content).digest('hex');
-        const metadata = { source: filePath, updated: today, content_hash: contentHash, ...(options.metadata || {}) };
-        // 2b. Dedup gate: skip the full delete/store/chunk/embed pipeline when the
-        //     file is unchanged AND the existing document is fully embedded. The
-        //     completeness check avoids wrongly skipping a partial/failed prior sync.
-        const existingDoc = this.db.prepare(`SELECT metadata FROM documents WHERE id = ?`).get(documentId);
-        if (existingDoc) {
+        // spec §7.1 + r5-8: 검증은 content 해석·dedup 판정보다 앞 (첫 실행문).
+        const { maxTokens } = this.validateChunkParams(options.chunkParams);
+        const signature = effectiveSignature(maxTokens);
+        const shaHex = (t) => createHash('sha256').update(t).digest('hex');
+        const zero = { reusedChunks: 0, newlyEmbeddedChunks: 0, queuedChunks: 0, deletedChunks: 0, chunkerTransitioned: false };
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            // r6-3: CAS 재시작 = 처음부터 — 파일 읽기·hash·metadata 도 attempt 안에서 재계산한다.
+            const content = options.content !== undefined ? options.content : fsSync.readFileSync(filePath, 'utf-8');
+            const bytes = Buffer.byteLength(content, 'utf-8');
+            const today = new Date().toISOString().slice(0, 10);
+            const contentHash = shaHex(content);
+            // spec §5.1: content_hash 는 system-owned — user metadata 뒤에 쓴다 (r1: spread 가 덮어쓸 수 있었다).
+            const metadata = { source: filePath, updated: today, ...(options.metadata || {}), content_hash: contentHash };
+            const snap = this.db.prepare(`SELECT content, metadata, chunking_signature FROM documents WHERE id = ?`)
+                .get(documentId);
             let existingHash;
-            try {
-                existingHash = JSON.parse(existingDoc.metadata)?.content_hash;
+            if (snap) {
+                try {
+                    existingHash = JSON.parse(snap.metadata)?.content_hash;
+                }
+                catch { /* hash 없으면 full 경로 */ }
             }
-            catch { /* ignore */ }
-            if (existingHash === contentHash) {
+            // dedup gate — spec §5.1 그대로: "content_hash 동일" 만 (r6-8: content=== 확장 금지.
+            // hash 가 없거나 낡은 문서는 full 경로로 가서 hash 가 복구된다). signature 무관.
+            if (snap && existingHash === contentHash) {
                 const cmCount = this.db.prepare(`SELECT count(*) AS n FROM chunk_metadata WHERE document_id = ?`).get(documentId).n;
-                // "Embedded" for dedup completeness = vector exists AND its profile is
-                // current (or legacy-NULL awaiting grandfather). Raw vector counts
-                // would misjudge old-profile rows as complete (beta 1R supplement).
                 const embCount = this.db.prepare(`
           SELECT count(*) AS n FROM chunks c JOIN chunk_metadata m ON c.rowid = m.rowid
           WHERE m.document_id = ? AND (m.provenance_state IS NULL OR m.profile_id = ?)
@@ -1671,100 +1964,141 @@ export class RAGKnowledgeGraphManager {
         `).get(documentId).n;
                 if (cmCount > 0 && cmCount === embCount) {
                     console.error(`⏭️  syncDocumentFromFile: ${documentId} unchanged (hash match, ${cmCount} chunks embedded) — skipped`);
-                    return { documentId, bytes, chunks: cmCount, embeddedChunks: embCount, linkedEntities: linked, skipped: true, reason: 'unchanged' };
+                    return { documentId, bytes, chunks: cmCount, embeddedChunks: embCount, linkedEntities: linked,
+                        skipped: true, reason: 'unchanged', ...zero };
                 }
                 if (cmCount > 0 && embCount < cmCount) {
-                    // v3.6 (spec §5b M12): identical content with incomplete/stale vectors
-                    // keeps the document, chunks, rowids and entity links — only the
-                    // missing vectors are re-queued via the coordinator. Full re-chunking
-                    // here would churn rowids and links for no content change.
+                    // v3.6 (spec §5b M12): identical content with incomplete/stale vectors keeps the
+                    // document, chunks, rowids and entity links — only missing vectors are re-queued.
                     console.error(`♻️ syncDocumentFromFile: ${documentId} unchanged but ${cmCount - embCount} vectors missing — re-queued (chunks preserved)`);
                     this.coordinator?.kick();
-                    return { documentId, bytes, chunks: cmCount, embeddedChunks: embCount, linkedEntities: linked, skipped: true, reason: 'unchanged-revectorizing', embedding_status: this.gate.isDisabled ? 'disabled' : 'queued' };
+                    return { documentId, bytes, chunks: cmCount, embeddedChunks: embCount, linkedEntities: linked,
+                        skipped: true, reason: 'unchanged-revectorizing',
+                        embedding_status: this.gate.isDisabled ? 'disabled' : 'queued',
+                        ...zero, queuedChunks: cmCount - embCount };
                 }
+                // cmCount === 0 이면 아래 full 경로로 계속 (최초 생성).
+            }
+            console.error(`🔄 syncDocumentFromFile: ${documentId} <- ${filePath} (${bytes} bytes)`);
+            const segments = this.chunkStructured(content, maxTokens);
+            // spec §5.2-2: 옛 행을 트랜잭션 밖에서 읽는다 (벡터 재사용 후보).
+            const oldRows = this.db.prepare(`
+        SELECT m.rowid, m.text, m.input_hash, m.profile_id, m.provenance_state, c.embedding
+        FROM chunk_metadata m LEFT JOIN chunks c ON c.rowid = m.rowid
+        WHERE m.document_id = ?`).all(documentId);
+            const oldRowids = oldRows.map(r => r.rowid);
+            const byHash = new Map();
+            for (const r of oldRows) {
+                if (!r.input_hash)
+                    continue;
+                const arr = byHash.get(r.input_hash);
+                if (arr)
+                    arr.push(r);
+                else
+                    byHash.set(r.input_hash, [r]);
+            }
+            // 임베딩/재사용 — 트랜잭션 밖, ready 경로 한정 (N2: not-ready 계약 불변).
+            const lazySync = !this.gate.isReady;
+            const slots = [];
+            let reusedChunks = 0, newlyEmbeddedChunks = 0;
+            if (lazySync) {
+                for (const seg of segments)
+                    slots.push({ seg, vec: null, provenance: null });
             }
-        }
-        console.error(`🔄 syncDocumentFromFile: ${documentId} <- ${filePath} (${bytes} bytes)`);
-        // 3. Two contracts (spec §5b):
-        //    ready       — pre-compute ALL embeddings BEFORE any DB mutation; if
-        //                  inference throws mid-way the old document stays intact
-        //                  (v3.5.0 atomicity, unchanged).
-        //    not-ready   — intentional lazy sync: store document + chunks + FTS in
-        //                  one transaction with NO vectors (embedding_status:
-        //                  queued); the backfill coordinator recovers them.
-        const { maxTokens = 800, overlap = 160 } = options.chunkParams || {};
-        const segments = this.chunkText(content, maxTokens, overlap);
-        const lazySync = !this.gate.isReady;
-        const embedded = [];
-        if (lazySync) {
-            for (const seg of segments)
-                embedded.push({ seg, embedding: null });
-        }
-        else {
-            for (const seg of segments) {
-                const embedding = await this.generateEmbedding(seg.text, 1024, false, 'bulk');
-                embedded.push({ seg, embedding });
-            }
-        }
-        // 4. Atomic swap: delete old -> insert doc -> insert chunks (+ embeddings
-        //    with verified provenance when ready), one synchronous transaction.
-        const applyTx = this.db.transaction(() => {
-            const db = this.db;
-            // 4a. cleanup old doc (inlined sync version of cleanupDocument).
-            const existing = db.prepare(`SELECT rowid FROM chunk_metadata WHERE document_id = ?`).all(documentId);
-            for (const ch of existing) {
-                db.prepare(`DELETE FROM chunk_entities WHERE chunk_rowid = ?`).run(ch.rowid);
-                db.exec(`DELETE FROM chunks WHERE rowid = ${safeRowid(ch.rowid)}`);
-            }
-            db.prepare(`DELETE FROM chunk_metadata WHERE document_id = ?`).run(documentId);
-            db.prepare(`DELETE FROM documents WHERE id = ?`).run(documentId);
-            // 4b. insert document.
-            db.prepare(`INSERT INTO documents (id, content, metadata) VALUES (?, ?, ?)`)
-                .run(documentId, content, JSON.stringify(metadata));
-            // 4c. insert chunk_metadata (FTS5 chunks_fts auto-filled by trigger);
-            //     vectors + provenance only on the ready path (§6a-2).
-            for (const { seg, embedding } of embedded) {
-                const chunkId = `${documentId}_chunk_${seg.chunk_index}`;
-                const info = db.prepare(`
-          INSERT INTO chunk_metadata (chunk_id, document_id, chunk_index, text, start_pos, end_pos, start_token, end_token)
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-        `).run(chunkId, documentId, seg.chunk_index, seg.text, seg.start_pos, seg.end_pos, seg.start_token, seg.end_token);
-                const rowid = Number(info.lastInsertRowid);
-                if (embedding) {
-                    db.prepare(`INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)`).run(Buffer.from(embedding.buffer));
-                    db.prepare(`UPDATE chunk_metadata SET input_hash = ?, profile_id = ?, provenance_state = 'verified' WHERE rowid = ?`)
-                        .run(createHash('sha256').update(seg.text).digest('hex'), this.currentProfileId, rowid);
+            else {
+                for (const seg of segments) {
+                    const hit = selectReusableVector(byHash.get(shaHex(seg.text)) ?? [], seg.text, this.currentProfileId, shaHex);
+                    if (hit) {
+                        slots.push({ seg, vec: hit.vec, provenance: hit.provenance });
+                        reusedChunks++;
+                    }
+                    else {
+                        const embedding = await this.generateEmbedding(seg.text, 1024, false, 'bulk');
+                        slots.push({ seg, vec: Buffer.from(embedding.buffer), provenance: 'verified' });
+                        newlyEmbeddedChunks++;
+                    }
                 }
             }
-        });
-        applyTx();
-        this.coordinator?.invalidateCoverage();
-        if (lazySync)
-            this.coordinator?.kick();
-        const embeddedChunks = lazySync ? 0 : embedded.length;
-        // 5. Entity linking AFTER commit. Non-destructive + idempotent (INSERT OR
-        //    IGNORE), so a linking failure cannot corrupt the doc/embeddings.
-        const linkedEntities = await this.autoLinkEntities(documentId);
-        let explicitlyLinked;
-        if (options.entityNames && options.entityNames.length > 0) {
-            const linkResult = await this.linkEntitiesToDocument(documentId, options.entityNames);
-            explicitlyLinked = linkResult.linkedEntities;
-        }
-        // 6. Terse summary only (no chunk text / content echo) to keep caller context flat.
-        const result = {
-            documentId,
-            bytes,
-            chunks: segments.length,
-            embeddedChunks,
-            linkedEntities,
-            embedding_status: lazySync ? (this.gate.isDisabled ? 'disabled' : 'queued') : 'embedded',
-            ...(explicitlyLinked !== undefined ? { explicitlyLinked } : {}),
-        };
-        if (linkedEntities === 0 && explicitlyLinked === undefined) {
-            result.warning = 'linkedEntities=0: ensure the file content contains entity-name literals (e.g. a wiki anchor line "RAG entity: ...") so term-matching can link entities.';
+            __syncFaultHook?.('pre-transaction');
+            // 한 트랜잭션: CAS 첫 문장 -> full delete/insert -> failure 정리 (spec §5.2-4·5).
+            const applyTx = this.db.transaction(() => {
+                const db = this.db;
+                const now = db.prepare(`SELECT content, metadata, chunking_signature FROM documents WHERE id = ?`)
+                    .get(documentId);
+                const same = (snap === undefined && now === undefined) ||
+                    (snap !== undefined && now !== undefined && now.content === snap.content &&
+                        now.metadata === snap.metadata && now.chunking_signature === snap.chunking_signature);
+                if (!same)
+                    throw new SyncCasConflictError(documentId);
+                const existing = db.prepare(`SELECT rowid FROM chunk_metadata WHERE document_id = ?`).all(documentId);
+                for (const ch of existing) {
+                    db.prepare(`DELETE FROM chunk_entities WHERE chunk_rowid = ?`).run(ch.rowid);
+                    db.exec(`DELETE FROM chunks WHERE rowid = ${safeRowid(ch.rowid)}`);
+                }
+                db.prepare(`DELETE FROM chunk_metadata WHERE document_id = ?`).run(documentId);
+                db.prepare(`DELETE FROM documents WHERE id = ?`).run(documentId);
+                db.prepare(`INSERT INTO documents (id, content, metadata, chunking_signature) VALUES (?, ?, ?, ?)`)
+                    .run(documentId, content, JSON.stringify(metadata), signature);
+                for (const { seg, vec, provenance } of slots) {
+                    const chunkId = `${documentId}_chunk_${seg.chunk_index}`;
+                    const info = db.prepare(`
+            INSERT INTO chunk_metadata (chunk_id, document_id, chunk_index, text, start_pos, end_pos, start_token, end_token)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          `).run(chunkId, documentId, seg.chunk_index, seg.text, seg.start_pos, seg.end_pos, seg.start_token, seg.end_token);
+                    const rowid = Number(info.lastInsertRowid);
+                    if (vec) {
+                        db.prepare(`INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)`).run(vec);
+                        db.prepare(`UPDATE chunk_metadata SET input_hash = ?, profile_id = ?, provenance_state = ? WHERE rowid = ?`)
+                            .run(shaHex(seg.text), this.currentProfileId, provenance, rowid);
+                    }
+                }
+                if (oldRowids.length > 0) {
+                    // r5-9: 키는 (kind, target_id) — kind 조건 없이 지우면 같은 숫자 ID 의 entity failure 까지 지운다.
+                    const ph = oldRowids.map(() => '?').join(',');
+                    db.prepare(`DELETE FROM embedding_backfill_failures WHERE kind = 'chunk' AND target_id IN (${ph})`)
+                        .run(...oldRowids.map(String));
+                }
+            });
+            try {
+                applyTx();
+            }
+            catch (e) {
+                if (e instanceof SyncCasConflictError) {
+                    console.error(`↻ sync CAS conflict on ${documentId} (attempt ${attempt}/3) — restarting from file read`);
+                    if (attempt === 3)
+                        throw e;
+                    continue;
+                }
+                throw e;
+            }
+            this.coordinator?.invalidateCoverage();
+            if (lazySync)
+                this.coordinator?.kick();
+            // Entity linking AFTER commit. Non-destructive + idempotent (INSERT OR IGNORE).
+            const linkedEntities = await this.autoLinkEntities(documentId);
+            let explicitlyLinked;
+            if (options.entityNames && options.entityNames.length > 0) {
+                const linkResult = await this.linkEntitiesToDocument(documentId, options.entityNames);
+                explicitlyLinked = linkResult.linkedEntities;
+            }
+            const result = {
+                documentId, bytes, chunks: segments.length,
+                embeddedChunks: reusedChunks + newlyEmbeddedChunks, // spec §5.3
+                linkedEntities,
+                embedding_status: lazySync ? (this.gate.isDisabled ? 'disabled' : 'queued') : 'embedded',
+                reusedChunks, newlyEmbeddedChunks,
+                queuedChunks: lazySync ? segments.length : 0,
+                deletedChunks: oldRowids.length,
+                chunkerTransitioned: snap !== undefined && snap.chunking_signature !== signature,
+                ...(explicitlyLinked !== undefined ? { explicitlyLinked } : {}),
+            };
+            if (linkedEntities === 0 && explicitlyLinked === undefined) {
+                result.warning = 'linkedEntities=0: ensure the file content contains entity-name literals (e.g. a wiki anchor line "RAG entity: ...") so term-matching can link entities.';
+            }
+            console.error(`✅ syncDocumentFromFile done: ${documentId} (${result.chunks} chunks, reused ${reusedChunks}, embedded ${newlyEmbeddedChunks})`);
+            return result;
         }
-        console.error(`✅ syncDocumentFromFile done: ${documentId} (${result.chunks} chunks, ${result.embeddedChunks} embedded, ${linkedEntities} linked)`);
-        return result;
+        throw new Error('unreachable');
     }
     async storeDocument(id, content, metadata = {}) {
         if (!this.db)
@@ -1790,12 +2124,12 @@ export class RAGKnowledgeGraphManager {
         if (!document) {
             throw new Error(`Document with ID ${documentId} not found`);
         }
-        const { maxTokens = 800, overlap = 160 } = options;
-        console.error(`🔪 Chunking document: ${documentId} (maxTokens: ${maxTokens}, overlap: ${overlap})`);
+        const { maxTokens } = this.validateChunkParams(options);
+        console.error(`🔪 Chunking document: ${documentId} (maxTokens: ${maxTokens}, chunker: c1)`);
         // Clean up existing chunks
         await this.cleanupDocument(documentId);
         // Create chunks
-        const chunks = this.chunkText(document.content, maxTokens, overlap);
+        const chunks = this.chunkStructured(document.content, maxTokens);
         const resultChunks = [];
         for (const chunk of chunks) {
             const chunkId = `${documentId}_chunk_${chunk.chunk_index}`;
@@ -1815,6 +2149,9 @@ export class RAGKnowledgeGraphManager {
             });
         }
         console.error(`✅ Document chunked: ${chunks.length} chunks created`);
+        // spec §7.1: 두 번째 chunk 생성 경로 — 스탬프를 안 박으면 §5.1 관측이 조용히 샌다.
+        this.db.prepare(`UPDATE documents SET chunking_signature = ? WHERE id = ?`)
+            .run(effectiveSignature(maxTokens), documentId);
         // Indirect missing-row producer (spec §5): freshly chunked rows have no
         // vectors yet — let the coordinator recover them without a restart.
         this.coordinator?.invalidateCoverage();
@@ -1867,6 +2204,73 @@ export class RAGKnowledgeGraphManager {
     hasCJK(text) {
         return /[\u3000-\u9fff\uac00-\ud7af\uff00-\uffef]/.test(text);
     }
+    // spec §5.4 (r7-2·r8-1·r9): primary name 의 본문 occurrence range [sCp, eCp).
+    // 의미 = buildEntityMatcher 와 동일 (CJK substring / Latin word-boundary) — 여기서
+    // 어긋나면 'Data' 가 'Database' 에 새로 링크되는 식으로 의미가 확장된다.
+    buildEntityRangeFinder(content) {
+        // 원문 UTF-16 -> codepoint 표. Latin 경로는 folded 가 아니라 **원문**에 regex 를 건다
+        // (r9-1: folded 에 걸면 fooİ -> fooi̇ 로 접힌 뒤 매치돼 현행 matcher 의미가 확장된다).
+        const origU16ToCp = [];
+        let origTotalCp = 0;
+        for (let u = 0; u < content.length;) {
+            const c = content.codePointAt(u);
+            origU16ToCp.push(origTotalCp);
+            if (c > 0xffff) {
+                origU16ToCp.push(origTotalCp);
+                u += 2;
+            }
+            else
+                u += 1;
+            origTotalCp++;
+        }
+        const origCpAt = (u16) => (u16 < origU16ToCp.length ? origU16ToCp[u16] : origTotalCp);
+        // folded 표 (CJK substring / fallback 경로 전용). unit -> 유래한 원문 cp.
+        let folded = '';
+        const u16ToCp = [];
+        let cp = 0;
+        for (const ch of content) { // for..of = codepoint 순회
+            const f = ch.toLowerCase(); // 다단위 fold 가능 (İ -> 'i̇')
+            for (let i = 0; i < f.length; i++)
+                u16ToCp.push(cp);
+            folded += f;
+            cp++;
+        }
+        // r9-1: exclusive end = "마지막으로 소비한 unit 의 원문 cp + 1".
+        // 경계 unit 을 읽으면 매치가 fold 전개 중간에서 끝날 때 1 모자란다 (漢İ/漢i 실측 [0,1)).
+        const endCp = (u16) => (u16 === 0 ? 0 : u16ToCp[Math.min(u16, u16ToCp.length) - 1] + 1);
+        return (name, isCjk) => {
+            const out = [];
+            const lower = name.toLowerCase();
+            const pushAllSubstr = () => {
+                let from = 0;
+                while (true) {
+                    const u = folded.indexOf(lower, from);
+                    if (u < 0)
+                        break;
+                    out.push({ s: u16ToCp[u], e: endCp(u + lower.length) });
+                    from = u + 1; // r9-2: 중첩 occurrence 보존
+                }
+            };
+            if (isCjk) {
+                pushAllSubstr();
+                return out;
+            }
+            try {
+                const escaped = lower.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const re = new RegExp(`\\b${escaped}\\b`, 'gi'); // buildEntityMatcher 와 동일 규칙,
+                let m; // 단 원문에 실행 (의미 확장 방지)
+                while ((m = re.exec(content)) !== null) {
+                    out.push({ s: origCpAt(m.index), e: origCpAt(m.index + m[0].length) });
+                    if (re.lastIndex === m.index)
+                        re.lastIndex++;
+                }
+            }
+            catch {
+                pushAllSubstr();
+            } // matcher 의 fallback 과 동일
+            return out;
+        };
+    }
     // Build a match pattern for an entity name — word-boundary for Latin, substring for CJK
     buildEntityMatcher(name) {
         const lower = name.toLowerCase();
@@ -1890,9 +2294,12 @@ export class RAGKnowledgeGraphManager {
             return 0;
         try {
             // Get all chunk text for this document
-            const chunks = this.db.prepare(`SELECT rowid, text FROM chunk_metadata WHERE document_id = ?`).all(documentId);
+            const chunks = this.db.prepare(`SELECT rowid, text, start_pos, end_pos FROM chunk_metadata WHERE document_id = ?`).all(documentId);
             if (chunks.length === 0)
                 return 0;
+            // spec §5.4: range 링킹용 — 문서 본문과 finder 를 1회 준비
+            const docRow = this.db.prepare(`SELECT content FROM documents WHERE id = ?`).get(documentId);
+            const findRanges = docRow ? this.buildEntityRangeFinder(docRow.content) : null;
             // Get all entities with observations for richer matching
             const entities = this.db.prepare(`SELECT id, name, entityType, observations FROM entities`).all();
             // Minimum name length: 2 for CJK (e.g. "할랄"), 4 for Latin (avoid "API", "Bug")
@@ -1938,6 +2345,19 @@ export class RAGKnowledgeGraphManager {
                         entityLinked = true;
                     }
                 }
+                // spec §5.4 (r7-2): chunk 단위 매칭은 경계에 잘린 이름을 영원히 놓친다 — c1 은
+                // overlap 이 없어 흡수도 안 된다. primary name 의 본문 occurrence range 와
+                // 교차하는 chunk 에 링크한다 (aliases 는 predicate 라 chunk 단위 유지).
+                if (findRanges) {
+                    for (const { s, e } of findRanges(entity.name, this.hasCJK(entity.name))) {
+                        for (const chunk of chunks) {
+                            if (chunk.start_pos !== null && chunk.end_pos !== null && chunk.start_pos < e && chunk.end_pos > s) {
+                                insertStmt.run(chunk.rowid, entity.id); // INSERT OR IGNORE — 중복 무해
+                                entityLinked = true;
+                            }
+                        }
+                    }
+                }
                 if (entityLinked)
                     linkedCount++;
             }
@@ -2192,10 +2612,20 @@ export class RAGKnowledgeGraphManager {
             created_at: row.created_at
         }));
         console.error(`✅ Export completed: ${entities.length} entities, ${relations.length} relations, ${documents.length} documents`);
+        // spec §6.4: lifecycle 정본을 함께 내보낸다. 이게 없으면 export->import 뒤
+        // 관찰의 신원·출처·이력이 사라지고 projection 만 남는다.
+        const observation_roots = this.db.prepare(`SELECT * FROM observation_roots ORDER BY entity_id, projection_order`).all();
+        const entity_observations = this.db.prepare(`SELECT * FROM entity_observations ORDER BY root_id, revision_no`).all();
+        const observation_sources = this.db.prepare(`SELECT * FROM observation_sources ORDER BY observation_id, source_kind, source_ref`).all();
+        const observation_events = this.db.prepare(`SELECT * FROM observation_events ORDER BY root_id, recorded_at, event_id`).all();
         return {
             entities,
             relations,
             documents,
+            observation_roots,
+            entity_observations,
+            observation_sources,
+            observation_events,
             metadata: {
                 exportedAt: new Date().toISOString(),
                 version: PKG_VERSION,
@@ -2211,66 +2641,245 @@ export class RAGKnowledgeGraphManager {
         console.error(`📥 Importing knowledge graph (merge: ${options.merge !== false})...`);
         const imported = { entities: 0, relations: 0, documents: 0 };
         const skipped = { entities: 0, relations: 0, documents: 0 };
-        // If merge=false, clear existing data first
-        if (options.merge === false) {
-            this.db.exec(`DELETE FROM relationships`);
-            this.db.exec(`DELETE FROM entities`);
-            this.db.exec(`DELETE FROM documents`);
-            console.error('🗑️ Cleared existing data for full import');
-        }
-        // Import entities using INSERT OR IGNORE
-        if (data.entities && Array.isArray(data.entities)) {
-            const stmt = this.db.prepare(`
+        // merge 로 배열 위치가 재배정된 관찰. 조용히 순서를 바꾸면 호출자가 알 수 없으므로
+        // 응답으로 내보낸다(advisor beta r3 발견 3).
+        const remapReport = [];
+        // spec §6.4: abort 는 0 mutation 이다. lifecycle 만 트랜잭션으로 감싸면
+        // 충돌로 throw 할 때 그 앞에서 넣은 entity·relation·document 가 살아남는다
+        // (T17b 가 ghost entity 로 실증). import 전체가 한 단위여야 한다.
+        // 내부 transaction() 호출은 better-sqlite3 에서 savepoint 로 중첩된다.
+        const importAll = this.db.transaction(() => {
+            // If merge=false, clear existing data first
+            if (options.merge === false) {
+                this.db.exec(`DELETE FROM relationships`);
+                // entities 삭제가 FK CASCADE 로 lifecycle 4테이블을 지우지만, 순서를 계약으로
+                // 두어 FK 가 꺼진 환경에서도 잔존 행이 남지 않게 한다.
+                this.db.exec(`DELETE FROM observation_events`);
+                this.db.exec(`DELETE FROM observation_sources`);
+                this.db.exec(`DELETE FROM entity_observations`);
+                this.db.exec(`DELETE FROM observation_roots`);
+                this.db.exec(`DELETE FROM entities`);
+                this.db.exec(`DELETE FROM documents`);
+                // entities 를 지워도 파생 데이터는 따라오지 않는다: chunk_metadata 에는
+                // entities 로 가는 FK 가 없고 entity_embedding_metadata.entity_id 는 UNIQUE 일
+                // 뿐이다. 그래서 replace-import 뒤에 **사라진 entity 의 벡터와 KG chunk 가
+                // 검색에 남았다**(advisor beta 발견 2). document chunk 는 documents 의
+                // CASCADE 로 이미 정리되므로 여기서는 entity·relationship chunk 만 지운다.
+                const orphanChunks = this.db.prepare(`SELECT rowid FROM chunk_metadata WHERE chunk_type IN ('entity','relationship')`)
+                    .all();
+                for (const c of orphanChunks) {
+                    this.db.exec(`DELETE FROM chunks WHERE rowid = ${Number(c.rowid)}`);
+                    this.db.prepare(`DELETE FROM chunk_metadata WHERE rowid = ?`).run(c.rowid);
+                }
+                this.db.exec(`DELETE FROM entity_embeddings WHERE rowid IN (SELECT rowid FROM entity_embedding_metadata)`);
+                this.db.exec(`DELETE FROM entity_embedding_metadata`);
+                console.error('🗑️ Cleared existing data for full import');
+            }
+            // Import entities using INSERT OR IGNORE
+            if (data.entities && Array.isArray(data.entities)) {
+                const stmt = this.db.prepare(`
         INSERT OR IGNORE INTO entities (id, name, entityType, observations, metadata, created_at)
         VALUES (?, ?, ?, ?, ?, ?)
       `);
-            for (const entity of data.entities) {
-                const result = stmt.run(entity.id, entity.name, entity.entityType || 'CONCEPT', JSON.stringify(entity.observations || []), JSON.stringify(entity.metadata || {}), entity.created_at || new Date().toISOString());
-                if (result.changes > 0) {
-                    imported.entities++;
-                }
-                else {
-                    skipped.entities++;
+                for (const entity of data.entities) {
+                    const result = stmt.run(entity.id, entity.name, entity.entityType || 'CONCEPT', 
+                    // v13: observations 는 projection 이다. lifecycle 행을 넣은 뒤
+                    // rebuildProjection 이 채운다 — 여기서 배열을 심으면 정본과 갈라진다.
+                    '[]', JSON.stringify(entity.metadata || {}), entity.created_at || new Date().toISOString());
+                    if (result.changes > 0) {
+                        imported.entities++;
+                    }
+                    else {
+                        skipped.entities++;
+                    }
                 }
             }
-        }
-        // Import relations using INSERT OR IGNORE
-        if (data.relations && Array.isArray(data.relations)) {
-            const stmt = this.db.prepare(`
+            // Import relations using INSERT OR IGNORE
+            if (data.relations && Array.isArray(data.relations)) {
+                const stmt = this.db.prepare(`
         INSERT OR IGNORE INTO relationships (id, source_entity, target_entity, relationType, confidence, metadata, created_at)
         VALUES (?, ?, ?, ?, ?, ?, ?)
       `);
-            for (const relation of data.relations) {
-                const result = stmt.run(relation.id, relation.source_entity, relation.target_entity, relation.relationType, relation.confidence ?? 1.0, JSON.stringify(relation.metadata || {}), relation.created_at || new Date().toISOString());
-                if (result.changes > 0) {
-                    imported.relations++;
-                }
-                else {
-                    skipped.relations++;
+                for (const relation of data.relations) {
+                    const result = stmt.run(relation.id, relation.source_entity, relation.target_entity, relation.relationType, relation.confidence ?? 1.0, JSON.stringify(relation.metadata || {}), relation.created_at || new Date().toISOString());
+                    if (result.changes > 0) {
+                        imported.relations++;
+                    }
+                    else {
+                        skipped.relations++;
+                    }
                 }
             }
-        }
-        // Import documents using INSERT OR REPLACE
-        if (data.documents && Array.isArray(data.documents)) {
-            const stmt = this.db.prepare(`
+            // Import documents using INSERT OR REPLACE
+            if (data.documents && Array.isArray(data.documents)) {
+                const stmt = this.db.prepare(`
         INSERT OR REPLACE INTO documents (id, content, metadata, created_at)
         VALUES (?, ?, ?, ?)
       `);
-            for (const doc of data.documents) {
-                const result = stmt.run(doc.id, doc.content, JSON.stringify(doc.metadata || {}), doc.created_at || new Date().toISOString());
-                if (result.changes > 0) {
-                    imported.documents++;
-                }
-                else {
-                    skipped.documents++;
+                for (const doc of data.documents) {
+                    const result = stmt.run(doc.id, doc.content, JSON.stringify(doc.metadata || {}), doc.created_at || new Date().toISOString());
+                    if (result.changes > 0) {
+                        imported.documents++;
+                    }
+                    else {
+                        skipped.documents++;
+                    }
                 }
             }
-        }
+            // ---- spec §6.4: lifecycle import ----
+            // 순서가 계약이다: entities -> roots -> revisions(root별 revision_no ↑)
+            // -> sources/events. §4.1 트리거가 root 선행과 체인 연속성을 요구하므로
+            // importer 는 입력 순서와 무관하게 재정렬한다 (역순 export 를 그대로
+            // 스트리밍하면 'immediately preceding revision' 으로 죽는다).
+            const sameRow = (a, b, cols) => cols.every(c => (a[c] ?? null) === (b[c] ?? null));
+            const hasLifecycle = Array.isArray(data.observation_roots);
+            if (hasLifecycle) {
+                const tx = this.db.transaction(() => {
+                    // 새 root 가 이미 점유된 (entity_id, projection_order) 슬롯을 요구할 수 있다:
+                    // 두 DB 가 같은 entity 이름을 갖고 서로 다른 관찰을 배열 0번에 두면 그렇다.
+                    // 이건 §6.4 의 "같은 키 다른 값" 충돌이 아니라 **슬롯 충돌**이고, 규칙이 없어서
+                    // raw UNIQUE 오류로 터졌다(내 MCP 왕복 테스트가 잡았다). merge 의 뜻은
+                    // "더한다"이므로 들어오는 root 에 다음 빈 순번을 준다 — 남의 관찰을 덮지 않고,
+                    // 배열 끝에 붙는다. remap 은 그 root 의 revision 들에도 그대로 적용해야 한다
+                    // (trg_obs_matches_root 가 둘의 일치를 요구한다).
+                    // 입력 순서에 결과가 의존하면 같은 dump 를 두 번 넣었을 때 배열 순서가 달라진다.
+                    // (entity_id, projection_order, root_id) 로 정렬해 결정론을 만든다.
+                    const incomingRoots = [...(data.observation_roots ?? [])].sort((a, b) => String(a.entity_id).localeCompare(String(b.entity_id)) ||
+                        (a.projection_order - b.projection_order) ||
+                        String(a.root_id).localeCompare(String(b.root_id)));
+                    const remappedOrder = new Map();
+                    for (const r of incomingRoots) {
+                        const cur = this.db.prepare(`SELECT * FROM observation_roots WHERE root_id = ?`)
+                            .get(r.root_id);
+                        if (cur) {
+                            // projection_order 는 **target-local** 속성이다: merge 는 배열 위치를
+                            // 이 DB 기준으로 재배정하므로, 이미 remap 된 root 를 같은 dump 로 다시
+                            // 넣으면 dump 의 옛 순번과 다를 수밖에 없다. 그걸 충돌로 보면 동일
+                            // 재수입이 실패한다(advisor beta r3 발견 3, 실행 재현).
+                            if (!sameRow(cur, r, ['entity_id', 'created_at']))
+                                throw new Error(`import conflict: observation_roots ${r.root_id} differs from the existing row`);
+                            remappedOrder.set(r.root_id, cur.projection_order);
+                            continue;
+                        }
+                        let order = r.projection_order;
+                        const taken = this.db.prepare(`SELECT root_id FROM observation_roots WHERE entity_id = ? AND projection_order = ?`)
+                            .get(r.entity_id, order);
+                        if (taken) {
+                            order = nextProjectionOrder(this.db, r.entity_id);
+                            remappedOrder.set(r.root_id, order);
+                            remapReport.push({ root_id: r.root_id, entity_id: r.entity_id,
+                                from: r.projection_order, to: order });
+                            console.error(`  ├─ ↪️ import: ${r.entity_id} position ${r.projection_order} is held by ` +
+                                `${taken.root_id}; appending imported observation at ${order}`);
+                        }
+                        this.db.prepare(`INSERT INTO observation_roots
+            (root_id, entity_id, projection_order, created_at) VALUES (?, ?, ?, ?)`)
+                            .run(r.root_id, r.entity_id, order, r.created_at);
+                    }
+                    // projection_order 는 root 와 같은 이유로 비교 대상이 아니다(target-local).
+                    const revCols = ['root_id', 'entity_id', 'revision_no', 'content',
+                        'status', 'supersedes_id', 'recorded_at', 'superseded_at'];
+                    const revs = [...(data.entity_observations ?? [])]
+                        .sort((a, b) => a.root_id === b.root_id
+                        ? a.revision_no - b.revision_no
+                        : String(a.root_id).localeCompare(String(b.root_id)));
+                    for (const v of revs) {
+                        const cur = this.db.prepare(`SELECT * FROM entity_observations WHERE observation_id = ?`)
+                            .get(v.observation_id);
+                        if (cur) {
+                            if (!sameRow(cur, v, revCols))
+                                throw new Error(`import conflict: entity_observations ${v.observation_id} differs from the existing row`);
+                            continue;
+                        }
+                        const order = remappedOrder.has(v.root_id)
+                            ? remappedOrder.get(v.root_id) : v.projection_order;
+                        this.db.prepare(`INSERT INTO entity_observations
+            (observation_id, root_id, entity_id, revision_no, projection_order,
+             content, status, supersedes_id, recorded_at, superseded_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                            .run(v.observation_id, v.root_id, v.entity_id, v.revision_no, order, v.content, v.status, v.supersedes_id ?? null, v.recorded_at, v.superseded_at ?? null);
+                    }
+                    for (const so of (data.observation_sources ?? [])) {
+                        const cur = this.db.prepare(`SELECT * FROM observation_sources
+            WHERE observation_id=? AND source_kind=? AND source_ref=?`)
+                            .get(so.observation_id, so.source_kind, so.source_ref);
+                        if (cur) {
+                            if (!sameRow(cur, so, ['source_hash', 'recorded_at']))
+                                throw new Error(`import conflict: observation_sources ` +
+                                    `${so.observation_id}/${so.source_kind}/${so.source_ref} differs from the existing row`);
+                            continue;
+                        }
+                        this.db.prepare(`INSERT INTO observation_sources
+            (observation_id, source_kind, source_ref, source_hash, recorded_at) VALUES (?, ?, ?, ?, ?)`)
+                            .run(so.observation_id, so.source_kind, so.source_ref, so.source_hash ?? null, so.recorded_at);
+                    }
+                    const evCols = ['root_id', 'from_id', 'to_id', 'event', 'change_kind', 'reason', 'actor', 'batch_id', 'recorded_at'];
+                    for (const e of (data.observation_events ?? [])) {
+                        const cur = this.db.prepare(`SELECT * FROM observation_events WHERE event_id = ?`)
+                            .get(e.event_id);
+                        if (cur) {
+                            if (!sameRow(cur, e, evCols))
+                                throw new Error(`import conflict: observation_events ${e.event_id} differs from the existing row`);
+                            continue;
+                        }
+                        this.db.prepare(`INSERT INTO observation_events
+            (event_id, root_id, from_id, to_id, event, change_kind, reason, actor, batch_id, recorded_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                            .run(e.event_id, e.root_id, e.from_id ?? null, e.to_id ?? null, e.event, e.change_kind ?? null, e.reason ?? null, e.actor ?? null, e.batch_id ?? null, e.recorded_at);
+                    }
+                });
+                tx();
+            }
+            else {
+                // 구(舊) 형식 export: lifecycle 필드가 없으므로 entities.observations 를
+                // 신규 root 로 승격한다. legacy import 필수 필드값 = spec §6.4.
+                const ts = new Date().toISOString();
+                const tx = this.db.transaction(() => {
+                    for (const ent of (data.entities ?? [])) {
+                        const entityId = ent.id ??
+                            `entity_${String(ent.name).toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
+                        for (const content of (ent.observations ?? [])) {
+                            addRevision(this.db, {
+                                entityId, content, status: 'active',
+                                sources: [{ source_kind: 'import', source_ref: 'legacy-export', source_hash: null }],
+                                actor: 'import', ts, event: 'import'
+                            });
+                        }
+                    }
+                });
+                tx();
+            }
+            // projection 재합성 + 파생 상태 무효화.
+            // 무효화가 없으면 이미 있던 entity 를 덮어쓴 뒤에도 옛 벡터·옛 KG chunk 가
+            // 검색에 남는다. import 는 관찰을 바꾸는 writer 이므로 다른 writer 와 같은
+            // 계약을 져야 한다(advisor beta 발견 2).
+            //
+            // 대상은 `data.entities` 가 아니라 **영향받은 entity 전부**다. lifecycle import 는
+            // observation_roots 만 있어도 활성화되므로, entities 없이 lifecycle 배열만 보내면
+            // revision 은 들어가는데 projection 이 갱신되지 않아 새 사실이 reader 에 안 보이고
+            // 옛 벡터가 남는다(advisor beta r3 발견 2, 실행 재현).
+            const affected = new Set();
+            for (const ent of (data.entities ?? [])) {
+                affected.add(ent.id ??
+                    `entity_${String(ent.name).toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`);
+            }
+            for (const r of (data.observation_roots ?? []))
+                if (r.entity_id)
+                    affected.add(r.entity_id);
+            for (const v of (data.entity_observations ?? []))
+                if (v.entity_id)
+                    affected.add(v.entity_id);
+            for (const entityId of affected) {
+                rebuildProjection(this.db, entityId);
+                this.invalidateDerivedForEntity(entityId);
+            }
+        });
+        importAll();
         console.error(`✅ Import completed: ${imported.entities} entities, ${imported.relations} relations, ${imported.documents} documents imported`);
         // Indirect missing-row producer (spec §5): imported rows may lack vectors.
         this.coordinator?.invalidateCoverage();
         this.coordinator?.kick();
-        return { imported, skipped };
+        return { imported, skipped, observation_order_remap: remapReport };
     }
     async hybridSearch(query, limit = 5, useGraph = true) {
         if (!this.db)
@@ -2596,8 +3205,12 @@ export class RAGKnowledgeGraphManager {
                 graphBoost += Math.min(entityBoost, 0.4);
             }
             // Generate semantic summary (skip when degraded — no embeddings available).
+            // RAG_MEMORY_SEARCH_SUMMARIES=off: diagnostic escape hatch (v5) — the summary
+            // path embeds EVERY sentence of EVERY candidate (~100+ inferences per search,
+            // measured 90-120s cold). Off = preview slices + relevanceScore 0; ranking
+            // then rests on vectorSimilarity + boosts. Default unchanged.
             let summary, keyHighlight, relevanceScore;
-            if (vectorDegraded || !primaryQueryEmbedding) {
+            if (vectorDegraded || !primaryQueryEmbedding || process.env.RAG_MEMORY_SEARCH_SUMMARIES === 'off') {
                 keyHighlight = result.text.slice(0, 150);
                 summary = result.text.slice(0, 300);
                 relevanceScore = 0;
@@ -2775,6 +3388,20 @@ export class RAGKnowledgeGraphManager {
         // reads version, model/reconciliation state, and provenance coverage here.
         const gs = this.gate.status;
         const cov = this.coordinator?.coverage();
+        // v14 (spec §7.2): document 기준 chunking 전환 상태 — 상호배타, 합 = documents.
+        // regex 분류는 SQL 밖(JS)에서: current = 런타임이 인식하는 c1 형식(강한 파서),
+        // legacy = 'legacy-unknown', unknown = 그 외 전부.
+        const sigRows = this.db.prepare(`SELECT chunking_signature AS s, count(*) AS n FROM documents GROUP BY chunking_signature`)
+            .all();
+        let sigCur = 0, sigLeg = 0, sigUnk = 0;
+        for (const r of sigRows) {
+            if (r.s === LEGACY_SIGNATURE)
+                sigLeg += r.n;
+            else if (isCurrentFormatSignature(r.s))
+                sigCur += r.n;
+            else
+                sigUnk += r.n;
+        }
         return {
             entities: {
                 total: entityStats.reduce((sum, stat) => sum + stat.count, 0),
@@ -2786,6 +3413,8 @@ export class RAGKnowledgeGraphManager {
             },
             documents: documentCount.count,
             chunks: chunkCount.count,
+            chunking: { current: sigCur, legacy: sigLeg, unknown: sigUnk,
+                default_signature: effectiveSignature(DEFAULT_MAX_TOKENS) },
             server: {
                 version: PKG_VERSION,
                 node: process.versions.node,
@@ -3082,7 +3711,7 @@ export class RAGKnowledgeGraphManager {
             .filter(m => m.version > targetVersion && m.version <= currentVersion)
             .sort((a, b) => b.version - a.version);
         migrationManager.rollback(targetVersion);
-        return {
+        const result = {
             rolledBack: migrationsToRollback.length,
             currentVersion: migrationManager.getCurrentVersion(),
             rolledBackMigrations: migrationsToRollback.map(m => ({
@@ -3090,6 +3719,18 @@ export class RAGKnowledgeGraphManager {
                 description: m.description
             }))
         };
+        // v14 rollback is a compatibility rollback ONLY (spec §6.3): dropping the
+        // chunking_signature column does not restore old chunk boundaries — c1 rows
+        // read fine on v13 code. Say so in the RESPONSE, not just the tool
+        // description, so a caller who rolled back sees the limit (advisor r5-10).
+        if (result.rolledBackMigrations.some(m => m.version === 14)) {
+            return {
+                ...result,
+                semanticRollback: false,
+                warning: 'v14 rollback removes the chunking_signature column only; chunk boundaries produced by chunker c1 are NOT restored (compatibility rollback). Data restore path = pre-migration backup snapshot.'
+            };
+        }
+        return result;
     }
 }
 // Initialize the manager
@@ -3125,7 +3766,32 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "createRelations":
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.createRelations(validatedArgs.relations), null, 2) }] };
             case "addObservations":
+                // v13: status·sources 를 그대로 넘긴다. 여기서 떨어뜨리면 스키마가 받아도
+                // 엔진에 도달하지 않아 provenance 가 조용히 사라진다.
                 return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.addObservations(validatedArgs.observations), null, 2) }] };
+            // v13 observation lifecycle (spec §6.1 / §6.2)
+            case "correctObservation":
+                return { content: [{ type: "text", text: JSON.stringify({ observation_id: await ragKgManager.correctObservation(validatedArgs.observation_id, validatedArgs.content, validatedArgs.change_kind ?? 'correction', validatedArgs.reason) }, null, 2) }] };
+            case "retractObservation":
+                await ragKgManager.retractObservation(validatedArgs.observation_id, validatedArgs.reason);
+                return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'retracted' }, null, 2) }] };
+            case "restoreObservation":
+                await ragKgManager.restoreObservation(validatedArgs.observation_id, validatedArgs.reason);
+                return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'active' }, null, 2) }] };
+            case "approveObservation":
+                await ragKgManager.approveObservation(validatedArgs.observation_id, validatedArgs.reason);
+                return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'active' }, null, 2) }] };
+            case "declineObservation":
+                await ragKgManager.declineObservation(validatedArgs.observation_id, validatedArgs.reason);
+                return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'retracted' }, null, 2) }] };
+            case "purgeObservation":
+                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.purgeObservation(validatedArgs.observation_id, validatedArgs.confirm), null, 2) }] };
+            case "getObservationHistory":
+                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getObservationHistory({
+                                entity_name: validatedArgs.entity_name,
+                                observation_id: validatedArgs.observation_id,
+                                root_id: validatedArgs.root_id,
+                            }), null, 2) }] };
             case "deleteEntities":
                 await ragKgManager.deleteEntities(validatedArgs.entityNames);
                 return { content: [{ type: "text", text: "Entities deleted successfully" }] };