rag-memory-epf-mcp 3.6.0 → 5.0.0

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

@@ -0,0 +1,45 @@
+import type Database from 'better-sqlite3';
+export type ObsStatus = 'active' | 'superseded' | 'retracted' | 'provisional';
+export type ObsEvent = 'add' | 'correct' | 'retract' | 'restore' | 'approve' | 'decline' | 'import';
+export type SourceInput = {
+    source_kind: 'document' | 'conversation' | 'decision' | 'import';
+    source_ref: string;
+    source_hash?: string | null;
+};
+export declare function nextProjectionOrder(db: Database.Database, entityId: string): number;
+export declare function recordEvent(db: Database.Database, a: {
+    rootId: string;
+    event: ObsEvent;
+    fromId?: string | null;
+    toId?: string | null;
+    changeKind?: 'correction' | 'world_change' | 'retraction' | null;
+    reason?: string | null;
+    actor?: string | null;
+    batchId?: string | null;
+    ts: string;
+}): void;
+export declare function linkSources(db: Database.Database, observationId: string, sources: SourceInput[], ts: string): number;
+export declare function addRevision(db: Database.Database, a: {
+    entityId: string;
+    content: string;
+    status: Extract<ObsStatus, 'active' | 'provisional'>;
+    sources?: SourceInput[];
+    actor?: string | null;
+    ts: string;
+    event?: Extract<ObsEvent, 'add' | 'import'>;
+}): string;
+export declare function correctRevision(db: Database.Database, a: {
+    observationId: string;
+    content: string;
+    changeKind: 'correction' | 'world_change';
+    reason?: string | null;
+    actor?: string | null;
+    ts: string;
+}): string;
+export declare function transitionStatus(db: Database.Database, a: {
+    observationId: string;
+    event: 'retract' | 'restore' | 'approve' | 'decline';
+    reason?: string | null;
+    actor?: string | null;
+    ts: string;
+}): void;

package/dist/src/observations/lifecycle.js

@@ -0,0 +1,101 @@
+import { randomUUID } from 'node:crypto';
+// 순번 정본은 observation_roots 다. entity_observations 로 세면 revision 이
+// purge 된 root 의 순번을 재사용해 이후 restore/approve 가 UNIQUE 로 실패한다.
+export function nextProjectionOrder(db, entityId) {
+    const r = db.prepare(`SELECT COALESCE(MAX(projection_order), -1) + 1 AS n FROM observation_roots WHERE entity_id = ?`).get(entityId);
+    return r.n;
+}
+export function recordEvent(db, a) {
+    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(randomUUID(), a.rootId, a.fromId ?? null, a.toId ?? null, a.event, a.changeKind ?? null, a.reason ?? null, a.actor ?? null, a.batchId ?? null, a.ts);
+}
+// 한 관찰에 evidence 를 더한다. 같은 사실이 다른 출처에서 다시 오면
+// 새 revision 이 아니라 source link 가 늘어난다(spec §8.3 T13).
+export function linkSources(db, observationId, sources, ts) {
+    let n = 0;
+    for (const s of sources) {
+        n += db.prepare(`INSERT OR IGNORE INTO observation_sources
+      (observation_id, source_kind, source_ref, source_hash, recorded_at)
+      VALUES (?, ?, ?, ?, ?)`)
+            .run(observationId, s.source_kind, s.source_ref, s.source_hash ?? null, ts).changes;
+    }
+    return n;
+}
+// 새 논리 관찰 = root 1 + rev1 1 + sources N + event 1.
+// event 는 기본 'add' 지만 legacy import 경로는 'import' 를 남겨야 한다(spec §6.4):
+// 그 관찰은 사람이 방금 추가한 것이 아니라 옛 형식 dump 에서 승격된 것이고,
+// 'add' 로 적으면 history 가 유입 경로를 잘못 말한다(advisor beta 발견 1).
+export function addRevision(db, a) {
+    const rootId = randomUUID();
+    const obsId = randomUUID();
+    const order = nextProjectionOrder(db, a.entityId);
+    db.prepare(`INSERT INTO observation_roots (root_id, entity_id, projection_order, created_at)
+              VALUES (?, ?, ?, ?)`).run(rootId, a.entityId, order, a.ts);
+    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 (?, ?, ?, 1, ?, ?, ?, NULL, ?, NULL)`)
+        .run(obsId, rootId, a.entityId, order, a.content, a.status, a.ts);
+    // 출처를 모르면 source 행을 만들지 않는다.
+    // source_ref 가 NOT NULL 인 것은 "행을 반드시 만들라"는 뜻이 아니다.
+    // sources 가 생략됐는데 conversation/unspecified 를 넣으면 "대화에서 왔다"는
+    // 사실을 발명하는 것이고, provenance 의 목적과 정반대다
+    // (advisor 구현리뷰 r1 발견 5). unknown 은 0행으로 표현한다.
+    if (a.sources?.length)
+        linkSources(db, obsId, a.sources, a.ts);
+    recordEvent(db, { rootId, event: a.event ?? 'add', toId: obsId,
+        actor: a.actor ?? null, ts: a.ts });
+    return obsId;
+}
+// §4.4 복합 전이: ①구 active -> superseded ②신규 revision -> active ③correct event.
+// 셋이 한 트랜잭션 안에서 일어나야 한다 — 호출자가 mutateEntityAndInvalidate 로 감싼다.
+export function correctRevision(db, a) {
+    const cur = db.prepare(`SELECT observation_id, root_id, entity_id, revision_no, projection_order, status
+     FROM entity_observations WHERE observation_id = ?`).get(a.observationId);
+    if (!cur)
+        throw new Error(`observation ${a.observationId} not found`);
+    if (cur.status !== 'active')
+        throw new Error(`cannot correct an observation in status '${cur.status}' — only 'active' (spec §4.4)`);
+    const newId = randomUUID();
+    // ① 구 행을 먼저 superseded 로. active-per-root 부분 UNIQUE 때문에 순서가 계약이다.
+    db.prepare(`UPDATE entity_observations SET status='superseded', superseded_at=? WHERE observation_id=?`)
+        .run(a.ts, cur.observation_id);
+    // ② 신규 revision. projection_order 는 전임자 상속 = 배열 위치가 움직이지 않는다.
+    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 (?, ?, ?, ?, ?, ?, 'active', ?, ?, NULL)`)
+        .run(newId, cur.root_id, cur.entity_id, cur.revision_no + 1, cur.projection_order, a.content, cur.observation_id, a.ts);
+    // ③ event
+    recordEvent(db, { rootId: cur.root_id, event: 'correct', fromId: cur.observation_id,
+        toId: newId, changeKind: a.changeKind, reason: a.reason ?? null,
+        actor: a.actor ?? null, ts: a.ts });
+    return newId;
+}
+// §4.4 전이 표를 코드로. 표에 없는 조합은 거부한다 — 'superseded' 는 종착이다.
+const ALLOWED = {
+    active: [{ to: 'retracted', event: 'retract' }],
+    retracted: [{ to: 'active', event: 'restore' }],
+    provisional: [{ to: 'active', event: 'approve' },
+        { to: 'retracted', event: 'decline' }],
+    superseded: [],
+};
+export function transitionStatus(db, a) {
+    const cur = db.prepare(`SELECT observation_id, root_id, entity_id, status FROM entity_observations WHERE observation_id = ?`).get(a.observationId);
+    if (!cur)
+        throw new Error(`observation ${a.observationId} not found`);
+    const allowed = (ALLOWED[cur.status] ?? []).find(x => x.event === a.event);
+    if (!allowed) {
+        throw new Error(`illegal transition: '${a.event}' from status '${cur.status}' is not in the §4.4 table` +
+            (cur.status === 'superseded'
+                ? " — 'superseded' is terminal; create a new revision instead"
+                : ''));
+    }
+    db.prepare(`UPDATE entity_observations SET status = ? WHERE observation_id = ?`)
+        .run(allowed.to, cur.observation_id);
+    recordEvent(db, { rootId: cur.root_id, event: a.event, fromId: cur.observation_id,
+        toId: cur.observation_id, reason: a.reason ?? null,
+        actor: a.actor ?? null, ts: a.ts });
+}

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

@@ -0,0 +1,3 @@
+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;

package/dist/src/observations/projection.js

@@ -0,0 +1,31 @@
+// active 행을 projection_order 순으로 모아 entities.observations 를 재작성한다.
+// 단계 1 에서는 이 배열이 여전히 FTS/벡터의 입력이다 — 그래서 projection 갱신만으로
+// 기존 entity FTS 트리거와 벡터 무효화가 따라온다(spec §4.5).
+export function rebuildProjection(db, entityId) {
+    const rows = db.prepare(`SELECT content FROM entity_observations
+     WHERE entity_id = ? AND status = 'active'
+     ORDER BY projection_order`).all(entityId);
+    db.prepare(`UPDATE entities SET observations = ? WHERE id = ?`)
+        .run(JSON.stringify(rows.map(r => r.content)), entityId);
+}
+// D4: observation 이 바뀌면 그 entity 를 가리키는 KG chunk 는 stale 이다.
+// 단계 1 에서는 재생성하지 않고 fail-closed 로 제거한다 — 낡은 텍스트가
+// hybridSearch 에 남아 있는 것이 없는 것보다 나쁘다.
+//
+// KG chunk 의 식별자는 document_id 가 아니라 (chunk_type, entity_id) 다:
+// generateKnowledgeGraphChunks() 는 document_id 를 넣지 않는다.
+//
+// 이 경로는 현재 dormant 다 — generateKnowledgeGraphChunks/embedKnowledgeGraphChunks
+// 는 MCP 도구로 노출되지 않고 내부 호출 지점도 없으며, 실사용 DB 의 chunk 는 전부
+// chunk_type='document' 였다. 그래서 이것은 미래·타 배포 대비 방어층이고,
+// 테스트는 KG chunk 를 직접 심어서 검증한다(자연 발생하지 않는다).
+export function deleteStaleKgChunks(db, entityId) {
+    const chunks = db.prepare(`SELECT rowid FROM chunk_metadata WHERE chunk_type = 'entity' AND entity_id = ?`).all(entityId);
+    let n = 0;
+    for (const c of chunks) {
+        db.exec(`DELETE FROM chunks WHERE rowid = ${Number(c.rowid)}`);
+        db.prepare(`DELETE FROM chunk_metadata WHERE rowid = ?`).run(c.rowid);
+        n++;
+    }
+    return n;
+}

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

@@ -0,0 +1 @@
+export declare const OBSERVATION_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS observation_roots (\n  root_id          TEXT PRIMARY KEY NOT NULL,\n  entity_id        TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,\n  projection_order INTEGER NOT NULL\n                   CHECK (typeof(projection_order) = 'integer' AND projection_order >= 0),\n  created_at       DATETIME NOT NULL,\n  UNIQUE (entity_id, projection_order)\n);\n\nCREATE TABLE IF NOT EXISTS entity_observations (\n  observation_id   TEXT PRIMARY KEY NOT NULL,\n  root_id          TEXT NOT NULL REFERENCES observation_roots(root_id) ON DELETE CASCADE,\n  entity_id        TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,\n  revision_no      INTEGER NOT NULL\n                   CHECK (typeof(revision_no) = 'integer' AND revision_no >= 1),\n  projection_order INTEGER NOT NULL\n                   CHECK (typeof(projection_order) = 'integer' AND projection_order >= 0),\n  content          TEXT NOT NULL,\n  status           TEXT NOT NULL CHECK (status IN\n                     ('active','superseded','retracted','provisional')),\n  supersedes_id    TEXT REFERENCES entity_observations(observation_id),\n  recorded_at      DATETIME NOT NULL,\n  superseded_at    DATETIME,\n  UNIQUE (root_id, revision_no)\n);\n\nCREATE TABLE IF NOT EXISTS observation_sources (\n  observation_id TEXT NOT NULL REFERENCES entity_observations(observation_id) ON DELETE CASCADE,\n  source_kind    TEXT NOT NULL CHECK (source_kind IN\n                   ('document','conversation','decision','import')),\n  source_ref     TEXT NOT NULL,\n  source_hash    TEXT,\n  recorded_at    DATETIME NOT NULL,\n  PRIMARY KEY (observation_id, source_kind, source_ref)\n);\n\nCREATE TABLE IF NOT EXISTS observation_events (\n  event_id     TEXT PRIMARY KEY NOT NULL,\n  root_id      TEXT NOT NULL REFERENCES observation_roots(root_id) ON DELETE CASCADE,\n  from_id      TEXT,\n  to_id        TEXT,\n  event        TEXT NOT NULL CHECK (event IN\n                 ('add','correct','retract','restore','approve','decline','import')),\n  change_kind  TEXT CHECK (change_kind IN ('correction','world_change','retraction')),\n  reason       TEXT,\n  actor        TEXT,\n  batch_id     TEXT,\n  recorded_at  DATETIME NOT NULL\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_obs_active_per_root\n  ON entity_observations(root_id) WHERE status = 'active';\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_obs_active_order\n  ON entity_observations(entity_id, projection_order) WHERE status = 'active';\n\nCREATE INDEX IF NOT EXISTS idx_obs_entity ON entity_observations(entity_id);\nCREATE INDEX IF NOT EXISTS idx_obs_root ON entity_observations(root_id);\nCREATE INDEX IF NOT EXISTS idx_obs_events_root ON observation_events(root_id);\n\nCREATE TRIGGER IF NOT EXISTS trg_roots_immutable\nBEFORE UPDATE ON observation_roots\nBEGIN\n  SELECT RAISE(ABORT, 'observation_roots is immutable');\nEND;\n\nCREATE TRIGGER IF NOT EXISTS trg_obs_content_immutable\nBEFORE UPDATE OF content ON entity_observations\nBEGIN\n  SELECT RAISE(ABORT, 'observation content is immutable; create a new revision');\nEND;\n\nCREATE TRIGGER IF NOT EXISTS trg_obs_identity_immutable\nBEFORE UPDATE OF observation_id, root_id, entity_id, revision_no, supersedes_id,\n                 projection_order, recorded_at\nON entity_observations\nBEGIN\n  SELECT RAISE(ABORT, 'identity/order fields are immutable after insert');\nEND;\n\nCREATE TRIGGER IF NOT EXISTS trg_obs_matches_root\nBEFORE INSERT ON entity_observations\nBEGIN\n  SELECT RAISE(ABORT, 'root_id must exist and (entity_id, projection_order) must match it')\n  WHERE NOT EXISTS (\n    SELECT 1 FROM observation_roots r\n    WHERE r.root_id = NEW.root_id\n      AND r.entity_id = NEW.entity_id\n      AND r.projection_order = NEW.projection_order);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS trg_obs_chain_wellformed\nBEFORE INSERT ON entity_observations\nBEGIN\n  SELECT RAISE(ABORT, 'revision_no must be >= 1') WHERE NEW.revision_no < 1;\n  SELECT RAISE(ABORT, 'first revision must have NULL supersedes_id')\n  WHERE NEW.revision_no = 1 AND NEW.supersedes_id IS NOT NULL;\n  SELECT RAISE(ABORT, 'non-first revision must have a predecessor')\n  WHERE NEW.revision_no > 1 AND NEW.supersedes_id IS NULL;\n  SELECT RAISE(ABORT, 'supersedes must be the immediately preceding revision of the same root')\n  WHERE NEW.supersedes_id IS NOT NULL AND NOT EXISTS (\n    SELECT 1 FROM entity_observations p\n    WHERE p.observation_id = NEW.supersedes_id\n      AND p.root_id = NEW.root_id\n      AND p.revision_no = NEW.revision_no - 1);\nEND;\n";

package/dist/src/observations/schema.js

@@ -0,0 +1,115 @@
+// v13 observation lifecycle schema (spec 2026-07-30 §4.1~4.3).
+// 마이그레이션과 테스트가 이 상수를 공유한다 — 두 곳에 DDL 을 복제하면 갈라진다.
+//
+// SQLite 함정 3가지가 이 DDL 의 형태를 결정했다 (전부 실측):
+//   1. INTEGER NOT NULL 은 타입 강제가 아니다      -> CHECK (typeof(x)='integer')
+//   2. TEXT PRIMARY KEY 는 NULL 을 허용한다        -> NOT NULL 명시
+//   3. BEFORE 트리거가 CHECK 보다 먼저 실행된다    -> 오류 문자열 순서가 정해진다
+export const OBSERVATION_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS observation_roots (
+  root_id          TEXT PRIMARY KEY NOT NULL,
+  entity_id        TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  projection_order INTEGER NOT NULL
+                   CHECK (typeof(projection_order) = 'integer' AND projection_order >= 0),
+  created_at       DATETIME NOT NULL,
+  UNIQUE (entity_id, projection_order)
+);
+
+CREATE TABLE IF NOT EXISTS entity_observations (
+  observation_id   TEXT PRIMARY KEY NOT NULL,
+  root_id          TEXT NOT NULL REFERENCES observation_roots(root_id) ON DELETE CASCADE,
+  entity_id        TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  revision_no      INTEGER NOT NULL
+                   CHECK (typeof(revision_no) = 'integer' AND revision_no >= 1),
+  projection_order INTEGER NOT NULL
+                   CHECK (typeof(projection_order) = 'integer' AND projection_order >= 0),
+  content          TEXT NOT NULL,
+  status           TEXT NOT NULL CHECK (status IN
+                     ('active','superseded','retracted','provisional')),
+  supersedes_id    TEXT REFERENCES entity_observations(observation_id),
+  recorded_at      DATETIME NOT NULL,
+  superseded_at    DATETIME,
+  UNIQUE (root_id, revision_no)
+);
+
+CREATE TABLE IF NOT EXISTS observation_sources (
+  observation_id TEXT NOT NULL REFERENCES entity_observations(observation_id) ON DELETE CASCADE,
+  source_kind    TEXT NOT NULL CHECK (source_kind IN
+                   ('document','conversation','decision','import')),
+  source_ref     TEXT NOT NULL,
+  source_hash    TEXT,
+  recorded_at    DATETIME NOT NULL,
+  PRIMARY KEY (observation_id, source_kind, source_ref)
+);
+
+CREATE TABLE IF NOT EXISTS observation_events (
+  event_id     TEXT PRIMARY KEY NOT NULL,
+  root_id      TEXT NOT NULL REFERENCES observation_roots(root_id) ON DELETE CASCADE,
+  from_id      TEXT,
+  to_id        TEXT,
+  event        TEXT NOT NULL CHECK (event IN
+                 ('add','correct','retract','restore','approve','decline','import')),
+  change_kind  TEXT CHECK (change_kind IN ('correction','world_change','retraction')),
+  reason       TEXT,
+  actor        TEXT,
+  batch_id     TEXT,
+  recorded_at  DATETIME NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_obs_active_per_root
+  ON entity_observations(root_id) WHERE status = 'active';
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_obs_active_order
+  ON entity_observations(entity_id, projection_order) WHERE status = 'active';
+
+CREATE INDEX IF NOT EXISTS idx_obs_entity ON entity_observations(entity_id);
+CREATE INDEX IF NOT EXISTS idx_obs_root ON entity_observations(root_id);
+CREATE INDEX IF NOT EXISTS idx_obs_events_root ON observation_events(root_id);
+
+CREATE TRIGGER IF NOT EXISTS trg_roots_immutable
+BEFORE UPDATE ON observation_roots
+BEGIN
+  SELECT RAISE(ABORT, 'observation_roots is immutable');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_obs_content_immutable
+BEFORE UPDATE OF content ON entity_observations
+BEGIN
+  SELECT RAISE(ABORT, 'observation content is immutable; create a new revision');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_obs_identity_immutable
+BEFORE UPDATE OF observation_id, root_id, entity_id, revision_no, supersedes_id,
+                 projection_order, recorded_at
+ON entity_observations
+BEGIN
+  SELECT RAISE(ABORT, 'identity/order fields are immutable after insert');
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_obs_matches_root
+BEFORE INSERT ON entity_observations
+BEGIN
+  SELECT RAISE(ABORT, 'root_id must exist and (entity_id, projection_order) must match it')
+  WHERE NOT EXISTS (
+    SELECT 1 FROM observation_roots r
+    WHERE r.root_id = NEW.root_id
+      AND r.entity_id = NEW.entity_id
+      AND r.projection_order = NEW.projection_order);
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_obs_chain_wellformed
+BEFORE INSERT ON entity_observations
+BEGIN
+  SELECT RAISE(ABORT, 'revision_no must be >= 1') WHERE NEW.revision_no < 1;
+  SELECT RAISE(ABORT, 'first revision must have NULL supersedes_id')
+  WHERE NEW.revision_no = 1 AND NEW.supersedes_id IS NOT NULL;
+  SELECT RAISE(ABORT, 'non-first revision must have a predecessor')
+  WHERE NEW.revision_no > 1 AND NEW.supersedes_id IS NULL;
+  SELECT RAISE(ABORT, 'supersedes must be the immediately preceding revision of the same root')
+  WHERE NEW.supersedes_id IS NOT NULL AND NOT EXISTS (
+    SELECT 1 FROM entity_observations p
+    WHERE p.observation_id = NEW.supersedes_id
+      AND p.root_id = NEW.root_id
+      AND p.revision_no = NEW.revision_no - 1);
+END;
+`;

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

@@ -563,7 +563,8 @@ Supports both merge (additive) and replace (clear + import) modes.
 - Replace mode provides clean import without conflicts
 - Handles partial imports (entities only, relations only, etc.)
 - Reports imported and skipped counts for verification
-- Supports full export format from exportGraph
+- Supports the full exportGraph format, including the v13 observation lifecycle tables
+  (revision history, provenance and events survive a round-trip)
 </features>
 
 <bestPractices>
@@ -587,12 +588,35 @@ Supports both merge (additive) and replace (clear + import) modes.
 - Full replace: {"data": {"entities": [...], "relations": [...], "documents": [...]}, "merge": false}
 - Entities only: {"data": {"entities": [{"id": "abc", "name": "Test", "entityType": "CONCEPT", "observations": ["fact1"]}]}}
 </examples>`;
+// dump 의 행은 객체다. z.any() 로 두면 광고 스키마에 type:'string' fallback 으로 나가
+// listTools 계약이 실제 입력과 어긋난다. z.record 는 "문자열 키를 가진 객체"로 광고되고
+// 비객체 입력을 거부한다(advisor beta r3 남은 P2).
+const dumpRow = () => z.record(z.any());
 const importGraphSchema = {
     data: z.object({
-        entities: z.array(z.any()).optional().describe('Array of entity objects to import'),
-        relations: z.array(z.any()).optional().describe('Array of relation objects to import'),
-        documents: z.array(z.any()).optional().describe('Array of document objects to import'),
-    }).describe('Object containing entities, relations, and/or documents arrays to import'),
+        entities: z.array(dumpRow()).optional().describe('Array of entity objects to import'),
+        relations: z.array(dumpRow()).optional().describe('Array of relation objects to import'),
+        documents: z.array(dumpRow()).optional().describe('Array of document objects to import'),
+        // v13: 이 네 배열이 스키마에 없으면 z.object().parse() 가 조용히 버린다. 그러면
+        // exportGraph 가 낸 완전한 dump 를 MCP 로 되돌릴 때 revision history·provenance·
+        // event log 가 전부 사라지고 legacy 관찰로 재생성된다 — 백업/복원이 조용히
+        // 손실 연산이 된다(advisor beta 발견 1, MCP 왕복으로 실측).
+        observation_roots: z.array(dumpRow()).optional()
+            .describe('Array of observation root rows (v13 lifecycle). Required to preserve history on restore'),
+        entity_observations: z.array(dumpRow()).optional()
+            .describe('Array of observation revision rows (v13 lifecycle)'),
+        observation_sources: z.array(dumpRow()).optional()
+            .describe('Array of observation provenance rows (v13 lifecycle)'),
+        observation_events: z.array(dumpRow()).optional()
+            .describe('Array of observation event rows (v13 lifecycle)'),
+        metadata: z.record(z.any()).optional()
+            .describe('Export metadata (exportedAt, version, counts). Ignored on import'),
+        // strict: dump 의 모든 정상 키를 위에 열거했으므로, 모르는 키는 **거부**한다.
+        // 기본 strip 은 모르는 테이블을 조용히 버리고(그게 lifecycle 4배열에서 실제로
+        // 일어난 일이다), passthrough 는 그것을 manager 까지 흘려보내 거기서 다시 조용히
+        // 무시된다 — 둘 다 같은 미래 데이터 손실 경로다. 지원하지 않는 dump 는 크게 실패해야
+        // 운영자가 엔진을 올린다(advisor beta r3).
+    }).strict().describe('A graph dump as produced by exportGraph, including the v13 observation lifecycle tables'),
     merge: z.boolean().optional().default(true).describe('If true (default), merge with existing data. If false, clear existing data first.'),
 };
 export const importGraphTool = {

package/dist/src/tools/knowledge-graph-tools.d.ts

@@ -6,6 +6,13 @@ export declare const hybridSearchTool: ToolDefinition;
 export declare const embedAllEntitiesTool: ToolDefinition;
 export declare const getDetailedContextTool: ToolDefinition;
 export declare const updateRelationsTool: ToolDefinition;
+export declare const retractObservationTool: ToolDefinition;
+export declare const restoreObservationTool: ToolDefinition;
+export declare const approveObservationTool: ToolDefinition;
+export declare const declineObservationTool: ToolDefinition;
+export declare const correctObservationTool: ToolDefinition;
+export declare const purgeObservationTool: ToolDefinition;
+export declare const getObservationHistoryTool: ToolDefinition;
 export declare const knowledgeGraphTools: {
     createEntities: ToolDefinition;
     createRelations: ToolDefinition;
@@ -14,4 +21,11 @@ export declare const knowledgeGraphTools: {
     hybridSearch: ToolDefinition;
     embedAllEntities: ToolDefinition;
     getDetailedContext: ToolDefinition;
+    correctObservation: ToolDefinition;
+    retractObservation: ToolDefinition;
+    restoreObservation: ToolDefinition;
+    approveObservation: ToolDefinition;
+    declineObservation: ToolDefinition;
+    purgeObservation: ToolDefinition;
+    getObservationHistory: ToolDefinition;
 };