rag-memory-epf-mcp 3.6.0 → 5.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/chunkerC.d.ts

@@ -0,0 +1,18 @@
+import type { Tiktoken } from 'tiktoken';
+export interface CSegment {
+    text: string;
+    start_pos: number;
+    end_pos: number;
+}
+export declare const DEFAULT_MAX_TOKENS = 800;
+export declare const LEGACY_SIGNATURE = "legacy-unknown";
+export declare function mergeMinTokens(maxTokens: number): number;
+export declare function effectiveSignature(maxTokens: number): string;
+export declare function isCurrentFormatSignature(sig: string): boolean;
+type Block = {
+    lines: string[];
+    heading: boolean;
+};
+export declare function buildBlocks(lines: string[]): Block[];
+export declare function chunkStructured(text: string, enc: Tiktoken, maxTokens?: number): CSegment[];
+export {};

package/dist/src/chunkerC.js

@@ -0,0 +1,210 @@
+export const DEFAULT_MAX_TOKENS = 800;
+export const LEGACY_SIGNATURE = 'legacy-unknown';
+// r11: heading is a preferred cut, not a mandatory one. A cut happens only when
+// the accumulated section group AND the next section are both >= this floor —
+// short adjacent sections merge, so cross-section queries still land in one
+// chunk (gate regression k05) and short log sections stop forming over-sharp
+// competitor chunks (k09). Derived, not independent: one knob (maxTokens).
+export function mergeMinTokens(maxTokens) {
+    return Math.floor(maxTokens / 2); // NOT >>1 — bitshift wraps at 2^31 (r12)
+}
+export function effectiveSignature(maxTokens) {
+    return `c1:enc=cl100k_base:max=${maxTokens}:overlap=0:fence=on:merge=${mergeMinTokens(maxTokens)}:fallback=cp-exact-${maxTokens}`;
+}
+// Strict parse (r5-15): the regex alone classified impossible signatures
+// (max=0, max/fallback mismatch) as current. Cross-check the components.
+export function isCurrentFormatSignature(sig) {
+    const m = /^c1:enc=cl100k_base:max=(\d+):overlap=0:fence=on:merge=(\d+):fallback=cp-exact-(\d+)$/.exec(sig);
+    if (!m)
+        return false;
+    const max = Number(m[1]);
+    return Number.isInteger(max) && max > 0 && m[1] === m[3] && Number(m[2]) === mergeMinTokens(max);
+}
+function splitLines(text) {
+    const lines = [];
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === '\n') {
+            lines.push(text.slice(start, i + 1));
+            start = i + 1;
+        }
+    }
+    if (start < text.length)
+        lines.push(text.slice(start));
+    return lines;
+}
+const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
+const HEADING_RE = /^#{1,4}[ \t]/;
+const BULLET_RE = /^(\s*)([-*+]|\d+[.)])[ \t]/;
+const BLANK_RE = /^\s*$/;
+export function buildBlocks(lines) {
+    const blocks = [];
+    let i = 0;
+    const attachTrailingBlanks = (blk) => {
+        while (i < lines.length && BLANK_RE.test(lines[i]))
+            blk.lines.push(lines[i++]);
+    };
+    while (i < lines.length) {
+        const line = lines[i];
+        const fm = line.match(FENCE_RE);
+        if (fm) {
+            const marker = fm[1][0];
+            const openLen = fm[1].length;
+            const blk = { lines: [lines[i++]], heading: false };
+            const closeRe = new RegExp(`^\\s{0,3}\\${marker}{${openLen},}\\s*$`);
+            while (i < lines.length) {
+                const l = lines[i];
+                blk.lines.push(l);
+                i++;
+                if (closeRe.test(l.replace(/\r?\n$/, '')))
+                    break; // unclosed -> EOF
+            }
+            attachTrailingBlanks(blk);
+            blocks.push(blk);
+        }
+        else if (HEADING_RE.test(line)) {
+            const blk = { lines: [lines[i++]], heading: true };
+            attachTrailingBlanks(blk);
+            blocks.push(blk);
+        }
+        else if (BULLET_RE.test(line)) {
+            const indent = line.match(BULLET_RE)[1].length;
+            const blk = { lines: [lines[i++]], heading: false };
+            while (i < lines.length) {
+                const l = lines[i];
+                if (BLANK_RE.test(l) || HEADING_RE.test(l) || FENCE_RE.test(l))
+                    break;
+                const bm = l.match(BULLET_RE);
+                if (bm && bm[1].length <= indent)
+                    break; // sibling/outer bullet
+                const li = l.match(/^(\s*)/)[1].length;
+                if (!bm && li <= indent)
+                    break; // dedented prose
+                blk.lines.push(l);
+                i++;
+            }
+            attachTrailingBlanks(blk);
+            blocks.push(blk);
+        }
+        else if (BLANK_RE.test(line)) {
+            const blk = { lines: [], heading: false };
+            while (i < lines.length && BLANK_RE.test(lines[i]))
+                blk.lines.push(lines[i++]);
+            blocks.push(blk);
+        }
+        else {
+            const blk = { lines: [lines[i++]], heading: false };
+            while (i < lines.length && !BLANK_RE.test(lines[i]) && !HEADING_RE.test(lines[i])
+                && !FENCE_RE.test(lines[i]) && !BULLET_RE.test(lines[i])) {
+                blk.lines.push(lines[i++]);
+            }
+            attachTrailingBlanks(blk);
+            blocks.push(blk);
+        }
+    }
+    return blocks;
+}
+// cp-exact oversize split, non-monotonicity-safe (spec §4.3-6, r5-5).
+// BPE prefix token counts are NOT monotonic ('/sdkX' -> 1,1,2,1,2), so binary
+// search is invalid. Scan prefixes linearly, remember the last fitting one, and
+// keep probing LOOKAHEAD candidates past a miss to recover dips. If not even
+// one codepoint fits, throw — never emit an over-budget chunk.
+const LOOKAHEAD = 16;
+function splitOversize(block, enc, maxTokens) {
+    const cps = [...block];
+    const out = [];
+    let start = 0;
+    while (start < cps.length) {
+        let lastFit = 0;
+        let missesSinceFit = 0;
+        for (let probe = start + 1; probe <= cps.length && missesSinceFit < LOOKAHEAD; probe++) {
+            const t = enc.encode(cps.slice(start, probe).join('')).length;
+            if (t <= maxTokens) {
+                lastFit = probe - start;
+                missesSinceFit = 0;
+            }
+            else
+                missesSinceFit++;
+        }
+        if (lastFit === 0) {
+            throw new Error(`chunker c1: codepoint at offset ${start} exceeds maxTokens=${maxTokens} on its own — cannot honor the token budget`);
+        }
+        out.push(cps.slice(start, start + lastFit).join(''));
+        start += lastFit;
+    }
+    return out;
+}
+export function chunkStructured(text, enc, maxTokens = DEFAULT_MAX_TOKENS) {
+    if (text.length === 0)
+        return [];
+    const blocks = buildBlocks(splitLines(text));
+    // r11 section pass: a section = one heading block through the next heading
+    // (preamble = blocks before the first heading). Cut decisions are precomputed
+    // per section so they depend only on section sizes, not packing state.
+    const minSection = mergeMinTokens(maxTokens);
+    const sectionOfBlock = new Array(blocks.length);
+    const sectionTexts = [];
+    let sec = -1;
+    blocks.forEach((b, bi) => {
+        if (b.heading || sec === -1) {
+            sec++;
+            sectionTexts[sec] = '';
+        }
+        sectionOfBlock[bi] = sec;
+        sectionTexts[sec] += b.lines.join('');
+    });
+    const secTokens = sectionTexts.map(t => enc.encode(t).length);
+    // Cut at section s iff the group accumulated since the last cut and section s
+    // are BOTH >= minSection. Group size = sum of section token counts (token
+    // counts are not additive across joins; the sum is a deterministic threshold
+    // proxy, never used as a budget).
+    const cutAtSection = new Array(secTokens.length).fill(false);
+    {
+        let groupTokens = 0;
+        for (let s = 0; s < secTokens.length; s++) {
+            if (s > 0 && groupTokens >= minSection && secTokens[s] >= minSection) {
+                cutAtSection[s] = true;
+                groupTokens = 0;
+            }
+            groupTokens += secTokens[s];
+        }
+    }
+    const pieces = [];
+    let acc = '';
+    const flush = () => { if (acc.length > 0) {
+        pieces.push(acc);
+        acc = '';
+    } };
+    for (let bi = 0; bi < blocks.length; bi++) {
+        const b = blocks[bi];
+        const btext = b.lines.join('');
+        if (btext.length === 0)
+            continue;
+        if (b.heading) {
+            const s = sectionOfBlock[bi];
+            // Preferred cut: honor the precomputed section cut. Merged headings still
+            // flush when their whole section cannot join the open chunk — splitting
+            // at the heading beats orphaning the heading line at a budget flush.
+            if (cutAtSection[s])
+                flush();
+            else if (acc.length > 0 && enc.encode(acc + sectionTexts[s]).length > maxTokens)
+                flush();
+        }
+        if (acc.length > 0 && enc.encode(acc + btext).length > maxTokens)
+            flush();
+        if (acc.length === 0 && enc.encode(btext).length > maxTokens) {
+            pieces.push(...splitOversize(btext, enc, maxTokens)); // mega-block fallback
+            continue;
+        }
+        acc += btext;
+    }
+    flush();
+    const segments = [];
+    let cursor = 0;
+    for (const p of pieces) {
+        const len = [...p].length;
+        segments.push({ text: p, start_pos: cursor, end_pos: cursor + len });
+        cursor += len;
+    }
+    return segments;
+}

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,138 @@ 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`);
+        }
+    },
+    {
+        version: 14,
+        description: 'Chunking signature: documents.chunking_signature (schema-only; backfill legacy-unknown)',
+        up: (db) => {
+            // spec §6.1: schema-only. 전환은 sync 의 content 변경 시에만 (spec §5.1, r4 D3).
+            // 백필값은 'legacy-unknown', NOT 'bpe-800-160': custom chunkDocument 파라미터가
+            // 기록된 적 없어 단정하면 거짓 표기가 된다 (advisor r1).
+            const before = db.prepare(`SELECT count(*) AS n FROM documents`).get().n;
+            db.exec(`ALTER TABLE documents ADD COLUMN chunking_signature TEXT NOT NULL DEFAULT 'legacy-unknown'`);
+            // 리터럴 고정 — 마이그레이션은 동결된 역사다. 런타임 기본값 진화는 boot upsert 소관.
+            db.prepare(`INSERT INTO server_meta (key, value) VALUES ('current_default_chunker', ?)
+                  ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
+                .run('c1:enc=cl100k_base:max=800:overlap=0:fence=on:fallback=cp-exact-800');
+            const after = db.prepare(`SELECT count(*) AS n FROM documents`).get().n;
+            if (after !== before)
+                throw new Error(`v14 gate: documents rows changed ${before} -> ${after}`);
+            const cols = db.prepare(`PRAGMA table_info(documents)`).all();
+            if (!cols.some(c => c.name === 'chunking_signature'))
+                throw new Error('v14 gate: column missing after ALTER');
+            const fk = db.prepare(`PRAGMA foreign_key_check`).all();
+            if (fk.length > 0)
+                throw new Error(`v14 gate: foreign_key_check reported ${fk.length} violations`);
+        },
+        down: (db) => {
+            // 호환성 rollback 뿐 (spec §6.3): chunk 경계는 복원하지 않는다. c1 행은 v13 코드가 읽는다.
+            db.exec(`ALTER TABLE documents DROP COLUMN chunking_signature`);
+            db.prepare(`DELETE FROM server_meta WHERE key = 'current_default_chunker'`).run();
+        }
     }
 ];

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