rag-memory-epf-mcp 3.6.0 → 4.0.0

package/dist/src/backup/preflight.d.ts

@@ -0,0 +1,5 @@
+import Database from 'better-sqlite3';
+export declare function backupBeforeMigration(db: Database.Database, dbPath: string, pendingVersions: number[], currentVersion: number): Promise<{
+    path: string;
+    sha256: string;
+} | null>;

package/dist/src/backup/preflight.js

@@ -0,0 +1,185 @@
+import { existsSync, openSync, readSync, closeSync, linkSync, unlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import Database from 'better-sqlite3';
+// 이 파일이 지켜야 하는 것은 두 줄이다:
+//   ① 복구점을 절대 덮어쓰지 않는다
+//   ② 재시작을 막지 않는다
+//
+// 이걸 "남아 있는 .bak 이 live 와 같은 상태인가"를 증명해서 풀려고 세 판본을 썼고
+// 세 번 다 틀렸다(스키마 버전을 신원으로 착각 → DB 내부 UUID+집계 지문 → 전체 논리
+// 다이제스트). 등가 증명은 애초에 필요하지 않았다: **백업은 스키마를 바꾸기 전에
+// 만들어지므로, 시도마다 다음 빈 슬롯에 하나 더 만들면 그 모든 파일이 정의상 유효한
+// pre-migration 스냅샷이다.** 덮어쓰지 않으니 ①, 막지 않으니 ②. 비교가 없으니
+// 비교 정확성 문제가 전부 사라진다. (advisor beta r2~r7 결론)
+//
+// 대가 = 디스크. 슬롯을 유한하게 두고 다 차면 fail-closed 한다.
+const MAX_RECOVERY_POINTS = 3;
+// spec §5.1: 마이그레이션 전 일관 스냅샷.
+//
+// **`VACUUM INTO` 를 쓰지 않는다.** SQLite 문서는 VACUUM 이 명시적
+// `INTEGER PRIMARY KEY` 가 없는 테이블의 ROWID 를 바꿀 수 있다고 명시한다. 이 스키마의
+// `entities` 는 `TEXT PRIMARY KEY` 라 hidden ROWID 테이블이고, `entities_fts` 는
+// `content_rowid='rowid'` 로 그 hidden ROWID 를 참조한다 — 재번호가 일어나면 백업
+// **자체가** external-content 불일치를 안고 태어나며, `quick_check` 는 그것을 통과시킨다.
+// 현재 빌드(SQLite 3.51.3, 이 스키마)에서는 재번호가 관측되지 않았다. 하지만
+// **관측되지 않은 것과 계약으로 금지된 것은 다르고**, `better-sqlite3` 는 `^12.8.0`
+// 부동이며 이 파일은 유일한 복구선이다. 그래서 bitwise-identical 스냅샷을 보장하는
+// Online Backup API(`db.backup()`)를 쓴다. (advisor beta r7 P0-1)
+//
+// 실패는 전부 throw = fail-closed. 백업 없이 스키마를 바꾸지 않는다:
+// 이 프로젝트군은 non-git 환경(Google Drive 폴더)에 배포되어 git 롤백이 없다.
+//
+// **단일 writer 전제**: 백업과 마이그레이션 사이에 다른 프로세스가 커밋하면 그 커밋은
+// 마이그레이션에는 들어가고 복구점에는 없다. 이 엔진은 프로젝트당 서버 하나로 배포되며
+// (프로젝트별 `.mcp.json`), 마이그레이션은 `server.connect()` 전에 끝난다. 같은 DB 를
+// 두 프로세스가 동시에 여는 것은 지원 대상이 아니다 — 상세 = docs/UPDATING.md.
+export async function backupBeforeMigration(db, dbPath, pendingVersions, currentVersion) {
+    if (pendingVersions.length === 0)
+        return null; // 대기 없으면 no-op
+    if (!dbPath || dbPath === ':memory:')
+        return null; // 메모리 DB 는 대상 아님
+    // 백업 대상 판정 = "잃을 데이터가 있는가". 테이블 목록을 하드코딩하면 그 목록 밖의
+    // 데이터가 안 보인다 — `embedding_profiles` 에만 행이 있는 version-0 DB 가 그렇게
+    // 무백업으로 통과했다(advisor beta r6 P0-3). 그래서 사용자 테이블 전체를 본다.
+    if (currentVersion <= 0 && !hasAnyUserRows(db))
+        return null;
+    const base = `${dbPath}.v${currentVersion}.bak`;
+    // 임시 파일에 먼저 만든다 = 이 프로세스가 독점 소유한다. 검증까지 통과한 뒤에야
+    // 슬롯에 게시하므로, 슬롯에는 절대 반쯤 만들어진 파일이 놓이지 않는다.
+    const tmp = `${base}.partial-${process.pid}`;
+    if (existsSync(tmp))
+        unlinkSync(tmp);
+    await db.backup(tmp);
+    try {
+        verifyRecoveryPoint(tmp);
+        const target = publishNoClobber(tmp, base);
+        const sha256 = streamSha256(target);
+        console.error(`  ├─ 🛟 backup ${target} (sha256 ${sha256.slice(0, 12)}…)`);
+        return { path: target, sha256 };
+    }
+    catch (e) {
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch { /* 정리 실패는 원인을 가리지 않는다 */ }
+        throw e;
+    }
+}
+// 이 파일이 실제로 복구점인가. `quick_check` 는 페이지 구조만 본다 — external-content
+// FTS5 의 rowid 불일치는 통과시킨다. FTS5 자신의 `integrity-check` 가 그 대조를 한다.
+function verifyRecoveryPoint(path) {
+    // 우리가 독점 소유한 임시 파일이므로 쓰기 모드로 연다(integrity-check 는 명령 삽입이다).
+    const v = new Database(path);
+    try {
+        const ok = v.pragma('quick_check', { simple: true });
+        if (ok !== 'ok')
+            throw new Error(`migration backup failed quick_check: ${ok}`);
+        const n = v.prepare(`SELECT COUNT(*) c FROM sqlite_master`).get();
+        if (!n || n.c === 0)
+            throw new Error('migration backup has empty schema');
+        const fts = v.prepare(`SELECT name FROM sqlite_schema WHERE type='table' AND sql LIKE '%USING fts5%'`)
+            .all();
+        for (const { name } of fts) {
+            const q = `"${name.replace(/"/g, '""')}"`;
+            try {
+                // **`rank = 1` 이 필수다.** 인자 없는 integrity-check 는 인덱스가 자기 자신과
+                // 정합한지만 본다 — external-content 테이블과의 대조는 하지 않는다. 실측:
+                // 인덱스에 content 없는 rowid 를 심어 놓으면 `quick_check` 도, 인자 없는
+                // integrity-check 도 **통과**하고 `rank=1` 만 malformed 를 던진다.
+                // 즉 rank 없이 부르면 이 검사를 넣은 이유였던 실패 모드를 못 잡는다
+                // (advisor beta r8 P0, 같은 런타임에서 재현).
+                v.exec(`INSERT INTO ${q}(${q}, rank) VALUES('integrity-check', 1)`);
+            }
+            catch (e) {
+                throw new Error(`migration backup failed FTS5 integrity-check on ${name}: ${e.message}. ` +
+                    `The snapshot would not be a usable recovery point.`);
+            }
+        }
+    }
+    finally {
+        v.close();
+    }
+}
+// 슬롯 게시. `link()` 는 목적지가 있으면 EEXIST 로 실패하므로 **원자적 no-clobber** 다
+// (rename 은 조용히 덮어쓴다). 그래서 경쟁하는 프로세스가 있어도 복구점을 잃지 않는다.
+function publishNoClobber(tmp, base) {
+    for (let attempt = 0; attempt < MAX_RECOVERY_POINTS; attempt++) {
+        const slot = pickRecoverySlot(base);
+        try {
+            linkSync(tmp, slot);
+            unlinkSync(tmp);
+            return slot;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            // 그 슬롯을 누가 먼저 가져갔다 — 다음 빈 슬롯으로.
+        }
+    }
+    throw slotsFullError(base);
+}
+// 다음 빈 복구점 슬롯. 기존 파일은 읽지도, 검증하지도, 건드리지도 않는다 —
+// 그것들이 무엇인지 판정하려는 시도가 앞선 세 판본의 결함 전부였다.
+function pickRecoverySlot(base) {
+    if (!existsSync(base))
+        return base;
+    for (let i = 1; i < MAX_RECOVERY_POINTS; i++) {
+        const candidate = `${base}.${i}`;
+        if (!existsSync(candidate))
+            return candidate;
+    }
+    throw slotsFullError(base);
+}
+// 슬롯이 찬 상태는 **이 스키마 버전에 대한 circuit breaker** 다. 전역 용량 상한이 아니고
+// (버전마다 자기 세트를 갖는다), "3회 실패"의 증거도 아니다 — 손상 파일이나 남의 파일이
+// 슬롯을 차지할 수도 있다. 그리고 이 오류는 `server.connect()` **전에** 나가므로
+// 클라이언트에는 MCP unavailable 로 보인다. 복구 절차를 아는 유일한 경로가 stderr 다.
+function slotsFullError(base) {
+    return new Error(`migration refused: all ${MAX_RECOVERY_POINTS} recovery-point slots for this schema version ` +
+        `are taken (${base} plus ${MAX_RECOVERY_POINTS - 1} numbered siblings). Nothing was written ` +
+        `and no existing file was touched. This is a circuit breaker for this version, not a disk ` +
+        `quota, and the files are not necessarily failed attempts — a stale or unrelated file occupies ` +
+        `a slot just the same. Inspect them, move the ones you do not need aside, then start the ` +
+        `server again. Runbook: docs/UPDATING.md "Recovery-point slots are full".`);
+}
+// 사용자 테이블 중 하나라도 행이 있으면 잃을 데이터가 있다.
+// 목록은 스키마에서 얻는다(하드코딩하면 새 테이블이 조용히 검사 밖에 남는다).
+// `schema_migrations` 는 순수 메타데이터라 제외한다 — 그것만 있는 DB 는 빈 DB 다.
+// 가상 테이블은 자기 shadow 테이블을 통해 이미 세어진다.
+function hasAnyUserRows(db) {
+    const tables = db.prepare(`SELECT name, sql FROM sqlite_schema WHERE type='table'
+       AND name <> 'schema_migrations'
+     ORDER BY name`).all();
+    for (const t of tables) {
+        if (/CREATE VIRTUAL TABLE/i.test(t.sql ?? ''))
+            continue;
+        const qt = `"${t.name.replace(/"/g, '""')}"`;
+        try {
+            const n = db.prepare(`SELECT EXISTS(SELECT 1 FROM ${qt}) e`).get();
+            if (n.e)
+                return true;
+        }
+        catch {
+            // 읽을 수 없는 테이블이 있으면 "빈 DB"라고 단정하지 않는다 = 백업한다.
+            return true;
+        }
+    }
+    return false;
+}
+// 스트리밍 해시. readFileSync 로 전체를 메모리에 올리면 fleet 의 큰 DB 에서
+// OOM 위험이 있다(advisor 구현리뷰 r1 발견 6).
+function streamSha256(path) {
+    const h = createHash('sha256');
+    const fd = openSync(path, 'r');
+    try {
+        const buf = Buffer.allocUnsafe(1 << 20);
+        let n;
+        while ((n = readSync(fd, buf, 0, buf.length, null)) > 0)
+            h.update(buf.subarray(0, n));
+    }
+    finally {
+        closeSync(fd);
+    }
+    return h.digest('hex');
+}

package/dist/src/migrations/migrations.d.ts

@@ -1,2 +1,4 @@
 import { Migration } from './migration-manager.js';
+export type MigrationFaultPoint = 'preflight' | 'roots' | 'revisions' | 'sources' | 'gate';
+export declare function setMigrationFaultPoint(point: MigrationFaultPoint | null): void;
 export declare const migrations: Migration[];

package/dist/src/migrations/migrations.js

@@ -1,3 +1,9 @@
+import { OBSERVATION_SCHEMA_SQL } from '../observations/schema.js';
+import { randomUUID } from 'node:crypto';
+let faultPoint = null;
+export function setMigrationFaultPoint(point) {
+    faultPoint = point;
+}
 export const migrations = [
     {
         version: 1,
@@ -641,5 +647,109 @@ export const migrations = [
             db.exec(`DROP TABLE IF EXISTS embedding_profiles`);
             db.exec(`DROP TABLE IF EXISTS server_meta`);
         }
+    },
+    // v13 (spec 2026-07-30 observation-lifecycle §4): 관찰 생애주기 정규화.
+    // 이 항목은 DDL 만 만든다. 데이터 변환은 후속 단계에서 같은 항목에 덧붙인다.
+    {
+        version: 13,
+        description: 'Observation lifecycle: roots/revisions/sources/events + immutability triggers',
+        up: (db) => {
+            db.exec(OBSERVATION_SCHEMA_SQL);
+            // ---- spec §5.3 변환 ----
+            // MIGRATION_TS = 이 DB 의 v12->v13 트랜잭션 시작시각 하나 (전 행 공유).
+            // entities.created_at 을 복사하지 않는다 — 그것은 entity 생성시각을
+            // 관찰 기록시각으로 단정하는 것이고, import event 는 실제로 지금 발생했다.
+            // 원래 관찰 시각은 unknown 으로 둔다 (v13 은 기록시간 축만 다룬다).
+            const MIGRATION_TS = new Date().toISOString();
+            const BATCH_ID = randomUUID();
+            // 단계 경계 fault injection. 주입은 setMigrationFaultPoint() 로만 하며
+            // 환경변수를 보지 않는다 — 환경변수로 두면 프로덕션에 "마이그레이션을 깨는
+            // 스위치"가 상시 존재하고, 오설정 한 줄이 .bak 을 남겨 재시작을 막는다
+            // (advisor beta 자기의심 2 = "더 나쁘다").
+            const fault = (point) => {
+                if (faultPoint === point)
+                    throw new Error(`injected fault at '${point}' (test-only)`);
+            };
+            // 1) 읽기 전용 preflight: array<string> 검증.
+            //    JSON.parse 만으로는 객체·숫자·null 요소가 통과한다.
+            const rows = db.prepare(`SELECT id, observations FROM entities`).all();
+            const parsed = new Map();
+            for (const r of rows) {
+                let val;
+                try {
+                    val = JSON.parse(r.observations ?? '[]');
+                }
+                catch {
+                    throw new Error(`v13 preflight: entity ${r.id} observations is not JSON`);
+                }
+                if (!Array.isArray(val))
+                    throw new Error(`v13 preflight: entity ${r.id} observations is not an array<string>`);
+                for (const el of val) {
+                    if (typeof el !== 'string')
+                        throw new Error(`v13 preflight: entity ${r.id} observations contains a non-string ` +
+                            `element (${el === null ? 'null' : typeof el}) — array<string> required`);
+                }
+                parsed.set(r.id, val);
+            }
+            fault('preflight');
+            // 2~4) roots -> revisions -> sources/events.
+            //      이 순서가 계약이다: trg_obs_matches_root 가 root 선행을 요구한다.
+            //      3패스로 나눈 이유 = 지점별 fault injection 을 검증 가능하게 하려면
+            //      단계 경계가 실제로 존재해야 한다(T11).
+            const insRoot = db.prepare(`INSERT INTO observation_roots
+        (root_id, entity_id, projection_order, created_at) VALUES (?, ?, ?, ?)`);
+            const insRev = 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, ?, ?, 'active', NULL, ?, NULL)`);
+            const insSrc = db.prepare(`INSERT INTO observation_sources
+        (observation_id, source_kind, source_ref, source_hash, recorded_at)
+        VALUES (?, 'import', 'v12-migration', NULL, ?)`);
+            const insEv = db.prepare(`INSERT INTO observation_events
+        (event_id, root_id, from_id, to_id, event, change_kind, reason, actor, batch_id, recorded_at)
+        VALUES (?, ?, NULL, ?, 'import', NULL, NULL, 'v12-migration', ?, ?)`);
+            const plan = [];
+            for (const [entityId, arr] of parsed) {
+                arr.forEach((content, order) => {
+                    const rootId = randomUUID();
+                    insRoot.run(rootId, entityId, order, MIGRATION_TS);
+                    plan.push({ entityId, rootId, obsId: randomUUID(), order, content });
+                });
+            }
+            fault('roots');
+            // pass 2: revisions
+            for (const p of plan)
+                insRev.run(p.obsId, p.rootId, p.entityId, p.order, p.content, MIGRATION_TS);
+            fault('revisions');
+            // pass 3: sources + events
+            for (const p of plan) {
+                insSrc.run(p.obsId, MIGRATION_TS);
+                insEv.run(randomUUID(), p.rootId, p.obsId, BATCH_ID, MIGRATION_TS);
+            }
+            fault('sources');
+            // 6) 검증 게이트 (a): FK 무결성.
+            //    FK 가 켜져 있어도 방어층으로 확인한다.
+            const fkBad = db.prepare(`PRAGMA foreign_key_check`).all();
+            if (fkBad.length > 0)
+                throw new Error(`v13 gate: foreign_key_check reported ${fkBad.length} violation(s)`);
+            fault('gate');
+            // 7) 검증 게이트 (b): 합성 배열 == 원본 배열 (중복·순서 포함 byte 동일)
+            const synthStmt = db.prepare(`SELECT content FROM entity_observations
+        WHERE entity_id = ? AND status = 'active' ORDER BY projection_order`);
+            for (const [entityId, arr] of parsed) {
+                const rebuilt = JSON.stringify(synthStmt.all(entityId).map(x => x.content));
+                const original = JSON.stringify(arr);
+                if (rebuilt !== original)
+                    throw new Error(`v13 gate: projection mismatch for entity ${entityId}\n` +
+                        `  original: ${original}\n  rebuilt:  ${rebuilt}`);
+            }
+        },
+        down: (db) => {
+            // 역순 삭제 (FK 의존 순서). 트리거는 테이블과 함께 사라진다.
+            db.exec(`DROP TABLE IF EXISTS observation_events`);
+            db.exec(`DROP TABLE IF EXISTS observation_sources`);
+            db.exec(`DROP TABLE IF EXISTS entity_observations`);
+            db.exec(`DROP TABLE IF EXISTS observation_roots`);
+        }
     }
 ];

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

@@ -0,0 +1,8 @@
+import type Database from 'better-sqlite3';
+export declare function getObservationHistory(db: Database.Database, sel: {
+    entity_name?: string;
+    observation_id?: string;
+    root_id?: string;
+}): {
+    roots: any[];
+};

package/dist/src/observations/history.js

@@ -0,0 +1,64 @@
+// spec §6.2: history 의 유일한 창구.
+// 응답은 항상 roots 배열이다 (entity_name 이면 N개, root_id/observation_id 면 1개).
+// 단일 객체로 두면 entity_name 선택자와 cardinality 가 모순된다.
+export function getObservationHistory(db, sel) {
+    // 정확히 하나만 받는다. 우선순위를 조용히 적용하면 두 개를 넘긴 호출자가
+    // *다른* 선택자의 답을 받고 그 사실을 모른다 — 실측으로 entity_name 이 유효한데
+    // 존재하지 않는 root_id 가 이겨서 `{roots: []}` 가 나갔다(advisor beta 발견 4-2).
+    const given = ['entity_name', 'observation_id', 'root_id']
+        .filter(k => sel[k] !== undefined && sel[k] !== null && sel[k] !== '');
+    if (given.length === 0) {
+        throw new Error('getObservationHistory requires one of: entity_name, observation_id, root_id');
+    }
+    if (given.length > 1) {
+        throw new Error(`getObservationHistory takes exactly one selector, got ${given.length} (${given.join(', ')}). ` +
+            `Applying a precedence order would silently answer a different question than the one asked.`);
+    }
+    let rootIds;
+    if (sel.root_id) {
+        rootIds = [sel.root_id];
+    }
+    else if (sel.observation_id) {
+        const r = db.prepare(`SELECT root_id FROM entity_observations WHERE observation_id = ?`)
+            .get(sel.observation_id);
+        rootIds = r ? [r.root_id] : [];
+    }
+    else if (sel.entity_name) {
+        const entityId = `entity_${sel.entity_name.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
+        rootIds = db.prepare(`SELECT root_id FROM observation_roots
+                           WHERE entity_id = ? ORDER BY projection_order`)
+            .all(entityId).map(r => r.root_id);
+    }
+    else {
+        throw new Error('getObservationHistory requires one of: entity_name, observation_id, root_id');
+    }
+    const roots = rootIds.map(rid => {
+        const root = db.prepare(`SELECT * FROM observation_roots WHERE root_id = ?`).get(rid);
+        if (!root)
+            return null;
+        const revs = db.prepare(`SELECT * FROM entity_observations WHERE root_id = ? ORDER BY revision_no`).all(rid);
+        // 정렬 = recorded_at, 동시각이면 event_id 사전순 (결정론)
+        const events = db.prepare(`SELECT * FROM observation_events WHERE root_id = ? ORDER BY recorded_at, event_id`).all(rid);
+        return {
+            root_id: root.root_id,
+            entity_id: root.entity_id,
+            projection_order: root.projection_order,
+            revisions: revs.map(v => ({
+                observation_id: v.observation_id,
+                revision_no: v.revision_no,
+                content: v.content,
+                status: v.status,
+                supersedes_id: v.supersedes_id,
+                recorded_at: v.recorded_at,
+                superseded_at: v.superseded_at,
+                sources: db.prepare(`SELECT source_kind, source_ref, source_hash, recorded_at
+                             FROM observation_sources WHERE observation_id = ?
+                             ORDER BY recorded_at, source_kind, source_ref`).all(v.observation_id),
+                // 이 revision 을 from/to 로 지목한 event 만
+                events: events.filter(e => e.from_id === v.observation_id || e.to_id === v.observation_id),
+            })),
+        };
+    }).filter(Boolean);
+    roots.sort((a, b) => a.projection_order - b.projection_order);
+    return { roots };
+}

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";